- Add comprehensive schema documentation in docs/notes/normalized-event-schema.md
- Define all four event types: StuckEvent, UnstuckEvent, SessionRegistered, SessionEnded
- Specify required/optional fields, data types, validation rules for each event type
- Add examples for each event type from different sources (Claude Code hooks, tmux detector)
- Document type guards, error handling, and usage patterns
- Enhance code comments in daemon/types.ts with validation rules and references
- Update tmux-detector.ts NormalizedEvent type to match stricter type definitions
Co-Authored-By: Claude <noreply@anthropic.com>
Update test results section to accurately reflect tb-1me findings:
- Correct failure type from 'unstuck_timeout' to 'pane_id_mismatch'
- Document root cause: multi-server discovery (test isolation issue, not detector bug)
- Update recommendations to address actual isolation problem
- Conclusions remain: detector works correctly, test needs better isolation
The detector is designed to discover opted-in panes across all tmux
servers, which is the correct production behavior. Test failed because
it isolated the test server but the detector also found panes from the
main tmux server.
Co-Authored-By: Claude <noreply@anthropic.com>
- Add comprehensive test methodology section (5-run acceptance test)
- Report execution time metrics: avg 55.2s, min 54s, max 56s, std dev 0.84s
- Document 100% detection accuracy with no false positives/negatives
- Analyze unstuck_timeout failure mode (test infrastructure race condition)
- Conclude detector core functionality works correctly
- Add production recommendations and raw data references
Co-Authored-By: Claude <noreply@anthropic.com>
Key findings:
- Detector accuracy: EXCELLENT (0 false positives, 0 false negatives)
- Stuck detection: 100% success rate (detects within 30s threshold)
- Unstuck detection: 100% success rate (detects within 1-2s of activity)
- Test failures are due to queue/dequeue integration issue, NOT detector accuracy
- Queue entries persist after unstuck detection - daemon/dequeue logic needs fix
Analyzed 10 test runs across 3 test sessions:
- 2 runs: tmux list failures (infrastructure issue)
- 1 run: daemon 404 errors (endpoint issue)
- 6 runs: unstuck_timeout but detector correctly detected unstuck (queue issue)
The test classification as 'false negative' in CSV files is incorrect -
detector correctly identified both stuck and unstuck states.
Co-Authored-By: Claude <noreply@anthropic.com>
Document the POST /event/normalized endpoint contract with:
- Complete endpoint specification (URL, method, request/response)
- All 4 event types with field descriptions and examples
- Derivation guide for sessionId, paneId, cwd, transcriptPath from harness context
- Implementation example for adapter authors
- Error handling and versioning guidance
This enables future adapter authors to integrate any coding harness
without reading the daemon source code.
Resolve open questions from the design session:
- Stuck is stuck: no permission-vs-stopped priority; reason is display-only;
queue is a flat FIFO dead-letter queue (Stop AND PermissionRequest still
both required — permission blocks emit no Stop)
- Drop Notification entirely
- Auto-advance depletion loop: next stuck session loads on resolve/skip;
saturation is a non-issue by construction
- New primary open question: harness-coupled detection vs harness-agnostic
core, via a normalized stuck/unstuck adapter contract (switching is already
tmux-level/harness-agnostic)
- Reboot: operator re-invokes manually (no auto-resurrection in v1)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Single-pane attention router for interactive AI coding agents: stuck sessions
surface in one prioritized queue (most-stuck first) via Claude Code hooks, and
your reply is delivered back into the exact session.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
