doctor

What this skill does

# doctor

You are a diagnostic agent for the babysitter runtime. Your job is to perform a comprehensive health check across 10 areas and produce a structured diagnostic report. Follow each section methodically. Track results as you go and produce the final summary at the end.

Initialize a results tracker with these 10 checks, all starting as PENDING:
1. Run Discovery
2. Journal Integrity
3. State Cache Consistency
4. Effect Status
5. Lock Status
6. Session State
7. Log Analysis
8. Disk Usage
9. Process Validation
10. Hook Execution Health

---

## 1. Run Discovery

**Goal:** Identify the target run and display its metadata.

- List all runs by running: `ls -lt .a5c/runs/`
- If the user provided a run ID argument, use that as the run ID. Otherwise, use the most recent run directory (the first entry from the listing).
- Store the resolved run ID and construct the run directory path: `.a5c/runs/<runId>`
- Verify the run directory exists. If it does not exist, report FAIL for this check and stop the entire diagnostic (no run to diagnose).
- Show run metadata by running: `npx babysitter run:status .a5c/runs/<runId> --json`
- Parse and display: runId, processId, entrypoint/importPath, createdAt, current state.
- Mark this check as PASS.

---

## 2. Journal Integrity

**Goal:** Verify the append-only event journal is well-formed and uncorrupted.

- List all journal events by running: `npx babysitter run:events .a5c/runs/<runId> --json`
- List all files in `.a5c/runs/<runId>/journal/` sorted by name.
- If the journal directory is empty or missing, mark as FAIL and note "No journal entries found."

For each journal file (named `<seq>.<ulid>.json`):

**Sequential numbering check:**
- Extract the sequence number prefix from each filename (e.g., `000001` from `000001.01JAXYZ.json`).
- Verify sequence numbers are contiguous starting from 000001 with no gaps.
- If gaps found, mark as WARN and list the missing sequence numbers.

**Checksum verification:**

The SDK computes checksums as follows: it first builds the event payload **without** the `checksum` field (`{ type, recordedAt, data }`), serializes it with `JSON.stringify(payload, null, 2) + "\n"` (pretty-printed with a trailing newline), then computes SHA256 of that string. To verify:

- Read each journal file as JSON.
- Extract and remove the `checksum` field from the parsed object.
- Re-serialize the remaining object with `JSON.stringify(remaining, null, 2) + "\n"` — **must** use 2-space indentation and a trailing newline to match the SDK.
- Compute SHA256 (hex) of that exact string.
- Compare computed checksum with the stored checksum.
- If any mismatch, mark as FAIL and list the corrupt files.

Example bash one-liner for a single file:
```bash
node -e "const fs=require('fs'); const f=process.argv[1]; const obj=JSON.parse(fs.readFileSync(f,'utf8')); const stored=obj.checksum; delete obj.checksum; const expected=require('crypto').createHash('sha256').update(JSON.stringify(obj,null,2)+'\n').digest('hex'); console.log(stored===expected?'OK':'MISMATCH',f)" <file>
```

**Timestamp monotonicity check:**
- Extract `recordedAt` from each event.
- Verify each timestamp is >= the previous one.
- If any timestamp goes backward, mark as WARN and list the offending entries.

**Event type summary:**
- Count events by type: RUN_CREATED, EFFECT_REQUESTED, EFFECT_RESOLVED, STOP_HOOK_INVOKED, RUN_COMPLETED, RUN_FAILED, and any other types encountered.
- Display the counts in a table.

**Orphan detection:**
- Flag any files in the journal directory that do not match the expected `<seq>.<ulid>.json` naming pattern.

If all sub-checks pass, mark as PASS. If any sub-check is WARN, mark as WARN. If any sub-check is FAIL, mark as FAIL.

---

## 3. State Cache Consistency

**Goal:** Verify the derived state cache matches the current journal.

- Check if `.a5c/runs/<runId>/state/state.json` exists.
- If it does not exist, mark as WARN and recommend: `npx babysitter run:rebuild-state .a5c/runs/<runId>`

If it exists:
- Read `state.json` and extract the `journalHead` field (contains `seq`, `ulid`, and `checksum`).
- Determine the actual last journal entry by reading the last file in `.a5c/runs/<runId>/journal/` (highest sequence number).
- Extract the sequence number and ULID from the last journal filename, and the checksum from its content.
- Compare:
  - `journalHead.seq` should match the last journal file's sequence number.
  - `journalHead.ulid` should match the last journal file's ULID.
  - `journalHead.checksum` should match the last journal file's checksum.
- If all match, mark as PASS.
- If any mismatch, mark as WARN and recommend: `npx babysitter run:rebuild-state .a5c/runs/<runId>`
- Also verify `schemaVersion` field is present and report its value.

---

## 4. Effect Status

**Goal:** Identify stuck, errored, or pending effects.

- Run: `npx babysitter task:list .a5c/runs/<runId> --json`
- Run: `npx babysitter task:list .a5c/runs/<runId> --pending --json`
- Parse the JSON output from both commands.

**All effects summary:**
- Count total effects, resolved effects, and pending effects.
- Group and count effects by `kind` (node, breakpoint, orchestrator_task, sleep, etc.).

**Stuck effect detection:**
- For each pending effect, check its `requestedAt` timestamp.
- If any pending effect was requested more than 30 minutes ago, flag it as STUCK.
- List stuck effects with their effectId, kind, taskId, and age.

**Error detection:**
- Identify any effects with error status in their results.
- List errored effects with their effectId and error message.

**Pending summary:**
- Summarize pending effects grouped by kind with count per kind.

Mark as PASS if no stuck or errored effects. Mark as WARN if there are pending effects older than 30 minutes. Mark as FAIL if there are errored effects.

---

## 5. Lock Status

**Goal:** Detect stale or orphaned run locks.

- Check if `.a5c/runs/<runId>/run.lock` exists.
- If it does not exist, mark as PASS ("No lock held -- run is not actively being iterated").

If it exists:
- Read the lock file (JSON with `pid`, `owner`, `acquiredAt`).
- Display the lock info: PID, owner, acquired time, and age of the lock.
- Check if the PID is still alive by running: `kill -0 <pid> 2>/dev/null; echo $?` (exit code 0 means alive, non-zero means dead). On Windows/MINGW, use `tasklist //FI "PID eq <pid>" 2>/dev/null` or equivalent.
- If the process is alive, mark as PASS ("Lock held by active process").
- If the process is dead, mark as FAIL ("Stale lock detected -- process <pid> is no longer running").
  - Recommend: `rm .a5c/runs/<runId>/run.lock`

---

## 6. Session State

**Goal:** Inspect babysitter session files for health and detect runaway loops.

- Search for session state files using Glob:
  - `plugins/babysitter/skills/babysit/state/*.md`
  - `.a5c/state/*.md`
  - `.a5c/state/*.json`
- For each session state file found:
  - Read the file and extract available information: iteration count, associated runId, timestamps, session status.
  - Display: filename, iteration count, runId (if present), last activity time.

**Runaway loop detection:**
- If any session file contains iteration timing data, compute the average time between iterations.
- If the average iteration time is less than 3 seconds, flag as WARN ("Possible runaway loop detected -- average iteration time is under 3 seconds").

**Session classification:**
- Active: session has recent activity (within last 30 minutes).
- Stale: session has no activity for more than 30 minutes.
- Display counts of active vs stale sessions.

Mark as PASS if no issues. Mark as WARN if runaway loops or stale sessions detected.

---

## 7. Log Analysis

**Goal:** Analyze babysitter log files for errors, warnings, and stop hook decisions.

Read the last 50 lines of each of these log files (if they exist):
- `$CLAUDE_PLUGIN_ROOT/.a5c/logs/hooks.log`
- `$CLAUDE_PLUGIN_ROOT/.a5c/logs/babysitter-stop-hook.log`
- `$CLAUDE_PLUGIN_ROOT/.a5c/logs/babysitter-stop-hook-st