# Python Blender Web Autopilot

This supervisor advances the authoritative `docs/EXECUTION_QUEUE.md` task toward
source-backed Blender Web behavior. Product backlog entries are bounded work
items inside that task, not a replacement queue. Blender source/Main remains the
specification. A task, route assignment, successful build or agent-written
`ready` result is never counted as completed migration.

## Commands

Run from the repository root with Python 3.11 or newer on Linux:

```bash
python3 my-tools/run_web_product_migration.py doctor
python3 my-tools/run_web_product_migration.py start
python3 my-tools/run_web_product_migration.py status
python3 my-tools/run_web_product_migration.py timings
python3 my-tools/run_web_product_migration.py pause
python3 my-tools/run_web_product_migration.py reconcile
python3 my-tools/run_web_product_migration.py resume
```

`start` detaches from the terminal and transfers an exclusive OS lock to its
child without an ownership gap. `run --once` performs at most one implementation
attempt in the foreground. `--max-cycles N` bounds a run; zero means unlimited
cycles within the token and failure budgets. The existing
`bash my-tools/start_unattended.sh` product entrypoint uses this supervisor.

`stop` aliases `pause`. It terminates the active process group and records the
outcome. Interrupted implementation/commit/push work enters `needs_reconcile`.
`reconcile` is read-only. After inspecting the referenced edits, process receipts
and remote HEAD where relevant, `resume --retry-blocked` explicitly acknowledges
that state and resets the affected failure budget. An unreadable checkpoint or
unknown write outcome is never silently replayed.

For login/boot service management:

```bash
python3 my-tools/run_web_product_migration.py service
systemctl --user daemon-reload
systemctl --user enable --now blender-web-autopilot
```

The generated service captures the executable search path and restarts unexpected
process failures. Exit codes 2/3/4 prevent restart loops for known blockers,
unknown outcomes and budget exhaustion. Unattended operation without a logged-in
user also requires the host's user-service lingering configuration.

## Execution Contract

1. Read and validate the current queue, parent manifest and compact context.
2. Select a bounded current-task workflow, prioritizing audited production gaps.
3. Run one noninteractive Codex CLI turn to implement source/protocol/UI code and
   prepare focused tests. The configured model is inherited; no model override,
   API credential or SSH password is embedded in the program.
4. Require actual process exit 0, `turn.completed` and schema-valid output.
   Finding a result file alone never ends or accepts a worker.
5. Independently run source build, typecheck, lint, Chromium, positive/negative,
   undo/redo, save/reopen and determinism checks. Duplicate argv/cwd pairs run
   once. Build parallelism is capped at eight jobs.
6. Require fresh runtime case receipts, native Main state observations and
   SHA-256-bound compiled/runtime artifacts. Bind the validation logs and input
   files in a supervisor-generated receipt.
7. Reuse receipts only while every input and artifact hash still matches.
   Complete untouched workflows before revisiting shared-file invalidations.
8. After all current workflows pass, run a separate handoff turn restricted to
   repository generators and evidence files, then independently run governance
   gates and verify the resulting manifest. Advance only to its `nextTask`.
9. Commit exact declared handoff paths using `git commit --only`, retaining
   unrelated staged edits. Pre-existing dirty paths cannot be silently included.
   Push without force and require remote `main` HEAD to equal the local commit.

A successor is generated through repository tools, never inferred from a task
number. With unverified source units and no valid successor, the supervisor
reports `planning_required`; it does not announce full desktop parity.

## Policy And Evidence

Configuration: `my-tools/wbv2_autopilot_policy.json`. Defaults are 30 minutes per
worker/check, three attempts per failing workflow, 500,000 reported input/output
tokens per run, 32 MiB per process log, eight build jobs, and six push retries.
The token limit is checked between turns, so the last turn can exceed it.
`autoCommit` and `autoPush` control repository publication. All mandatory runtime
check categories remain required even when policy is edited.

The supervisor uses the existing authenticated `codex exec` CLI with
`workspace-write` sandbox and no interactive approvals. Worker stdout is JSONL;
structured output is requested with `--output-schema` and
`--output-last-message`. Consult the installed `codex exec --help` for the
supported CLI flags in this environment.

State is under `tests/golden/WBV2/autopilot/`:

- `state.json`: atomic checkpoint, job states, PIDs and reasons.
- `owner.lock`: OS-backed exclusive ownership with process identity.
- `baseline.json`: initial HEAD and pre-existing dirty paths for publication.
- `events.jsonl`, `daemon.log`: concise lifecycle events and detached output.
- `runs/<attempt>/`: worker output, check logs, process exit receipts, fresh
  behavioral receipts and the final verified receipt.

`node tools/web/print-wbv2-live-status.mjs --json` includes Python supervisor
state. The existing Python status display no longer infers completion from
34/34 implemented backlog entries.

Production implementation workers do not SSH, deploy or mutate the live website.
They verify new code against disposable local runtime fixtures. The production
origin is available as `WBV2_DEPLOYED_ORIGIN`; release deployment remains a
separate operation after tested artifacts and a rollback target exist. Configure
deployment credentials through the existing host credential facilities, never
inside this policy or logs.

## Verification

```bash
python3 -m unittest discover -s my-tools -p test_wbv2_autopilot.py -v
python3 -m py_compile my-tools/wbv2_autopilot.py my-tools/run_web_product_migration.py
node tools/web/run-wbv2-scheduler.mjs --preflight-only
git diff --check
```

The tests exercise supervisor behavior with synthetic fixtures and real child
processes. They are not Blender migration coverage. Actual coverage is earned
only by source-backed native/Chromium module validation and repository binding.

## Source-First Workflow Rule

Business modules and function routes drive implementation: module -> user
workflow -> function route -> native source/operator cases. Search the supplied
`blender-5.2.0` source and task-scoped references before editing Web behavior.
Use `search-wbv2-batch-source.mjs --unit <id> --pattern <symbol>` for a bounded
source search. Worker results must name `workflow`, exact catalog `routeIds`
and native `sourceReferences`; the independent receipt binds those files.

## Timing And Provider Backoff

Displayed time labels use Beijing time, `YYYY-MM-DD HH:MM`. Machine checkpoints
retain precise timestamps; reports express elapsed time in minutes.

```bash
python3 my-tools/run_web_product_migration.py timings
python3 my-tools/run_web_product_migration.py timings --json --write
python3 my-tools/benchmark_wbv2_autopilot.py
```

`timings` is read-only unless `--write` is given. It reports each completed step,
phase totals/shares, maximum durations and the current process. JSONL tool spans
separate provider wait, model response, reads, edits and command execution.
Nested spans are not added to process totals again. Old logs cannot reconstruct
per-item timestamps or unrecorded gaps.

Short commands wait for process completion directly. Heartbeats are written
every five seconds rather than on every poll. Provider events are read
incrementally with a default observation interval of 0.25 seconds. Shared
evidence paths are hashed once per fingerprint operation.

Before any agent action, overload/concurrency/rate-limit errors end the waiting
process promptly. No first action within 60 seconds also ends the request.
Automatic retry requires a known JSONL handshake, no actions or unknown output,
and unchanged source/protected fingerprints. Retry delays are 30, 60, 120 and
at most 240 seconds; four provider failures stop with `provider_blocked`.
Provider failures do not consume implementation attempts. Silence after actions
has a 180-second limit unless a tool is active; unknown outcomes require
reconciliation. Build/test limits and behavioral gates remain in force.

After a reviewed maintenance commit, `resume --retry-blocked --refresh-baseline`
can refresh the Git baseline only when no workflow edits or receipts are recorded.
It retains remaining dirty paths as protected pre-existing work, and cannot
absorb partially implemented or already verified workflow changes.