F: publish a finished task's pull request in production (#103)

[mchwang]

Closes #103.

What it does

TaskPublishing (runner/publishing.ts) publishes a task's pull request in production, with the real publisher from setUpRunner. The publisher uses GhAlreadyFixedGateway, GhPullRequestGateway and a GitBranchPusher.

Pushing. The push goes from the runner-owned repository to pushUrl(github.repository) on GH_HOST, never to a configured url (#101 review, finding 6). ownedCommits is the ledger's origin: 'owned' SHAs. Before #22, only recordRebase writes foreign entries, and nothing in production calls it (#101 review, finding 4).

Mode, decided by task status. A running task whose plan items have all completed at the current revision gets a ready PR. A task in needs human, by any path, gets a draft PR. Its problems come from what sent it there: the spent budget, or the current attempt's safety finding or diagnostic.

When it publishes:

• after a start/resume run ends;
• when a refused start/resume moves the task to needs human (an expired budget);
• on the new publish runner action (expectedStateVersion plus an action ID);
• once at startup, if a publish is owed. The CLI starts it after it re-verifies the runner lock.

Last outcome. Schema v10 adds publish_outcomes. GET /api/runner shows it as publish: { available, active, publishable, draft, last }, and the same transaction updates the publish action's replay. The upgrade records tasks already running or in needs human as not published, so the first start opens nothing unasked.

Shutdown. Step 2a in runner-lifecycle.md: publishes are aborted in step 1 and awaited before the write gate closes.

Guards:

• Start, resume and a second publish are refused while a publish runs.
• Demos never publish.
• github.baseBranch is required with a runner block, and is checked before the lock.

Decisions (user, 2026-10-03): github.baseBranch; publish decided by status after the run; a durable outcome (v10); one startup publish if owed.

Tests

• test/runner-publishing.test.ts, 12 tests. They use a local bare repository as the remote and a fake GitHub. They cover:
  • a completed run opens one ready PR, with the branch at the task head;
  • a needs-human task gets a draft PR with its problems;
  • a refused resume that moves the task to needs human publishes a draft;
  • a refused resume on a task already in needs human publishes nothing;
  • BranchPushRefused leaves the task running, the publish action retries it, and the replay reports the outcome;
  • start, resume and a second publish are refused while a publish runs;
  • shutdown during the push, and during the opening, closes the Store only after the publish settled, and the next start publishes once or recovers the opening by its marker;
  • a PR whose reply arrives after the abort is recorded before the write gate closes;
  • a demo never publishes;
  • baseBranch validation.
• cli.test.ts: a missing or full-ref baseBranch is refused before the lock and before the token check.
• Schema tests: v9→v10, and the not published baseline.
• Each guard was broken on purpose, and a test failed each time: the startup publish, the after-run publish, the publish after a refused resume, the status-change check, the busy guard, the replay update, and the shutdown wait (removed, or moved after the write gate).

Current local counts. Typecheck passes. Without agent-container and agent-supervisor, 1,402 tests ran: 1,394 passed and 1 was skipped. The other 7 timed out while a parallel Docker run loaded the machine; their six test files pass when rerun alone (144 tests). The two Docker files failed locally (10 tests). A comparison run on main was stopped at its 30-minute limit, so it is not yet known whether they fail without this change. The real-docker job decides.

Review rounds

Round	Source	Findings	Outcome
1	/code-review high + independent review agent	budget-expiry needs-human not published; stale safety finding in the problems; first upgraded start would publish old tasks; stale publishing replay; refs//HEAD base accepted; missing race tests; weak assertions ("restart publishes nothing", replay); no test that the publish wait comes before closeWrites; double progress read; unredacted gh text in outcomes; late GH_HOST check; misleading refusal text; orphaned doc comment	all fixed
2	/code-review high	a refused resume re-ran an owed publish; startup publish before the CLI's lock re-check; #problems read every attempt; mode computed twice	all fixed
3	/code-review high	docs lagged behind the fixes	fixed
4	/code-review high	none	—
5	/code-review high (fresh pass on the full diff)	a spent budget hid the current safety finding in a draft; the push used the setup's env while the gh gateways used process.env; recorded errors were redacted with process.env's tokens; no test that the CLI starts the owed publish	fixed in cfb38a9, each with a regression that fails without it
6	Copilot review on b6a7db7	a crash after the publish action committed its publishing reply, but before the publish recorded an outcome, left the replay saying publishing for ever	fixed in b2fe796, with no schema change. A saved reply that still says publishing counts as unsettled. Any later outcome of the task settles it, and startup settles it as stopped (interrupted) when nothing is owed. Regressions: two crash/restart tests, one for each half of the fix, and each fails without its half
7	Copilot review on b2fe796 ("previously missed")	an automatic publish (after a run, at startup) had no durable in-flight marker, so a crash after its PR opened left publish.last empty or stale for good	fixed in b35a2a0. Every publish records publishing before its first external call, and does not run if that write fails. Startup publishes again when one is owed, and otherwise settles a leftover record as stopped. Regressions: the marker is written before GitHub, a leftover is settled at startup, and no marker means no publish; each fails without its piece
8	Copilot review on b35a2a0	(high) a task whose earlier run owed a scope pause or a safety escalation (its write failed, or the process stopped) could be published as a ready PR showing unreviewed out-of-scope changes, since every item had run and nothing would pay it; (previously missed) the CLI checked baseBranch before the lock only when a github block existed	fixed in 1439ccf. Publishing refuses owed work, and a run's end, startup and a refused publish action have the executor pay it first (ItemExecutor.owes/payOwed). The CLI refuses a missing github block before the lock. Regressions: the unrecorded-pause state at startup and on the action, and the CLI with the lock held by another runner; each fails without its part

Declined or deferred. These are posted on #103.

• Cancel during a draft opening: it can leave a cancelled task with an open draft PR. The PR is recorded, and closing it is the existing "close the draft on cancel" slice.
• Untracked push on a crash: the production push registers no process group, so a crash mid-push leaves the push untracked. A normal shutdown aborts and awaits it.
• Commits outside the ledger: snapshot.head comes from the review snapshot and may include commits the ledger does not record. This belongs with Add pre-merge rebase and head-bound command checks #22.
• Outcome version stamp: the version is stamped at record time, not at the publish's last guarded write. No failing interleaving was found (low confidence).

Validated head. 1439ccf:

• Typecheck passes.
• Publishing, publish, lifecycle store, cli, production, execution and start pass (426 tests).
• CI test and real-docker are still running; real-docker is not a required check.

Review-lesson audit. Each finding falls under an existing AGENTS.md rule:

• the idempotent replay ("keep the saved response current");
• the shutdown ordering ("track an in-flight irreversible subprocess");
• token redaction (the guarded-external-actions rules);
• tests that must fail ("A test's setup must leave the state the production path would", and the Design system and plan format #1 E2E rule).

The Copilot round 8 findings fall under "Check an operation's source-state preconditions before any shortcut" and "Prefer validating dependencies before acquisition". The Copilot round 7 finding falls under "Record in-flight ownership before the first external write". The Copilot round 6 finding falls under the idempotency rules ("keep the saved response current with the durable outcome it reports"). The upgrade baseline and the resume trigger are one-off product decisions. No new AGENTS.md rule is needed.

🤖 Generated with Claude Code

[mchwang]

Follow-up issues for the deferred findings: #111 (close the draft on cancel), #112 (track the push's process group across a crash), #113 (publish only ledger-recorded commits; with #22), #114 (outcome version stamp, low confidence).

[Copilot]

Copilot review overview

🟡 Changes recommended

Crash recovery loses the publish action correlation, leaving idempotent replays permanently stuck at publishing.

Review effort: Balanced
Findings: 1

Open (1)

• Persist publish action ID for crash-safe recovery · New

What changed in this PR

Connects the existing pull-request publisher to production runner tasks.

Changes:

• Publishes ready or draft PRs after runs, retries, and startup recovery.
• Adds durable publish outcomes, replay handling, and shutdown coordination.
• Adds production wiring, validation, tests, and documentation.

File	Description
web/​server.ts	Coordinates publishing actions and lifecycle.
web/​cli.ts	Validates configuration and starts recovery publishing.
runner/​publishing.ts	Adds task publishing orchestration.
runner/​production.ts	Builds production publisher dependencies.
runner/​store.ts	Adds schema v10 publish outcomes.
runner/​branch-push.ts	Exports token-variable metadata.
github/​pull-requests.ts	Supports explicit gh environments.
github/​already-fixed.ts	Supports explicit gh environments.
github/​merge.ts	Adds optional base-branch configuration.
test/​runner-publishing.test.ts	Covers publishing and shutdown behavior.
test/​runner-production.test.ts	Updates runner configuration fixture.
test/​runner-lifecycle-store.test.ts	Tests outcome migration and persistence.
test/​publish.test.ts	Tests schema and environment behavior.
test/​cli.test.ts	Tests validation and startup publishing.
README.md	Documents runner publishing.
docs/​implementation/​runner-lifecycle.md	Documents shutdown ordering.
docs/​implementation/​pull-request-opening.md	Documents publishing behavior.
docs/​architecture.md	Updates publishing architecture status.

---

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

[Copilot]

Copilot review overview

🔵 Needs a closer look

Automatic publishes can permanently lose their durable outcome after a successful PR opening.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Persist publish action ID for crash-safe recovery

Previously missed (1)

In code that hasn't changed since last review

Automatic publishes lack durable in-flight state, preventing startup reconcilia…

runner/​publishing.ts:136

An automatic after-run/startup publish has no durable in-flight marker. If opening succeeds and moves the task to in review, but this outcome write fails (or the process exits between those writes), this catch clears the in-memory run and startup later sees neither an owed publish nor an unsettled publish action. publish.last therefore remains null or stale permanently despite the recorded open PR. Persist ownership before every automatic publish and reconcile it at startup, as is done for action-triggered publishes.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unrecovered scope findings can be published as ready, and persistence failures can leave publish ownership and replays permanently inconsistent.

Review effort: Balanced
Findings: 1

Open (1)

• Publishing can bypass an unreconciled owed scope pause · New

Previously missed (1)

In code that hasn't changed since last review

Validate baseBranch before locking when github configuration is absent

web/​cli.ts:43

This conditional skips the promised pre-lock validation when the entire github block is absent. A runner with that malformed configuration acquires the runner lock first (and can report a lock conflict instead of the configuration error), contrary to the PR description and pull-request-opening.md:132. Validate baseBranch unconditionally for every non-demo runner.

[Copilot]

Copilot review overview

🔵 Needs a closer look

It combines irreversible GitHub operations, asynchronous recovery and shutdown behavior, and a database migration across multiple lifecycle boundaries.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Publishing can bypass an unreconciled owed scope pause