[rochecompaan]

Summary

Adds the design and implementation plan for interactive Issue runs, explored in #225. Docs only. No code changes. The second commit aligns the first draft with the skills-first kernel (#329) and the planning merge gates. The third runs interactive implementation through pi-subagents. The fourth publishes agent-done before the review wait. The fifth adds the implementation plan (docs/plans/2026-11-01-issue-225-interactive-issue-runs.md): 11 tasks covering slices 1–3, to be built on a fresh branch from main.

 docs/specs/
+└── 2026-10-14-issue-225-interactive-issue-runs-design.md

The maintainer works out the spec and plan with the agent in a Pi chat. Patchmill then runs the rest of its usual workflow, and the same chat stays open until the implementation PR is merged:

patchmill run-once --issue N --interactive
  open Pi chat with the Patchmill extension
  runOneIssue(..., humanChannel)              same kernel loop, one optional dependency
    planning phase -> envelope sent into the chat
      agent + maintainer write spec/plan, agent commits, pushes, opens planning PR
      submit tool (maintainer confirms) -> verifyOutcome
        check fails -> reasons back to the agent, retry in the same Run attempt
    gate PR open -> wait in process, keep in-progress and the lock
      maintainer says "merged" -> continue tool -> derive facts again
    implementation -> pi-subagents worker (spawn, context: fork), progress in chat
      needs-input -> questions in chat -> guidance confirmed, posted to issue
                  -> same worker continues via resume                     (slice 2)
    console exits -> stop worker; restart stops any stray worker first    (D7)
    verified implementation PR -> agent-done + one comment, run stays open
      review wait: agent pushes PR updates, no new session or comment
      maintainer says "merged" -> continue tool -> run ends, no second comment
  Issue run ends; chat stays open -> start another issue                  (slice 3)

Points that most need review:

• No saved state. The first draft relied on Run recovery state for resume and blocks. The kernel forbids persisted workflow state, so every wait is derived again from git and the host.
• Decisions D1–D7. A new section lists the changes this revision makes to earlier answers. The main ones: the implementation worker forks the Console session through pi-subagents, started by the Patchmill extension, not the agent (D1); block guidance is posted to the issue (D3); a verified implementation PR gets agent-done at once, but the Issue run stays open for PR updates until the merge (D5, D6); and the worker never outlives the console (D7). Non-interactive runs keep pi -p.
• Anti-goals. One runOneIssue for both modes. The agent decides when to go on, after the maintainer's word. Patchmill derives what happens next.
• Slice order. Planning through to a merged PR comes first. Unblocking in place comes second.

Refs #225

Evidence

• npx prettier --check and npx markdownlint-cli2 pass on the revised file.
• File and symbol references were checked against main at 2834e8e3: runOneIssue, derivePhase, verifyOutcome, planningGateComment, supervisePi, sumSessionUsage, and the envelope template. Pi 1.4.0 still exports InteractiveMode and createAgentSessionRuntime. The pinned pi-subagents 0.80.0 RPC offers spawn (with fork context), steer, resume, stop, status and cost.
• The first draft had a fresh-context review. These revisions have not had one yet.

Merge Danger

Door: two-way

Docs only. A revert removes the file.

Blast Radius: issue-225

This repo has workflow.specApproval.required: true. The kernel opens the spec gate only for a merged PR whose head is agent/issue-225--spec. This PR's head is docs/issue-225-interactive-console, so merging it does not open the gate. A later run-once --issue 225 would start a spec session on a spec that is already on main, and it would likely stop with needs-info. #225 is labeled agent-unsuitable, so only an explicit --issue run reaches this.