[rochecompaan]

Implements the interactive Issue runs design from #327 (docs/specs/2026-10-14-issue-225-interactive-issue-runs-design.md). Closes #225.

Summary

patchmill run-once --interactive [--issue N] opens a Pi console session for one issue. Planning happens in the chat. Implementation runs as a background pi-subagents worker. The Issue run stays open until the implementation PR is merged. Non-interactive runs are unchanged.

patchmill run-once --interactive [--issue N]
  selectIssue                      # same choice as plain run-once; no eligible issue → exit 0
  startConsole                     # Pi InteractiveMode + Patchmill extension + pi-subagents
    open <runsDir>/issue-N/console/ newest session, or a fresh one
    stop stray workers of this session
    runOneIssue(N, human channel)  # same kernel: facts → phase → launch → verify → publish
      planning        → envelope sent into the chat; submit tool + dialogs
        gate required → Approve? → Open a planning PR?
          PR    → gate wait until the maintainer says it merged (continue tool)
          no PR → kernel pushes the approved document on the implementation branch
      implementation  → pi-subagents worker, forked from the chat
        blocked       → questions come to the chat; the same phase continues
      verified PR     → agent-done stop published; review wait (not the end)
      PR merged       → Issue run ends; clean worktrees and local branches removed
    /patchmill-issue M             # switch to issue M's console session and start it

What decides the next step is still only git and the host. The new gate fact for chat approval:

 required gate passes when
   gate PR is merged into base
+  or the gate document is on the pushed implementation branch
+     (only the kernel puts it there, after a recorded approval)

New code is in src/console/ (extension, tools, controller, worker launcher, session host, planning usage). Kernel changes are in src/kernel/: the phase launcher and stop publication were extracted, plus the human channel, review wait, chat approval, merged cleanup and run snapshots. The README, CONTEXT.md and the spec were updated.

Fixes from live runs in rochecompaan/patchmill-test (issues 1–4):

• planning cost from the console session now goes into the PR cost report;
• one console session per issue, so a new issue never reopens another issue's chat;
• the console and the worker load the whole installed skill pack;
• after the merge, the issue's implementation, spec and plan worktrees and local branches are removed when git status --porcelain is empty. That is the only check.

Evidence

• npm test: 864 of 864 pass. npm run lint and npm run build pass.
• Startup and lifecycle smoke tests run the real Pi SDK and the real pi-subagents: console start, session switch, worker fork, quit, and a forced session-switch failure with a custom theme (exits 1 within the time limit).
• Live runs: issues 1–3 in patchmill-test went from planning to a merged PR in the console (for example PR chore(main): release 0.6.0 #13). Those runs found the cost, session-reuse, skill and cleanup bugs above.
  • Before: "PR cost report unavailable: Session usage unavailable: …/sessions/1"; issue 2 reopened issue 1's chat.
  • After: regression tests cover both cases.
• Not yet tested live: the newest in-chat gate approval (9a8da6b9, 3a1cc01f, 664e5c12). Tests cover it with real local git and a fake host.

Merge Danger

Door: two-way. --interactive is opt-in. Reverting removes the console. Issue state lives in labels, branches and PRs, as before.

Blast Radius: mostly interactive runs. These changes reach shared kernel code:

• planningWorkspace also passes a required gate when its document is on the pushed implementation branch. A non-interactive run sees the same fact: a gated document someone pushed there by hand counts as approved.
• run-once.ts was split into the phase launcher and stop publication. It is at its 445-line limit.
• facts.ts artifact reading moved to artifact-source.ts. Behavior is unchanged.

No npm dependency changes.

Known gaps:

• Triage doesn't unblock issues once their blockers close. This dates from feat!: replace workflow engine with skills-first kernel #329 and is tracked in Triage never unblocks issues whose blockers are closed #334.
• A skill-pack path containing a comma is split by the pi-subagents frontmatter parser (upstream).