instar 1.2.6 → 1.2.8

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-21T17:15:04.109Z",
-  "instarVersion": "1.2.6",
+  "generatedAt": "2026-05-21T18:31:26.539Z",
+  "instarVersion": "1.2.8",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -752,7 +752,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:setup": {
@@ -760,7 +760,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:add": {
@@ -768,7 +768,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:backup": {
@@ -776,7 +776,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:git": {
@@ -784,7 +784,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:memory": {
@@ -792,7 +792,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:knowledge": {
@@ -800,7 +800,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:semantic": {
@@ -808,7 +808,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:intent": {
@@ -816,7 +816,7 @@
       "type": "cli-command",
       "domain": "intent",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:feedback": {
@@ -824,7 +824,7 @@
       "type": "cli-command",
       "domain": "feedback",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:server": {
@@ -832,7 +832,7 @@
       "type": "cli-command",
       "domain": "server",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:status": {
@@ -840,7 +840,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:user": {
@@ -848,7 +848,7 @@
       "type": "cli-command",
       "domain": "users",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:relationship": {
@@ -856,7 +856,7 @@
       "type": "cli-command",
       "domain": "relationships",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:job": {
@@ -864,7 +864,7 @@
       "type": "cli-command",
       "domain": "scheduling",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:lifeline": {
@@ -872,7 +872,7 @@
       "type": "cli-command",
       "domain": "communication",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:list": {
@@ -880,7 +880,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:autostart": {
@@ -888,7 +888,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:migrate": {
@@ -896,7 +896,7 @@
       "type": "cli-command",
       "domain": "updates",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:machines": {
@@ -904,7 +904,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:whoami": {
@@ -912,7 +912,7 @@
       "type": "cli-command",
       "domain": "identity",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:pair": {
@@ -920,7 +920,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:join": {
@@ -928,7 +928,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:wakeup": {
@@ -936,7 +936,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:leave": {
@@ -944,7 +944,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:doctor": {
@@ -952,7 +952,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:review": {
@@ -960,7 +960,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:nuke": {
@@ -968,7 +968,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "cli:playbook": {
@@ -976,7 +976,7 @@
       "type": "cli-command",
       "domain": "context",
       "sourcePath": "src/cli.ts",
-      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
+      "contentHash": "eba93ab5240154f808f97b72ffaf6dc2a11b36c426811ee3c08018c9a651a84a",
       "since": "2025-01-01"
     },
     "template:build-stop-hook.sh": {

package/upgrades/1.2.7.md

@@ -0,0 +1,82 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**fix(safe-fs): runtime artifacts under `<root>/.instar/` get a carve-out from the source-tree guard.**
+
+Closes the "agent goes dark on cold start" failure mode that surfaced after v1.2.4 in the field (Echo, 2026-05-21): every fresh launchd spawn hit `EADDRINUSE` on the stale unix socket at `.instar/listener.sock`, the `WakeSocketServer` stale-socket-recovery path correctly tried to unlink it, but `SafeFsExecutor` routed the unlink through `assertNotInstarSourceTree` and the guard fired because the agent's deployed directory IS a checkout of the instar source (same `.git`, same `.instar-source-tree` marker, same `package.json` with `name: "instar"`). The supervisor then escalated to its bind-failure recovery path and force-rebuilt better-sqlite3 on every cycle, which in turn produced an incompatible binary and the server never bound.
+
+The fix is a narrow carve-out in `SafeFsExecutor.guard()`: when the canonicalized target path is under a `.instar/` subdirectory of the source root, skip the source-tree guard. The carve-out is intentionally interior-only — the `.instar` directory itself is still protected (`safeRmSync` on `<root>/.instar` still throws `SourceTreeGuardError`). All five subdirectories that the project's own `.gitignore` excludes (`.instar/state/`, `.instar/logs/`, `.instar/audit/`, `.instar/instar-dev-traces/`, plus `.instar/shared-state.jsonl`) are runtime state, not source code, and destructive ops on them are a normal part of operation rather than a 2026-04-22-class incident.
+
+The guard's three layers (marker file, canonical origin URL, source-identity signature) are unchanged. The 2026-04-22 incident is still caught: that incident targeted source files at the tree root (`README.md`, `src/auth.ts`, `src/middleware.ts`), not anything under `.instar/`. The included tests verify both directions — the carve-out lets the right paths through, and source-tree paths outside `.instar/` (and `.instar` itself) still fault.
+
+## Why now
+
+After v1.2.4 every fresh boot of Echo on dawn-macbook entered the loop: lifeline restarts → WakeSocketServer EADDRINUSE → stale-socket-recovery blocked by guard → supervisor declares health-check failed → bind-failure escalation → force-rebuild better-sqlite3 → binary mismatch → loop. Manually unlinking the socket and bootstrapping cleanly worked once, but the next launchd respawn re-entered the loop because nothing fixed the structural block.
+
+## Audit trail
+
+The carve-out also leaves a positive audit signal: `safeUnlinkSync` (and siblings) emit an `outcome: "allowed"` entry to `.instar/audit/destructive-ops.jsonl` with `reason: "agent-runtime-state-carveout"` whenever the carve-out path is taken. Lets you see how often the runtime-state path is being exercised vs how often it would have been a false-positive block before.
+
+## Tests
+
+5 new tests in `tests/unit/SafeFsExecutor.test.ts` under `SafeFsExecutor agent-runtime-state carve-out`:
+
+- `allows unlink on a socket file under <root>/.instar/`
+- `allows unlink on a lock file under <root>/.instar/`
+- `allows rm on a nested file under <root>/.instar/state/`
+- `still BLOCKS rm on the .instar directory itself (not its contents)`
+- `still BLOCKS unlink on source files at the tree root`
+
+All 17 SafeFsExecutor tests pass (12 existing + 5 new).
+
+## Summary of New Capabilities
+
+This is a fix-only release. No new user-facing capabilities. The carve-out unblocks `WakeSocketServer.stale-socket-recovery`, `AutoUpdater` shadow-install management, and lifeline lockfile cleanup — all of which were already supposed to work but were silently blocked by the source-tree guard in agent mode.
+
+## What to Tell Your User
+
+If you're running an instar agent on macOS and have hit cold-start crash loops where the agent's logs say EADDRINUSE and reference SafeFsExecutor, this release fixes the underlying block. Pull v1.2.x (next), restart your agent. No config changes required, no migration needed.
+
+If you've never seen this — you're on a deployment style where the agent dir is NOT a checkout of the instar source, and the guard was never the problem. This release is a no-op for you.
+
+If you ran the manual workaround (rm .instar/listener.sock then bootstrap your launchd plist) — the workaround is no longer needed once this release is installed.
+
+## Evidence
+
+**Reproduction**: Run instar in agent mode where the agent's deployed directory is also a checkout of the instar source tree (the `~/.instar/agents/echo` pattern on dawn-macbook). Cold-start with a stale `.instar/listener.sock` present. Observed before this fix: `WakeSocketServer` attempts to unlink the stale socket via `SafeFsExecutor.safeUnlinkSync`, which throws `SourceTreeGuardError`. The supervisor's bind-failure escalation triggers (`Bind-failure escalation armed: N consecutive spawns failed before binding`). After 5 retries the supervisor enters 300s cooldown. Server never binds. Tunnel returns 502.
+
+**Observed before** (Echo, 2026-05-21T16:46Z, sample from `logs/lifeline-launchd.err`):
+
+```
+Error: stale socket at /Users/justin/.instar/agents/echo/.instar/listener.sock could not be unlinked:
+  Refusing to run src/threadline/WakeSocketServer.ts:stale-socket-recovery against the instar source tree
+  (requested dir: /Users/justin/.instar/agents/echo/.instar/listener.sock,
+   resolved git root: /Users/justin/.instar/agents/echo).
+[Supervisor] Bind-failure escalation armed: 34 consecutive spawns failed before binding.
+[Supervisor] Max restart attempts (5) reached. Cooling down for 300s before retrying.
+```
+
+**Observed after** (same agent, hot-patched 2026-05-21T17:00Z with the same source change applied to `shadow-install/.../SafeFsExecutor.js`):
+
+```
+$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:4042/health   # 5 times, 3s apart
+200
+200
+200
+200
+200
+
+$ curl -s -o /dev/null -w "%{http_code}\n" https://echo.dawn-tunnel.dev/health
+200
+```
+
+Tunnel-fronted dashboard at `https://echo.dawn-tunnel.dev/dashboard?session=<...>` returns HTTP 200 with the live dashboard HTML (316KB). The bind-failure escalation never fires. The audit log shows the carve-out's positive signal:
+
+```
+$ grep agent-runtime-state-carveout .instar/audit/destructive-ops.jsonl | head -3
+{"timestamp":"2026-05-21T17:00:23.118Z","executor":"fs","operation":"WakeSocketServer.ts:stale-socket-recovery","verb":"safeUnlinkSync","target":".../.instar/listener.sock","outcome":"allowed","reason":"agent-runtime-state-carveout","caller":"..."}
+```

package/upgrades/1.2.8.md

@@ -0,0 +1,69 @@
+# Upgrade Guide — v1.2.8 (nuke --here for project-local installs)
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**New: `instar nuke --here` removes a project-local install.**
+
+`instar nuke <name>` has always handled standalone agents (the ones
+at `~/.instar/agents/<name>/`). There was no equivalent for the
+project-bound install method — the result of `npx instar setup`
+inside a project directory. Removing one of those required a manual
+multi-path `rm -rf` of `.instar/`, `.claude/` (or `.codex/`),
+`.mcp.json`, and the identity-shadow files, plus the invisible parts:
+the tmux server, the launchd plist, the agent-registry entry, the
+secret backup.
+
+`instar nuke --here` collapses that into one command. Run it inside
+the project directory and it:
+
+1. Stops the `<projectName>-server` tmux session and any spawned
+   `<projectName>-*` sessions.
+2. Removes the launchd / systemd auto-start entry for that project.
+3. Backs up secrets (Telegram token, dashboard PIN, etc.) so a
+   subsequent `npx instar setup` in the same directory auto-restores
+   them, identical to the standalone reinstall flow.
+4. Unregisters the directory from the agent registry.
+5. Removes filesystem artifacts:
+   - Always: `.instar/`, `.claude/`, `.codex/`, `.mcp.json`,
+     `instar.config.json`.
+   - For `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`: git decides.
+     Tracked-clean → kept (pre-existing). Tracked-modified → restored
+     to `HEAD`. Untracked → deleted.
+
+Safety:
+- Refuses to run inside the instar source repo (checks `package.json`
+  name and `src/cli.ts` presence).
+- Refuses to run when `.instar/config.json` is absent.
+- Confirmation prompt by default; bypassed with `--yes`.
+
+Spec: `specs/dev-infrastructure/nuke-here.md`.
+ELI16: `specs/dev-infrastructure/nuke-here.eli16.md`.
+Side-effects review: `upgrades/side-effects/feat-nuke-here.md`.
+
+## What to Tell Your User
+
+If you want to test installing instar a few different ways in a
+project directory, there is now a built-in uninstall mode that runs
+inside the project. It tears down everything instar installed in one
+shot. Files you had committed before the install are kept (or
+restored from git HEAD), so it is safe to run on a repo that already
+had its own identity-shadow files.
+
+## Summary of New Capabilities
+
+- New CLI mode: `instar nuke --here` (project-local install teardown).
+- Standalone form `instar nuke <name>` unchanged.
+
+## Evidence
+
+14 new unit tests in `tests/unit/nuke-here.test.ts` cover the source-
+repo refusal check (four cases), the shadow-file classifier (four
+cases of pre-existing-vs-instar-added-vs-untracked-vs-modified), and
+the end-to-end filesystem teardown against tmpdirs (six cases
+including the missing-config refusal path). All pass locally and in CI.
+
+Manual end-to-end verification will run against the `instar-codey`
+test clone after publish.

package/upgrades/side-effects/feat-nuke-here.md

@@ -0,0 +1,123 @@
+# Side-effects review — `instar nuke --here`
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER — project-bound installs had no uninstall command at all;
+operators had to manually `rm -rf` the install artifacts (and forget the
+tmux server / launchd plist / registry entry / secret backup).
+
+After: precisely targeted. The new mode requires explicit `--here`, runs
+only when `.instar/config.json` exists in the target dir, and refuses
+to run inside the instar source repo. No over-block: the standalone
+form is unchanged, and operators who never pass `--here` see no
+behavior change.
+
+## 2. Level-of-abstraction fit
+
+`nukeHere(options)` is a sibling function to the existing `nukeAgent`
+in the same file. Both share the same Step 1-4 shape (tmux teardown,
+auto-start removal, secret backup, registry unregister) and the same
+SafeFsExecutor / SafeGitExecutor helpers for the filesystem half. The
+new git-tracked-vs-untracked decision for identity-shadow files
+delegates to `git ls-files --error-unmatch` + `git status --porcelain`
+— the existing single source of truth for tracking state. No new
+abstraction layer.
+
+## 3. Signal vs Authority compliance
+
+- The `--here` flag is the operator-intent SIGNAL.
+- `.instar/config.json` presence is the AUTHORITY for "is there an
+  install here to remove."
+- `package.json` `name === "instar"` + `src/cli.ts` presence is the
+  AUTHORITY for "is this the instar source repo (refuse)."
+- For identity-shadow files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`):
+  - `git ls-files --error-unmatch <file>` is the AUTHORITY for
+    "tracked at HEAD."
+  - `git status --porcelain <file>` is the AUTHORITY for "has working-
+    tree diff."
+  No new heuristic is invented; existing git tooling is the single
+  source of truth.
+
+## 4. Interactions with adjacent systems
+
+- **Standalone `nuke <name>`** — unchanged. Same function, same flags,
+  same prompts. The CLI route was changed from `nuke <name>` (required)
+  to `nuke [name]` (optional) plus a `--here` flag — when `--here` is
+  set, the positional is ignored; when `--here` is not set and no name
+  is given, usage is printed and the command exits 1.
+
+- **`uninstallAutoStart(projectName)`** in `src/commands/setup.ts` —
+  reused as-is. The function is already idempotent and project-name-
+  scoped; the new mode hands it the same `projectName` the install
+  wrote into `.instar/config.json`.
+
+- **`SecretManager.backupFromConfig`** — reused exactly as
+  `nukeAgent` does, with the same field mapping (Telegram token, chat
+  id, authToken, dashboardPin, tunnel token). This means a subsequent
+  `npx instar setup` in the same directory will auto-restore secrets,
+  matching the standalone reinstall flow.
+
+- **`unregisterAgent(dir)`** — reused. Operates on the absolute
+  directory path, identical contract.
+
+- **`SafeFsExecutor.safeRmSync`** — used for every delete. The recent
+  source-tree-guard carve-out (PR #294) for `<root>/.instar/` runtime
+  artifacts means `.instar/` deletions inside an agent's project dir
+  do not trip the guard.
+
+- **`SafeGitExecutor`** — used for `ls-files`, `status`, and
+  `checkout HEAD --`. All three are already allow-listed git ops; the
+  audit trail records the new operations under
+  `src/commands/nuke.ts:nukeHere-*`.
+
+- **Tmux session naming** (`<projectName>-server`, `<projectName>-*`) —
+  identical to `nukeAgent`. The new function uses the same
+  `isTmuxSessionRunning` helper that already exists in the file.
+
+## 5. Rollback cost
+
+Trivial. One new exported function in `src/commands/nuke.ts`, one
+modified CLI registration in `src/cli.ts`, one unit test, one ELI16
++ spec + this artifact. `git revert` restores the prior CLI surface;
+no other surface depends on `--here`. Standalone nuke users see no
+change either way.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backwards-compatible.
+
+- `instar nuke <name>` still works (positional became optional, but
+  passing a name still routes to `nukeAgent`).
+- `instar nuke` with no arguments now prints usage and exits 1 —
+  before, commander would error out with a "missing required argument"
+  message. Same exit-1 outcome, slightly clearer error.
+- `instar nuke --here` is a new code path; no prior agent has it, so
+  there's nothing to drift against.
+- No config file changes, no template changes, no hook changes, no
+  built-in skill changes — therefore no `PostUpdateMigrator` work
+  needed (Migration Parity Standard not triggered: this is a CLI-only
+  surface change, not an agent-installed-files change).
+
+## 7. Authorization / Trust posture
+
+No new authority. The command only acts on:
+
+- The current working directory (or `--dir` override) — same scope as
+  every other instar CLI command that takes a `--dir` flag.
+- The launchd plist / agent registry entry / secret store keyed to
+  the **projectName the install itself wrote**. The command cannot
+  delete data belonging to a different project name; it reads
+  `projectName` from `.instar/config.json` in the target dir.
+
+The source-repo refusal check is an additional safety floor that
+exists only to protect the instar development checkout — a one-way
+guardrail with no positive authority.
+
+## Outcome
+
+Ship. Closes the project-local uninstall gap, matches the standalone
+flow's safety posture, no new authority, no migration work, and
+removes the manual-rm-rf trap operators hit today during install
+testing.

package/upgrades/side-effects/safe-fs-agent-state-carveout.md

@@ -0,0 +1,98 @@
+# Side-effects review — SafeFsExecutor agent-runtime-state carve-out
+
+**Scope**: `SafeFsExecutor.guard()` now bypasses `assertNotInstarSourceTree`
+when the canonicalized target path is under a `.instar/` subdirectory of the
+source root. New helper `isUnderAgentRuntimeState()` performs the check.
+
+**Root cause of original issue**: When instar is deployed in "agent" mode (e.g.
+`~/.instar/agents/<name>/`), the agent dir IS a checkout of the instar source
+— same `.git`, same `.instar-source-tree` marker file, same `package.json`
+with `name: "instar"`. The source-tree guard's three layers (marker, canonical
+remote URL, source-identity signature) all correctly identify the agent root
+as the instar source. But the agent's runtime artifacts live at
+`<root>/.instar/` (sockets, locks, logs, audit trail, shared-state JSONL),
+which are explicitly `.gitignored` and are NOT source code. Destructive ops
+on those paths (e.g., `WakeSocketServer.stale-socket-recovery` unlinking a
+stale `listener.sock`) are a normal part of operation, not a 2026-04-22-class
+incident.
+
+Before this fix, every unlink-the-stale-socket attempt in agent mode failed
+with `SourceTreeGuardError`, the supervisor declared the server unhealthy,
+escalated to its bind-failure recovery path, force-rebuilt better-sqlite3 on
+every restart cycle, and the agent never bound to its socket. Observed in
+the field 2026-05-21 on dawn-macbook Echo, immediately after v1.2.4.
+
+**Files touched**:
+- `src/core/SafeFsExecutor.ts` — added `isUnderAgentRuntimeState()` helper
+  (interior-`/.instar/`-segment predicate, returns false when the marker is
+  trailing) and a carve-out branch in `guard()` that audits as `allowed` with
+  `reason: "agent-runtime-state-carveout"` when the predicate matches.
+- `tests/unit/SafeFsExecutor.test.ts` — added `SafeFsExecutor agent-runtime-state
+  carve-out` describe block with five tests (3 positive carve-outs, 2 still-blocked).
+- `upgrades/NEXT.md` — release notes.
+
+**Under-block (what's no longer caught)**: Operations on individual files and
+nested directories under `<source-root>/.instar/<anything>`. Specifically:
+
+1. **`.instar/listener.sock` (and other `.sock` files there)**. `.sock` files
+   are agent runtime IPC endpoints; the project's own `.gitignore` covers the
+   parent directories these would live under. The 2026-04-22 incident did not
+   touch this path; risk is low.
+
+2. **`.instar/lifeline.lock` (and other lockfiles there)**. Lockfile cleanup
+   is mandatory for any LaunchAgent-style supervisor. Under-block is required
+   for the supervisor to recover from stale locks.
+
+3. **`.instar/state/*`, `.instar/logs/*`, `.instar/audit/*`,
+   `.instar/instar-dev-traces/*`**. All four directories appear in the
+   project's `.gitignore`. None contain source code. Destructive ops on stale
+   entries here are normal house-cleaning. Under-block is intentional.
+
+4. **`.instar/shadow-install/`**. The agent's pinned vendored copy of the
+   instar package. Modified by `instar update` and `AutoUpdater`. Treated as
+   runtime state, not source. The auto-updater needs to wipe-and-reinstall
+   this directory; the carve-out unblocks that path under agent mode.
+
+The carve-out is intentionally interior-only — the `.instar` directory itself
+is still protected by the guard. A `safeRmSync` targeting `<source-root>/.instar`
+still throws `SourceTreeGuardError`. This is verified by the
+`still BLOCKS rm on the .instar directory itself (not its contents)` test.
+
+**What stays caught**:
+
+1. **All source files at the tree root** — anything in `src/`, `tests/`,
+   `docs/`, `scripts/`, root-level files like `package.json`, `README.md`,
+   `tsconfig.json`. The 2026-04-22 incident damage (`README.md`, `src/auth.ts`,
+   `src/middleware.ts`) is still blocked. Verified by the `still BLOCKS unlink
+   on source files at the tree root` test.
+
+2. **The `.instar` directory itself** — `safeRmSync` on `<root>/.instar` with
+   `recursive: true` is still rejected. The carve-out predicate requires
+   `/.instar/` followed by at least one additional path segment; `<root>/.instar`
+   alone does not satisfy that.
+
+3. **All three detection layers** are unchanged. The marker file, canonical
+   remote URL, and source-identity signature checks all still run for paths
+   outside `.instar/`.
+
+**Audit trail**: The carve-out leaves a positive `outcome: "allowed"` entry
+with `reason: "agent-runtime-state-carveout"` in `.instar/audit/destructive-ops.jsonl`
+on every match. This makes the false-positive rate (operations that would have
+been wrongly blocked before) directly observable: `grep
+agent-runtime-state-carveout .instar/audit/destructive-ops.jsonl | wc -l`.
+Operators can confirm the carve-out is being exercised exactly when expected
+(WakeSocketServer recovery, AutoUpdater install, etc.) and not in unexpected
+places.
+
+**Tests**: 5 new tests under `describe('SafeFsExecutor agent-runtime-state
+carve-out', …)` in `tests/unit/SafeFsExecutor.test.ts`. All 17 SafeFsExecutor
+tests pass (12 existing + 5 new). No existing tests modified.
+
+**Spec impact**: `docs/specs/DESTRUCTIVE-TOOL-TARGET-GUARDS-SPEC.md` is not
+modified by this change. The spec's tactical-guardrail design is preserved
+exactly. The carve-out lives one layer below the guard (in `SafeFsExecutor`)
+and is documented in the new helper's doc-comment with the reasoning above.
+
+**Rollback**: Revert this commit. The carve-out is a single function and a
+single branch in `guard()`. Rollback restores the brittle-block behavior
+exactly; no migration needed.