@haven_ai/connect 0.0.0-dev.202609182134.2018100 → 0.0.0-dev.202609190328.55ffe63

package/README.md

@@ -109,7 +109,7 @@ report stays `version: 1`; `level` is additive.
 | Level | Meaning | Example |
 | --- | --- | --- |
 | `ok` | Nothing to say. | The installed signer matches the connector's pin. |
-| `advisory` | Worth reading; nothing is broken. Exit 0. | `signer_runtime`: the install is intact but behind the pinned version ("intact, but outdated" — both versions named, `--repair` offered). `superseded_agents` on a recognised runtime with no config file the connector can read (Claude Code, `other`): a second live key is reported, and the check says why "wired" cannot be verified from this machine. |
+| `advisory` | Worth reading; nothing is broken. Exit 0. | `signer_runtime`: the install is intact but behind the pinned version ("intact, but outdated" — both versions named, `--repair` offered); `signer_runtime_unused` (#3123): runtime directories nothing references. `superseded_agents` on a recognised runtime with no config file the connector can read (Claude Code, `other`): a second live key is reported, and the check says why "wired" cannot be verified from this machine. |
 | `failed` | A real failure with one repair action. Exit 1. | A stale or empty runtime directory; a live key in a directory the runtime's config demonstrably does not use. |
 
 What stays blocking is live spend authority: a directory whose stored key
@@ -194,10 +194,74 @@ It tombstone-first (so a stale long-lived host still hears `HAVEN-TOMBSTONE`,
 never a masked `ENOENT`), then removes THAT agent's hosted + signer pair from
 every runtime config it appears in (Hermes YAML, Codex TOML, the Cursor / VS
 Code / Insiders / Claude Desktop JSON configs), plus the Hermes dotenv API-key
-line — bare `MCP_HAVEN_API_KEY` or named `MCP_HAVEN_<SLUG>_API_KEY`. Finally it
-tears down the target directory's local key material (signer key, any abandoned
-re-key, the stored API key) so `--doctor` reports `retired`, not the
-still-spend-capable `superseded`; the #2155 tombstone mirror keeps the record.
+line — bare `MCP_HAVEN_API_KEY` or named `MCP_HAVEN_<SLUG>_API_KEY`. Then it
+decides about the target directory's local key material (signer key, any
+abandoned re-key, the stored API key) — and since #3123 it **asks before it
+destroys**.
+
+#### Teardown refuses before destroying the recovery credential (#3123)
+
+A revoked agent's API key and delegate signature are exactly what the
+sweep-recovery routes still accept — they are the only local means of
+recovering a stranded delegate balance. So after the wiring is removed,
+`--unwire` runs the one read it has (the identity probe, `GET
+/machine-payments/agent` with the stored key — no new network call, no
+backend change) and **refuses to destroy the key material on every answer**:
+
+| Probe | What it means | What `--unwire` does |
+| --- | --- | --- |
+| `ok` | The agent is still active: its key still spends. | Refuses; tells you to revoke on the Haven agent page (connect never revokes), then re-run. |
+| `unauthorized` | The key no longer authenticates on normal routes (revoked, archived, paused, pending approval, rotated, or not a key the backend knows — it does not say which). | Refuses; says plainly that a stranded balance **may** exist and the connector **cannot check**; recover first (`haven_sweep_delegate`, or the agent page). |
+| `network_error` / `bad_response` | Could not verify. | Refuses: unknown is not "safe to delete". Retry. |
+| *(no stored API key + URL)* | Nothing the recovery routes would accept. | Proceeds, unprobed — the pre-#3123 shape. |
+
+The refusal is exit 1 with the wiring already gone; the key stays in the
+0o600 credential file only (the config and Hermes-env copies are scrubbed
+first, so a refusal leaves the key in the credential file and in any config
+this run could not clean — those are reported `✗` above, never silently),
+and `--doctor` keeps reporting the directory as `superseded` until the key is
+revoked or destroyed — that is the honest state. **`--destroy-key-material`**
+proceeds on every answer, states what it destroyed and that local recovery
+of a stranded balance ends with it. In `--json` the record carries an
+additive `teardown: { status: destroyed | retained | forced, probe, detail,
+remedy? }`.
+
+The `claude-code` copy of the key (written by `claude mcp add`, into a config
+the connector does not own) is out of scope for `--unwire`, as it always was:
+remove it with `claude mcp remove haven` / `haven-signer` (or the named
+pair) yourself; `--doctor --runtime claude-code` cannot see it either.
+
+### Pruning signer-runtime directories (`--prune-signer-runtimes`, #3123)
+
+Every pinned version — and, since #2424, every `HAVEN_*_SPEC` override — gets
+its own `~/.haven/signer-runtime/<key>/`, and nothing reclaimed them:
+
+```
+npx @haven_ai/connect@<channel> --prune-signer-runtimes --dry-run
+npx @haven_ai/connect@<channel> --prune-signer-runtimes
+```
+
+It walks the root (so override-keyed `override-<hash>` directories are seen,
+not only manifest versions), **keeps** every directory any credential
+directory names — through its `signer-runtime.json` or through the path its
+wrapper launches — wired, superseded or retired; the prune never decides who
+is live — and the connector's current pin (what
+`--repair` installs), and removes the rest, reporting each with a #3121
+level: kept/removed are `ok`, a dry-run candidate is an `advisory`, a removal
+that failed (a signer process still holding the directory open on a platform
+that refuses the unlink) is `failed` and the only thing that exits 1. On
+POSIX a running signer keeps its open files until it restarts, and since
+only directories no sidecar and no wrapper names go, a configured agent is
+not started against a removed one. The prune trusts those two reference
+sources (the sidecar's `runtime_directory` and the path the wrapper
+launches — so a directory whose sidecar is missing or corrupt but whose
+wrapper is intact keeps its runtime); it reads the default agents root AND
+the parent of an explicit `--credentials-dir`, a union, never either/or. It
+is its own flag — never part of `--repair`, never automatic; `--doctor`
+reports unused directories as an advisory (`signer_runtime_unused`) that
+names this command — names only; sizes come from `--dry-run`, and a kept
+directory is never sized (its row says "not sized"). `--json` emits
+`{ pruned: true, version: 1, root, dry_run, level, removed, reclaimed_bytes, entries[] }`.
 
 An **unnamed** pair (`haven` / `haven-signer`) is shared by every unnamed agent
 and is only removed when this directory's wrapper is the one the config
@@ -387,9 +451,11 @@ already-configured machine behaves as follows (characterized in
   managed Codex/Hermes equivalents) and re-points them at the new agent's
   credentials; unrelated MCP servers and configuration are preserved. Once
   the runtime install has actually completed, each superseded directory is
-  tombstoned and its local key files removed — the same teardown `--unwire`
-  performs — so `--doctor` reads it as `retired` rather than still
-  spend-capable. If the install ends with an error code the retirement is
+  tombstoned and its local key files removed — the unconditional key-material
+  teardown; `--unwire` itself runs that teardown only when its #3123 probe says
+  there is nothing to preserve, and `--replace` deliberately does not probe
+  (the owner has just chosen to overwrite; see the #3119 follow-up) — so
+  `--doctor` reads it as `retired` rather than still spend-capable. If the install ends with an error code the retirement is
   **skipped**, because the old wiring may still be the only working one; the
   outcome's `superseded_agents_retired_locally` says which happened and
   `retired_agent_ids` names exactly the directories it reached. With

package/dist/cli.cjs

@@ -567,9 +567,9 @@ var init_runtime_manifest = __esm({
       mcpPackage: "@haven_ai/mcp",
       mcpVersion: mcp.MCP_VERSION,
       sdkPackage: "@haven_ai/sdk",
-      sdkVersion: "0.0.0-dev.202609182134.2018100",
+      sdkVersion: "0.0.0-dev.202609190328.55ffe63",
       signerPackage: "@haven_ai/signer",
-      signerVersion: "0.0.0-dev.202609182134.2018100",
+      signerVersion: "0.0.0-dev.202609190328.55ffe63",
       // Sourced from the SDK, never a literal (#1161). This field read '20.0.0'
       // while every package's `engines` said `>=24` and the docs said `>=24.0.0`,
       // so the guard that was supposed to enforce the floor waved Node v23 through
@@ -1538,7 +1538,7 @@ async function probeLocalSignerCredential(signerPath) {
   }
 }
 async function probeLocalMcpTools(command, args, requiredTools, timeoutMs = 1e4) {
-  return new Promise((resolve9) => {
+  return new Promise((resolve10) => {
     const child = child_process.spawn(command, args, { stdio: ["pipe", "pipe", "ignore"] });
     let stdout = "";
     let settled = false;
@@ -1550,7 +1550,7 @@ async function probeLocalMcpTools(command, args, requiredTools, timeoutMs = 1e4)
       settled = true;
       clearTimeout(timeout);
       child.kill();
-      resolve9(result);
+      resolve10(result);
     };
     const timeout = setTimeout(() => finish({ status: "timeout" }), timeoutMs);
     child.on("error", () => finish({ status: "process_error" }));
@@ -3195,8 +3195,51 @@ async function unwireAgent(input) {
       }
     }
   }
-  await teardownLocalKeyMaterial(input.directory, identity);
-  return { directory: input.directory, agentId, slug, tombstoned, runtimes };
+  const teardown = await decideTeardown(identity, input);
+  if (teardown.status !== "retained") await teardownLocalKeyMaterial(input.directory, identity);
+  return { directory: input.directory, agentId, slug, tombstoned, runtimes, teardown };
+}
+async function decideTeardown(identity, input) {
+  const ended = "Local recovery of a stranded delegate balance ends with it: the sweep-recovery routes accept only this agent's API key and delegate signature, and neither exists on this machine any more.";
+  if (!identity?.api_key || !identity.api_url) {
+    return {
+      status: input.destroyKeyMaterial ? "forced" : "destroyed",
+      probe: "not_probed",
+      detail: "No stored API key + API URL to probe with \u2014 nothing the sweep-recovery routes would accept, so nothing to preserve."
+    };
+  }
+  const probe = await (input.probeHostedIdentity ?? probeHostedAgentIdentity)(identity.api_key, identity.api_url, input.fetch);
+  if (input.destroyKeyMaterial) {
+    return {
+      status: "forced",
+      probe: probe.status,
+      detail: `Key material destroyed under ${DESTROY_FLAG} (probe: ${probe.status}): signer.json, any parked re-key, and the API key in identity.json.`,
+      remedy: ended
+    };
+  }
+  switch (probe.status) {
+    case "ok":
+      return {
+        status: "retained",
+        probe: "ok",
+        detail: "This agent is still ACTIVE on the backend: its API key and delegate key still carry spend authority, so destroying them would be a live spend-authority change. Key material kept in this directory (0o600); its MCP wiring above is gone.",
+        remedy: `Revoke the agent on the Haven agent page (connect never revokes), then re-run --unwire; or, to delete the key anyway, re-run with ${DESTROY_FLAG}.`
+      };
+    case "unauthorized":
+      return {
+        status: "retained",
+        probe: "unauthorized",
+        detail: "This key no longer authenticates on normal routes (revoked, archived, paused, pending approval, rotated, or not a key the backend knows \u2014 it does not say which). A stranded delegate balance MAY still exist and the connector CANNOT check: this directory may hold the only local credential the sweep-recovery routes would still accept. Key material kept.",
+        remedy: `Recover any stranded balance first (haven_sweep_delegate from a runtime still wired to this agent, or the Haven agent page), then re-run with ${DESTROY_FLAG} to remove the key material.`
+      };
+    default:
+      return {
+        status: "retained",
+        probe: probe.status,
+        detail: `Could not verify what this key is still good for (${probe.status}). Unknown is not "safe to delete": destroying it on a failed check would erase the evidence of a live key. Key material kept.`,
+        remedy: `Retry when the backend is reachable, or re-run with ${DESTROY_FLAG} to remove the key material regardless.`
+      };
+  }
 }
 async function tombstoneDirectoryIfAbsent(input) {
   if (await readOptionalText(path.join(input.directory, TOMBSTONE_FILENAME)) !== null) return false;
@@ -3217,9 +3260,10 @@ async function teardownLocalKeyMaterial(directory, identity) {
 async function readIdentityFile(directory) {
   return identityAt(directory);
 }
-var RUNTIMES;
+var RUNTIMES, DESTROY_FLAG;
 var init_unwire = __esm({
   "src/unwire.ts"() {
+    init_probes();
     init_config_writers();
     init_server_names();
     init_signer_runtime();
@@ -3233,6 +3277,7 @@ var init_unwire = __esm({
       { runtime: "vscode-insiders", label: "VS Code Insiders MCP config", kind: "json", serverRoot: "servers" },
       { runtime: "claude-desktop", label: "Claude Desktop config", kind: "json", serverRoot: "mcpServers" }
     ];
+    DESTROY_FLAG = "--destroy-key-material";
   }
 });
 
@@ -3244,6 +3289,174 @@ var init_rekey_messages = __esm({
   }
 });
 
+// src/prune-runtimes.ts
+var prune_runtimes_exports = {};
+__export(prune_runtimes_exports, {
+  normalizeRuntimePath: () => normalizeRuntimePath,
+  pruneSignerRuntimes: () => pruneSignerRuntimes,
+  referencedRuntimeDirectories: () => referencedRuntimeDirectories,
+  rollUpPruneLevel: () => rollUpPruneLevel,
+  signerRuntimeRoot: () => signerRuntimeRoot
+});
+function signerRuntimeRoot(homeDir) {
+  return path.join(homeDir, ".haven", "signer-runtime");
+}
+function classifyKey(key) {
+  if (key.startsWith("override-")) return "override";
+  if (key === MCP_RUNTIME_MANIFEST.signerVersion || /^\d+\.\d+\.\d+/.test(key)) return "version";
+  return "unknown";
+}
+async function directoryBytes(directory) {
+  let total = 0;
+  const walk = async (dir) => {
+    let entries = [];
+    try {
+      entries = await promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const path$1 = path.join(dir, entry.name);
+      if (entry.isDirectory()) await walk(path$1);
+      else if (entry.isFile()) {
+        try {
+          total += (await promises.stat(path$1)).size;
+        } catch {
+        }
+      }
+    }
+  };
+  await walk(directory);
+  return total;
+}
+async function normalizeRuntimePath(path$1) {
+  const resolved = path.resolve(path$1).replace(/[\\/]+$/, "");
+  try {
+    return await promises.realpath(resolved);
+  } catch {
+    return resolved;
+  }
+}
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+async function referencedRuntimeDirectories(homeDir, credentialsDir) {
+  const roots = /* @__PURE__ */ new Set([path.join(homeDir, ".haven", "agents")]);
+  if (credentialsDir) roots.add(path.dirname(path.resolve(credentialsDir)));
+  const referenced = /* @__PURE__ */ new Map();
+  const runtimeRoot = await normalizeRuntimePath(signerRuntimeRoot(homeDir));
+  const rootSpellings = [.../* @__PURE__ */ new Set([path.resolve(signerRuntimeRoot(homeDir)), runtimeRoot])];
+  const wrapperRe = new RegExp(`(?:${rootSpellings.map(escapeRegExp).join("|")})[\\/]+([^\\/'"\\s]+)`, "g");
+  const add = async (runtimeDirectory, by) => {
+    const key = await normalizeRuntimePath(runtimeDirectory);
+    const list = referenced.get(key) ?? [];
+    if (!list.includes(by)) list.push(by);
+    referenced.set(key, list);
+  };
+  for (const root of roots) {
+    let entries = [];
+    try {
+      entries = await promises.readdir(root);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const directory = path.join(root, entry);
+      try {
+        const sidecar = JSON.parse(await promises.readFile(path.join(directory, "signer-runtime.json"), "utf8"));
+        if (typeof sidecar.runtime_directory === "string" && sidecar.runtime_directory.length > 0) {
+          await add(sidecar.runtime_directory, directory);
+        }
+      } catch {
+      }
+      try {
+        const wrapper = await promises.readFile(path.join(directory, "bin", "haven-signer.mjs"), "utf8");
+        for (const match of wrapper.matchAll(wrapperRe)) await add(path.join(runtimeRoot, match[1]), directory);
+      } catch {
+      }
+    }
+  }
+  return referenced;
+}
+function rollUpPruneLevel(entries) {
+  if (entries.some((e) => e.level === "failed")) return "failed";
+  if (entries.some((e) => e.level === "advisory")) return "advisory";
+  return "ok";
+}
+async function pruneSignerRuntimes(input, deps = {}) {
+  const homeDir = deps.homeDir ?? os.homedir();
+  const root = signerRuntimeRoot(homeDir);
+  const measure = input.measure ?? true;
+  const referenced = await referencedRuntimeDirectories(homeDir, deps.credentialsDir);
+  const pin = await normalizeRuntimePath(path.join(root, MCP_RUNTIME_MANIFEST.signerVersion));
+  const remove = deps.rm ?? (async (directory) => promises.rm(directory, { recursive: true, force: false }));
+  const entries = [];
+  let keys = [];
+  try {
+    keys = (await promises.readdir(root, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+  } catch {
+    return { version: 1, root, dryRun: input.dryRun, entries, removed: 0, reclaimedBytes: 0, level: "ok" };
+  }
+  let removed = 0;
+  let reclaimedBytes = 0;
+  for (const key of keys) {
+    const directory = path.join(root, key);
+    const normalized = await normalizeRuntimePath(directory);
+    const referencedBy = referenced.get(normalized) ?? [];
+    const kind = classifyKey(key);
+    if (referencedBy.length > 0 || normalized === pin) {
+      entries.push({
+        directory,
+        key,
+        kind,
+        bytes: 0,
+        referencedBy,
+        action: "kept",
+        level: "ok",
+        detail: referencedBy.length > 0 ? `kept \u2014 named by ${referencedBy.length} credential director${referencedBy.length === 1 ? "y" : "ies"} (sidecar or wrapper)` : "kept \u2014 the connector's current pinned version (what --repair installs)"
+      });
+      continue;
+    }
+    const bytes = measure ? await directoryBytes(directory) : 0;
+    if (input.dryRun) {
+      entries.push({
+        directory,
+        key,
+        kind,
+        bytes,
+        referencedBy,
+        action: "would_remove",
+        level: "advisory",
+        detail: `would remove \u2014 no credential directory names it (${kind}-keyed)`
+      });
+      continue;
+    }
+    try {
+      await remove(directory);
+      removed += 1;
+      reclaimedBytes += bytes;
+      entries.push({ directory, key, kind, bytes, referencedBy, action: "removed", level: "ok", detail: `removed \u2014 no credential directory named it (${kind}-keyed)` });
+    } catch (err) {
+      entries.push({
+        directory,
+        key,
+        kind,
+        bytes,
+        referencedBy,
+        action: "failed",
+        level: "failed",
+        detail: `removal failed: ${err instanceof Error ? err.message : String(err)} \u2014 a signer process may still hold it open; stop it and re-run`
+      });
+    }
+  }
+  return { version: 1, root, dryRun: input.dryRun, entries, removed, reclaimedBytes, level: rollUpPruneLevel(entries) };
+}
+var init_prune_runtimes = __esm({
+  "src/prune-runtimes.ts"() {
+    init_runtime_manifest();
+  }
+});
+
 // src/rekey.ts
 var rekey_exports = {};
 __export(rekey_exports, {
@@ -4099,6 +4312,17 @@ async function runDoctor(input, deps = {}) {
   }
   const signerProcess = primaryChecksById.get("signer_process");
   if (signerProcess) checks.push(signerProcess);
+  const prune = await (deps.pruneSignerRuntimes ?? pruneSignerRuntimes)({ dryRun: true, measure: false }, { homeDir, credentialsDir: input.credentialsDir });
+  const unused = prune.entries.filter((entry) => entry.action === "would_remove");
+  if (unused.length > 0) {
+    checks.push({
+      id: "signer_runtime_unused",
+      label: "Unused signer-runtime directories",
+      level: "advisory",
+      detail: `${unused.length} signer-runtime director${unused.length === 1 ? "y" : "ies"} under ${prune.root} that no credential directory names: ${unused.map((entry) => entry.key).join(", ")}. Nothing is broken; they are left over from earlier pins or overrides (sizes: --prune-signer-runtimes --dry-run).`,
+      repair: `Run: ${RERUN} --prune-signer-runtimes (add --dry-run to list only).`
+    });
+  }
   const restart = restartRequiredForRuntime(input2.runtime, deps.env);
   checks.push({
     id: "restart",
@@ -4205,6 +4429,7 @@ async function runRepair(input, deps = {}) {
 var RERUN;
 var init_doctor = __esm({
   "src/doctor.ts"() {
+    init_prune_runtimes();
     init_runtime_manifest();
     init_probes();
     init_signer_runtime();
@@ -4518,7 +4743,7 @@ async function pathExists2(path) {
 init_unwire();
 init_local_mcp_runtime();
 init_runtime_manifest();
-var CONNECTOR_VERSION = "0.0.0-dev.202609182134.2018100";
+var CONNECTOR_VERSION = "0.0.0-dev.202609190328.55ffe63";
 var CONNECT_OUTCOME_SCHEMA_VERSION = 1;
 var failureOutcomesByError = /* @__PURE__ */ new WeakMap();
 function failureOutcomeFor(runtimeHint, error) {
@@ -5104,7 +5329,7 @@ function describeWaitBound(timeoutMs) {
 async function waitForBudgetApproval(api, setupId, apiKey, log, options = {}) {
   const intervalMs = options.intervalMs ?? 5e3;
   const timeoutMs = options.timeoutMs ?? 18e4;
-  const sleep = options.sleep ?? ((ms) => new Promise((resolve9) => setTimeout(resolve9, ms)));
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve10) => setTimeout(resolve10, ms)));
   const maxPolls = Math.max(1, Math.floor(timeoutMs / intervalMs));
   const remindEvery = Math.max(1, Math.floor(3e4 / intervalMs));
   let waitingAnnounced = false;
@@ -5243,6 +5468,9 @@ function parseArgs(argv, env = process.env) {
   let tombstoneReason;
   let tombstoneReplacedBy;
   let unwire;
+  let destroyKeyMaterial = false;
+  let pruneSignerRuntimes2 = false;
+  let dryRun = false;
   let unwireDir;
   let replace = false;
   for (let i = 0; i < argv.length; i += 1) {
@@ -5270,6 +5498,12 @@ function parseArgs(argv, env = process.env) {
         unwireDir = next;
         i += 1;
       }
+    } else if (arg === "--destroy-key-material") {
+      destroyKeyMaterial = true;
+    } else if (arg === "--prune-signer-runtimes") {
+      pruneSignerRuntimes2 = true;
+    } else if (arg === "--dry-run") {
+      dryRun = true;
     } else if (arg === "--reason") {
       tombstoneReason = requireValue(argv, ++i, arg);
     } else if (arg === "--replaced-by") {
@@ -5312,7 +5546,7 @@ function parseArgs(argv, env = process.env) {
     return { options, help, json, doctor, repair, tombstone, rekey };
   }
   if (replace) {
-    if (rekeyPhase || tombstoneDir || unwire || doctor || repair) {
+    if (rekeyPhase || tombstoneDir || unwire || doctor || repair || pruneSignerRuntimes2) {
       throw new Error("--replace belongs to a --setup run: it says what to do when the bare haven / haven-signer pair is already wired to another agent.");
     }
     if (options.serverName) {
@@ -5322,6 +5556,22 @@ function parseArgs(argv, env = process.env) {
     }
     options.replaceExistingWiring = true;
   }
+  if (destroyKeyMaterial && !unwire) {
+    throw new Error("--destroy-key-material only applies to --unwire.");
+  }
+  if (destroyKeyMaterial && unwire) unwire = { ...unwire, destroyKeyMaterial: true };
+  if (dryRun && !pruneSignerRuntimes2) {
+    throw new Error("--dry-run only applies to --prune-signer-runtimes.");
+  }
+  if (pruneSignerRuntimes2) {
+    if (unwire || tombstoneDir || rekeyPhase || doctor || repair) {
+      throw new Error("--prune-signer-runtimes is its own operation; run it alone.");
+    }
+    if (options.setupToken) {
+      throw new Error("--prune-signer-runtimes takes no --setup token; it reads stored state only.");
+    }
+    return { options, help, json, doctor, repair, tombstone, rekey, unwire, unwireDir, pruneSignerRuntimes: { dryRun } };
+  }
   if (rekey) {
     if (options.setupToken) {
       throw new Error("--rekey replaces an existing agent's key; it does not take --setup. Drop one of them.");
@@ -5443,6 +5693,12 @@ function helpText() {
     "                             API key are removed locally (record kept via the #2155 tombstone mirror) and",
     "                             nothing is ever revoked on the backend \u2014 that stays an owner action on the",
     "                             Haven agent page.",
+    "  --destroy-key-material     With --unwire: destroy the signer key + stored API key even when the agent",
+    "                             is still active or cannot be verified (#3123). Local sweep recovery ends.",
+    "  --prune-signer-runtimes    Remove ~/.haven/signer-runtime directories no credential directory references",
+    "                             (version- and override-keyed alike); --dry-run lists them. Exits 1 only on a",
+    "                             removal that failed (#3123).",
+    "  --dry-run                  With --prune-signer-runtimes: report, remove nothing.",
     "  --reason <text>            Reason recorded in the tombstone (with --tombstone or --unwire).",
     "  --replaced-by <agent-id>   Successor agent recorded in the tombstone (with --tombstone or --unwire).",
     "  --help                     Show this help.",
@@ -5516,13 +5772,13 @@ async function runCli(argv, io = {
   }
   if (parsed.tombstone) {
     const { writeAgentTombstone: writeAgentTombstone2 } = await Promise.resolve().then(() => (init_tombstone(), tombstone_exports));
-    const { readFile: readFile14 } = await import('fs/promises');
-    const { join: join12 } = await import('path');
+    const { readFile: readFile15 } = await import('fs/promises');
+    const { join: join13 } = await import('path');
     try {
       let agentId = "unknown";
       try {
         const identity = JSON.parse(
-          await readFile14(join12(parsed.tombstone.directory, "identity.json"), "utf8")
+          await readFile15(join13(parsed.tombstone.directory, "identity.json"), "utf8")
         );
         agentId = identity.agent_id ?? "unknown";
       } catch {
@@ -5560,20 +5816,22 @@ async function runCli(argv, io = {
   }
   if (parsed.unwire) {
     const { unwireAgent: unwireAgent2 } = await Promise.resolve().then(() => (init_unwire(), unwire_exports));
-    const { homedir: homedir10 } = await import('os');
-    const { join: join12 } = await import('path');
-    const homeDir = homedir10();
-    const root = parsed.options.credentialsDir ?? join12(homeDir, ".haven", "agents");
-    const directory = parsed.unwireDir ?? (parsed.options.serverName ? join12(root, parsed.options.serverName) : root);
+    const { homedir: homedir11 } = await import('os');
+    const { join: join13 } = await import('path');
+    const homeDir = homedir11();
+    const root = parsed.options.credentialsDir ?? join13(homeDir, ".haven", "agents");
+    const directory = parsed.unwireDir ?? (parsed.options.serverName ? join13(root, parsed.options.serverName) : root);
     try {
       const result = await unwireAgent2({
         directory,
         slug: parsed.options.serverName,
         reason: parsed.unwire.reason,
         replacedBy: parsed.unwire.replacedBy,
+        destroyKeyMaterial: parsed.unwire.destroyKeyMaterial,
         homeDir
       });
       const failures = result.runtimes.filter((r) => r.status === "refused" || r.status === "unreadable");
+      const retained = result.teardown.status === "retained";
       if (parsed.json) {
         io.stdout(
           `${redactSecrets(
@@ -5588,7 +5846,14 @@ async function runCli(argv, io = {
                 label: r.label,
                 status: r.status,
                 ...r.detail ? { detail: r.detail } : {}
-              }))
+              })),
+              // #3123: additive — what happened to the key material and why.
+              teardown: {
+                status: result.teardown.status,
+                probe: result.teardown.probe,
+                detail: result.teardown.detail,
+                ...result.teardown.remedy ? { remedy: result.teardown.remedy } : {}
+              }
             })
           )}
 `
@@ -5604,14 +5869,19 @@ async function runCli(argv, io = {
           io.stdout(redactSecrets(`  ${mark} ${r.label}: ${r.status}${r.detail ? ` \u2014 ${r.detail}` : ""}
 `));
         }
+        const t = result.teardown;
+        io.stdout(redactSecrets(`  ${t.status === "retained" ? "\u2717" : t.status === "forced" ? "!" : "\u2713"} Key material: ${t.status} (probe: ${t.probe}) \u2014 ${t.detail}
+`));
+        if (t.remedy) io.stdout(redactSecrets(`    \u21B3 ${t.remedy}
+`));
         io.stdout(
-          failures.length > 0 ? "  Some entries were NOT removed (\u2717 above). Re-run `--unwire` after resolving each refusal \u2014\n  it is idempotent.\n" : "  Verify: `--doctor --runtime <runtime>` per host should report this agent as `retired` with a\n  clean runtime-config check.\n"
+          failures.length > 0 ? "  Some entries were NOT removed (\u2717 above). Re-run `--unwire` after resolving each refusal \u2014\n  it is idempotent.\n" : retained ? "  The wiring is gone; the key material is not (\u2717 above). `--doctor` will keep reporting this directory\n  as `superseded` until the key is revoked or destroyed \u2014 that is the honest state.\n" : "  Verify: `--doctor --runtime <runtime>` per host should report this agent as `retired` with a\n  clean runtime-config check.\n"
         );
         io.stdout(
-          "Restart EVERY long-lived MCP host (gateway, TUI workers, editors): each holds the wiring snapshot\nfrom its own start time. This directory\u2019s local key material was removed and the tombstone\nrecord + #2155 mirror survive \u2014 but nothing was REVOKED on the backend. If you have not\nalready, revoke the agent on the Haven agent page to stop it spending entirely.\n"
+          "Restart EVERY long-lived MCP host (gateway, TUI workers, editors): each holds the wiring snapshot\nfrom its own start time. " + (retained ? "This directory\u2019s local key material was KEPT (see above); the tombstone\n" : "This directory\u2019s local key material was removed and the tombstone\n") + "record + #2155 mirror survive \u2014 but nothing was REVOKED on the backend. If you have not\nalready, revoke the agent on the Haven agent page to stop it spending entirely.\n"
         );
       }
-      return failures.length > 0 ? 1 : 0;
+      return failures.length > 0 || retained ? 1 : 0;
     } catch (err) {
       return failSubcommand(io, parsed.json, err, { unwired: false }, {
         code: "unwire_failed",
@@ -5619,6 +5889,57 @@ async function runCli(argv, io = {
       });
     }
   }
+  if (parsed.pruneSignerRuntimes) {
+    const { pruneSignerRuntimes: pruneSignerRuntimes2 } = await Promise.resolve().then(() => (init_prune_runtimes(), prune_runtimes_exports));
+    try {
+      const report = await pruneSignerRuntimes2(
+        { dryRun: parsed.pruneSignerRuntimes.dryRun },
+        { credentialsDir: parsed.options.credentialsDir }
+      );
+      if (parsed.json) {
+        io.stdout(`${redactSecrets(JSON.stringify({
+          pruned: true,
+          version: report.version,
+          dry_run: report.dryRun,
+          level: report.level,
+          root: report.root,
+          removed: report.removed,
+          reclaimed_bytes: report.reclaimedBytes,
+          entries: report.entries.map((e) => ({
+            key: e.key,
+            kind: e.kind,
+            bytes: e.bytes,
+            action: e.action,
+            level: e.level,
+            referenced_by: e.referencedBy,
+            detail: e.detail
+          }))
+        }))}
+`);
+      } else {
+        io.stdout(`Signer runtimes under ${report.root}${report.dryRun ? " (dry run \u2014 nothing removed)" : ""}:
+`);
+        if (report.entries.length === 0) io.stdout("  (none)\n");
+        for (const e of report.entries) {
+          const mark = e.level === "failed" ? "\u2717" : e.level === "advisory" ? "!" : e.action === "removed" ? "\u2713" : "\u2022";
+          const size = e.bytes > 0 ? `${Math.round(e.bytes / 1024 / 1024)} MB` : e.action === "kept" ? "not sized" : "0 MB";
+          io.stdout(redactSecrets(`  ${mark} ${e.key} (${e.kind}, ${size}): ${e.detail}
+`));
+        }
+        io.stdout(
+          report.dryRun ? `Would remove ${report.entries.filter((e) => e.action === "would_remove").length} director(y/ies); re-run without --dry-run to reclaim.
+` : `Removed ${report.removed} director(y/ies), reclaimed ${Math.round(report.reclaimedBytes / 1024 / 1024)} MB.
+`
+        );
+      }
+      return report.level === "failed" ? 1 : 0;
+    } catch (err) {
+      return failSubcommand(io, parsed.json, err, { pruned: false }, {
+        code: "prune_failed",
+        nextAction: "review_the_error_and_rerun_prune_which_is_idempotent"
+      });
+    }
+  }
   if (parsed.rekey) {
     const { startRekey: startRekey2, finishRekey: finishRekey2 } = await Promise.resolve().then(() => (init_rekey(), rekey_exports));
     const { restartGuidance: restartGuidance2 } = await Promise.resolve().then(() => (init_rekey_restart(), rekey_restart_exports));