feat: Claude Code Monitor — lanes, pipelines and a merged workspace

Internal SmartGift build of a Claude Code monitoring dashboard. Lanes: a durable unit of parallel agent work, one per working directory, tracked across session restarts. Managed lanes are git worktrees the dashboard provisions and can reset or remove behind a three-check destroy guard and a counted preflight; adopted lanes are directories you already own and are never destroyable. Pipelines: a lane moves through pipeline stages. A stage the agent declares with evidence renders green; a stage inferred from the tool-event stream renders dashed amber and never counts as done. Detection is forward-only within a 30-minute window, and never writes the declared stage. Workspace: one page at /run with a lane grid, the selected lane's pipeline, and a full Claude console behind a disclosure.
2026-07-29 17:07:45 +07:00
commit 57dc91585d
783 changed files with 221743 additions and 0 deletions
@@ -0,0 +1,72 @@
+---
+description: >
+  Trace the full event chain for one Claude Code session into an ordered
+  timeline of every event type with tool_name and summary, highlighting gaps,
+  out-of-order events, and failures. Reads /api/events?session_id= and
+  /api/sessions/:id from the Agent Monitor dashboard. Use when debugging what a
+  session actually did, step by step.
+---
+
+# Event Trace
+
+Build a chronological, annotated event timeline for a single session.
+
+## Input
+
+The user provides: **$ARGUMENTS**
+
+This is a session ID. It may also be:
+- `latest` / `last` — trace the most recently updated session
+- `errors` — trace the most recent session whose status is `error`
+
+## Data Sources
+
+| Endpoint | Returns |
+|----------|---------|
+| `GET /api/sessions?limit=N` | session list (used to resolve `latest`/`errors` and the target id) |
+| `GET /api/sessions/:id` | full session detail (status, model, cwd, started_at, ended_at, cost, nested agents + events) |
+| `GET /api/events?session_id=X` | the ordered event stream: event_type, tool_name, summary, data, timestamp |
+
+## Report Sections
+
+### 1. Resolve the session
+If `$ARGUMENTS` is a raw id, use it. If `latest`/`last`, call
+`GET /api/sessions?limit=1`. If `errors`, call
+`GET /api/sessions?limit=10&status=error` and pick the newest. Confirm the id
+resolves via `GET /api/sessions/:id`; if not, report it as missing and stop.
+
+### 2. Session header
+From `GET /api/sessions/:id`: id, status, model, cwd, started_at → ended_at,
+total duration, cost (USD to 4 decimals), and counts (events, agents).
+
+### 3. Ordered timeline
+From `GET /api/events?session_id=X`, list every event in timestamp order. One row
+per event:
+
+`| # | time | Δ since prev | event_type | tool_name | summary |`
+
+Cover all event types present: SessionStart, PreToolUse, PostToolUse, Stop,
+SubagentStop, Compaction, APIError, TurnDuration, Notification, SessionEnd.
+
+### 4. Gap & failure highlights
+Annotate the timeline:
+- **Gaps**: any Δ > 30s between consecutive events — mark ⏳ and note the wait.
+- **Unpaired tool calls**: a PreToolUse with no matching PostToolUse (same
+  tool_name, next in stream) — mark ⚠️ "no completion recorded".
+- **Failures**: APIError events and PostToolUse whose `summary`/`data` indicates
+  an error — mark ❌ with the error text.
+- **Compaction**: mark ♻️ and note it resets the visible token baseline.
+- **Missing bookends**: no SessionStart at the head or no Stop/SessionEnd at the
+  tail of an ended session — mark 🚩.
+
+### 5. Verdict
+One line: CLEAN, GAPS DETECTED, or FAILURES PRESENT — with the count of each
+flag type and the single most likely thing to investigate next.
+
+## Output
+
+- Markdown timeline table, events in strict timestamp order.
+- Status glyphs inline: ✅ ok, ❌ error, ⚠️ warning/unpaired, ⏳ gap, ♻️ compaction, 🚩 missing bookend.
+- Currency in USD to 4 decimals.
+- Cite only event data returned by the API — do not invent timestamps or summaries.
+- If the dashboard is unreachable, tell the user to start it with `npm start` from the repo root.