Execution Log: tmux-backed observable/interactive harness sessions

Append-only log of progress for the user's visibility. Checked in alongside the spec at docs/specs/issue-32/. The-loop keeps the work item's phase label in the ticketing system in sync with the phase front-matter above.

Phase transitions

Phase	Entered	Reviewed/approved by	Notes
brainstorming	2026-07-16	@MadaraUchiha-314 (PR #33 reviews + merge; advance instruction)	issue #32 is exploratory (asks architecture/alternatives questions) → Phase 0
requirements-definition	2026-07-17	@MadaraUchiha-314 ("let's implement", PR #35)	derived from the locked brainstorm; Q2/Q3 carried to design
design	2026-07-17	@MadaraUchiha-314 (same instruction — spec+implementation approved together)	decides Q2 (paste injection) and Q3 (pre-assigned id) → decision-021
tasks-breakdown	2026-07-17	@MadaraUchiha-314 (same instruction)	8-task DAG
implementation	2026-07-17		TDD: 22 new tests red → green; make check green
needs-review	2026-07-17		awaiting owner review of PR #35
complete

Progress entries

2026-07-16 — brainstorm drafted

• Phase: brainstorming
• Did: studied the current spawn/resume path (issue-15: Dispatcher._spawn_for, HarnessAdapter, session registry) and drafted brainstorm.md answering the issue's four questions — architecture options (tmux-hosts-interactive vs. tmux-as-viewer vs. runner abstraction), user-interaction pattern, tmux's role vs. alternatives (screen, dtach, Zellij, ttyd/GoTTY, vendor-hosted), and the three access modes (local / SSH / web terminal).
• Checkpoint/tests: markdownlint on the new docs (spec-only change; no code).
• Next: human review of the brainstorm — open questions 1–5 (interaction fidelity, injection reliability, id/completion capture, web-mode scope, per-item runner) need the owner's answers before the artifact can lock and requirements be derived.
• Blockers: waiting on brainstorm review/lock (requireHumanReviewPerPhase).

2026-07-17 — first human review round on the brainstorm

• Phase: brainstorming
• Did: owner reviewed on PR #33: Option A chosen for question 1 (typing into the live TUI is the bar), and asked for more detail on questions 4 (web-mode scope) and 5 (mixed fleets). Replied on each thread, then edited brainstorm.md in place: question 1 marked resolved, questions 4/5 expanded with the unpacked recommendations, leaning updated to "A semantics confirmed".
• Checkpoint/tests: markdownlint on the spec docs.
• Next: owner's calls on the remaining questions (2–5); then lock the brainstorm and derive requirements.md.
• Blockers: brainstorm still in-review (questions 2–5 open).

2026-07-17 — second human review round on the brainstorm

• Phase: brainstorming
• Did: owner resolved more open questions on PR #33: access control is environmental (VPN / provider network for remote hosts; nothing needed on a local laptop — the-loop ships no auth of its own), and question 5 is receiver-globalrouting.runner. Replied on both threads and updated brainstorm.md: security constraint rewritten as the environmental-access assumption, question 4 reduced to the ship-vs-document call, question 5 marked resolved, leaning updated.
• Checkpoint/tests: markdownlint on the spec docs.
• Next: owner's calls on questions 2 (injection reliability), 3 (id/completion capture — likely a design-phase spike) and the remaining half of 4 (ship vs. document the web layer); then lock the brainstorm and derive requirements.md.
• Blockers: brainstorm still in-review (questions 2–4 open).

2026-07-17 — third human review round: web layer in scope + installability

• Phase: brainstorming
• Did: owner ruled that installing the-loop must satisfy the ttyd dependency — resolving question 4 fully: the web layer ships (not just a documented recipe). Replied on the thread with the dependency mechanics (native binaries can't ride the Python wheel → preflight/doctor verification with per-platform guidance as the baseline; static-binary auto-download parked as enhancement; system-package auto-install rejected) and updated brainstorm.md: constraints, question 4, leaning and hand-off now carry the installability requirement.
• Checkpoint/tests: markdownlint on the spec docs.
• Next: questions 2 (injection reliability) and 3 (id/completion capture) remain; then lock the brainstorm and derive requirements.md.
• Blockers: brainstorm still in-review (questions 2–3 open).

2026-07-17 — brainstorm locked; requirements derived (new rolling PR)

• Phase: requirements-definition
• Did: PR #33 was merged (owner notes: by mistake, but the artifact content stands); a merged PR cannot be reopened, so the work continues on the same branch restarted from main with a new rolling PR carrying the remaining phases. Owner instructed to advance to design/implementation → brainstorm marked approved (Q2/Q3 explicitly carried to design), and requirements.md derived: 7 requirements (tmux runner, session identity, event delivery, attach UX, web terminal, dependency verification, lifecycle) + NFRs, scope fences, and the two design-phase questions.
• Checkpoint/tests: markdownlint on the spec docs (docs-only change).
• Next: owner reviews/locks requirements.md on the new PR, then design.md is derived (deciding Q2 with a spike) in the same PR.
• Blockers: requirements in-review — awaiting owner approval (requireHumanReviewPerPhase).

2026-07-17 — design + tasks + implementation (owner: "let's implement", PR #35)

• Phase: implementation → needs-review
• Did: owner approved the requirements and instructed to proceed. Derived design.md (Q2 → bracketed-paste injection, Q3 → pre-assigned session id; decision-021) and the 8-task tasks.md DAG, then implemented end-to-end: cli/the_loop/runner.py (TmuxRunner + check_dependencies + web_terminal_argv), interactive_argv on the adapters, registry runner/tmuxTarget fields, dispatcher tmux spawn/deliver/PR-close-kill, receiver preflight + ttyd lifecycle, sessions attach + tmux-aware list/close, config schema + config keys, and the docs fold-in (capability doc interactive-sessions.md, decision-021).
• Checkpoint/tests (red→green evidence):
  • RED: pytest cli/tests/test_tmux_runner.py cli/tests/test_tmux_runner_integration.py → 2 collection errors (the_loop.runner absent; new fields/APIs missing).
  • GREEN: full suite uv run --project cli python -m pytest -q cli → 102 passed (22 new: 19 unit + 3 Gherkin integration scenarios; 80 pre-existing unaffected).
  • make check (ruff, markdownlint, ruff-format, pyright, config validate, pytest) → all green.
• Next: self-review, then reviewer briefing on PR #35 and owner review (needs-review; tier 3+ → human-approves-pr).
• Blockers: none.

Review cycles

Cycle	Type (self/critic)	Reviewer	Outcome	Link
1	human (brainstorm)	@MadaraUchiha-314	Option A chosen (Q1); Q4/Q5 explanations expanded	PR #33 review threads
2	human (brainstorm)	@MadaraUchiha-314	Access control environmental (Q4 auth half); receiver-global runner (Q5)	PR #33 review threads
3	human (brainstorm)	@MadaraUchiha-314	Web layer ships; installing the-loop must satisfy the ttyd dependency (Q4 resolved)	PR #33 review thread
4	self (implementation)	claude (multi-angle finder + verify)	6 confirmed findings fixed (stale-session collision on spawn, flags-after-positional extra_args, attach misreporting missing tmux, unreaped ttyd on bind failure, unbounded PR-close kill, spawn registering doomed sessions when the harness binary is missing) + 1 layering cleanup (UnsupportedRunnerError moved to harness/base); 2 candidates refuted/recorded as design choices	commit on PR #35
5	human (review)	@MadaraUchiha-314	design.md mermaid sequence diagram failed to render — <br/> unsupported in sequenceDiagram notes; collapsed note to one line + escaped <slug> (e8c16e7)	PR #35 thread

Final validation evidence

• Test suite: uv run --project cli python -m pytest -q cli → 102 passed (22 new for issue-32: 19 unit + 3 Gherkin integration scenarios against a recording stub tmux). make check (ruff, markdownlint, format, pyright, config validate, tests) green.
• Live smoke test against real tmux (container, tmux 3.x): TmuxRunner.spawn with a fake echoing harness → session visible via has_session; deliver bracketed-pasted a webhook prompt which the PTY process received (GOT: webhook event #1… captured from the pane); kill terminated it and has_session went false. Full transcript in PR #35's reviewer briefing.
• Back-compat: pre-issue-32 registry JSON (no runner/tmuxTarget) loads as a process-mode session (unit-tested); routing.runner unset behaves as before.