---
description: Scan recent events from the active launch-beacon monitor session via the launch-beacon MCP. Defaults to last 50 events across all kinds; pass a kind (`error`, `click`, `fetch`, `route`, `dialog`, `probe`, etc.) to filter, and/or a numeric limit. Read-only.
---

# /kit:beacon-scan

Recent runtime events captured by a `launch-beacon monitor` session. Use this as the first step when investigating something that just happened in the browser — clicks, failed network calls, errors, route changes, probe() calls, dialog mount/unmount.

Parse `$ARGUMENTS` as space-separated tokens, in any order:
- A **kind filter**: one of `error`, `unhandledrejection`, `fetch`, `xhr`, `click`, `mousedown`, `route`, `dialog`, `submit`, `probe`. Anything else that doesn't parse as an integer or a known `--flag` is treated as an explicit session token.
- A **limit**: integer. Default 50. Hard cap 500 (the `beacon_recent.limit` tool ceiling).
- An explicit **session token** (8-char hex like `8f3c2a91`) — passed straight through as the `session` MCP arg.
- `--worktree=<slug>` — orbit worktree slug (from `launch-orbit create`). Forwarded to the MCP as the `worktree` arg so a Claude session pinned to the main repo can read sessions captured inside a worktree.
- `--project_root=<path>` — explicit project root (absolute, or relative to cwd). Forwarded to the MCP as `project_root`. Takes precedence over `--worktree`.

Examples:
- `/kit:beacon-scan` → last 50 events of any kind from the latest session
- `/kit:beacon-scan error` → last 50 errors only
- `/kit:beacon-scan click 20` → last 20 click events
- `/kit:beacon-scan 100` → last 100 events of any kind
- `/kit:beacon-scan fetch 50 8f3c2a91` → last 50 fetches from a specific session
- `/kit:beacon-scan fetch --worktree=beacon_rewrite` → last 50 fetches captured in that worktree

## Scan

Call `mcp__local-launch-beacon__beacon_recent` with `kind: <kind?>`, `limit: <limit>`, `session: <session?>`, plus `worktree: <slug?>` and `project_root: <path?>` if the user supplied them. The tool defaults to the most-recent session and returns one compact summary line per event.

If the response is `{error: "no session found"}` OR an empty events array, **alert the user with the exact MCP error string**, then walk the fallback below — do NOT silently grep.

**Fallback when the MCP returns nothing:**
1. If the user did NOT pass `--worktree` / `--project_root` and the cwd is the main repo of a project that has worktrees registered with `launch-orbit`, suggest re-running with `--worktree=<slug>` before falling back to the filesystem — that's usually the actual fix and avoids a wrong-directory scan.
2. Look for `.launchsecure/beacon-*.ndjson` in cwd, then in up to 2 parent dirs. Use the `Read` tool to inspect the most-recently-modified matching file — do NOT use `grep`, `find`, or `ls` as the primary path.
3. If files are found at an alternative path, tell the user the path mismatch explicitly: `"MCP scans <root>/.launchsecure/ but the session lives at <found-path>. Reading directly."`
4. If nothing is found anywhere, stop with: `"No beacon sessions found. Start one with: npx launch-beacon monitor"`.

## Output

Group events by **time** (most recent last — chronological matches user intuition for "what happened"). For each event, render one line:

```
HH:MM:SS  KIND     SUMMARY
```

Where SUMMARY is a one-liner pulled from the event body:
- **error / unhandledrejection** → `message` (truncate ≤ 80 chars)
- **fetch / xhr** → `METHOD status url (durationMs)` — flag `FAILED` if `failed:true`
- **click / mousedown** → `target.selector` and, when `hitMatchesTarget === false`, also append `(occluded by <hitTarget.selector>)` — that's exactly the diagnostic the user is here for
- **route** → `from → to (via)`
- **dialog** → `<action> <selector>` (e.g. `mount dialog#xyz` or `unmount section[role=dialog]`)
- **submit** → `<form selector> (preventDefault?)`
- **probe** → `<label>: <truncated JSON>`

If a summary line is missing detail you need (truncated response body, full selector chain, stack frames), call `mcp__local-launch-beacon__beacon_event` with that event's `seq` for the full JSON — and forward the same `worktree` / `project_root` args you used on `beacon_recent`. Only on demand — not unconditional.

After the timeline, if anything looks suspicious (clusters of failed network calls, a click followed by no observable effect, a `hitMatchesTarget:false` event, an unhandled rejection), call it out in **one short paragraph** at the end. Don't analyze every event — only surface the standouts.

If the buffer is empty after filtering, say so: `No events match that filter in <session>.`

## Constraints

- **MCP-first.** Use `beacon_recent` / `beacon_event` — never `grep`, `find`, `ls`, `tail`, `head` as the primary path.
- **Alert on fallback.** If the MCP can't answer, say so verbatim before reading the file directly.
- **Read-only.** Never delete, modify, or write to the NDJSON file. Wiping is `/kit:beacon-clear`.
- **Always use the latest session by default.** Pass an explicit token as the third arg only when the user wants a specific older session.
- **Plain text output.** Monospace alignment beats markdown tables here.
- **Don't speculate on root cause.** Surface anomalies; let the user direct the next query (often: `/kit:beacon-pulse` for context around the latest failure).
