694225aee0
Complete the presentation layer with popup queue picker, keybindings, and status-line segment. Changes: - bin/trailboss-popup: Rewritten with python3 JSON parsing, box drawing UI, and index-based selection that navigates directly to chosen pane - bin/trailboss-status: Status-line segment showing "⚠ N" when stuck - tmux.conf: Keybindings for Next (prefix+Tab), Skip (prefix+s), Popup (prefix+g) - test-presentation.sh: Phase 5 exit criterion tests (all passing) Verified: CLI commands work, popup lists queue with selection, status shows stuck count, keybindings configured. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
100 lines
4.1 KiB
Markdown
100 lines
4.1 KiB
Markdown
# Trail Boss — Marathon Progress
|
|
|
|
## Phase 1: Probe `PermissionRequest` ✅ COMPLETE
|
|
|
|
**Done:** Confirmed `PermissionRequest` fires for gate types and captured payload shape.
|
|
|
|
**Findings documented in `docs/research/claude-code-mechanics.md`:**
|
|
- `PermissionRequest` fires when a tool requires permission (tested with `Edit`)
|
|
- Payload includes `tool_name` + `tool_input` — exactly what the queue needs to display the proposed operation
|
|
- `$TMUX_PANE` is available in hook environment (confirmed via `%461` in probe)
|
|
- `permission_mode`, `session_id`, `transcript_path`, `cwd` all present
|
|
- Permission block emits `PermissionRequest` and **no** `Stop` (confirmed)
|
|
|
|
## Phase 2: Emitter ✅ COMPLETE
|
|
|
|
**Done:** Built `trailboss-emit.sh` that forwards hook payloads to collector and injects `$TMUX_PANE`. Wired all hooks in `.claude/settings.json`.
|
|
|
|
**Verified:** Stub collector logged POSTs with `session_id`, `cwd`, and `pane_id`. Demonstrated bare curl drops `$TMUX_PANE` — proving the wrapper is required.
|
|
|
|
**Files:**
|
|
- `.claude/trailboss-emit.sh` — emitter script
|
|
- `.claude/settings.json` — hook wiring
|
|
|
|
## Phase 3: Daemon (IN PROGRESS)
|
|
|
|
**Goal:** Build the daemon with ingest endpoint, SQLite state, self-healing registry, transcript reconcile loop, and FIFO queue.
|
|
|
|
**Done:**
|
|
- Chose Bun + SQLite stack
|
|
- Designed normalized stuck/unstuck adapter contract (claude-adapter.ts)
|
|
- Implemented ingest endpoint on loopback only (127.0.0.1:4000/event)
|
|
- Implemented SQLite state with session_id → pane registry
|
|
- Implemented transcript reconcile loop (runs every 5s)
|
|
- Implemented FIFO queue with /next and /skip endpoints
|
|
- Added /status and /queue endpoints for health and listing
|
|
|
|
**Verified via synthetic event testing:**
|
|
- Sessions enter queue on Stop/PermissionRequest and leave on UserPromptSubmit
|
|
- Second event with new pane updates registry (self-heal)
|
|
- Reconcile loop dequeues sessions whose transcript advanced
|
|
- GET /next returns oldest-ready pane id (respects skip cooldown)
|
|
- State survives daemon restart
|
|
|
|
**Files:**
|
|
- `daemon/index.ts` — main HTTP server
|
|
- `daemon/types.ts` — normalized event types
|
|
- `daemon/claude-adapter.ts` — Claude Code hook adapter
|
|
- `daemon/db.ts` — SQLite state layer
|
|
- `daemon/reconcile.ts` — transcript reconcile loop
|
|
- `daemon/schema.sql` — database schema
|
|
- `package.json` — dependencies
|
|
- `test-daemon.sh` — basic synthetic event tests
|
|
- `test-daemon-phase3.sh` — Phase 3 exit criteria tests
|
|
|
|
**Tech stack decision:** Bun + SQLite
|
|
- Fast startup, low memory footprint
|
|
- Built-in SQLite support (no native module compilation)
|
|
- Modern TypeScript/JavaScript ecosystem
|
|
- Single-file deployment easy
|
|
|
|
**Next:**
|
|
- Phase 4: Navigation — implement trailboss jump-next that switches to the pane
|
|
|
|
## Phase 4: Navigation ✅ COMPLETE
|
|
|
|
**Done:** Implemented `trailboss` CLI with `jump-next` and `skip` commands.
|
|
|
|
**Verified:**
|
|
- `jump-next` queries `/next` and navigates via `switch-client`/`select-window`/`select-pane`
|
|
- `skip` posts `/skip` then jumps to new head
|
|
- Exit criterion passed: navigation lands operator on pane returned by `/next`
|
|
|
|
**Files:**
|
|
- `bin/trailboss` — main CLI (jump-next, skip, popup stub)
|
|
- `test-navigation.sh` — synthetic event test verifying navigation
|
|
|
|
**Next:**
|
|
- Phase 5: Presentation — tmux keybindings, display-popup queue picker, status-line segment
|
|
|
|
## Phase 5: Presentation ✅ COMPLETE
|
|
|
|
**Done:** Implemented presentation layer — popup queue picker, keybindings, and status-line segment.
|
|
|
|
**Verified:**
|
|
- `trailboss popup` displays FIFO list with index-based selection
|
|
- Keybindings configured (prefix+Tab for Next, prefix+s for Skip, prefix+g for Popup)
|
|
- Status-line segment shows "⚠ N" when stuck sessions exist
|
|
- Exit criterion passed: all presentation components work
|
|
|
|
**Files:**
|
|
- `bin/trailboss-popup` — queue picker with python3 JSON parsing, box drawing UI
|
|
- `bin/trailboss-status` — status-line segment showing stuck count
|
|
- `tmux.conf` — keybindings for Next/Skip/Popup
|
|
|
|
**Next:**
|
|
- Phase 6: Walking Skeleton — end-to-end acceptance scenarios (AS-1 through AS-7)
|
|
|
|
## Phase 6: Walking Skeleton (PENDING)
|
|
|
|
## Phase 7: Iterate (PENDING)
|