Troubleshoot

7. Stale Running Actions

Trigger: Actions with status running for >1 hour Fix: Two layers of cleanup:

1. One-shot bulk repair for any historical backlog:

   # Preview what would change
   node scripts/_run-with-env.mjs scripts/repair-stale-running-actions.mjs --dry-run --older-than-hours 1
   # Apply (status='completed' with "Auto-closed" summary; preserves error_message → 'failed')
   node scripts/_run-with-env.mjs scripts/repair-stale-running-actions.mjs --older-than-hours 1

2. Prevent re-accumulation — install dashclaw_stop.py (Stop hook). At turn end it queries each open action and PATCHes status='completed' only when the action is still running. Terminal statuses written by PostToolUse are preserved. See setup-dashclaw skill.

For ad-hoc closure of a single action: claw.updateOutcome(actionId, { status: 'failed', output_summary: 'Timed out' }).

8. Agent Silent

Trigger: Agent heartbeat lost >10 minutes Fix: Ensure agent sends heartbeats: claw.heartbeat({ status: 'online' }).

Diagnostic Tools

Health probe

curl -sf "$DASHCLAW_BASE_URL/api/health" | jq '.'

Returns {status, version, checks: {database, runtime, realtime, ...}}. Anything other than status: "healthy" points at the failing check.

Doctor (config audit)

node scripts/doctor.mjs

Audits the local config — env vars, DB connectivity, schema state, generated artifact freshness.

Live SDK round-trip

# Node — guard → createAction → updateOutcome against the live instance
node scripts/_run-with-env.mjs scripts/test-sdk-live.mjs

# Python equivalent
node scripts/_run-with-env.mjs scripts/run-sdk-live-python.mjs

Both scripts emit a real action that you should see appear on /decisions within seconds. If the round-trip fails, the error pinpoints the layer (HTTP, validation, DB).

Startup smoke test

npm run startup:smoke

Boots Next.js, hits the critical routes, and reports which (if any) fail to respond.

Hook Troubleshooting

Pretool not firing

• Verify .claude/settings.json has PreToolUse hook configured
• Check matcher pattern: Bash|Edit|Write|MultiEdit
• Verify Python is available: python --version
• Check hook script path is correct relative to project root

Pretool allows everything

• Check DASHCLAW_HOOK_MODE — if set to observe, it logs but never blocks
• Check DASHCLAW_RISK_THRESHOLD — default is 60, lower it to catch more
• Verify policies exist: curl -H "x-api-key: $KEY" $URL/api/policies

Pretool blocks everything

• Check guard policies — a too-broad policy may be catching all actions
• Try DASHCLAW_HOOK_MODE=observe first to understand what's being caught
• Check risk scoring — are file operations being scored too high?

Posttool not recording outcomes

• Check temp file bridge: pretool writes to {tempdir}/dashclaw_last_action_{tool_use_id}
• Verify DASHCLAW_BASE_URL and DASHCLAW_API_KEY are set for posttool
• Posttool never blocks — failures are silent. Check DashClaw server logs.

Stop hook not capturing tokens (Analytics shows $0 / 0 tokens)

• Verify .claude/settings.json has the Stop block (one entry, no matcher needed). If missing, re-run node /path/to/DashClaw/scripts/install-hooks.mjs --target=..
• During a turn, confirm pretool is appending action_ids: ls /tmp/dashclaw_turn_<session_id> (Linux/macOS) or dir %TEMP%\dashclaw_turn_<session_id> (Windows). After Stop fires, that file is deleted and /tmp/dashclaw_stop_cursor_<session_id> appears.
• Manually fire the Stop hook to test:

  echo '{"session_id":"<your-session-id>","transcript_path":"<path/to/.jsonl>"}' \
    | python .claude/hooks/dashclaw_stop.py; echo "exit=$?"

  Then query the DB for any action_id from that session — tokens_in, tokens_out, model, cost_estimate should be populated.
• Confirm PATCH /api/actions/:id accepts token fields by checking the deployed server version: curl -sf $DASHCLAW_BASE_URL/api/health | jq '.version' should be ≥ 2.13.1. Older deploys silently drop tokens_in/tokens_out.

Stale running actions piling up

• Verify the Stop hook is installed (above). It auto-closes any action still in status='running' at turn end. Without it, every interrupted/abandoned tool stays open forever.
• For a one-shot cleanup: node scripts/_run-with-env.mjs scripts/repair-stale-running-actions.mjs --older-than-hours 1 (preview with --dry-run first).