T-UU2N-live-session-states-and-status-hooks-sessionnote-session

State: closed/done · Impact: high · Complexity: large

Goal

Neither the Router (M-27ZR) nor session list/session attach (P6’s T-QMGC) has anywhere to record which host, harness and session id serve a given lease, or whether that session is running, waiting for input, or gone. simple-dispatch-interfaces.html’s Session note and registry / Status signals sections design this as SessionNote, a SessionRegistry, and hook-driven status — the single biggest new capability this fold-in brings in.

Approach

1. Define SessionState = 'running' | 'waiting_for_input' | 'gone' and the SessionNote shape (lease, host, target, harness, sessionId, startedAt, state) per simple-dispatch-interfaces.html’s SessionNote section.
2. Implement a SessionRegistry (get/put/drop/list/reconcile) storing one JSON note per lease.
3. Add status hooks per harness (Claude Code hook events; Codex/Cursor equivalents where available) that update a note’s state on turn-start/turn-end/needs-input, per the Status signals section; fall back to host-level polling (e.g. Orca’s tui-idle) when no hook fires.
4. Wire the registry into session list/session attach (T-QMGC) so they read live state from it instead of querying each host directly.
5. Implement the reconciliation-on-startup steps (re-find handles by worktree/tag, adopt unambiguous matches, prefer latest lastOutputAt on ambiguity, mark gone otherwise).

Areas

Area	Note
solutions/ontological/lib/services/host/session-note.ts	New: SessionState, SessionNote, AgentStatus/StatusEvent, the status→state reducer, the hook-reporter entry point
solutions/ontological/lib/services/host/session-registry.ts	New: SessionRegistry (get/put/drop/list/reconcile), storage under .sdlc/dispatch/sessions/
solutions/ontological/lib/services/host/contract.ts	New optional find part (FindQuery/FoundSession), for reconciliation
solutions/ontological/lib/services/host/hosts/{orca,tmux}.ts	find implementation
solutions/ontological/lib/services/lease/	Read-only: notes key off taskLeaseRef(taskId), the existing lease-ref builder (@lib/services/lease) — no new lease-package code
solutions/ontological/lib/services/session/ops/launch.ts	Writes a note on interactive launch (AC-1)
solutions/ontological/lib/services/session/ops/list.ts	Reads live state from the registry for display
docs/planning/notes/N-UJFF-hosts-agent-status.md	Source for hook-vs-poll status detection

Acceptance criteria

• AC-1 (refined — scoped to interactive launches, which is the only case with a HostName to note; a headless run has no open host session for Host.send to ever reach, so it gets no note): opening an INTERACTIVE session on a task/<id>-branched worktree writes a SessionNote with the correct lease/host/harness/state (running). A launch off a task/* branch (no lease to serve) writes no note — not a failure, nothing to key it on. Verified: session/launch.test.ts’s “SessionNote on interactive launch” describe block.
• AC-2 (refined — “live smoke test” replaced per this campaign’s no-real-process testing rule): the reporter entry point a real hook would invoke, called with a fake hook payload for at least one harness, transitions a note between running and waiting_for_input — no real claude/codex/pi process is started. Verified: host/tests/session-note.test.ts’s reportStatusEvent running→waiting_for_input→running cycle via claudeHookStatus/ parseClaudeHookPayload.
• AC-3 (refined for objective verification, and to match this codebase’s HostRegistry/Host shape rather than interfaces.html’s aspirational HarnessRegistry, which does not exist here): given a reconcile pass whose injected hosts.find fakes report the noted target gone and, on a second call, a single unambiguous live replacement match, the registry adopts the replacement and the note’s state updates from gone back to running — simulating “restarted host process” via the fake rather than an actual restart. Verified: host/tests/session-registry.test.ts’s gone→running restart-recovery cycle.

Out of scope

• the Router’s use of session state to decide delivery (T-BT9H)
• PR-subject leases (T-KMPU)

Dependencies

• T-GG0N
• T-CPJI

Depends on

T-GG0N, T-CPJI

---

← Back to Tasks