F: start and resume a task's plan through /api/runner (#91, part 2)

[mchwang]

Part 2 of #91. Part 1 (#102) is merged (80ac5f2), and this PR now targets main.

Decisions: #91 (comment) and the 2026-10-02 comment on #91 (start accepts in review or queued).

What this does

POST /api/runner gets two actions. Each sends expectedStateVersion and an actionId, with no attempt ID. Both run the plan item by item through ItemExecutor.

• start runs a task that is in review or queued, has no execute attempt at its current plan revision, and has no pending requeue. An in review task moves to queued in the same action.
• resume continues a running or queued task that has started running: it has an execute attempt at any revision, or recovery left it to requeue. It starts at the first item the current revision has not completed, whether the last item completed, failed or was stopped. It claims requeue_pending in the admitting transaction. This is also how a task that stopped between items continues.
• Both refuse:
  • a closed task;
  • a pending cancel;
  • an active attempt, a run still finishing, or an active merge;
  • a scope pause (F2: continue a task after a scope pause (reconcile the prefix, validate the rest) #88);
  • a plan revised after an earlier revision's items made runner commits (F2: continue a task after a scope pause (reconcile the prefix, validate the rest) #88). Earlier attempts that committed nothing do not block.
• A spent budget is refused by admission itself. That refusal also moves an idle running or queued task to needs human.
• Owed work: when none of those refusals applies, a finding or scope pause owed from an earlier run is acted on first. Nothing is admitted (outcome: "settled").
• GET /api/runner adds startable and resumable, from the same checks. Retrying an execute attempt is refused: a plan item runs again only through resume.

How it works: ItemExecutor is split into #begin (the synchronous prelude and the first item's admission), #admit and #continue, plus a public begin().

• begin() runs inside the user action's transaction and throws any refusal, so the action's own writes (the move to queued) roll back with it. runTask keeps reporting a refusal as not started.
• An owed finding is settled only after its escalation commits (afterCommit).

No UI yet; the buttons are a follow-up.

Validation

• npm run typecheck: clean.
• vitest without the real-Docker files: 56 files, 1,285 tests pass at fb10295.
• This PR changes nothing under agents/ and adds no Docker path. Part 1's real-Docker files (runner-workspace, agent-question) passed locally. Watch CI's real-docker job to the end before merging, because it is not required.

Review rounds (independent agents, fresh context)

Round	Found	Outcome
1	A plan revised mid-run left the task stuck; an owed finding was settled before the action committed; view flags disagreed with the action; wrong test setup field; missing regressions	Fixed (a3e0a3a)
2	The budget check bypassed admission's needs-human effect (a regression from round 1); #88 refused tasks with no commits; the shutdown test asserted nothing	Fixed (ed14125)
3	The start rule and docs disagreed; an in-review task could get stuck; a strict begin could report "settled" on a revision change	Fixed (9ea6e1b)
4	No code defects; test and doc gaps	Fixed (fb10295)

Declined: acting on an owed in-memory safety finding before the other refusals. It exists only because its durable save failed, a restart loses it regardless of this order, and nothing unsafe runs meanwhile.

Review lessons (merge gate)

• A refusal check placed before an action that has a side effect (the budget) → captured as a one-off in the code comment ("Only the view stops here"); covered by AGENTS.md "Check an operation's source-state preconditions…".
• An in-memory effect applied before the outer transaction commits → covered by the F1: apply a stop only after the caller's transaction commits #79 rule (afterCommit).
• A test whose assertion never runs (the 503) → covered by AGENTS.md "A test's setup must leave the state the production path would…" and the Design system and plan format #1 E2E rule.
• A rule change without a test that fails when reverted → covered by AGENTS.md "give it a test that fails if the claim is false".

After #102 merged

• main (F: wire the runner and startup recovery into the server (#91, part 1) #102, squashed) was merged into this branch (997b63e). main's tree equals part 1's final commit 15db8db, which this branch already had, so the merge changed no file.
• Code review rounds 1–5 were run on this PR in a separate session (3f18b0c, 8e0a84e, 0a78b97, d1eda14, 4bd51d7). Round 5 found no defects.
• Copilot (on F: start and resume a task's plan through /api/runner (#91, part 2) #105): status polls loaded and decoded all attempt history. Fixed (b210311): one targeted query per poll.
• Three Copilot findings deferred from F: wire the runner and startup recovery into the server (#91, part 1) #102, now fixed (2c78519):
  • an issue whose title and body already exceed the prompt budget is refused before any comment page is read;
  • recovery warnings quote Docker labels and file names;
  • a lock.verify() failure after startup prints its message instead of a stack.
• Validation at 2c78519: typecheck clean; 57 files and 1,329 tests pass, excluding the real-Docker files.

Open design questions from review round 5. Each needs a decision, so none is changed here:

• start does not check plan-item approvals.
• start and resume do not check the plan's review_version.
• requeue_pending stays set when a resume ends in needs human. runner-lifecycle.md says exactly one path clears it.
• The F2: continue a task after a scope pause (reconcile the prefix, validate the rest) #88 refusals run before owed work is acted on.
• resume does not check that completed items' commits are still in the task head across runs.

Copilot 2 on #105 (fixed in ea7136b):

• The early size check counted raw bytes, so text that only exceeds the budget once escaped still read comment pages. The title and body now go through the prompt's own serializer first. Lesson: covered by the existing AGENTS.md rule "Align subprocess output limits with every payload…".
• JSON.stringify leaves C1 controls, U+2028/U+2029 and bidi characters literal. A new quoteForTerminal helper escapes them. Lesson: one-off (a terminal-quoting helper and its test); see AGENTS.md "quote agent-chosen text".

Head ea7136b: test and real-docker pass. A full local run was not possible (machine load average ~155); the changed files' tests pass locally.

The five design questions above are not fixed here. They are follow-ups for a person to decide.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Status polling repeatedly loads and decodes unbounded full attempt history.

Review effort: Balanced
Findings: 1

Open (1)

• Avoid repeated full attempt decoding during status polling · New

What changed in this PR

Adds transactional start and resume actions to /api/runner, building on the production runner wiring from #102.

Changes:

• Adds start/resume admission checks and status flags.
• Refactors item execution for synchronous first-item admission.
• Adds lifecycle documentation and regression coverage.

File	Description
web/​server.ts	Exposes start/resume actions and availability flags.
runner/​execution.ts	Splits execution into admission and continuation phases.
runner/​coordinator.ts	Supports atomic recovery requeue claims.
test/​runner-start.test.ts	Tests start/resume behavior and races.
test/​runner-execution.test.ts	Tests synchronous admission and rollback behavior.
test/​runner-production.test.ts	Updates execute-retry refusal expectations.
README.md	Documents the new API actions.
docs/​implementation/​runner-lifecycle.md	Defines start/resume lifecycle semantics.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Prompt-size prevalidation remains incomplete, and recovery warnings permit Unicode line-control injection.

Review effort: Balanced
Findings: 2

Open (2)

• Validate serialized prompt size before fetching collaborators or comments · New
• Escape C1 controls and Unicode line separators after JSON quoting · New

Resolved since last review (1)

• Avoid repeated full attempt decoding during status polling