feat: Event-driven RunPane orchestration

[parsakhaz]

---

type: epic-spec
id: runpane-event-orchestration
status: ready
zone: 1
pr: one PR for the whole epic — phases commit sequentially
github: #356

Epic: Event-driven RunPane orchestration

Problem / context

A long-lived "Pane Chat" orchestrator supervising background coding agents has no way to
sleep until something meaningful happens. It polls panels screen / short-timeout
panels wait, re-reads unchanged terminal output, and infers transitions itself — burning
tool calls, context tokens, and wall-clock while risking missed blockers between polls.
panels wait --for ready returns while the agent is still actively working because
isCliReady latches permanently after the CLI's first response, independent of activity.

Research established the foundation is closer than the original issue (#353) assumed: the
daemon socket protocol already broadcasts event frames to all connected clients
(main/src/daemon/server.ts:66) — current CLI clients just discard them
(packages/runpane/src/daemonClient.ts:134). What's missing is semantic state in the main
process, durable event persistence with cursors, and CLI subscription surfaces.

Supersedes GitHub issue #353 (close with cross-link on publish). The two quick wins peeled
from #353 — declarative pane pinning and slash-command-aware prompt submission — are
separate Feature Tickets with their own PRs, not phases of this epic.

Goals

• An orchestrator can block on one command until a panel becomes idle, requires input,
  becomes blocked, or exits — without screen text in the payload and without polling.
• Multiple panels/panes are supervisable through a single watch, including panels created
  after the watch starts.
• A disconnected client resumes from a cursor without silently losing transitions.
• Pane/agent creation can verify the initial prompt was actually submitted and work began.
• Routine supervision payloads are compact enough that dozens of panels are practical.
• Everything the event surface can observe is also pull-readable via request/response
  commands — polling stays a fully supported fallback (D8).

Non-goals

• Encoding plan/implement/review/merge policy in RunPane — higher-level skills interpret
  events.
• Auto-approving irreversible actions (merge, release, deploy, publish).
• Replacing terminal inspection — panels screen/output remain for deliberate use.
• Semantic understanding of arbitrary terminal apps without adapter support.
• A remote hosted event service — local daemon/IPC delivery only.
• Per-agent screen-aware idle detection as a base requirement (see D1).

Key architecture decisions (cross-cutting)

• D1 — Agent activity (active/idle) is derived from a byte-silence debounce,
  longer and configurable vs today's fixed 30s — it generalizes to any agent with no
  per-agent adapters, keeping the base event contract agent-agnostic · rejected:
  screen-aware per-agent adapters as the base signal (privileges Claude/Codex; may later
  refine the signal as an optional layer but must never be load-bearing for base
  events). Empirically validated (2026-07-21, refs/idle-probe-evidence.md): both
  Claude Code 2.1.217 and Codex 0.144.4 emit zero PTY bytes for 150s+ at the idle
  composer, and emit continuously while working — the repaint-while-idle failure mode
  did not occur. Remaining accepted limitation: silent thinking past the debounce reads
  as a false idle (mitigated by configurable debounce + D9 reconciliation).
• D2 — panels watch (JSONL subscription over the existing daemon event broadcast)
  is the core primitive; panels await / await-any are exit-on-first-match sugar;
  panels wait is frozen as the legacy polling surface — its conditions are polling
  predicates, semantically different from event waits · rejected: extending
  panels wait (conflates the two models); a new orchestrate command group
  (reconciliation is just panes status --changed-since).
• D3 — One global daemon-scoped monotonic cursor over a bounded in-memory event
  ring; reconnect recovery is snapshot-then-subscribe (panes status --changed-since
  returns a race-free cursor); lifecycle-event and output cursors are separate
  namespaces. An app restart kills every PTY, so pre-restart lifecycle events describe
  dead processes — the correct recovery is a fresh snapshot, not replay; a pre-restart
  or over-aged cursor yields a structured cursor_expired pointing at snapshot
  reconciliation. A durable SQLite table is introduced only in phase 5, where milestones
  (the one genuinely replay-shaped payload) land · rejected: SQLite-persisted lifecycle
  log upfront (schema migration + retention pruning for replay no orchestrator decision
  needs); per-pane cursor scopes (complexity, no gain).
• D4 — Semantic transitions are computed in the main process and become the
  orchestrator-facing canonical attention layer — no reusable source exists today:
  unread state and notification debounce live renderer-only
  (frontend/src/hooks/useNotifications.ts), unreachable from the daemon. Two
  attention truths coexist during this epic (renderer human-facing, main-process
  orchestrator-facing); that is accepted: the smarter semantic layer is the safe default
  the orchestrator consumes, with the dumb reliable signal (raw activityStatus +
  pull polling) as the fallback. Migrating renderer notifications onto the canonical
  layer is a named follow-up ticket, not part of this epic (see Dependencies) ·
  rejected: reusing renderer notification state as feat: add event-driven RunPane orchestration and reliable agent startup #353 scope item 6 proposed (not
  implementable as written).
• D5 — Agent-emitted milestones are namespaced, schema-versioned, and trust-labeled
  claims (producer preserved, daemon-derived vs agent-emitted distinguished); they never
  grant authority for merge/deploy/release/publish or other hard-stop actions.
• D6 — Unknown or consequential interstitials (auth, permissions, destructive
  confirmations, terms, payments) are never auto-answered; automatic handling covers only
  an explicit allowlist of reversible responses under caller opt-in, and everything else
  emits input_required with structured blocker data.
• D7 — All changes are additive: existing commands and JSON contracts keep working,
  npm CLI / daemon schema / generated contracts / Python wrapper stay in parity
  (scripts/test-runpane-contract.js), machine-readable output stays stdout-clean.
• D8 — Pull remains first-class, not a legacy compatibility shim: every semantic
  state and transition observable via watch/await must also be readable through a
  request/response command (panels screen/wait carry the phase-1 state block;
  panes status --changed-since is the canonical pull reconciliation) — an orchestrator
  must always be able to poll when it prefers pull or the event path is unavailable ·
  rejected: event subscription as the sole observation path (a broken/unavailable stream
  would leave supervision blind).
• D9 — Long-lived waits self-check: an await/watch that has received no events
  for a configurable heartbeat interval (default on the order of minutes, well under the
  timeout) internally pulls current state and reconciles it against the event log, so a
  missed event, wedged stream, or dead panel resolves the wait or surfaces a structured
  error instead of silently hanging to timeout — push paths fail quietly; heartbeat
  reconciliation is the standard supervisor pattern (Claude Code's monitors do the
  same) · rejected: trusting push delivery alone until timeout expiry (turns a dropped
  event into a full-timeout stall).

Phases (sequential)

#	Phase	Desired end state	Depends on	Size	✓
1	Semantic state model	Orthogonal terminalReady/agentActivity/inputRequired/blocked state with configurable debounce, exposed in existing responses	—	M	[ ]
2	Event log, cursors, single-panel watch/await	Durable event log; panels watch --jsonl --since and panels await --event work for one panel	1	L	[ ]
3	Multi-target supervision + reconciliation	await-any across panels, panes watch --include-future-panels, panes status --changed-since	2	M	[ ]
4	Verified startup + safe interstitials	panes create high-level mode completes only on verified submission + activity begun	2	M	[ ]
5	Milestones, warnings, incremental output	panels events emit, warning severity separation, panels output --since	2	M	[ ]

Phase 1 — Semantic state model

• Scope: Define the orthogonal state fields (terminalReady, agentActivity with
  unknown|starting|active|idle|exited, inputRequired, blocked, hasNewOutput,
  lastActivity, lastMeaningfulEventAt) computed in the main process; make the
  idle debounce configurable and longer than the current 30s default; surface the new
  state block in existing panels screen/wait JSON responses additively.

• Out of scope: event persistence, new CLI commands, renderer notification migration.

• Proposed approach: Activity tracking already lives in
  main/src/services/terminalPanelManager.ts (~1105–1117: first-output→active,
  30s-silence→idle) and emits panel:activityStatus; state assembly for RunPane responses
  lives in main/src/ipc/runpane.ts (~852–1016), including the bounded-screen blocker
  scan that blocked/inputRequired can reuse. isCliReady latching
  (terminalPanelManager.ts:~981) stays as-is and feeds terminalReady.

• Verification:

  • AC1 — WHEN a CLI panel has produced its first CLI response and is still emitting
    PTY output, panels screen --json shall report terminalReady: true and
    agentActivity: "active" as distinct fields in the same response.
  • AC2 — WHEN a panel emits no PTY output for the configured debounce interval,
    the state shall transition to agentActivity: "idle" and record
    lastMeaningfulEventAt.
  • AC3 — WHEN the idle debounce is configured to N seconds, the active→idle
    transition shall occur after N seconds of silence, not the previous fixed 30.
  • AC4 — WHEN a panel's process exits, the state shall report
    agentActivity: "exited".

  Criterion	Method	Command / flow	✓
  AC1	automated	main-process integration test (pattern: main/src/ipc/runpane.test.ts)	[ ]
  AC2	automated	integration test with fake PTY silence + short debounce	[ ]
  AC3	automated	same test parameterized over debounce config	[ ]
  AC4	automated	integration test killing the PTY	[ ]

Phase 2 — Event log, cursors, single-panel watch/await

• Scope: Bounded in-memory event ring (D3) recording semantic transitions
  (panel_created, terminal_ready, prompt_staged, prompt_submitted, agent_active,
  agent_idle, input_required, blocked, unblocked, panel_exited,
  panel_archived); global monotonic cursor with bounded retention; panels watch --panel --event --since --jsonl (long-lived subscription client in npm + Python
  wrappers); panels await --panel --event --timeout-ms sugar; exclusive --since,
  stable event IDs, at-least-once delivery, structured cursor_expired error naming the
  earliest available cursor; heartbeat reconciliation inside await/watch per D9
  (configurable interval, pull-and-reconcile when no events arrive); timeout returns a
  result, not a bare failure — timedOut: true plus the current reconciled state — and
  exit codes documented to distinguish matched / timed-out / transport-error.

• Out of scope: multi-panel/pane targets, milestone emission, output cursors,
  durable event storage (phase 5, with milestones).

• Proposed approach: The daemon already broadcasts event frames to all socket clients
  (main/src/daemon/server.ts:66, sinks at main/src/daemon/bootstrap.ts:245); the gap
  is client-side — both wrappers close after one matching response
  (packages/runpane/src/daemonClient.ts:107,
  packages/runpane-py/src/runpane/daemon_client.py:62) — plus sequencing: event frames
  carry no sequence numbers today. Stamp transitions from phase 1's state machine with
  the global cursor into a bounded in-memory ring, and serve both bounded replay
  (--since) and live tail over the existing channel.

• Verification:

  • AC1 — WHEN panels await --event agent-idle is issued against a panel where
    terminalReady is true and agentActivity is active, the command shall remain
    blocked until an idle/input-required/blocked/exited transition occurs (regression for
    the observed ready-while-active early return).
  • AC2 — WHEN a watched panel undergoes a semantic transition, panels watch --jsonl
    shall emit exactly one JSON record containing event ID, cursor, type, timestamp,
    paneId, panelId, and compact state — with no screen.text field.
  • AC3 — WHILE a watched panel's state is unchanged, panels watch shall emit zero
    records for that panel.
  • AC4 — WHEN a client reconnects with --since <cursor>, the stream shall replay
    all retained events strictly after that cursor in order, and re-delivered duplicates
    shall be identifiable by identical event IDs.
  • AC5 — IF --since names a cursor older than retention, THEN the command shall
    exit with a structured cursor_expired error containing the earliest available
    cursor.
  • AC6 — WHEN a client presents a pre-restart cursor after the Pane app restarts,
    the response shall be a structured cursor_expired error naming the earliest
    available cursor and a snapshot reconciliation command — never a silent empty
    stream.
  • AC7 — IF a semantic transition occurs but its event is not delivered to an
    active await/watch (simulated stream stall), THEN the command shall detect the
    satisfied condition via heartbeat reconciliation within one heartbeat interval and
    resolve with the reconciled state, marked as reconciled rather than event-delivered
    (D9).
  • AC8 — WHEN an await reaches its timeout without a matching event, the result
    shall contain timedOut: true plus the panel's current reconciled state, and the
    process shall exit with the documented timed-out exit code, distinct from the
    matched and transport-error codes.

  Criterion	Method	Command / flow	✓
  AC1	automated	integration test: latched isCliReady + active output + await	[ ]
  AC2, AC3	automated	watch subscription test over fake transitions	[ ]
  AC4, AC5	automated	replay/dedup/expiry tests against the event ring	[ ]
  AC6	automated	stale-cursor test across daemon re-bootstrap	[ ]
  AC7	automated	await with suppressed event delivery + short heartbeat	[ ]
  AC8	automated	await with short timeout; assert payload + exit code	[ ]
  AC1–AC8 parity	automated	scripts/test-runpane-contract.js extended for new commands	[ ]

Phase 3 — Multi-target supervision + reconciliation

• Scope: panels await-any accepting repeated --panel/--pane; panes watch --pane --include-future-panels; panes status --pane --changed-since compact snapshot
  returning per-panel semantic state plus a snapshot cursor that is race-free against a
  subsequent --since subscription.

• Out of scope: cross-pane aggregation policies; any UI changes.

• Proposed approach: Filtering layer over phase 2's event stream — targets resolve to
  panel sets, panel_created events extend the set when --include-future-panels is on.
  Snapshot reads current state + max cursor atomically enough that
  snapshot-then-subscribe loses nothing.

• Verification:

  • AC1 — WHEN any one of N awaited panels transitions to a requested event, the
    result shall identify that panel's panelId and paneId.
  • AC2 — WHEN a new panel is created inside a watched pane with
    --include-future-panels, the stream shall emit its panel_created event and
    subsequent transitions without restarting the watch.
  • AC3 — WHEN panes status --changed-since <cursor> is issued, the response shall
    list only panels with transitions after the cursor and include a new cursor such
    that a watch started from it observes no gap and no duplicate beyond at-least-once
    semantics.

  Criterion	Method	Command / flow	✓
  AC1–AC3	automated	multi-panel integration tests + contract parity run	[ ]

Phase 4 — Verified startup + safe interstitials

Dependency gate: benefits from the standalone "slash-command-aware prompt
submission" Feature Ticket landing first — this phase builds on its verified
submit-composer semantics for /-prefixed prompts.

• Scope: High-level creation/start mode (panes create ... --start-agent --wait-active) that stages the initial prompt, submits via the semantic composer path,
  reports success only after verifiedSubmitted: true and agent_active; optional
  --handle-known-interstitials safe executing only allowlisted reversible responses
  (e.g. skip an optional update prompt) then continuing the original prompt exactly once;
  idempotent retry after transport failure without duplicating the prompt.
  Regression fixtures include three interstitials reproduced on 2026-07-21: the Codex
  update prompt intercepting initial startup (allowlist candidate), a
  planning-suggestion modal swallowing normal prompt submission (recovered in the
  field by submit-composer --strategy auto), and the Codex directory-trust prompt,
  which killed a session when blind text+Enter submission hit it
  (refs/idle-probe-evidence.md) — trust prompts are consequential and must emit
  input_required, never be auto-answered (D6).

• Out of scope: auto-answering anything beyond the allowlist (D6); interstitial
  handling for arbitrary third-party TUIs.

• Proposed approach: Compose existing primitives — submit-composer verification
  (main/src/ipc/runpane.ts:~1128: active-transition or composer-prompt-disappearance)
  plus phase 2's prompt_submitted/agent_active events — into one daemon-side flow so
  the caller gets a single structured result. Interstitial detection extends the existing
  bounded-screen blocker scan with an explicit allowlist registry.

• Verification:

  • AC1 — WHEN the high-level start completes with ok: true, the response shall
    include verifiedSubmitted: true and agentActivity: "active".
  • AC2 — IF prompt text remains visible in the composer after bounded submit
    retries, THEN the command shall return ok: false with a submission_unverified
    blocker and attempt count.
  • AC3 — WHEN an allowlisted interstitial is detected under
    --handle-known-interstitials safe, the response shall list the handled
    interstitial and the original prompt shall be submitted exactly once thereafter.
  • AC4 — IF a non-allowlisted interstitial is detected, THEN the flow shall stop and
    emit input_required with structured blocker data, regardless of the
    interstitial-handling flag.

  Criterion	Method	Command / flow	✓
  AC1, AC2	automated	integration tests over scripted composer states	[ ]
  AC3, AC4	automated	fixture interstitials (allowlisted + unknown) driven through the flow	[ ]

Phase 5 — Milestones, warnings, incremental output

• Scope: panels events emit --type <ns>.<name> --data-file producing durable
  namespaced milestone events labeled with producer and trust status (D5), backed by
  the epic's one SQLite table + migration (durable storage arrives here per D3 —
  milestones are the replay-shaped payload that justifies it); warning
  events (e.g. mcp_authentication) carrying severity and observed impact separately,
  deduplicated while unchanged, subscribable independently of blocking events;
  panels output --panel --since <output-cursor> --limit for incremental agent output.

• Out of scope: inferring high-level milestones from terminal text; any authority
  attached to milestones.

• Proposed approach: Milestones reuse phase 2's event table with a producer /
  namespace envelope. Warnings extend the blocker-scan classification with a severity
  axis — warning text alone never produces blocked (behavioral evidence or explicit
  agent request required). Output cursoring can seed from session_outputs.id
  (main/src/database/schema.sql:33) — but raw scrollback is not 1:1 with
  session_outputs rows, so the phase must first decide which stream --since reads
  and document it (open question below).

• Verification:

  • AC1 — WHEN an agent emits a milestone via events emit, subscribers shall
    receive an event carrying its namespace, schema version, producer, and an explicit
    agent-emitted (unverified) trust marker.
  • AC2 — WHILE terminal text contains an authentication warning and the agent
    continues producing output, the state shall report the warning as blocking: false
    and shall not emit a blocked event.
  • AC3 — WHEN the same warning persists unchanged, no additional warning event
    shall be emitted.
  • AC4 — WHEN panels output --since <cursor> is issued, the response shall
    contain only output recorded after that cursor.

  Criterion	Method	Command / flow	✓
  AC1	automated	emit + subscribe round-trip test	[ ]
  AC2, AC3	automated	fixture warning screens + activity simulation	[ ]
  AC4	automated	output cursor test over seeded rows	[ ]

Cross-cutting concerns

• Contract parity — every phase extends scripts/test-runpane-contract.js and the
  generated contracts; npm and Python wrappers ship the same surface (D7).
• Migration safety — the epic's single schema migration (phase 5's milestone table)
  follows the existing dual migration system; retention pruning must not grow the DB
  unbounded.
• Security — D5 (milestones are unverified claims, never authority) and D6
  (interstitial allowlist) are review checkpoints in every affected phase.
• Docs — docs/RUNPANE_CLI_CONTRACT.md gains copy-paste examples with representative
  JSON/JSONL for each new command as its phase lands.
• Dogfood metric — after phase 3, measure monitoring calls and bytes returned per
  agent-hour in a real Pane Chat workstream vs the polling baseline from feat: add event-driven RunPane orchestration and reliable agent startup #353.

Dependencies

• Standalone Feature Tickets (separate PRs, peeled from feat: add event-driven RunPane orchestration and reliable agent startup #353): declarative pane
  pinning (feat: Declarative pane pinning via RunPane CLI #357) and reliable slash-command initial prompt delivery (feat: Reliable slash-command initial prompt delivery #358).
  Neither blocks phases 1–3; phase 4 prefers feat: Reliable slash-command initial prompt delivery #358 landed first (see its dependency
  gate).
• Named follow-up ticket (captured after this epic, not part of it): migrate renderer
  unread/notification logic onto the main-process canonical attention layer — until
  then the two attention truths coexist per D4.

Justification

• Byte-silence idle detection is unvalidated — held: PTY probes (claude 2.1.217,
  codex 0.144.4) show 0 bytes over 150s idle windows and continuous emission while
  active; residual false-idle risk mitigated by configurable debounce + D9
  (refs/idle-probe-evidence.md).
• A durable SQLite event log is over-built for lifecycle replay — held by concession:
  replaced with bounded in-memory ring + snapshot-then-subscribe; durable table
  deferred to phase 5 where milestones justify it.
• Phases 4–5 may be speculative — held: three phase-4 interstitial failures reproduced
  in the field on 2026-07-21 and captured as regression fixtures; phase 5's consumer is
  the runpane-orchestrator skills; post-phase-3 dogfood metric retained as a non-gating
  checkpoint.
• Two attention truths would drift — held as accepted cost: semantic layer is the
  orchestrator-facing canonical default, raw signal is the fallback, and renderer
  migration is a named follow-up ticket in Dependencies.

Open questions

• [NEEDS CLARIFICATION] Which stream panels output --since reads —
  session_outputs rows or serialized scrollback — resolve before phase 5 is picked up.
• [NEEDS CLARIFICATION] Default value for the idle debounce (and its config surface) —
  resolve during phase 1 planning.

References (in refs/)

• refs/discussion.md — decision log from the 2026-07-21 discussion (research findings
  with file:line evidence, decisions D1–D4 provenance).
• refs/idle-probe-evidence.md — PTY probe measurements validating D1 (byte-silence at
  idle composer for Claude Code and Codex), plus incidental interstitial/warning
  evidence for phases 4–5.

[parsakhaz]

Event-driven RunPane orchestration (issue #353) — decision log

Date: 2026-07-21
Participants: parsakhaz, Claude (code research via Codex code-researcher)

Context

Issue #353 specifies an event-driven, resumable orchestration surface for RunPane so a
long-lived Pane Chat orchestrator can sleep until meaningful agent transitions instead of
polling panels screen / panels wait. Follow-up to #277 / PR #278.

Key research findings (all file:line-verified)

• Push transport already exists. The daemon socket protocol defines event frames
  (shared/types/daemon.ts:27) and the server broadcasts session/panel/terminal events to
  all connected socket clients (main/src/daemon/server.ts:66, fanout at
  main/src/daemon/bootstrap.ts:245). Node/Python CLI clients discard event frames and
  close after one response (packages/runpane/src/daemonClient.ts:134,
  packages/runpane-py/src/runpane/daemon_client.py:62). panels watch is a client +
  semantics problem, not a new transport.
• activityStatus is a byte-silence heuristic: first PTY output → active, 30s silence
  → idle (main/src/services/terminalPanelManager.ts:1111). Not agent semantics.
• No canonical attention state exists to reuse. Activity lives in main, session status
  in sessionManager, unread + notification debounce (60s + focus gating) renderer-only
  (frontend/src/hooks/useNotifications.ts:20,166). Issue scope item 6 ("reuse the
  attention state powering human notifications") is not implementable as written — the
  semantic state must be created in main process as new canonical truth; renderer
  notifications can consume it later.
• No event cursors exist; only session_outputs.id is monotonic
  (main/src/database/schema.sql:33). Daemon event frames carry no sequence numbers.
• ready + active coexistence confirmed: isCliReady latches permanently after
  first CLI response (terminalPanelManager.ts:981), independent of activity.
• Pinning is nearly free: sessions.is_favorite + favorite_pinned_at exist in DB,
  startPinned exists on session creation (sessionManager.ts:322), and
  sessions:toggle-favorite is already in the shared daemon command registry
  (main/src/ipc/session.ts:1461) — the CLI just doesn't expose it.
• Slash-command hardening builds on existing submit-composer (verifiedSubmitted,
  blocker/nextCommand at shared/types/runpaneOrchestration.ts:389,
  main/src/ipc/runpane.ts:1128).
• Output-cursor gotcha: raw terminal scrollback is not 1:1 with session_outputs rows;
  panels output --since must pick which stream it reads.

Decisions

1. Split the issue (decided): peel two small, independent, dogfood-unblocking tickets
   out of feat: add event-driven RunPane orchestration and reliable agent startup #353 —

   • (a) declarative pane pinning (--pinned on create, pin/unpin mutation, pinned in
     list/status output);
   • (b) slash-command-aware initial prompt submission (semantic submit + verify +
     bounded retry for /do TM-x-style prompts).
     The remainder becomes an epic: phase 1 = semantic state model on byte-silence signal,
     phase 2 = event persistence + cursors + watch/await CLI, phase 3 = verified startup /
     interstitial handling + multi-target/pane watch. Milestone emission (events emit) and
     MCP-warning severity ride in later phases as specced.

2. agent_idle detection = byte-silence debounce only for phase 1 (decided; user
   rationale: it generalizes — works for any agent without per-agent adapters, keeping
   the base event contract agent-agnostic instead of privileging Claude/Codex).

   • Accepted limitation, to be stated in the epic contract: a TUI that repaints while
     semantically idle reads as active, and an agent thinking silently past the debounce
     emits a false agent_idle. The acceptance criterion "spinner frames never satisfy
     the wait" holds only to the extent the debounce absorbs them.
   • Upgrade path: optional per-agent screen-aware adapters (same bounded screen-scan
     machinery as blocker detection, main/src/ipc/runpane.ts:968) may later refine the
     signal but must never become load-bearing for base events.
   • Debounce should be longer/configurable than the current 30s.

3. Command shape (recommended, unobjected): panels watch (JSONL subscription over
   the existing event channel) as core primitive; panels await / await-any as
   exit-on-first-match sugar. panels wait frozen as legacy polling surface. No
   orchestrate command group; reconciliation is panes status --changed-since.

4. Cursor scope & retention (recommended, unobjected): one global daemon-scoped
   monotonic sequence, persisted in a new SQLite events table (survives app restart =
   daemon restart), bounded retention by count + age. Lifecycle-event and output cursors
   are separate namespaces (output already has session_outputs.id).

5. Attention source of truth (recommended, unobjected): promote semantic transitions
   into the main process as the new canonical layer (phase 1); renderer notification
   logic can migrate onto it later rather than the CLI borrowing renderer state.

Open questions

• Which stream panels output --since reads (session_outputs vs scrollback) — resolve in
  epic phase 2 planning.
• Exact debounce default/configurability for byte-silence idle.
• Whether feat: add event-driven RunPane orchestration and reliable agent startup #353 is edited down to the epic scope or superseded by new items linking back.

[parsakhaz]

D1 empirical validation — PTY idle-silence probes (2026-07-21)

Question under test (Socratic gate Q1): do Claude Code and Codex TUIs actually go
byte-silent at the idle composer, or do they repaint while semantically idle (which
would make byte-silence idle detection dead on arrival)?

Method

Python probe (pty_idle_probe*.py): fork the agent CLI in a real PTY (120×40,
TERM=xterm-256color), record every output chunk with a monotonic timestamp and raw
bytes. Timeline: 25s startup → submit hi, respond with one short sentence → 45s
response window → 150s idle observation window (longer than the 60s the gate
suggested). Raw capture verifies the agent truly rendered a response and reached the
idle composer (ruling out a silently stalled dialog).

Versions: claude 2.1.217, codex-cli 0.144.4, macOS, run inside a scratch git repo.

Results

Agent	Response rendered?	Idle-window bytes (150s)	Verdict
Claude Code (run 1, size-only)	—	0	byte-silent
Claude Code (run 2, raw-verified: "Hi! What can I help you with today?")	yes	0	byte-silent
Codex (run 3, raw-verified: "Hi, nice to meet you!")	yes	0	byte-silent

Last output: Claude at ~27–36s (response paint), Codex at ~30.6s. Zero PTY bytes from
then to the end of the window in every successful run.

Inverse signal also observed: while working, both TUIs emit bytes continuously
(Claude spinner + token/elapsed counters; Codex • Working (Ns) spinner at ~12 Hz),
so byte-flow reliably indicates active.

Incidental findings (strengthen phases 4–5)

• Codex runs 1–2 died at the directory trust prompt ("Do you trust the contents
  of this directory? … Press enter to continue"): blind text+Enter submission killed
  the session (run 2) — the exact interstitial failure phase 4 exists to fix. The
  trust prompt joins the phase-4 fixture list alongside the update prompt and the
  planning-suggestion modal.
• Claude rendered "⚠ 4 MCP servers need authentication · run /mcp" and Codex
  rendered "⚠ MCP startup incomplete (failed: node_repl)" as non-blocking banners
  while both agents continued to answer — live confirmation of phase 5's
  warning-severity separation (warning text alone must never imply blocked).

Conclusion for D1

Byte-silence debounce is a valid base idle signal for both flagship agents: the
repaint-while-idle failure mode did not occur in 150s windows. The remaining accepted
limitation is only the inverse direction (an agent thinking silently longer than the
debounce reads as a false idle) — mitigated by the configurable debounce and D9
heartbeat reconciliation surfacing state for the orchestrator to judge.

Raw logs: scratchpad claude_idle{,2}.log/.raw, codex_idle{,2,3}.log/.raw
(session-scratch; statistics reproduced above).

[parsakhaz]

<!doctype html>

<title>Event-driven RunPane orchestration — Explainer</title> <style> :root { --paper: #FAF8F5; --ink: #1F2328; --ink-soft: #5A5F66; --line: #E4DFD7; --panel: #FFFFFF; --accent: #0E7569; --accent-soft: #E3F0EE; --warn: #B45309; --warn-soft: #F7EBDD; --out: #9F3A38; --out-soft: #F6E8E7; --mono: ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace; --serif: Georgia, "Iowan Old Style", "Times New Roman", serif; --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; } @media (prefers-color-scheme: dark) { :root { --paper: #15191D; --ink: #E8E6E1; --ink-soft: #9BA1A8; --line: #2C3237; --panel: #1C2126; --accent: #2FA79A; --accent-soft: #16302D; --warn: #D98E3D; --warn-soft: #32271A; --out: #CF6F6C; --out-soft: #33211F; } }

• { margin: 0; padding: 0; box-sizing: border-box; }
  body { background: var(--paper); color: var(--ink); font-family: var(--sans); line-height: 1.6; font-size: 16px; }
  .page { max-width: 720px; margin: 0 auto; padding: 3rem 1.25rem 5rem; }

header.masthead { border-bottom: 1px solid var(--line); padding-bottom: 1.75rem; margin-bottom: 2.5rem; }
.meta-row { display: flex; flex-wrap: wrap; gap: .5rem .75rem; align-items: center; margin-bottom: 1rem; }
.badge { font-family: var(--mono); font-size: .72rem; letter-spacing: .06em; padding: .2rem .55rem; border-radius: 3px; text-transform: uppercase; }
.badge.type { background: var(--accent-soft); color: var(--accent); }
.badge.status { border: 1px solid var(--line); color: var(--ink-soft); }
.badge.zone { border: 1px solid var(--warn); color: var(--warn); background: var(--warn-soft); }
h1 { font-family: var(--serif); font-weight: 500; font-size: 2.1rem; line-height: 1.2; letter-spacing: -.01em; text-wrap: balance; margin-bottom: .75rem; }
.standfirst { color: var(--ink-soft); font-size: 1.05rem; max-width: 60ch; }
.links { margin-top: 1rem; font-size: .85rem; display: flex; gap: 1.25rem; flex-wrap: wrap; }
.links a { color: var(--accent); text-decoration: none; border-bottom: 1px solid var(--accent-soft); }

section { margin-bottom: 2.75rem; }
.eyebrow { font-family: var(--mono); font-size: .72rem; letter-spacing: .1em; text-transform: uppercase; color: var(--accent); margin-bottom: .6rem; }
h2 { font-size: 1.25rem; margin-bottom: .75rem; letter-spacing: -.01em; }
h3.phase-head { font-size: 1rem; margin: 1.4rem 0 .5rem; }
p { margin-bottom: .9rem; max-width: 65ch; }
code { font-family: var(--mono); font-size: .85em; background: var(--panel); border: 1px solid var(--line); padding: .08em .35em; border-radius: 3px; }

.before-after { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1.25rem 0; }
@media (max-width: 560px) { .before-after { grid-template-columns: 1fr; } }
.panel { background: var(--panel); border: 1px solid var(--line); border-radius: 6px; padding: 1.1rem 1.2rem; }
.panel h3 { margin-bottom: .6rem; font-size: .78rem; font-family: var(--mono); letter-spacing: .08em; text-transform: uppercase; color: var(--ink-soft); }
.panel.after { border-color: var(--accent); }
.panel.after h3 { color: var(--accent); }
.panel ul { padding-left: 1.1rem; font-size: .92rem; }
.panel li { margin-bottom: .4rem; }

.diagram { margin: 1.5rem 0 2.5rem; }
.diagram svg, .diagram img { display: block; max-width: 100%; height: auto; }
.diagram figcaption { margin-top: .5rem; font-size: .8rem; color: var(--ink-soft); }

.pipeline { display: flex; align-items: stretch; margin: 1.5rem 0; overflow-x: auto; padding-bottom: .5rem; }
.stage { background: var(--panel); border: 1px solid var(--line); border-radius: 6px; padding: .75rem .9rem; min-width: 130px; flex: 1; }
.stage.hot { border-color: var(--accent); background: var(--accent-soft); }
.stage .name { font-family: var(--mono); font-size: .78rem; font-weight: 600; margin-bottom: .25rem; }
.stage .desc { font-size: .78rem; color: var(--ink-soft); line-height: 1.45; }
.arrow { align-self: center; padding: 0 .5rem; color: var(--ink-soft); flex: none; }
.strip-note { margin: -.5rem 0 0; font-size: .8rem; color: var(--ink-soft); }

.decision { border-left: 3px solid var(--accent); padding: .2rem 0 .2rem 1.1rem; margin-bottom: 1.25rem; }
.decision .tag { font-family: var(--mono); font-size: .78rem; font-weight: 700; color: var(--accent); }
.decision p { margin: .3rem 0 0; font-size: .95rem; }
.decision .rejected { color: var(--ink-soft); font-size: .85rem; }
.decision .rejected::before { content: "rejected — "; font-style: italic; }

.scope { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; }
@media (max-width: 560px) { .scope { grid-template-columns: 1fr; } }
.scope .panel.in { border-top: 3px solid var(--accent); }
.scope .panel.outof { border-top: 3px solid var(--out); }
.scope .panel.outof h3 { color: var(--out); }

.vgroup { margin-bottom: 1.6rem; }
.vgroup-head { font-family: var(--mono); font-size: .72rem; letter-spacing: .06em; text-transform: uppercase; color: var(--accent); margin-bottom: .7rem; }
.vlist { list-style: none; }
.vlist li { position: relative; padding-left: 1.9rem; margin-bottom: .55rem; font-size: .92rem; line-height: 1.45; max-width: 66ch; }
.vlist li::before { content: ""; position: absolute; left: 0; top: .18em; width: 15px; height: 15px; border: 1.5px solid var(--ink-soft); border-radius: 4px; }

.question { background: var(--warn-soft); border-left: 3px solid var(--warn); border-radius: 0 6px 6px 0; padding: .8rem 1.1rem; margin-bottom: .75rem; font-size: .95rem; }
.question strong { color: var(--warn); font-family: var(--mono); font-size: .78rem; letter-spacing: .05em; }

.dials { border: 1px solid var(--line); border-radius: 8px; background: var(--panel); padding: 1.15rem 1.3rem; }
.dial { display: grid; grid-template-columns: 118px 1fr; gap: 1rem; align-items: start; padding: .8rem 0; border-bottom: 1px solid var(--line); }
.dial:last-child { border-bottom: none; }
.dial-label { font-family: var(--mono); font-size: .72rem; letter-spacing: .05em; text-transform: uppercase; color: var(--ink-soft); padding-top: .3rem; }
.dial-opts { display: flex; gap: .45rem; flex-wrap: wrap; align-items: center; }
.pill { font-size: .82rem; padding: .32rem .72rem; border-radius: 999px; border: 1px solid var(--line); color: var(--ink-soft); }
.pill.on { border-color: var(--accent); background: var(--accent-soft); color: var(--accent); font-weight: 600; }
.dial-why { flex-basis: 100%; font-size: .8rem; color: var(--ink-soft); margin: .4rem 0 0; }
.dials-note { font-size: .8rem; color: var(--ink-soft); margin: .9rem 0 0; }

footer { border-top: 1px solid var(--line); margin-top: 3rem; padding-top: 1.25rem; font-size: .8rem; color: var(--ink-soft); }
</style>

epic ready zone 1 — substantial

Event-driven RunPane orchestration

Let a supervising agent sleep until something meaningful happens in a pane — wake on meaning, not terminal motion.

supersedes issue #353

TODAY — POLL LOOP orchestrator sleep 45 → poll screen / wait same 30 lines again Pane daemon ready ∧ active conflated agent panels PTY bytes only

  <!-- divider -->
  <line x1="10" y1="110" x2="660" y2="110" stroke="var(--line)"/>

  <!-- AFTER -->
  <text x="10" y="134" fill="var(--accent)" font-weight="700" font-size="11" letter-spacing="1">AFTER — EVENT-DRIVEN</text>
  <rect x="10" y="150" width="150" height="60" rx="6" fill="var(--accent-soft)" stroke="var(--accent)"/>
  <text x="85" y="174" text-anchor="middle" fill="var(--ink)">orchestrator</text>
  <text x="85" y="192" text-anchor="middle" fill="var(--ink-soft)" font-size="10">blocks on await/watch</text>
  <path d="M160 180 H 250" stroke="var(--accent)" fill="none" marker-end="url(#arr-acc)"/>
  <text x="205" y="172" text-anchor="middle" fill="var(--accent)" font-size="10">watch --since</text>
  <rect x="250" y="140" width="180" height="80" rx="6" fill="var(--panel)" stroke="var(--accent)"/>
  <text x="340" y="162" text-anchor="middle" fill="var(--ink)">Pane daemon</text>
  <text x="340" y="180" text-anchor="middle" fill="var(--ink-soft)" font-size="10">semantic state machine</text>
  <text x="340" y="196" text-anchor="middle" fill="var(--ink-soft)" font-size="10">+ cursored event ring</text>
  <text x="340" y="212" text-anchor="middle" fill="var(--ink-soft)" font-size="10">(SQLite for milestones, ph5)</text>
  <rect x="480" y="150" width="180" height="60" rx="6" fill="var(--panel)" stroke="var(--line)"/>
  <text x="570" y="174" text-anchor="middle" fill="var(--ink)">agent panels</text>
  <text x="570" y="192" text-anchor="middle" fill="var(--ink-soft)" font-size="10">transitions, debounced</text>
  <path d="M480 180 H 430" stroke="var(--ink-soft)" fill="none" marker-end="url(#arr-soft)"/>
  <path d="M250 200 H 200 Q 190 200 190 210 V 250 Q 190 260 200 260 H 250" stroke="var(--accent)" fill="none" stroke-dasharray="4 3"/>
  <text x="222" y="278" fill="var(--accent)" font-size="10">agent_idle · input_required</text>
  <text x="222" y="292" fill="var(--accent)" font-size="10">blocked · exited — one JSONL</text>
  <text x="222" y="306" fill="var(--accent)" font-size="10">record per real transition</text>

  <defs>
    <marker id="arr-out" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 z" fill="var(--out)"/></marker>
    <marker id="arr-acc" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 z" fill="var(--accent)"/></marker>
    <marker id="arr-soft" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 z" fill="var(--ink-soft)"/></marker>
  </defs>
</svg>
<figcaption>Today the orchestrator polls screens and re-reads unchanged output; after, it blocks on a cursor-resumable event stream fed by a daemon-side semantic state machine.</figcaption>

01 · Why

Supervision is the remaining bottleneck

#277 / PR #278 made setup reliable (semantic composer submission, no-focus panel creation). But after work starts, a supervising Pane Chat still loops sleep 45; panels screen, re-interpreting unchanged terminal text — and panels wait --for ready returns instantly while the agent is mid-task, because isCliReady latches forever after the CLI's first response.

Research found the foundation is closer than #353 assumed: the daemon socket already broadcasts event frames to every connected client — the CLI clients just discard them. And there is no reusable attention state: unread/notification logic lives renderer-only. So this epic builds the semantic layer in the main process and exposes it as a durable, cursor-resumable event surface. No UI is touched — this is a daemon + CLI change only.

Before

• Arbitrary sleep loops; every poll re-enters model context
• ready conflates "CLI initialized" with "agent done"
• Brief blockers can be missed between polls
• N panels ⇒ N polling loops
• Client restart loses everything observed

After

• One blocking await/watch per supervision scope
• Orthogonal state: terminalReady ≠ agentActivity
• Every transition durably logged with a cursor
• One watch supervises a whole pane, future panels included
• --since <cursor> resumes with no silent loss

02 · Direction

Locked decisions and the phase timeline

<div class="decision">
  <span class="tag">D1 — byte-silence debounce for activity</span>
  <p><code>active</code>/<code>idle</code> derives from PTY-output silence with a configurable debounce (longer than today's fixed 30s). It generalizes to any agent with zero per-agent adapters. <strong>Empirically validated:</strong> PTY probes (2026-07-21) show Claude Code and Codex both emit zero bytes for 150s+ at the idle composer and emit continuously while working. Remaining limitation, stated in the contract: silent thinking past the debounce reads as a false idle (mitigated by configurable debounce + D9 reconciliation).</p>
  <p class="rejected">screen-aware per-agent adapters as the base signal — may later <em>refine</em>, never load-bearing.</p>
</div>
<div class="decision">
  <span class="tag">D2 — watch is the primitive, wait is frozen</span>
  <p><code>panels watch</code> (JSONL subscription) is the core; <code>await</code>/<code>await-any</code> are exit-on-first-match sugar. <code>panels wait</code> keeps its polling semantics untouched.</p>
  <p class="rejected">extending <code>panels wait</code> (conflates polling predicates with semantic events); a new <code>orchestrate</code> command group.</p>
</div>
<div class="decision">
  <span class="tag">D3 — one global cursor over an in-memory event ring</span>
  <p>A daemon-scoped monotonic cursor over a bounded in-memory ring; reconnect recovery is snapshot-then-subscribe (<code>panes status --changed-since</code> returns a race-free cursor). App restart kills every PTY, so pre-restart lifecycle events describe dead processes — recovery is a fresh snapshot, not replay; stale cursors get a structured <code>cursor_expired</code>. The durable SQLite table arrives only in phase 5, where milestones (the one replay-shaped payload) land. Lifecycle and output cursors stay separate namespaces.</p>
  <p class="rejected">SQLite-persisted lifecycle log upfront — schema migration + retention pruning for replay no orchestrator decision needs; per-pane cursor scopes.</p>
</div>
<div class="decision">
  <span class="tag">D4 — main process becomes the orchestrator-facing canonical layer</span>
  <p>Semantic transitions are computed in main. Two attention truths coexist during this epic (renderer human-facing vs main-process orchestrator-facing) — accepted: the smarter semantic layer is the safe default the orchestrator consumes, with the dumb reliable signal (raw <code>activityStatus</code> + pull polling) as fallback. Renderer migration onto the canonical layer is a named follow-up ticket.</p>
  <p class="rejected">borrowing renderer unread/notification state — it's renderer-only, unreachable from the daemon.</p>
</div>
<div class="decision">
  <span class="tag">D5 — milestones are claims, never authority</span>
  <p>Agent-emitted milestone events are namespaced, versioned, producer-labeled, and explicitly unverified. They never authorize merge/deploy/release/publish.</p>
</div>
<div class="decision">
  <span class="tag">D6 — interstitials: allowlist or ask</span>
  <p>Only explicitly allowlisted, reversible responses may be auto-handled, under caller opt-in. Auth, permissions, destructive confirmations, terms, payments → always <code>input_required</code>.</p>
</div>
<div class="decision">
  <span class="tag">D7 — additive, parity-kept</span>
  <p>Existing commands and JSON contracts keep working; npm CLI, daemon schema, generated contracts, and Python wrapper stay in parity; stdout stays machine-clean.</p>
</div>
<div class="decision">
  <span class="tag">D8 — pull remains first-class</span>
  <p>Everything <code>watch</code>/<code>await</code> can observe is also readable request/response: <code>panels screen</code>/<code>wait</code> carry the new state block, <code>panes status --changed-since</code> is the canonical pull reconciliation. An orchestrator can always poll — by preference, or when the event path is unavailable.</p>
  <p class="rejected">event subscription as the sole observation path — a broken stream would leave supervision blind.</p>
</div>
<div class="decision">
  <span class="tag">D9 — long waits self-check via heartbeat reconciliation</span>
  <p>An <code>await</code>/<code>watch</code> that has received no events for a configurable heartbeat interval (minutes, well under the timeout) internally pulls current state and reconciles against the event log — a missed event, wedged stream, or dead panel resolves the wait or surfaces a structured error instead of hanging to timeout. The pattern Claude Code's own monitors use.</p>
  <p class="rejected">trusting push delivery alone until timeout expiry — turns a dropped event into a full-timeout stall.</p>
</div>

<div class="pipeline">
  <div class="stage hot"><div class="name">1 · state model</div><div class="desc">orthogonal fields, configurable debounce — M</div></div>
  <div class="arrow">&#8594;</div>
  <div class="stage"><div class="name">2 · events + watch</div><div class="desc">event ring, cursors, single-panel watch/await — L</div></div>
  <div class="arrow">&#8594;</div>
  <div class="stage"><div class="name">3 · multi-target</div><div class="desc">await-any, pane watch, status snapshot — M</div></div>
  <div class="arrow">&#8594;</div>
  <div class="stage"><div class="name">4 · verified start</div><div class="desc">start-agent + safe interstitials — M</div></div>
  <div class="arrow">&#8594;</div>
  <div class="stage"><div class="name">5 · milestones+</div><div class="desc">events emit, warnings, output --since — M</div></div>
</div>
<p class="strip-note">Binding phase sequence — one PR, phases commit in order. Phases 3, 4, 5 all depend only on 2; phase 4 prefers the standalone slash-command ticket landed first.</p>

03 · Scope

Goals vs non-goals

Goals

• Block on one command until idle / input-required / blocked / exited
• Supervise many panels (incl. future ones) with one watch
• Resume from a cursor with no silent event loss
• Creation verifies the prompt actually submitted and work began
• Payloads compact enough for dozens of panels
• Everything push-observable is also pull-readable — polling stays a supported fallback

Non-goals

• Encoding SDLC policy in RunPane — skills interpret events
• Auto-approving irreversible actions
• Replacing panels screen/output inspection
• Per-agent screen adapters as a base requirement
• Remote hosted event service — local daemon only

Peeled out as standalone tickets with their own PRs: declarative pane pinning and slash-command-aware prompt submission. Neither blocks phases 1–3.

04 · Verification

What we'll prove, per phase

All backend/CLI — every criterion is proven by automated main-process integration tests plus the extended npm/Python contract-parity suite. Highlights below; full EARS criteria live in item.md.

<h3 class="phase-head">Phase 1 — semantic state model</h3>
<div class="vgroup">
  <ul class="vlist">
    <li>AC1 — first CLI response + still streaming ⇒ <code>terminalReady: true</code> AND <code>agentActivity: "active"</code> as distinct fields</li>
    <li>AC2 — silence past the debounce ⇒ <code>idle</code> + <code>lastMeaningfulEventAt</code> recorded</li>
    <li>AC3 — debounce configured to N ⇒ transition at N, not the old fixed 30s</li>
    <li>AC4 — process exit ⇒ <code>agentActivity: "exited"</code></li>
  </ul>
</div>

<h3 class="phase-head">Phase 2 — events, cursors, watch/await</h3>
<div class="vgroup">
  <ul class="vlist">
    <li>AC1 — <code>await --event agent-idle</code> stays blocked while ready-but-active (the #353 regression case)</li>
    <li>AC2 — one JSONL record per transition: ID, cursor, type, timestamp, pane/panel IDs, compact state, no screen text</li>
    <li>AC3 — unchanged state ⇒ zero records</li>
    <li>AC4 — <code>--since</code> replays retained events in order; duplicates identifiable by event ID</li>
    <li>AC5 — expired cursor ⇒ structured <code>cursor_expired</code> with earliest available cursor</li>
    <li>AC6 — a pre-restart cursor gets a structured <code>cursor_expired</code> pointing at snapshot reconciliation, never a silent empty stream</li>
    <li>AC7 — a suppressed/stalled event stream still resolves the wait via heartbeat reconciliation, result marked as reconciled</li>
    <li>AC8 — timeout is a result, not a failure: <code>timedOut: true</code> + current reconciled state + a distinct documented exit code</li>
  </ul>
</div>

<h3 class="phase-head">Phase 3 — multi-target + reconciliation</h3>
<div class="vgroup">
  <ul class="vlist">
    <li>AC1 — any of N panels transitioning identifies which panel</li>
    <li>AC2 — panel created inside a watched pane joins the stream without restart</li>
    <li>AC3 — <code>panes status --changed-since</code> lists only changed panels + a gap-free snapshot cursor</li>
  </ul>
</div>

<h3 class="phase-head">Phase 4 — verified startup + interstitials</h3>
<div class="vgroup">
  <ul class="vlist">
    <li>AC1 — <code>ok: true</code> only with <code>verifiedSubmitted: true</code> and activity begun</li>
    <li>AC2 — composer still holding text after bounded retries ⇒ <code>submission_unverified</code> blocker + attempt count</li>
    <li>AC3 — allowlisted interstitial handled ⇒ listed in response, original prompt submitted exactly once</li>
    <li>AC4 — unknown interstitial ⇒ stop with <code>input_required</code>, regardless of flags</li>
  </ul>
</div>

<h3 class="phase-head">Phase 5 — milestones, warnings, output</h3>
<div class="vgroup">
  <ul class="vlist">
    <li>AC1 — emitted milestone carries namespace, schema version, producer, unverified trust marker</li>
    <li>AC2 — auth-warning text + agent still working ⇒ <code>blocking: false</code>, no <code>blocked</code> event</li>
    <li>AC3 — unchanged warning ⇒ no re-emission</li>
    <li>AC4 — <code>output --since</code> returns only rows after the cursor</li>
  </ul>
</div>

05 · Unresolved

Open questions

OQ1 — Which stream panels output --since reads: session_outputs rows or serialized scrollback (they are not 1:1). Resolve before phase 5.

OQ2 — Default idle-debounce value and its config surface. Resolve during phase 1 planning.

06 · Run config

How /do will run this

Zone

0123

System-shaping local-tool change; phase 5's milestone table migration trips the schema/migration escalator floor (zone 1 minimum). Not zone 0 — no direct production user/data/money surface.

Derived

epic = full machineryfull dossiercap 3/3single lane — Codexfrontend verifier: n/a (no UI)

Per zones.md epic override: dossier + cap 3 always; lanes follow the zone (single Codex at zone 1). review_lanes: stays human-editable on the tracker until /do runs.

Estimated by /create-epic from stakes + consequence radius; dials derive from references/zones.md. You set the final zone at capture.

zone 1 — substantial · Generated by /create-epic · This page is the alignment surface; item.md remains the contract /do executes against.

[parsakhaz]

Dogfood observation for the epic (2026-07-22, runpane 2.4.30): while orchestrating #357/#358, panels screen --limit 60 returned screen.text of 0 chars for a live, never-focused background panel (claude process running, activityStatus: idle, isCliReady: true). Persisted output history held only the first 15 CRLF bytes. A supervising agent had no working observation channel for a hidden panel — submission had to be verified via OS process inspection and ~/.claude/projects transcript existence.

Relevant to phase 1/D8 (pull-readable state must actually work for background panels) and to the D9 heartbeat: reconciliation that pulls an empty screen would be as blind as the event path it backstops. Background-panel screen hydration deserves a regression fixture in phase 1.

[parsakhaz]

Postmortem — 356 (ops-only)

Postmortem — 356 (ops-only)

Run operations (always)

Wall-clock span: 2026-07-22 20:45 → 2026-07-23 07:46 UTC = 661 min (11.0 h), 561 transcript events.
Human-idle: ~0 min (0.0%). Only three human messages arrived all run, each answered within seconds. Post-completion idle: 0 — the run ended on its own output.

On the waiting axis this run was effectively fully autonomous. The interesting failures are elsewhere: one autonomy leak that happened to cost nothing, and one hung dispatch that cost 25 minutes.

Per-step timing

Step / dispatch	Start	Dur	Tokens	Note
Preflight + load (gh, deps, item, artifacts)	20:45	~8m	—	branch reset to origin/main; 3 artifacts harvested
code-researcher · phase 1	13:48	6m	124,474	full-lane dossier
plan-1 authoring (overseer)	13:55	~13m	—
plan-reviewer · p1 pass 1	14:18	8m	98,461	6 Must Fix
plan-reviewer · p1 pass 2	14:26	8m	98,197	3 Must Fix
plan-reviewer · p1 pass 3	14:33	7m	89,236	1 Must Fix
implementer · phase 1	14:18	10m	191,059
backend-verifier · phase 1	14:30	3m	78,555	all 4 ACs pass
code-reviewer · p1 pass 1	14:34	6m	131,473	2 Must Fix
implementer · p1 fix 1	14:39	7m	+153,919
code-reviewer · p1 pass 2	14:47	6m	129,150	0 Must Fix — loop exits
commit 9626f77 (phase 1)	14:51
code-researcher · phase 2	14:52	9m	179,786	ran parallel with commit
plan-2 authoring (overseer)	15:00	~18m	—
plan-reviewer · p2 pass 1	15:00	25m	unknown	⚠️ HUNG — killed manually, output lost
plan-reviewer · p2 pass 1b	15:20	7m	76,940	9 Must Fix
plan-reviewer · p2 pass 2	15:27	7m	116,351	8 Must Fix
plan-reviewer · p2 pass 3	15:34	7m	129,760	3 Must Fix
implementer · phase 2	15:41	26m	415,009	largest single dispatch
commit 96e8bd6 (phase 2)	16:29
code-researcher · phases 3-5	16:11	9m	142,423	overlapped phase-2 implementer
plan-3 authoring (overseer)	16:20	~15m	—	compressed plan, owner scope change
plan-reviewer · p3 pass 1 (only)	16:49	6m	74,110	4 Must Fix
implementer · phase 3+4	16:53	15m	281,560	Group C cut
implementer · p3 AC-tests	17:10	7m	+154,360	exposed 2 real bugs
backend-verifier · final	17:18	3m	71,323	1 fail (order-dependent)
code-reviewer · final pass 1	17:18	4m	181,733	4 Must Fix, 2 security
implementer · fix round 2	17:24	6m	+86,861
code-reviewer · fixscope 1	23:56	4m	120,674	2 Must Fix, 2 security
implementer · fix round 3	00:03	6m	+230,630
code-reviewer · fixscope 2	00:12	3m	118,357	3 Must Fix, 2 security
implementer · fix round 4 (centralize)	00:17	17m	+174,278	CreateInputGuard
code-reviewer · fixscope 3	00:35	5m	161,889	1 Must Fix, 1 security
implementer · fix round 5	00:44	6m	+84,212
Build gate, rebase, push, PR	00:50	~12m	—	PR #363

Aggregates. Phase 1 ≈ 62 min (9%). Phase 2 ≈ 97 min (15%), plus 25 min lost to the hung dispatch. Phases 3+4 including five security fix rounds ≈ 200 min (30%). Overseer authoring/turnaround between dispatches ≈ 165 min (25%) — the single largest non-dispatch cost, dominated by writing and revising three plans by hand.

gantt
  title Epic 356 — dispatch timeline (parallelism vs serialization)
  dateFormat HH:mm
  axisFormat %H:%M
  section Phase 1
  research            :13:48, 6m
  plan review x3      :14:18, 22m
  implement           :14:18, 10m
  verify + review x2  :14:30, 23m
  section Phase 2
  research            :14:52, 9m
  plan review HUNG    :crit, 15:00, 25m
  plan review x3      :15:20, 21m
  implement           :15:41, 26m
  section Phase 3+4
  research (overlap)  :16:11, 9m
  plan review x1      :16:49, 6m
  implement           :16:53, 15m
  AC tests            :17:10, 7m
  section Security fix loop
  review 1 + fix      :17:18, 12m
  review 2 + fix      :23:56, 13m
  review 3 + fix      :00:12, 22m
  review 4 + fix      :00:35, 15m

Loading

Stalls (autonomy leaks), ranked

1. One turn-end needing a "continue" nudge, at ~06:35 local, immediately before the scoped security re-review. The overseer ended its turn with work remaining and did not schedule a self-wakeup. Cost was ~0 min only because the human happened to be present; overnight this would have stalled indefinitely. This is the single most important operational finding — the /do skill's own rule ("ending a turn with work remaining requires a ScheduleWakeup") was violated by its own overseer.
2. Hung Codex dispatch, ~25 min lost. The plan-reviewer phase-2 pass-1 dispatch ran past its 900 s watchdog and had to be killed by hand; its output was lost and the pass re-run from scratch. Root cause below.

Blocker inventory

• AskUserQuestion gates: 0. No red-tier gate was hit; no production surface, no schema change, no secrets.
• Rate-limit hits: 0.
• Legitimate background waits: 24 Codex dispatches, ~3.5 h of productive dispatch time — not leaks.
• Mid-run human input: 2 owner scope messages (base-branch correction; phase compression). Both were genuine input answered inline, not stalls.
• Tooling failures: 1 (the hung dispatch); 1 timeout binary absent on macOS, worked around inline.

The single change that would have removed the biggest stall

Fix the watchdog in the codex skill. Its documented launcher is
perl -e 'alarm shift; exec @ARGV' 900 codex exec … — but exec replaces the Perl process with Node, and the pending SIGALRM never fires against it, so the watchdog is silently inert. Every hung dispatch in the fleet runs unbounded until a human notices. Replacing it with a background-kill watchdog (which this run switched to mid-flight, with no further hangs across 14 subsequent dispatches) removes the failure class entirely.

What we asked for

Epic #356: an event-driven supervision surface for RunPane so a long-lived orchestrator can block until something meaningful happens instead of polling — five phases, zone: 1, one PR.

Outcome vs intended

Deferred to the human's PR review. Phases 1–4 shipped with all fifteen of their ACs proven by named tests; phase 5 (four ACs) was cut under an owner-directed compression with an explicit priority order that anticipated exactly this. The compression was the owner's call mid-run, so "fell short" is not the right frame — but whether the shipping subset is the right subset is theirs to judge at #363.

Why the gap happened

Omitted — operational-only postmortem. The outcome half runs after the human reviews #363.

What to change so it doesn't recur

1. Fix the Codex watchdog (highest value — silent failure across every run)

dcouple/orchestra → claude/skills/codex/SKILL.md, step 2 launcher.

-#!/usr/bin/env bash
-perl -e 'alarm shift; exec @ARGV or die "exec failed: $!"' <cap> \
-  codex exec -m gpt-5.6-sol -c model_reasoning_effort="<effort>" --yolo \
-  [--ephemeral] --skip-git-repo-check -C <repo root> \
-  -o <owner dir>/<name>.md "$(cat <owner dir>/<name>.prompt)" </dev/null
-status=$?
+#!/usr/bin/env bash
+# NOTE: `perl -e 'alarm N; exec ...'` does NOT work — exec replaces Perl with
+# Node and the pending SIGALRM never fires, leaving the dispatch unbounded.
+codex exec -m gpt-5.6-sol -c model_reasoning_effort="<effort>" --yolo \
+  [--ephemeral] --skip-git-repo-check -C <repo root> \
+  -o <owner dir>/<name>.md "$(cat <owner dir>/<name>.prompt)" </dev/null &
+cpid=$!
+( sleep <cap>; kill -9 $cpid 2>/dev/null ) &
+wpid=$!
+wait $cpid; status=$?
+kill $wpid 2>/dev/null

2. Make the self-wakeup rule mechanical, not advisory

dcouple/orchestra → claude/skills/do/SKILL.md, Autonomy & safety.

 - **A phase or step boundary is not a turn boundary.** …
+  **Mechanical check before ending any turn:** if a dispatch is outstanding, or
+  any plan/phase checkbox is unticked, the turn MUST end with a `ScheduleWakeup`
+  call in the same message. Ending a turn with neither the run complete nor a
+  wakeup scheduled is a pipeline defect, not a judgment call — an overseer that
+  "expects to continue immediately" is exactly the case that stalls overnight.

3. Give the code-reviewer an explicit "enumerate the call sites" instruction for safety-critical invariants

dcouple/orchestra → claude/agents/code-reviewer.md.

Four consecutive review passes each found a D6 bypass in a different create-time write path. Each reviewer verified the paths it was pointed at and stopped; none asked "what is the complete set of paths that can reach a PTY write?". The fix only converged when the overseer ordered centralization.

+## Invariant-shaped findings
+
+When a finding is an invariant that must hold on EVERY path ("never write
+without classifying", "never emit twice", "always hold the lock"), do not stop
+at the path you were shown. Enumerate the complete set of call sites that can
+reach the guarded operation, list them in the report, and state for each whether
+it is guarded. If the set cannot be enumerated from the code, say so — that
+unenumerability IS the finding, and the fix is a chokepoint, not another patch.

4. Have the implementer's charter forbid tests that fabricate the state under test

dcouple/orchestra → references/agents/implementer/instructions.md.

Three separate tests in this run asserted around their own behaviour: one fabricated both initialInputSentAt and an already-active snapshot to "prove" verified startup; another chose staged/interstitial strings that the buggy global-replacement implementation would also have passed. Each was caught by review, but only after shipping through a verifier.

+## Tests must be able to fail
+
+A test that fabricates the state it claims to verify proves nothing. Before
+writing an assertion, ask: would this test FAIL against the pre-fix code? If it
+would pass either way, it is not a regression test. Specifically: do not
+hand-construct the snapshot/flag that the code under test is supposed to derive;
+drive the real callback and let the code produce it. When a fix is about
+ordering, the test must exercise the ordering.

5. Record that plan-review yield stays high through pass 3 on large phases

dcouple/orchestra → references/zones.md, The record.

Phase 2's plan needed all three passes and yielded 9 / 8 / 3 Must Fixes — no pass was wasted. This is evidence against trimming plan-review caps at zone 1 for large phases, and worth recording before some future tuning pass lowers them.

Dial record & right-sizing

Dial	Value
zone	1 (epic — full machinery, no escalation)
review lanes	single (Codex)
plan passes	phase 1: 3/3 · phase 2: 3/3 (+1 hung) · phase 3: 1/1 (owner-compressed)
plan Must Fixes	phase 1: 6/3/1 · phase 2: 9/8/3 · phase 3: 4
post-impl review passes	phase 1: 2 · final diff: 4
post-impl Must Fixes	phase 1: 2 → 0 · final: 4 → 2 → 3 → 1 (all security)
verifiers	backend ×2; frontend-verifier not run (no UI surface)
QA pass	command-shaped only
wall-clock	661 min (11.0 h), ~0% human-idle
pr_size	40 files, +5855 / −132
tokens — Codex	≈ 3.89 M (implementer 1.77 M · code-reviewer 843 k · plan-reviewer 683 k · code-researcher 447 k · backend-verifier 150 k) + 1 hung dispatch unknown
tokens — main loop	output 237 k · cache read 51.6 M · cache write 840 k · input 4 k
spend_ratio	≈ 690 tokens per changed line

Agents roster: code-researcher (gpt-5.6-sol/low, ×3), plan-reviewer (medium, ×7), implementer (medium, ×9 across 3 sessions), code-reviewer (medium ×5, high ×1), backend-verifier (low, ×2). 24 dispatches total.

Judgment: review effort was right-sized, arguably underdone. Every single review pass — 7 plan, 6 code — returned Must Fixes; not one was pure spend. The final security loop is the proof: passes returning 4, 2, 3 and 1 Must Fixes, each a genuine bypass in a path the previous pass had not examined. Had the cap been enforced at 3, the run would have shipped the pass-4 bypass, in which a create timing out before CLI-ready would blindly type into a directory-trust prompt. The dial that would have changed this outcome is the post-PR loop cap — and the right lesson is not "raise the cap" but the code-reviewer charter change above (proposal 3): the cap was never the binding constraint, the reviewers' path-at-a-time framing was.

Acceptance

Still awaiting human review — PR #363 is open and labelled awaiting-human-review.

System changes

Comment URLs recorded below on publish. Approval verdicts pending — this postmortem was auto-run at wrap-up and does not wait for them.

[parsakhaz]

Deferred work from this epic is tracked in #364 — the whole of original phase 5 (panels events emit milestones, warning severity separation, panels output --since), plus the deliberately-cut idempotent panes create retry, the renderer-notification migration owed by D4, and wiring the new wrapper test suite into CI.

Recorded there so it survives this issue closing when #363 merges.