---
description: Soft-delete launch-beacon monitor session NDJSON files. Default clears only the latest session (so you can start a clean repro); pass `all` to clear every `.launchsecure/beacon-*.ndjson`. Always shows what will be cleared and asks for confirmation. Recoverable from `.launchsecure/.trash/<ts>/`.
---

# /kit:beacon-clear

Clean slate before a fresh repro. The receiver appends to the same NDJSON file across reconnects of the same session, so an existing file accumulates noise from earlier attempts — clearing first makes the new stream easier to reason about.

Parse `$ARGUMENTS` as space-separated tokens, in any order:
- empty → clear the most recent session file only
- `all` → clear every `.launchsecure/beacon-*.ndjson` in the target dir
- a specific token or filename → clear that one file (must match a real path)
- `--worktree=<slug>` — orbit worktree slug. Forwarded to MCP as the `worktree` arg; the soft-delete acts on the worktree's `.launchsecure/`.
- `--project_root=<path>` — explicit project root (absolute, or relative to cwd). Forwarded as `project_root`. Takes precedence over `--worktree`.

Examples:
- `/kit:beacon-clear` → clear the most recent session in cwd's `.launchsecure/`
- `/kit:beacon-clear all` → clear every session in cwd's `.launchsecure/`
- `/kit:beacon-clear all --worktree=beacon_rewrite` → clear every session in that worktree's `.launchsecure/`

## Enumerate candidates

Call `mcp__local-launch-beacon__beacon_sessions`, forwarding `worktree` / `project_root` if supplied. Use `token`, `last_ts`, `events`, and `path` (absolute) from the response. **The filesystem operations below MUST use `path` from this response — never reconstruct paths from `.launchsecure/beacon-<token>.ndjson` relative to cwd**, because with `--worktree` / `--project_root` the real directory is elsewhere.

If the response is `{sessions: []}` OR `{error: ...}`, **alert the user with the exact MCP error string**, then walk the fallback below — do NOT silently `ls`.

**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 — never `ls`, `find`, or globbing as the primary path.
3. If files are found at an alternative path, tell the user the path mismatch and ASK before proceeding — the user may not want to clear files at an unexpected location.
4. If nothing is found anywhere, stop with: `"No beacon sessions found in .launchsecure/. Nothing to clear."`.

## Decide target set

- empty → most-recent session (highest `last_ts`)
- `all`  → every session the MCP returned
- otherwise → resolve `$ARGUMENTS` to a single token: try the literal arg first as a session id, then strip a `.ndjson` suffix, then try matching against the filename portion of a path containing `beacon-<token>.ndjson`. Refuse with a clear message if none match.

## Refusal rules

Refuse with a clear message if:
- the target set is empty
- any target resolves outside `.launchsecure/` (defence against `..` injection from `$ARGUMENTS` — even if the user passes an absolute path)
- the active session is being written *right now* (`last_ts` within the last 5 seconds) — print a one-line warning and ask the user to stop the monitor first:
  ```
  ⚠ .launchsecure/beacon-8f3c2a91.ndjson was last written 2s ago — looks active.
    Stop the receiver (Ctrl+C in the launch-beacon monitor terminal) and re-run /kit:beacon-clear.
  ```
  The user can still force by passing the token explicitly — but never silently nuke an actively-written file.

## Confirmation

Print what's about to be moved and ask before doing it.

```
About to soft-delete 1 file:
  .launchsecure/beacon-a1b2c3d4.ndjson   89 events, 12m ago

Recoverable from .launchsecure/.trash/<UTC-timestamp>/ until manually purged.

Confirm? (y/N)
```

For `all`, list every file with event count + age. Don't truncate.

Wait for explicit `y`/`yes`. Anything else → abort with `Cancelled. No files were moved.`

## Soft-delete (move, don't rm)

Create `<sessionDir>/.trash/<UTC-ISO-timestamp>/` and `mv` each target into it, where `<sessionDir>` is `dirname(path)` from the `beacon_sessions` response — NOT a hard-coded `.launchsecure/`. This matters when `--worktree` or `--project_root` was passed, because the dir is then the worktree's `.launchsecure/`, not cwd's. **Never `rm`.** This is the mitigation for the recall coverage gap — recall doesn't snapshot `.launchsecure/*` today (tracked in LS work item #144). Soft-delete preserves the option to recover within the same machine.

```bash
SESSION_DIR=$(dirname "<path-from-beacon_sessions>")  # e.g. /repo/.claude/worktrees/foo/.launchsecure
TRASH="$SESSION_DIR/.trash/$(date -u +%Y%m%dT%H%M%SZ)"
mkdir -p "$TRASH"
mv "$SESSION_DIR/beacon-<token>.ndjson" "$TRASH/"
```

After the move, print:

```
✓ moved 1 file to .launchsecure/.trash/20260526T142233Z/ (89 events archived).
  Recover with: mv .launchsecure/.trash/20260526T142233Z/beacon-a1b2c3d4.ndjson .launchsecure/
```

For `all`, print the count and the trash dir once; don't list every recovery command.

## Constraints

- **MCP-first for enumeration.** Use `beacon_sessions` — never `ls` as the primary path.
- **Destructive — always confirm.** Even if `$ARGUMENTS` is `all`, ask first.
- **Scope-locked to the session dir.** The session dir is `dirname(path)` from `beacon_sessions` (typically `.launchsecure/`, but `<worktree>/.launchsecure/` when `--worktree`/`--project_root` is passed). Reject any target outside the dir the MCP told you about, even if the user passes an absolute path. We never touch files we didn't write.
- **Soft-delete only.** Never `rm` — always `mv` into `.launchsecure/.trash/<ts>/`. The trash dir is not auto-pruned; cleaning it up is a deliberate user action.
- **Don't stop the monitor server.** This command only moves files. The receiver keeps running and will reopen the same file on its next write — which is fine, the file just starts empty again.
