trail-boss/PROGRESS.md

# 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 ✅ COMPLETE

**Done:** All 7 acceptance scenarios pass end-to-end.

**Verified:**
- `test-walking-skeleton.sh` passes all scenarios (AS-1 through AS-7)
- AS-1: Single permission block — enqueue, navigate, approve, dequeue
- AS-2: FIFO ordering — session A before B, depletes oldest-first
- AS-3: Answered-in-pane reconcile — transcript advance dequeues without UI action
- AS-4: Dropped-event recovery — collector down during Stop, reconcile rebuilds queue
- AS-5: Skip + cooldown — skip moves to tail, cooldown makes queue empty until expiry
- AS-6: No forced focus-steal — resolving a session does NOT auto-switch client
- AS-7: Pane reuse regression — new session in old pane: navigation targets current owner

**Files:**
- `test-walking-skeleton.sh` — comprehensive acceptance scenario test suite (399 lines)
- `notes/tb-4mq.md` — phase 6 completion notes

**Next:**
- Phase 7: Iterate — polish, edge cases, and enhancement loop

## Phase 7: Iterate (IN PROGRESS)

**Done:**
- Dashboard labels: `trailboss-watch` now resolves pane_id → tmux session name (alpha, bravo, etc.) via a single `tmux list-panes -a` call per render, falling back to CWD last component
- Fixed `prefix+s` conflict with tmux's built-in session chooser → moved skip to `prefix+S`
- `trailboss-start` auto-creates the `trail-boss` tmux session if it doesn't exist
- Confirmed real hooks firing and dequeuing bootstrap entries correctly (ended/unstuck events in daemon log)

**Verified working end-to-end:**
- Daemon running in `trail-boss:daemon` window (stable, survives shell exits)
- Dashboard showing NATO session names (alpha → mike) + telegram-bridge panes
- Real Claude Code hooks (Stop, UserPromptSubmit) dequeuing sessions as they become active

## Phase 9: Supervisor Split View ✅ COMPLETE

**Done:** `trail-boss:dashboard` is now a 2-pane split — TUI on top (60%), live preview on bottom (40%).

**Implemented:**
- `bin/trailboss-preview` — bash loop: reads `/tmp/trailboss-preview-target`, renders `tmux capture-pane` output every 0.5s
- `tui/client.go` — `WritePreviewTarget()` writes selected pane_id to target file
- `tui/model.go` — `syncPreview()` called on every cursor movement + queue update
- `bin/trailboss-start` — kill-session + fresh session; uses stable window ID (`@NNN`) + pane ID (`%NNN`) to avoid pane-base-index and auto-rename pitfalls; passes command directly to `split-window` (no send-keys race)
- `tmux.conf` — `prefix+B` always returns to `trail-boss:dashboard`
- `bin/trailboss` — `return` command targets `trail-boss:dashboard`

## Phase 8: TUI Rewrite ✅ COMPLETE

**Done:** Replaced bash-based `trailboss-watch`/`trailboss-popup` with a proper Go + Bubble Tea TUI.

**Implemented:**
- `tui/client.go` — HTTP client for daemon, tmux pane map, JumpToPane with origin tracking
- `tui/theme.go` — Dracula palette Lipgloss styles with dumb-terminal fallback
- `tui/model.go` — Full Bubble Tea model: split layout, vim keys, auto-refresh, help overlay
- `tui/main.go` — Entry point with AltScreen + mouse support
- `bin/trailboss-tui` — Pre-built binary (10MB, Go 1.24.2)
- `bin/trailboss-start` — Updated to `exec "$TB_DIR/bin/trailboss-tui"`

**Features:**
- Split layout: list (40%) + detail (60%) for width≥100, list-only for narrow terminals
- Color: stopped=yellow `#F1FA8C`, permission=red `#FF5555`, selected=purple `#BD93F9`
- Keys: j/k, gg/G, ctrl+d/ctrl+u, Enter (jump), l/Tab (detail focus), s (skip), r (refresh), J/K (detail scroll), 1-9 (direct jump), ? (help), q (quit)
- Auto-refresh every 3s; graceful daemon-unreachable display in status bar
- Detail pane: word-wrapped last_message, CWD, relative stuck time
- Help overlay centered with rounded border