Execution Log: resume-on-respawn collides with the tmux session it replaces

Append-only log of progress for the user's visibility. Checked in alongside the spec at docs/specs/issue-146/.

Phase transitions

Phase	Entered	Reviewed/approved by	Notes
requirements-definition	2026-08-04		Issue #146: tmux new-session hits duplicate session on the respawn fallback and the identical failure recurs. Traced to six defects across runner.py and dispatcher.py.
design	2026-08-04		Tri-state session_state probe (tmux answered vs. never answered), a protective+verified _clear_target, and a _respawn_tmux that routes into a live occupant instead of replacing it.
tasks-breakdown	2026-08-04		15-task DAG, extended to 19 after the owner's follow-up.
implementation	2026-08-04		Implemented on claude/github-issue-146-icpgbh
needs-review
complete

Progress entries

2026-08-04 — spec drafted

• Phase: requirements → design → tasks
• Did: Read the whole tmux delivery/respawn path end to end (Dispatcher._dispatch_one → TmuxRunner.deliver → _respawn_tmux → _try_resume → TmuxRunner.spawn) plus the poll-path retry accounting (Poller._process_comment, PollState). Confirmed six cooperating defects rather than the single missing has-session check the issue reports — crucially, spawn already probes and clears, so the collision arises from the probe's fail-open reading of an unanswered tmux has-session (10 s timeout) against a new-session that waits dispatchTimeoutSeconds (1800 s) and therefore gets the real answer. Table of causes in bugfix.md § Root cause.
• Decided: an occupant of loop-<slug> is always this work item's own agent, so a live one is never killed — the pending event is delivered into it. That single rule removes both the crash-loop and the silent-kill bug that today's "working" branch has.
• Next: implement T1–T15 (TDD per task).

2026-08-04 — owner follow-up folded in (AC11, AC12)

• Phase: requirements → design → tasks (re-opened, then re-locked)
• Input: issue comment — (1) an upgraded CLI + restarted poller should pick up already-stuck items; (2) is "registry active but tmux killed → resume the same conversation in a new tmux session" handled?
• Found: (1) was a real gap the collision fix alone would not close. _process_comment gives up after polling.maxRetries and then calls resolve_comment(...), which baselines the comment identically to a successful delivery — so the ledger cannot distinguish "done" from "abandoned", and no later cycle would ever revisit it. (2) is the issue-89 path; it exists, and issue-146 was what made it unreliable.
• Decided: record a give-up as one (gaveUp: {comments, version}) and re-arm it version-gated, once per item per run — not on every start, because poll --once from cron would otherwise re-forward abandoned comments every minute; and by construction anyone who has this fix has upgraded, so the upgrade is the correct trigger. No proactive tmux sweep: the re-armed comment is a real event, so the existing delivery/respawn path heals the session with no synthesized boot prompt. Answered on the ticket.
• Next: T12b–T12d alongside the original DAG.

2026-08-04 — implemented, self-reviewed, docs updated

• Phase: implementation → needs-review
• Did: T1–T14. runner.py: TmuxResult.exit_code, the four SESSION_* states, session_state, a protective+verified _clear_target and the single-retry duplicate session handler. dispatcher.py: the opening occupancy check in _respawn_tmux, _deliver_into_occupant, _skip_occupied, the session_exists branch of both spawn call sites, and a _try_resume that no longer blames the conversation for a collision. poller.py: gaveUp: {comments, version} and a version-gated, once-per-item-per-run re-arm. New event types session.respawn_averted / poll.rearmed and the session-occupied drop reason.
• Deviations from the plan, and why:
  • T3 — has_session was not re-expressed over session_state: that would have added a pane read to terminate_harness and sessions attach, which only need existence. It stays one call with its unknown→False reading.
  • T10 — instead of renaming STUB_TMUX_PANE_DEAD_ONCE, the stub tmux was made stateful. The old stub answered has-session with "yes, and it is live" for every name, which (a) is why a bug this shape could ship, and (b) made the new pre-flight refuse every first spawn in the suite. With session lifetime modelled, absence is the default, new-session on a held name reports duplicate session, and the pane knob became unnecessary in three tests.
  • Self-review finding, fixed: _clear_target(present=True) originally fell through to kill-session when the probe would not say what held the name — i.e. it could still destroy a live agent it could not see, contradicting the decision the whole change rests on. It now reports such an occupant as live so the caller tries delivering into it; only a definite dead-pane reading licenses a kill.
• Evidence: 1132 passed, 2 skipped; ruff (check + format), pyright (0 errors), markdownlint (0 errors), validate_config.py all clean — the same commands the pre-commit hooks and CI run.
• Known limit (recorded, not hidden): AC11 is forward-looking. A comment abandoned before this ships carries no gaveUp record and is indistinguishable from a delivered one, so it is not re-armed; what un-sticks an already-stranded item is the collision fix itself landing the next event. Stated on the ticket and in bugfix.md § Out of scope.
• Next: T15 — PR + reviewer briefing, then human approval (tier 3).

2026-08-04 — CI: the-loop's own PDLC gate rejected the spec's headings

• Phase: needs-review (no code change)
• Failed: the gate job — the-loop check issue-146 --recompute --fail-on block → BLOCK requirements-definition · required section is missing: Requirements. checks (ruff/pyright/pytest/markdownlint) was green.
• Cause: the spec was written with paraphrases of the required headings ("Acceptance criteria (EARS)" for ## Requirements, numbered "6. Testing strategy" for ## Testing strategy, "Tasks" for ## Task list). validate-artifacts matches heading text exactly, by design — which is the point of the gate, and dogfooding it means using the bundled templates' vocabulary rather than my own.
• Fixed: restructured all three artifacts to the template headings (bugfix.md: ## Requirements with seven ### Requirement N blocks, each carrying its EARS criteria and keeping the (ACn) tags everything references; design.md: ## Architecture / ## Components & interfaces / ## Error handling / ## Testing strategy / ## Trade-offs & decisions / ## Security design; tasks.md: ## Task list), ticked T15/T16, and named the upstream security markers (trust boundary, abuse case) in both artifacts so enforces-boundaries-from runs instead of skipping on a near-miss word ("trust boundaries" is not a substring of "trust boundary").
• Also verified the gates CI cannot reach yet (the walk stops at the human requirements-approval, correctly): ran the design and tasks-breakdown hooks' checks directly — required sections present and non-empty, artifacts locked, mermaid blocks pass check_mermaid, no unchecked task boxes.
• Evidence: the-loop check issue-146 --recompute --fail-on block → exit 0 (WAIT requirements-approval · no authorized feedback yet — the normal state of an open PR). Code gate re-run: 1132 passed, ruff/pyright/markdownlint clean.
• Learning candidate: a spec artifact should be started from skills/the-loop/templates/*.md rather than written freehand and reconciled later. Third occurrence would justify a write-up per selfImprovement.