---
name: AgentDeck Diagnostics
slug: agentdeck-diagnostics
category: Quality
description: AgentDeck Diagnostics collects bridge logs, checks for cursor desync, stale options, hook gaps, and state-machine regressions. Use it to diagnose AgentDeck Stream Deck and PTY synchronization issues, add focused tests, and verify fixes with pnpm.
github: "https://github.com/puritysb/AgentDeck/tree/master/.agents/skills/sdc-diagnose"
language: TypeScript
stars: 219
forks: 42
install: "npx degit https://github.com/puritysb/AgentDeck/tree/master/.agents/skills/sdc-diagnose ~/.claude/skills/sdc-diagnose"
installs_to: ~/.claude/skills/sdc-diagnose
source_path: .agents/skills/sdc-diagnose/SKILL.md
collection_size: 5
category_size: 1557
collection_url: "https://dirskills.com/collections/puritysb/AgentDeck"
added: 2026-09-04T05:25:08.308Z
last_synced: 2026-09-04T05:25:08.308Z
canonical_url: "https://dirskills.com/skills/agentdeck-diagnostics"
---

# AgentDeck Diagnostics

AgentDeck Diagnostics collects bridge logs, checks for cursor desync, stale options, hook gaps, and state-machine regressions. Use it to diagnose AgentDeck Stream Deck and PTY synchronization issues, add focused tests, and verify fixes with pnpm.

**Install:**

```bash
npx degit https://github.com/puritysb/AgentDeck/tree/master/.agents/skills/sdc-diagnose ~/.claude/skills/sdc-diagnose
```

## README

# 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:

```bash
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:

```bash
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):
```typescript
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:

```bash
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) |