Design: define safe cleanup semantics for leftover issue worker tmux sessions

[devkade]

Description

Scheduled issue-cron work for issue #198 / PR #200 left Ilchul/Kapi tmux runtime sessions that were not safely closed through the current workflow control plane.

This appears to be a runtime lifecycle / cleanup contract gap rather than an implementation blocker in PR #200.

Evidence

• Completed PR: feat: add PhasePreset schema contract #200
• Issue context: Design: define full-lifecycle PhasePreset and runtime spec schemas #198
• Remaining tmux sessions observed after PR merge:
  • issue-198-phase-preset-worker
  • issue-198-phasepreset-runtime-schema
• issue-198-phase-preset-worker registry/status evidence:
  • status: active
  • phase: planning
  • piLaunch.status: completed-output-present after probe
  • promptDispatch.status: failed
  • runtime observation/recommendation earlier: stale-registry-runtime-mismatch, restart-not-recommended
• issue-198-phasepreset-runtime-schema had a live tmux pane but no registry entry visible from the supervisor worktree (entry: null).

Reproduction / context

1. Start/continue an Ilchul/Kapi worker for a bounded issue from an isolated supervisor worktree.
2. If initial prompt dispatch/readiness is ambiguous, manually continue or fall back to direct supervisor implementation.
3. Complete PR review/merge successfully.
4. List tmux sessions; the worker sessions remain active/attached state 0 without an obvious safe completion/cleanup path through the supervisor status/probe surface.

Decision questions

• Should the supervisor have a safe closeout command for abandoned/stale issue workers after a PR has been merged by direct fallback?
• Should sessions with promptDispatch.status: failed but live pane output be classified as retained, stale, or cleanup-eligible?
• Should registry-missing tmux sessions with Ilchul issue slugs be discoverable and cleanup-plan-reportable without requiring destructive tmux kills?

Proposed acceptance criteria

• Runtime cleanup/report surfaces distinguish retained active work from safe cleanup candidates.
• Registry-missing but Ilchul-owned tmux sessions can be reported with non-destructive evidence.
• The cleanup path never silently kills user-owned sessions and never deletes worktrees/branches without explicit authorization.

Labels

Please keep needs-design until Kade confirms the desired lifecycle semantics.

[devkade]

Additional occurrence from the 2026-05-17 scheduled issue-cron run:

New leftover session evidence

• Completed PR: feat: define graph execution component boundary #202
• Completed issue: Design: define full-lifecycle preset catalog and graph-execution runtime components #199
• Remaining tmux session observed after PR merge:
  • issue-199-graph-worker
• Registry/status evidence from supervisor worktree /tmp/ilchul-issue-199-preset-components:
  • status: active
  • phase: planning
  • piLaunch.status: manual-attach-required
  • promptDispatch.status: failed
  • runtime observation: stale-registry-runtime-mismatch
  • recommended action: restart-not-recommended
• Safe cleanup attempt:
  • npm exec -- kapi cleanup issue-199-graph-worker --from /tmp/ilchul-issue-199-preset-components --safe --json
  • result: cleaned: false, updated: false
  • note: not safe to cleanup non-terminal registry status active

This matches the existing design question: completed issue/PR work can leave an active registry + live tmux session when prompt dispatch/readiness failed and Ragna completed the bounded slice through supervisor fallback. Keeping this issue as the shared cleanup-semantics tracker rather than opening a duplicate.

[devkade]

Scheduled issue-cron observed additional retained Ilchul/Kapi tmux sessions after successful PR merges. This appears to be the same cleanup/lifecycle semantics gap tracked here, so I am adding evidence instead of opening a duplicate issue.

Additional observed sessions (2026-05-17 06:10 UTC)

• issue-198-runtime-schema
  • Pane shows readiness probe text was typed into the shell / zsh (zsh: command not found: KAPI_READY...) rather than cleanly consumed by the runtime.
  • Worktree prompt: ~/.ilchul/worktrees/issue-198-runtime-schema, branch feat/issue-198-runtime-schema.
• issue-199-graph-worker
  • Pane shows completed worker-style summary with verification passing and reviewer subagent approve.
  • Worktree prompt: ~/.ilchul/worktrees/issue-199-graph-worker, branch feat/issue-199-graph-worker.

Still observed from the original report:

• issue-198-phase-preset-worker
• issue-198-phasepreset-runtime-schema

Non-destructive handling

• No tmux sessions were killed.
• No worktrees or branches were deleted.
• This comment only records bounded pane evidence so the future cleanup contract can classify retained/completed/stale sessions safely.

[devkade]

Design decision

needs-design is resolved.

Decisions:

• The supervisor should have a safe closeout/report command for abandoned or stale issue workers after a PR has been completed by direct fallback.
• A session with promptDispatch.status: failed but live pane output is not automatically active authority. It should be classified by observed evidence:
  • completed-retained when pane/output shows completed useful work that should be kept for audit;
  • stale-registry when registry says active but runtime readiness/dispatch ownership is inconsistent;
  • safe-to-close only when terminal, unretained, Kapi/Ilchul-owned, and no active claim/work evidence remains.
• Registry-missing tmux sessions with Ilchul issue slugs should be discoverable and cleanup-plan-reportable non-destructively.
• Safe cleanup must never silently kill user-owned sessions and must never delete worktrees or branches without explicit authorization.
• Cleanup/reporting should prefer evidence and classification first; destructive tmux kills remain explicit safe cleanup actions only for eligible terminal/unretained sessions.

Implementation can proceed as a lifecycle/cleanup slice. This issue is not a blocker for #196, but its semantics should inform worker retention and stale-registry handling.