$run: unattended queue execution

You are the launcher and the narrator. The loop belongs to gate.py run: a deterministic script that spawns one CLI process per task, checks each commit with the pre-commit hook, reviews closed tasks when configured and runs selected stage checks when the queue has no TODO left, and decides when to stop.

Why the loop is not you: an agent that supervises its own work can be talked out of stopping and can convince itself a task is done. The verdict comes from a command's exit code.

1. Find the runner and preflight

Use the delivery scope and risk choice made by flow-run: ordinary small tools need acceptance, not an automatically enabled model review. Honor explicit project requirements. When review is enabled, review once at the delivery boundary; repairs get targeted verification of original blockers and directly introduced regressions, never another general audit. Preserve the original findings and BUG ids in the repair acceptance. Stage checks are selected by delivery.stage and declared impact; queue exhaustion is not product delivery. A new run does not reset the host-managed delivery budget. Further in-goal repair reuses existing goal authorization and cumulative limits. A failed run returns control to the host; it does not automatically require user approval.

flow home prints the checkout; gate.py is <home>/gate/gate.py.

flow doctor --repo <project>
flow admit --plan --repo <project>

Reuse flow-run's preflight if queue, spec and configuration are unchanged; do not repeat it just because this skill was loaded. Show actionable results. Stop and report if the pre-commit hook is not installed, the queue parses to zero tasks, or the head task is BLOCKED. If the head task is REFUSE or UNDECLARED, say so before launching: advisory mode proceeds with a warning, strict_admit stops. Offer to add the missing scope line:

<!-- task:WP-7 files: src/foo.py, tests/test_foo.py -->

2. Confirm once

Use the task count already authorized or supplied by flow-run; otherwise the configured default. Do not ask again for decisions already settled.

3. Detach it from your session

An unattended task can outlive the interactive session. A foreground call, and a background tool shell alike, can die and orphan a worker mid-task. Launch through Task Scheduler, which owns the process:

pwsh -NoProfile -File "$(flow home)/gate/launch-detached.ps1" `
     -Repo <project> -MaxTasks <N> -TaskName gate-<slug>

That wraps supervise.ps1, which restarts the runner if it vanishes without a report and honours every stop the gate decides. Off Windows, fall back to nohup python <gate.py> run --repo <project> --max-tasks <N> and say the run may not survive this session.

Then watch the journal: append-only NDJSON at <repo>/.gate/journal.ndjson.

Watch incremental events, not repeated transcripts

Arm a cursor BEFORE launch; initialization skips history. Use one cursor per host, and never reinitialize during a run (that would discard unseen events):

python <flow-home>/gate/watch-journal.py <repo> --init

With a persistent Monitor, attach it to the same helper with --follow; output is flushed only for relevant events and it exits after run_end. Retire that monitor before starting a replacement. The existing watch-journal.sh remains a legacy line-number interface; do not stack both watchers or append buffering filters.

Without a Monitor, call --once: the byte cursor reads only new complete records and returns bounded event summaries. Follow next_poll_s (60 → 120 → 300 seconds while idle; reset on events), subject to the host's wait/response limits. For a host that cannot wait that long, --once --wait 55 waits internally for an event for at most 55 seconds; do useful independent work between checks. Keep the active turn open while the authorized run proceeds. Do not invent a persistent tool or rely on a tool-shell background loop surviving the session.

more: true means unread events remain: drain another bounded page immediately. idle is not success, failure or a reason to inspect the transcript. The cursor survives sessions; invalid or oversized records and journal resets emit warnings. New runners include their PID; the watcher emits run_interrupted once if that process exits without run_end, and follow mode exits. Treat it as missing completion evidence, not a failed test or success. Inspect the owner/exit status once, then resume only the unfinished stage using passed review evidence. For older runs without a PID, check owner liveness at a suspected stall before waiting again; do not spend the whole test timeout polling a dead runner. On a warning, inspect the affected journal segment before treating it as healthy. On run_end, read RUN-REPORT once, bottom-up. Review the worker's bounded final excerpt only for a failure/scope request, a user status question, or suspected stall (no journal activity for more than twice the configured heartbeat interval). Do not repeatedly read full logs, diffs, config or skills. Keep a separate offset if more worker diagnostics are needed. No acceptance/review rules are weakened.

Narrating

Report task completion, blockers, review/acceptance and meaningful changes. Combine adjacent start/end events where possible. No repeated “still running” messages or minor test-by-test updates; obey any higher-priority host update requirement with the shortest necessary status, without extra transcript reads merely to fill it.

WP-A -> claude, started
WP-A running 12m, last: "pytest tests/test_a.py -q"
WP-A DONE in 56m, commit 8ebf530
review of WP-A, WP-4: pass (fable), 2 findings recorded
full acceptance: PASS, 561 passed

If heartbeats stop for much longer than the interval, say so.

4. Report the outcome

From .gate/RUN-REPORT.md: lead with Waiting on you (empty on a clean run), then how many tasks closed and why it stopped, then Review and Full acceptance, then the task table and anything left uncommitted. If a task did not close, quote the last lines of its log from .gate/runs/<run-id>/.

The report also records Efficiency. flow metrics --last 5 --repo <project> compares runs without model calls or tests. Legacy missing measures are unknown; worker time includes its checks. Read metrics when assessing workflow cost, not on every poll. Do not run flow usage at startup: the runner probes on demand.

Never

• Never mark a task done, edit the queue status, or touch a verify command.
• Never git commit --no-verify, and never suggest it. The block is the product.
• Never take over an IN_PROGRESS task. Never push, merge or open a PR.
• Never turn a review finding into a queue row. REVIEW-NOTES.md is a record.
• Never put flow resume / flow recall output, CONTEXT or host history into a worker prompt or queue row; workers get the bounded task packet only. After run_end the host (flow-run) saves state with flow checkpoint.
• Never restart a run just because it stopped, and never raise --max-tasks, max_model_calls or max_task_files to push past a stop.

Reading a stop reason

Stopping is good. The only unacceptable outcome is a green light that lies.

Repair continuation

Reuse the user's existing goal authorization for evidenced in-scope fixes. After a failed repair, the host records named tasks and an expiry in the bounded grant; this is not a request for repeated approval. Keep cumulative user limits, stop unchanged no-progress retries, and verify only the repair/direct regressions. Follow flow-run and docs/autonomy.md; optional findings do not create tasks.