---
description: Show the most recent failure from the active launch-beacon monitor session, plus the N events that preceded it (default 10). Answers "what was happening when it broke" without scrolling through the full stream. Read-only.
---

# /kit:beacon-pulse

The "what happened just before this failure" command — a single pulse, freezing the moment the beacon caught a failure. When a bug fires, the actual story is usually the chain of events leading up to it: the click that triggered a state change, the failed fetch that left auth in a bad state, the route change that mounted the wrong component.

A "failure" here is anything `mcp__local-launch-beacon__beacon_failures` returns — window errors, unhandled rejections, fetch/xhr with status ≥ 400 or thrown, and clicks where overlay interception blocked the intended target. Broader than just `kind=error`; matches what users mean when they say "something broke."

Parse `$ARGUMENTS` as space-separated tokens, in any order:
- An optional **integer** — the count of preceding events to include. Default 10. Cap at 50 (the `beacon_correlate.before` tool limit).
- `--worktree=<slug>` — orbit worktree slug. Forwarded to every MCP call as the `worktree` arg.
- `--project_root=<path>` — explicit project root (absolute, or relative to cwd). Forwarded as `project_root`. Takes precedence over `--worktree`.

Examples:
- `/kit:beacon-pulse` → 10 events before the latest failure
- `/kit:beacon-pulse 25` → 25 events before
- `/kit:beacon-pulse --worktree=beacon_rewrite` → query a worktree's session

## Locate the most recent failure

Call `mcp__local-launch-beacon__beacon_failures` with `limit: 1` (and `worktree` / `project_root` if the user supplied them). The tool implicitly targets the most recent session.

If the response is `{error: "no session found"}` OR an empty failures array, **alert the user with the exact MCP error string**, then walk the fallback below — do NOT silently grep. The MCP can come up empty for two non-bug reasons: (a) no session has been started, (b) the session NDJSON lives outside the MCP's watch root (e.g. inside an orbit worktree the user didn't name).

**Fallback when the MCP returns nothing:**
1. If the user did NOT pass `--worktree` / `--project_root` and `launch-orbit` has worktrees registered for this repo, suggest re-running with `--worktree=<slug>` before falling back to the filesystem.
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"`.

Capture the failure's `seq`, `kind`, `ts`, and message.

## Pull the context window

Call `mcp__local-launch-beacon__beacon_correlate` with `seq: <failure.seq>`, `before: N`, `after: 0`, plus the same `worktree` / `project_root` args you used on `beacon_failures`. The tool returns event summaries directly — no JSON parsing required.

If a context event's summary is missing detail you need for analysis (truncated stack, missing response body, selector chain), call `mcp__local-launch-beacon__beacon_event` with that event's specific `seq` for the full JSON — and forward the same root args. Only do this when the summary is insufficient — not unconditional.

## Output

Render a **timeline** with the failure visually separated at the bottom:

```
session: <token>
window:  N events before failure at seq <seq>

12:34:51  click       button.submit-btn
12:34:51  fetch       POST 401 /api/sessions (120ms)  FAILED
12:34:51  fetch       GET 401 /api/me (45ms)  FAILED
12:34:52  route       /login → /dashboard (pushState)
...

╴╴╴╴ FAILURE ╴╴╴╴
12:34:53  error       Cannot read properties of undefined (reading 'orgSlug')
              at apps/Console.tsx:42:18
              stack: Console.render
                     React.renderWithHooks
                     React.beginWork
```

Format rules:
- One line per event, same SUMMARY format as `/kit:beacon-scan`.
- The failure block at the end gets the message + (truncated) stack frames if present. For fetch/xhr failures, include method + status + url + response body summary.
- Separator above the failure is the visual cue.

After the timeline, write **one short paragraph** of analysis: what does the chain *look* like? Common patterns:
- 401s → error referencing user/org → "auth expired or org context missing"
- click → no observable effect → click again → error → "first click handler crashed silently; second click landed on something else"
- route change → error → "component on the new route blew up during initial render"
- repeated 400s on the same endpoint → "request shape mismatch — check the server's Zod schema against the client payload"

Don't dive into a fix — name the suspected proximate cause, suggest one concrete next step (which file to read, which probe to add, which `/kit:beacon-scan <kind>` to drill into).

## Constraints

- **MCP-first.** Use `beacon_failures`, `beacon_correlate`, `beacon_event` — never `grep`, `find`, `ls`, `sed`, `cut`, or `tail` as the primary path.
- **Alert on fallback.** If the MCP can't answer, say so verbatim before reading the file directly.
- **Read-only.**
- **Most recent failure only.** For an earlier one, clear the session (`/kit:beacon-clear`) and reproduce, or use `/kit:beacon-scan error` / `/kit:beacon-scan fetch` to browse.
- **Plain text.** Same monospace conventions as `/kit:beacon-scan`.
