feat(web): add source-first Python autopilot and optimize provider waits

my-tools/AUTOPILOT.md

@@ -0,0 +1,168 @@
+# 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.