169 lines
8.6 KiB
Markdown
169 lines
8.6 KiB
Markdown
# 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.
|