sdc-diagnose

name	sdc-diagnose
description	Diagnose AgentDeck Stream Deck/PTY option synchronization, cursor state, hook ingestion, and bridge state-machine issues. Collects diagnostics, searches known failure patterns, adds focused regression tests, and verifies with pnpm tests.

AgentDeck Diagnostic Skill

Canonical diagnostic procedure for AgentDeck bridge synchronization issues between device displays and agent terminals (cursor desync, false idle, stale options, action dispatch races, hook ingestion gaps, state-machine regressions). This file is the single source of truth — .claude/skills/sdc-diagnose.md is a thin pointer to it.

Step 1: Collect Diagnostic Data

From the repo root, try the live bridge first:

cd /Users/puritysb/github/AgentDeck
agentdeck diag --tail 500 2>/dev/null || echo "Bridge not running — using journal files directly"

If the bridge isn't running, read journal/log files directly:

ls -la ~/.agentdeck/journal/ 2>/dev/null
ls -t ~/.agentdeck/journal/*.jsonl 2>/dev/null | head -1 | xargs tail -500
tail -200 /tmp/sdc-debug.log 2>/dev/null || echo "No debug log found"

If these commands fail because of sandboxing or access to user-local files, request scoped approval before relying on guesses.

Step 2: Analyze for Known Failure Patterns

2a. Cursor Desync

navigate_option followed by a stale cursor_update with conflicting indices.

Pattern: navigate_option cursor=X->Y ... cursor_update cursorIndex=X (reverted)
Root cause: PTY confirmation overwrites optimistic update
Fix: cursor authority system (A3) — optimistic suppresses PTY within 200ms

2b. False Idle

option_prompt followed by idle within 500ms.

Pattern: option_prompt (N options) ... idle_detected (< 500ms gap)
Root cause: Small chunk with "❯ No" misclassified as idle prompt
Fix: Semantic idle check (A2) — only "❯" or ">" as sole non-ws content

2c. Stale Options

option_prompt with missing or non-contiguous indices.

Pattern: option_prompt indices=[0,1,3] (missing 2)
Root cause: Buffer corruption or partial redraw parsed as complete
Fix: Buffer tail re-parse with debounce

2d. Action Dispatch Race

select_option overlapping rapid state transitions.

Pattern: select_option ... state AWAITING->PROCESSING->AWAITING (rapid cycle)
Root cause: Enter sent before arrow navigation completes
Fix: Proportional delay (A4) — 50 + |delta| * 20ms

2e. ANSI Cursor Invisible

Terminal keyboard input without a corresponding cursor_update for >500ms.

Pattern: (arrow key in terminal) ... no cursor_update for >500ms
Root cause: ink repositions cursor via ANSI sequences without ❯ in chunk
Fix: ANSI reposition detection (A1) — re-parse buffer on small non-❯ chunks

2f. Codex Hook Gap

Missing codex_user_prompt_submit, codex_tool_start, codex_tool_end, or codex_stop in daemon hook logs.

Pattern: Codex session active but lifecycle hooks absent from hook log
Root cause: ~/.codex/config.toml hooks not installed/migrated, or fence corrupted
Fix: re-run `agentdeck codex` (installs/migrates) or inspect installCodexHooksIfNeeded

Step 3: Add Regression Tests

Add focused tests near the subsystem under change:

• Parser / state-machine / cursor issues: bridge/src/__tests__/cursor-sync.test.ts, state-machine.test.ts, or parser tests.
• Codex hook issues: hooks/src/__tests__/codex-install.test.ts, bridge/src/__tests__/state-machine.test.ts, or the Codex APME adapter tests.
• Apple timeline/rendering issues: apple/AgentDeckTests/.

Template (cursor desync, vitest):

it('reproduces cursor desync from journal entry', () => {
  const sm = bootToIdle();
  sm.handleParserEvent('option_prompt', {
    options: [/* options from journal */],
    navigable: true,
    cursorIndex: 0,
  });

  sm.updateCursorIndex(/* target */, 'optimistic');
  vi.advanceTimersByTime(/* gap from journal */);
  sm.updateCursorIndex(/* stale PTY value */, 'pty');

  expect(sm.getCursorIndex()).toBe(/* expected */);
});

Step 4: Run & Verify

Run the narrowest useful tests first, then broaden when shared behavior changed:

cd /Users/puritysb/github/AgentDeck
pnpm test
pnpm -r exec tsc --noEmit

Check that all existing tests pass, new regression tests pass, and there are no TypeScript errors.

Step 5: Report

## Diagnostic Report

### Issues Found
1. [PATTERN]: Description
   - Journal entries: [timestamps]
   - Expected: X
   - Actual: Y
   - Fix: [A1/A2/A3/A4/A5/codex] — description

### Tests Generated
- <file>: N new tests
- Regression coverage: [patterns covered]

### Verification
- pnpm test: PASS/FAIL
- TypeScript: PASS/FAIL

### Recommendations
- [Any additional fixes or monitoring suggestions]

Key Files Reference

File	Purpose
bridge/src/output-parser.ts	PTY output parsing, cursor detection
bridge/src/state-machine.ts	State transitions, cursor authority
bridge/src/index.ts	Bridge wiring, command handlers
bridge/src/__tests__/cursor-sync.test.ts	Cursor sync test suite
hooks/src/codex-install.ts	Codex lifecycle hook installer (hook-gap issues)
~/.agentdeck/journal/	Event journal files
/tmp/sdc-debug.log	Debug log (when -d flag used)