harnery 0.35.0 → 0.37.0

package/src/commands/agents.ts

@@ -23,7 +23,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
@@ -44,7 +44,19 @@ import {
   resolveOwnerWithSource,
   sessionIdentityFromEnv,
 } from "../core/agents/index.ts";
-import { reopenLiveCoordinationGenerationV3 } from "../core/agents/live-authority-v3.ts";
+import {
+  bootstrapLiveCoordinationAuthorityV3,
+  LiveCoordinationAuthorityV3Error,
+  reopenLiveCoordinationGenerationV3,
+} from "../core/agents/live-authority-v3.ts";
+import {
+  isAddressableName,
+  MailboxCapacityError,
+  type QueueResult,
+  queueMailboxMessage,
+  suggestNames,
+} from "../core/agents/mailbox.ts";
+import { reconcileCoordinationV3 } from "../core/agents/reconcile-coordination-v3.ts";
 import {
   listSessionFinalizationRequestsV3,
   observeHostDisappearedV3,
@@ -56,6 +68,7 @@ import {
   SESSION_NAME_DISPLAY_NOTE,
   sessionNameDisplayPending,
 } from "../core/agents/session-name-display.ts";
+import { agentDisplayName } from "../core/agents/state/activity-log.ts";
 import {
   buildLifecycleSuggestedName,
   buildSuggestedName,
@@ -80,6 +93,10 @@ import type { EventTypeV3 } from "../core/events/v3/contract.ts";
 import { readEventV3ControlState } from "../core/events/v3/control.ts";
 import { projectCoordinationViewV3 } from "../core/events/v3/coordination-view.ts";
 import { liveInstanceIdV3 } from "../core/events/v3/live-routing.ts";
+import {
+  countSummarizedSinceV3,
+  listDiagnosticSummariesV3,
+} from "../core/events/v3/producers/diagnostic-summaries.ts";
 import {
   listHookIntakeGroupsV3,
   listHookIntakeRecordsV3,
@@ -92,7 +109,10 @@ import { readLedgerV3 } from "../core/events/v3/reader.ts";
 import { EVENT_V3_LEDGER_RELATIVE_ROOT } from "../core/events/v3/writer.ts";
 import type { RunQualitySnapshot, RunQualityStatus } from "../core/guard/index.ts";
 import { evaluateRunQualityIfDue } from "../core/guard/index.ts";
-import { readRuntimeContextUsage } from "../core/hooks/adapter/runtime-telemetry.ts";
+import {
+  readRuntimeContextTelemetry,
+  readRuntimeContextUsage,
+} from "../core/hooks/adapter/runtime-telemetry.ts";
 import { type RemoteMachine, readRemoteMachines } from "../core/presence/index.ts";
 import { registerContextCommand } from "./context.ts";
 
@@ -264,6 +284,7 @@ export function registerAgentsCommand(
   program: Command,
   emitParam: EmitContext,
   programContext?: HarneryProgramContext,
+  binName = resolveBinName(),
 ): void {
   emit = emitParam;
   const cmd = program
@@ -385,7 +406,7 @@ export function registerAgentsCommand(
     )
     .option(
       "--session-id <id>",
-      `Set the task on the heartbeat with this session_id directly, bypassing the ppid walk. Mirror of \`status --session-id\`: use it when the ppid walk can't resolve self (e.g. Cursor, whose shell tool calls don't descend from a pid-map-registered anchor). Discover the id via \`${resolveBinName()} agents list --json\`.`,
+      `Set the task on the heartbeat with this session_id directly, bypassing the ppid walk. Mirror of \`status --session-id\`: use it when the ppid walk can't resolve self (e.g. Cursor, whose shell tool calls don't descend from a pid-map-registered anchor). Discover the id via \`${binName} agents list --json\`.`,
     )
     .action((text: string[], opts: { sessionId?: string }) => {
       runSetTask(text.join(" "), opts);
@@ -422,7 +443,8 @@ export function registerAgentsCommand(
   cmd
     .command("reconcile")
     .description(
-      "Reconcile archive, idle, parent/run completion, stale, superseded, and host lifecycle signals into V3 session finalization.",
+      "Sweep the stale coordination cache, then reconcile archive, idle, parent/run " +
+        "completion, stale, superseded, and host lifecycle signals into V3 session finalization.",
     )
     .option("--watch", "Keep reconciling until interrupted")
     .option("--interval-seconds <n>", "Watch interval in seconds")
@@ -472,9 +494,10 @@ export function registerAgentsCommand(
   cmd
     .command("ping <name> <message...>")
     .description(
-      "Append a 'handoff' entry to a peer agent's journal. Body prefixed with " +
-        "`from agent-<me>:`. Use to leave actionable coordination notes for peers " +
-        "currently holding files you need.",
+      "Send a message to another agent by name. Works whether or not that agent " +
+        "is running: a live peer sees it on their next prompt, and a name with no " +
+        "live session gets it queued until a session of that name next starts. " +
+        "Only an unknown name is refused.",
     )
     .option("--json", "JSON output")
     .action((name: string, message: string[], opts: { json?: boolean }) => {
@@ -484,7 +507,7 @@ export function registerAgentsCommand(
   cmd
     .command("wait <name>")
     .description(
-      `Block until a peer agent releases files (their \`files_touched\` becomes empty, OR they exit). Pair with \`${resolveBinName()} agents ping\` to coordinate hand-offs.`,
+      `Block until a peer agent releases files (their \`files_touched\` becomes empty, OR they exit). Pair with \`${binName} agents ping\` to coordinate hand-offs.`,
     )
     .option(
       "--file <path>",
@@ -533,7 +556,7 @@ export function registerAgentsCommand(
     .command("health")
     .description(
       "One-screen coord-layer health rollup: heal events, council activity, " +
-        "zombie detection, and anomalies. Designed for " +
+        "heartbeat cache issues, and findings. Designed for " +
         "daily glance + dashboard ingestion. Reads .harnery/.",
     )
     .option("--since <window>", "Window (Nh | Nd). Default: 24h.", "24h")
@@ -567,12 +590,11 @@ export function registerAgentsCommand(
   cmd
     .command("heal")
     .description(
-      "Force a coord-layer recovery action on a specific agent. " +
-        "Kinds: pidmap (repair process attribution) and cache (rebuild the " +
-        "disposable V3 coordination cache from the authoritative ledger).",
+      "Repair the current session's disposable coordination cache from V3. " +
+        "Use explicit options to target another generation or repair process attribution.",
     )
-    .requiredOption("--owner <id>", "Target agent's instance_id")
-    .requiredOption("--kind <kind>", "pidmap | cache")
+    .option("--owner <id>", "Target agent's instance_id. Defaults to the current session.")
+    .option("--kind <kind>", "pidmap | cache. Defaults to cache.")
     .option(
       "--session-id <id>",
       "(--kind cache) native session id used to join the authoritative V3 generation.",
@@ -589,14 +611,26 @@ export function registerAgentsCommand(
         "when calling from outside Claude Code's Bash tool tree (e.g. " +
         "from cron or an external script).",
     )
+    .option(
+      "--quarantine-transaction <id>",
+      "Quarantine one irreconcilable prepared authority transaction after proving its event was never committed.",
+    )
+    .option(
+      "--approval-record-id <id>",
+      "Durable identifier for the operator approval authorizing transaction quarantine.",
+    )
+    .option("--yes", "Confirm the exact prepared transaction may be quarantined.")
     .option("--json", "JSON envelope output")
     .action(
       (opts: {
-        owner: string;
-        kind: string;
+        owner?: string;
+        kind?: string;
         sessionId?: string;
         adapter?: string;
         pid?: string;
+        quarantineTransaction?: string;
+        approvalRecordId?: string;
+        yes?: boolean;
         json?: boolean;
       }) => {
         runHeal(opts);
@@ -723,7 +757,7 @@ async function runSessionReconcile(opts: {
   }
   let stopped = false;
   do {
-    emit.data(reconcileSessionFinalizationV3(root));
+    emit.data(reconcileCoordinationV3(root));
     if (!opts.watch || stopped) return;
     await new Promise<void>((resolvePromise) => {
       const timer = setTimeout(resolvePromise, interval * 1_000);
@@ -935,14 +969,15 @@ function runIdentityAssume(
     });
     process.exit(1);
   }
-  if (!opts.sessionId) ensureCursorSession(root);
+  if (!opts.sessionId) ensureAdapterSession(root);
   const owner = opts.sessionId ?? resolveOwner();
   if (!owner) {
-    emit.error({
-      code: "no_pidmap_entry",
-      message:
+    emit.error(
+      sessionResolutionFailure(
+        root,
         "not in an agent session; ppid walk found no pid-map entry (pass --session-id to bypass)",
-    });
+      ),
+    );
     process.exit(1);
   }
   try {
@@ -1214,14 +1249,13 @@ function runWhoami(opts: { json?: boolean }): void {
     process.exit(1);
   }
 
-  ensureCursorSession(root);
+  ensureAdapterSession(root);
   const resolved = resolveOwnerWithSource();
   const myOwner = resolved.owner;
   if (!myOwner) {
-    emit.error({
-      code: "no_pidmap_entry",
-      message: "not in an agent session; ppid walk found no pid-map entry",
-    });
+    emit.error(
+      sessionResolutionFailure(root, "not in an agent session; ppid walk found no pid-map entry"),
+    );
     process.exit(1);
   }
 
@@ -1703,49 +1737,96 @@ function cursorEnvSessionId(): string | null {
   return raw.startsWith("bc-") && raw.length > 3 ? raw.slice(3) : raw;
 }
 
-function shouldBootstrapCursorSession(): boolean {
-  return process.env.CURSOR_AGENT === "1" && cursorEnvSessionId() !== null;
+interface CommandSessionBootstrap {
+  adapter: "claude-code" | "cursor" | "codex";
+  sessionId: string;
 }
 
-function ensureCursorSession(root: string): void {
-  if (!shouldBootstrapCursorSession()) return;
+function commandSessionBootstrap(): CommandSessionBootstrap | null {
+  const cursorSessionId = cursorEnvSessionId();
+  if (process.env.CURSOR_AGENT === "1" && cursorSessionId) {
+    return { adapter: "cursor", sessionId: cursorSessionId };
+  }
+  if (process.env.HARNERY_AGENT_COORD_BRIDGE?.trim() === "codex-wsl") {
+    const sessionId = sessionIdentityFromEnv();
+    if (sessionId) return { adapter: "codex", sessionId };
+  }
+  const claudeSessionId = process.env.CLAUDE_CODE_SESSION_ID?.trim();
+  if (claudeSessionId) {
+    return { adapter: "claude-code", sessionId: claudeSessionId };
+  }
+  return null;
+}
+
+function ensureAdapterSession(root: string): void {
+  const bootstrap = commandSessionBootstrap();
+  if (!bootstrap) return;
+  // Claude Code owns a reliable native SessionStart hook. Its environment is
+  // accepted by the explicit `agents heal` recovery path, but ordinary
+  // identity and status commands must not impersonate that hook. The heal
+  // bootstrap records derived provenance instead.
+  if (bootstrap.adapter === "claude-code") return;
   // Explicit owner override means the caller already knows who they are.
   // Bootstrapping sessionStart inherits that env into the child hook, which
   // re-projects a fresh heartbeat onto the override owner and can wipe an
   // assumed persona agent_id (seen under Cursor integration fixtures).
-  if (process.env.HARNERY_AGENT_COORD_OWNER?.trim()) return;
+  if (bootstrap.adapter === "cursor" && process.env.HARNERY_AGENT_COORD_OWNER?.trim()) return;
   if (resolveOwnerBySessionEnv(root)) return;
 
-  const sessionId = cursorEnvSessionId();
-  if (!sessionId) return;
   const agentHook = coordBinPath("agent-hook", root);
   if (!agentHook) return;
 
   const payload = JSON.stringify({
-    conversation_id: sessionId,
-    session_id: sessionId,
+    ...(bootstrap.adapter === "cursor" ? { conversation_id: bootstrap.sessionId } : {}),
+    session_id: bootstrap.sessionId,
     hook_event_name: "sessionStart",
     workspace_roots: [root],
     cwd: root,
-    composer_mode: "agent",
-    is_background_agent: false,
+    ...(bootstrap.adapter === "cursor"
+      ? { composer_mode: "agent", is_background_agent: false }
+      : { source: "resume" }),
   });
 
-  spawnSync("bash", [agentHook, "session-start", "--adapter", "cursor"], {
+  spawnSync("bash", [agentHook, "session-start", "--adapter", bootstrap.adapter], {
     input: payload,
     cwd: root,
     encoding: "utf8",
     timeout: 3000,
     env: {
       ...process.env,
-      HARNERY_AGENT_COORD_PLATFORM: "cursor",
+      HARNERY_AGENT_COORD_PLATFORM: bootstrap.adapter,
       HARNERY_COORD_ROOT_OVERRIDE: root,
-      CURSOR_SESSION_ID: sessionId,
-      CURSOR_CONVERSATION_ID: sessionId,
+      HARNERY_AGENT_COORD_SESSION_ID: bootstrap.sessionId,
+      ...(bootstrap.adapter === "cursor"
+        ? {
+            CURSOR_SESSION_ID: bootstrap.sessionId,
+            CURSOR_CONVERSATION_ID: bootstrap.sessionId,
+          }
+        : { CODEX_THREAD_ID: bootstrap.sessionId }),
     },
   });
 }
 
+function sessionResolutionFailure(
+  root: string,
+  fallbackMessage: string,
+): { code: string; message: string } {
+  if (!sessionIdentityFromEnv()) return { code: "no_pidmap_entry", message: fallbackMessage };
+  const control = readEventV3ControlState(root);
+  if (control.state !== "candidate" && control.state !== "active") {
+    const detail = `${control.state}:${control.reason}`;
+    return {
+      code: "event_v3_control_unavailable",
+      message: `the adapter session identity is present, but the V3 control state cannot accept session onboarding (${detail})`,
+    };
+  }
+  return {
+    code: "session_generation_unavailable",
+    message:
+      "the adapter session identity is present, but no current V3 session generation was available after onboarding",
+  };
+}
+
 function runReleaseClaim(path: string): void {
   const root = monorepoRoot();
   if (!root) {
@@ -1757,10 +1838,9 @@ function runReleaseClaim(path: string): void {
   }
   const myOwner = resolveOwner();
   if (!myOwner) {
-    emit.error({
-      code: "no_pidmap_entry",
-      message: "not in an agent session; ppid walk found no pid-map entry",
-    });
+    emit.error(
+      sessionResolutionFailure(root, "not in an agent session; ppid walk found no pid-map entry"),
+    );
     process.exit(1);
   }
   // Canonicalize: absolute paths under coordRoot get the prefix stripped;
@@ -1801,14 +1881,15 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
   // returns null by design, and erroring here orphans the session's first
   // ritual command. The env id carries the same trust as an explicit
   // --session-id, and set-task mints the heartbeat exactly as that path does.
-  if (!opts?.sessionId) ensureCursorSession(root);
+  if (!opts?.sessionId) ensureAdapterSession(root);
   const myOwner = opts?.sessionId ?? resolveOwner() ?? sessionIdentityFromEnv();
   if (!myOwner) {
-    emit.error({
-      code: "no_pidmap_entry",
-      message:
+    emit.error(
+      sessionResolutionFailure(
+        root,
         "not in an agent session; no session-id environment identity and the ppid walk found no pid-map entry (pass --session-id to bypass)",
-    });
+      ),
+    );
     process.exit(1);
   }
 
@@ -1897,14 +1978,15 @@ function runLifecycle(rawState: string, opts: { reason?: string; sessionId?: str
     process.exitCode = 1;
     return;
   }
-  if (!opts.sessionId) ensureCursorSession(root);
+  if (!opts.sessionId) ensureAdapterSession(root);
   const myOwner = opts.sessionId ?? resolveOwner() ?? sessionIdentityFromEnv();
   if (!myOwner) {
-    emit.error({
-      code: "no_pidmap_entry",
-      message:
+    emit.error(
+      sessionResolutionFailure(
+        root,
         "not in an agent session; ppid walk found no pid-map entry (pass --session-id to bypass)",
-    });
+      ),
+    );
     process.exitCode = 1;
     return;
   }
@@ -2079,14 +2161,15 @@ function runSuggestName(
 
   // Identity: prefer explicit --session-id (ppid-walk-free escape hatch, mirrors
   // `status`/`set-task`), fall back to the ppid walk for interactive shell use.
-  if (!opts.sessionId) ensureCursorSession(root);
+  if (!opts.sessionId) ensureAdapterSession(root);
   const myOwner = opts.sessionId ?? resolveOwner();
   if (!myOwner) {
-    emit.error({
-      code: "no_pidmap_entry",
-      message:
+    emit.error(
+      sessionResolutionFailure(
+        root,
         "not in an agent session; ppid walk found no pid-map entry (pass --session-id to bypass)",
-    });
+      ),
+    );
     process.exit(1);
   }
 
@@ -2158,14 +2241,15 @@ function runStatus(opts: {
 
   // Identity resolution: prefer explicit --session-id (hook-friendly), fall
   // back to ppid walk for interactive shell usage.
-  if (!opts.sessionId) ensureCursorSession(root);
+  if (!opts.sessionId) ensureAdapterSession(root);
   const myOwner = opts.sessionId ?? resolveOwner();
   if (!myOwner) {
-    emit.error({
-      code: "no_pidmap_entry",
-      message:
+    emit.error(
+      sessionResolutionFailure(
+        root,
         "not in an agent session; ppid walk found no pid-map entry (pass --session-id from a hook payload)",
-    });
+      ),
+    );
     process.exit(1);
   }
 
@@ -2207,7 +2291,7 @@ function runStatus(opts: {
     }
   }
 
-  emitEventV3({
+  const statusEmitted = emitEventV3({
     owner: myOwner,
     session: nativeSessionIdentity(hb, myOwner),
     adapter: normalizeAdapter(hb.platform),
@@ -2216,6 +2300,16 @@ function runStatus(opts: {
       status: opts.endTurn ? "end_turn_checked" : opts.json ? "json_checked" : "box_checked",
     },
   });
+  // The closing box is a success artifact. Never print it when the exact
+  // evidence enforced by the Stop hook did not reach the ledger.
+  if (opts.endTurn && !statusEmitted) {
+    emit.error({
+      code: "status_event_failed",
+      message: `the end-of-turn status event could not be recorded; no status box was issued; rerun \`${resolveBinName(root)} agents status --end-turn\``,
+    });
+    process.exitCode = 1;
+    return;
+  }
 
   let sessionEnd:
     | { state: "queued" | "already_requested"; request_id: string }
@@ -2285,10 +2379,7 @@ function runStatus(opts: {
   if (!ctxUsage) {
     ctxStr = "unavailable";
   } else if (ctxUsage.percentOnly) {
-    // Cursor reports percent only; absolutes are estimates against a hard-coded
-    // window. Show the percent + window estimate, marked as estimated.
-    const pct = Math.round((ctxUsage.used / ctxUsage.window) * 100);
-    ctxStr = `~${pct}% (Cursor; ${fmtTokens(ctxUsage.window)} window est.)`;
+    ctxStr = `${Math.round(ctxUsage.usedPercent)}% (Cursor first-party)`;
   } else {
     ctxStr = `${fmtTokens(ctxUsage.used)} / ${fmtTokens(ctxUsage.window)} (${Math.round(
       (ctxUsage.used / ctxUsage.window) * 100,
@@ -2296,7 +2387,7 @@ function runStatus(opts: {
   }
 
   const timeStr = formatLocalTime(new Date());
-  const displayName = `agent-${hb.name || "unknown"}`;
+  const displayName = agentDisplayName(hb.instance_id, hb.name);
 
   // Council pending: list of council IDs where this agent is a member of an
   // active council in `open` round_status without a contribution to that round.
@@ -2340,8 +2431,8 @@ function runStatus(opts: {
       })),
     })),
     pending_councils: pendingCouncils,
-    context_used: ctxUsage?.used ?? null,
-    context_window: ctxUsage?.window ?? null,
+    context_used: ctxUsage && "used" in ctxUsage ? ctxUsage.used : null,
+    context_window: ctxUsage && "window" in ctxUsage ? ctxUsage.window : null,
     timestamp_iso: new Date().toISOString(),
     timestamp_local: timeStr,
     ...(quality ? { quality } : {}),
@@ -2485,15 +2576,17 @@ export function collectStatusPeerHealth(
   root: string,
   myOwner: string,
   nowMs = Date.now(),
+  readRows: (root: string) => StatusPeerHeartbeat[] = readLiveCoordinationRows,
+  freshnessSeconds = freshnessCutoffSecs(),
 ): { livePeers: StatusPeerHeartbeat[]; stale: number } {
   let rows: StatusPeerHeartbeat[] = [];
   try {
-    rows = readLiveCoordinationRows(root);
+    rows = readRows(root);
   } catch {
     // V3 authority failures must not resurrect disposable cache rows.
   }
 
-  const cutoffMs = nowMs - freshnessCutoffSecs() * 1000;
+  const cutoffMs = nowMs - freshnessSeconds * 1000;
   const livePeers: StatusPeerHeartbeat[] = [];
   let stale = 0;
   for (const peer of rows) {
@@ -2515,85 +2608,28 @@ function fmtTokens(n: number): string {
 function readContextUsage(
   sessionId: string,
   platform?: string | null,
-): { used: number; window: number; percentOnly?: boolean } | null {
+):
+  | { used: number; window: number; percentOnly?: false }
+  | { usedPercent: number; percentOnly: true }
+  | null {
   if (!sessionId) return null;
   // Dispatch by platform: Codex's JSONL shape is different from Claude Code's
   // (event_msg/response_item vs user/assistant), and Codex transcripts live
   // under ~/.codex/sessions/YYYY/MM/DD/ rather than ~/.claude/projects/.
-  // Cursor doesn't surface token counts in its transcript JSONL but DOES
-  // store `contextUsagePercent` per composer in workspaceStorage's state.vscdb;
-  // readCursorContextUsage reads that via bun:sqlite (percent-only).
+  // Cursor stores a first-party percentage in workspaceStorage. The shared
+  // runtime reader returns it without fabricating a token denominator.
   if (platform === "codex") return readRuntimeContextUsage("codex", sessionId);
-  if (platform === "cursor") return readCursorContextUsage(sessionId);
-  return readRuntimeContextUsage("claude-code", sessionId);
-}
-
-function readCursorContextUsage(
-  sessionId: string,
-): { used: number; window: number; percentOnly: true } | null {
-  // Cursor stores per-chat (composer) context usage as a percent in each
-  // workspace's state.vscdb at ItemTable.composer.composerData. The value
-  // is a JSON blob with .allComposers[].contextUsagePercent. We find the
-  // composer matching the agent's session_id (Cursor uses session_id == composerId
-  // for parent chats).
-  //
-  // Roots searched: ~/.config/Cursor/User/workspaceStorage (Linux native install)
-  // and /mnt/c/Users/*/AppData/Roaming/Cursor/User/workspaceStorage (WSL).
-  // We don't filter by workspace path; we scan every workspace's state.vscdb
-  // looking for a composerId match. Cheap enough at status time (~60K per file,
-  // <10ms typical). When a match is found, returns synthetic { used, window }
-  // pair where the percent is what's real; absolutes are derived as
-  // (window * percent / 100). Window hard-coded to a Cursor-typical 200K.
-  const roots: string[] = [];
-  const linuxRoot = resolve(homedir(), ".config", "Cursor", "User", "workspaceStorage");
-  if (existsSync(linuxRoot)) roots.push(linuxRoot);
-  try {
-    if (existsSync("/mnt/c/Users")) {
-      for (const u of readdirSync("/mnt/c/Users")) {
-        const p = `/mnt/c/Users/${u}/AppData/Roaming/Cursor/User/workspaceStorage`;
-        if (existsSync(p)) roots.push(p);
-      }
-    }
-  } catch {
-    // ignore
-  }
-  for (const root of roots) {
-    let workspaces: string[];
-    try {
-      workspaces = readdirSync(root);
-    } catch {
-      continue;
-    }
-    for (const ws of workspaces) {
-      const dbPath = `${root}/${ws}/state.vscdb`;
-      if (!existsSync(dbPath)) continue;
-      try {
-        // Lazy-import bun:sqlite so non-Bun runtimes (if any) don't choke at load.
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { Database } = require("bun:sqlite");
-        const db = new Database(dbPath, { readonly: true });
-        const row = db
-          .query("SELECT value FROM ItemTable WHERE key = 'composer.composerData'")
-          .get() as { value: string | Uint8Array } | null;
-        db.close();
-        if (!row?.value) continue;
-        const text =
-          typeof row.value === "string" ? row.value : Buffer.from(row.value).toString("utf8");
-        const parsed = JSON.parse(text);
-        const composers = Array.isArray(parsed?.allComposers) ? parsed.allComposers : [];
-        for (const c of composers) {
-          if (c?.composerId === sessionId && typeof c?.contextUsagePercent === "number") {
-            const window = 200000; // hard-coded Cursor-typical window; refine when Cursor exposes the actual ceiling
-            const used = Math.round((window * c.contextUsagePercent) / 100);
-            return { used, window, percentOnly: true };
-          }
-        }
-      } catch {
-        // ignore: DB locked, schema drift, etc. Move on to the next workspace.
-      }
-    }
+  if (platform === "cursor") {
+    const telemetry = readRuntimeContextTelemetry({
+      adapter: "cursor",
+      session_id: sessionId,
+      mode: "status",
+    });
+    return telemetry.state === "observed" && "used_percent" in telemetry
+      ? { usedPercent: telemetry.used_percent, percentOnly: true }
+      : null;
   }
-  return null;
+  return readRuntimeContextUsage("claude-code", sessionId);
 }
 
 function formatLocalTime(d: Date): string {
@@ -2993,10 +3029,10 @@ interface HealthReport {
     lines: number;
     cursor_backlog: number;
   };
-  // Heartbeats present in active/ but broken: no name, unparseable, or an
-  // absurd (epoch-ish) last_heartbeat. These are the `agent-unknown` peer-table
-  // ghosts; a positive count means dead files the sweep isn't catching.
-  zombies: {
+  // Heartbeat cache files present in active/ but stale or malformed. These are
+  // files the sweep is not catching; a parseable old heartbeat is stale, not
+  // evidence of an epoch-like or corrupt timestamp.
+  heartbeat_cache_issues: {
     count: number;
     samples: string[];
   };
@@ -3012,7 +3048,7 @@ interface HealthReport {
     latest_at: string | null;
     sessions: string[];
   };
-  anomalies: string[];
+  findings: string[];
 }
 
 /** Open-span soft watermark per producer state. The producer-state reader
@@ -3049,12 +3085,21 @@ export type EventLedgerHealthV3 =
         groups: Array<{ adapter: string; session_hash: string; count: number }>;
       };
       diagnostics_spool: {
+        /** Logical occurrences: loose files plus coalesced summary counts. */
         total: number;
+        /** Physical loose diagnostic files. */
+        loose_total: number;
+        /** Occurrences coalesced into summaries instead of loose files. */
+        summarized_total: number;
+        /** Physical summary files in `diagnostic-summaries/`. */
+        summary_files: number;
         last_24h: number;
         last_1h: number;
         latest_at: string | null;
         by_category: Record<string, { total: number; last_24h: number }>;
         recent_by_category: Record<string, { last_1h: number; latest_at: string | null }>;
+        /** Times the summary gate failed open (loose write proceeded). */
+        mitigation_fail_open: number;
       };
       span_pressure: Array<{ instance_id: string; generation_id: string; span_count: number }>;
       collection_errors: string[];
@@ -3194,6 +3239,47 @@ export function collectEventLedgerHealthV3(root: string, nowMs = Date.now()): Ev
     collectionErrors.push(`diagnostics spool unreadable: ${errorText(error)}`);
   }
 
+  // 4b) Coalesced diagnostic summaries: occurrences the producer bounded into
+  // `diagnostic-summaries/` instead of loose files. Counted into the logical
+  // totals so mitigation can never make an active fault look healthy; the
+  // physical loose file count stays visible separately.
+  let summarizedTotal = 0;
+  let summaryFiles = 0;
+  let mitigationFailOpen = 0;
+  try {
+    const listing = listDiagnosticSummariesV3(root);
+    summaryFiles = listing.file_count;
+    mitigationFailOpen = listing.mitigation_health?.fail_open_count ?? 0;
+    if (listing.unreadable_count > 0) {
+      collectionErrors.push(`${listing.unreadable_count} diagnostic summary file(s) unreadable`);
+    }
+    const dayAgoMs = nowMs - 24 * 60 * 60 * 1000;
+    const hourAgoMs = nowMs - 60 * 60 * 1000;
+    for (const summary of listing.summaries) {
+      summarizedTotal += summary.summarized_count;
+      const entry = byCategory[summary.category] ?? { total: 0, last_24h: 0 };
+      const recent = recentByCategory[summary.category] ?? { last_1h: 0, latest_at: null };
+      byCategory[summary.category] = entry;
+      recentByCategory[summary.category] = recent;
+      entry.total += summary.summarized_count;
+      const day = countSummarizedSinceV3([summary], dayAgoMs, undefined, nowMs);
+      const hour = countSummarizedSinceV3([summary], hourAgoMs, undefined, nowMs);
+      entry.last_24h += day;
+      diagnostics24h += day;
+      recent.last_1h += hour;
+      diagnostics1h += hour;
+      const lastMs = summary.last_summarized_at ? Date.parse(summary.last_summarized_at) : NaN;
+      if (Number.isFinite(lastMs)) {
+        latestDiagnosticMs = Math.max(latestDiagnosticMs, lastMs);
+        if (!recent.latest_at || lastMs > Date.parse(recent.latest_at)) {
+          recent.latest_at = new Date(lastMs).toISOString();
+        }
+      }
+    }
+  } catch (error) {
+    collectionErrors.push(`diagnostic summaries unreadable: ${errorText(error)}`);
+  }
+
   return {
     state: "live",
     mode: control.state,
@@ -3204,7 +3290,10 @@ export function collectEventLedgerHealthV3(root: string, nowMs = Date.now()): Ev
     pending_finalizations: pending,
     intake_spool: { total: intakeTotal, groups: intakeGroups },
     diagnostics_spool: {
-      total: diagnosticsTotal,
+      total: diagnosticsTotal + summarizedTotal,
+      loose_total: diagnosticsTotal,
+      summarized_total: summarizedTotal,
+      summary_files: summaryFiles,
       last_24h: diagnostics24h,
       last_1h: diagnostics1h,
       latest_at: Number.isFinite(latestDiagnosticMs)
@@ -3212,6 +3301,7 @@ export function collectEventLedgerHealthV3(root: string, nowMs = Date.now()): Ev
         : null,
       by_category: byCategory,
       recent_by_category: recentByCategory,
+      mitigation_fail_open: mitigationFailOpen,
     },
     span_pressure: spanPressure,
     collection_errors: collectionErrors,
@@ -3717,13 +3807,15 @@ type ActiveHealthHeartbeat = {
 export function collectActiveAgentHealth(
   root: string,
   nowMs = Date.now(),
+  readRows: (root: string) => ActiveHealthHeartbeat[] = readLiveCoordinationRows,
+  freshnessSeconds = freshnessCutoffSecs(),
 ): ActiveAgentHealthSummary {
   const source: ActiveAgentHealthSummary["source"] = "event-ledger-v3";
   let heartbeats: ActiveHealthHeartbeat[] = [];
   try {
     const control = readEventV3ControlState(root);
     if (control.state === "candidate" || control.state === "active") {
-      heartbeats = readLiveCoordinationRows(root);
+      heartbeats = readRows(root);
     }
   } catch {
     // The event-ledger section reports the authority read failure. Do not
@@ -3749,7 +3841,7 @@ export function collectActiveAgentHealth(
     const ageMs = Number.isFinite(lastObservedMs)
       ? nowMs - lastObservedMs
       : Number.POSITIVE_INFINITY;
-    if (ageMs > freshnessCutoffSecs() * 1000) stale += 1;
+    if (ageMs > freshnessSeconds * 1000) stale += 1;
   }
   return {
     source,
@@ -3761,6 +3853,22 @@ export function collectActiveAgentHealth(
   };
 }
 
+export type HeartbeatCacheIssue = "no-name" | "invalid-heartbeat" | "stale-age";
+
+/** Classify a parseable heartbeat cache file without conflating age with corruption. */
+export function classifyHeartbeatCacheIssue(
+  heartbeat: Pick<Heartbeat, "name" | "last_heartbeat">,
+  nowMs: number,
+  staleAgeMs: number,
+): HeartbeatCacheIssue | null {
+  if (!heartbeat.name || heartbeat.name === "unknown") return "no-name";
+  const lastHeartbeatMs = heartbeat.last_heartbeat
+    ? Date.parse(heartbeat.last_heartbeat)
+    : Number.NaN;
+  if (!Number.isFinite(lastHeartbeatMs)) return "invalid-heartbeat";
+  return nowMs - lastHeartbeatMs > staleAgeMs ? "stale-age" : null;
+}
+
 function runHealth(opts: { since: string; json?: boolean }): void {
   if (opts.json) emit.config({ format: "json" });
 
@@ -3845,12 +3953,12 @@ function runHealth(opts: { since: string; json?: boolean }): void {
     .map(([agent, count]) => ({ agent, count }));
 
   const activeAgents = collectActiveAgentHealth(root, nowMs);
-  // Zombies: files in active/ that are broken: unparseable, nameless, or an
-  // absurd (epoch-ish) last_heartbeat. These show as `agent-unknown` ghosts and
-  // mean dead files the sweep isn't reaping.
-  let zombieCount = 0;
-  const zombieSamples: string[] = [];
-  const ABSURD_AGE_MS = 24 * 60 * 60 * 1000; // > 1 day = clearly not a live, self-healing agent
+  // Heartbeat cache issues: files in active/ that are unparseable, nameless,
+  // invalidly timestamped, or stale. Old parseable timestamps are ordinary
+  // staleness, not evidence of epoch-like timestamp corruption.
+  let cacheIssueCount = 0;
+  const cacheIssueSamples: string[] = [];
+  const STALE_HEARTBEAT_AGE_MS = 24 * 60 * 60 * 1000;
   if (existsSync(activeDir)) {
     for (const file of readdirSync(activeDir)) {
       if (!file.endsWith(".json")) continue;
@@ -3862,20 +3970,16 @@ function runHealth(opts: { since: string; json?: boolean }): void {
         hb = null;
       }
       if (!hb || typeof hb.instance_id !== "string") {
-        zombieCount++;
-        if (zombieSamples.length < 5)
-          zombieSamples.push(`${idFromFile.slice(0, 12)} (unparseable/no-id)`);
+        cacheIssueCount++;
+        if (cacheIssueSamples.length < 5)
+          cacheIssueSamples.push(`${idFromFile.slice(0, 12)} (unparseable/no-id)`);
         continue;
       }
-      const lastHbMs = hb.last_heartbeat ? Date.parse(hb.last_heartbeat) : Number.NaN;
-      const ageMs = Number.isFinite(lastHbMs) ? nowMs - lastHbMs : Number.POSITIVE_INFINITY;
-      // Zombie heuristics on a parseable heartbeat: no name, or an age so large
-      // it can only be a broken/epoch timestamp (a real agent would have healed).
-      if (!hb.name || hb.name === "unknown" || ageMs > ABSURD_AGE_MS) {
-        zombieCount++;
-        if (zombieSamples.length < 5) {
-          const why = !hb.name || hb.name === "unknown" ? "no-name" : "epoch-age";
-          zombieSamples.push(`${idFromFile.slice(0, 12)} (${why})`);
+      const cacheIssue = classifyHeartbeatCacheIssue(hb, nowMs, STALE_HEARTBEAT_AGE_MS);
+      if (cacheIssue) {
+        cacheIssueCount++;
+        if (cacheIssueSamples.length < 5) {
+          cacheIssueSamples.push(`${idFromFile.slice(0, 12)} (${cacheIssue})`);
         }
       }
     }
@@ -3891,11 +3995,11 @@ function runHealth(opts: { since: string; json?: boolean }): void {
     }
   }
 
-  // Anomaly detection.
-  const anomalies: string[] = [];
+  // Finding detection.
+  const findings: string[] = [];
   for (const { agent, count } of healTopAgents) {
     if (count >= 5) {
-      anomalies.push(
+      findings.push(
         `${agent} self-healed ${count}x in ${opts.since}; possible idle-prune loop or PID instability`,
       );
     }
@@ -3906,7 +4010,7 @@ function runHealth(opts: { since: string; json?: boolean }): void {
       activeAgents.source === "event-ledger-v3"
         ? "lifecycle reconciliation may be delayed"
         : "heal mechanism may not be firing";
-    anomalies.push(
+    findings.push(
       `${activeAgents.stale} active ${noun}(s) without activity for ${Math.floor(freshnessCutoffSecs() / 60)}min; ${action}`,
     );
   }
@@ -3915,31 +4019,33 @@ function runHealth(opts: { since: string; json?: boolean }): void {
     (schema) => schema !== expectedSchema,
   );
   if (unexpectedSchemas.length > 0) {
-    anomalies.push(
+    findings.push(
       `Unexpected active-agent schema versions in use: ${unexpectedSchemas.join(", ")} (expected ${expectedSchema})`,
     );
   }
-  // Only recent hook failures are active anomalies. Historical rows remain in
+  // Only recent hook failures are active findings. Historical rows remain in
   // the report with exact error signatures and their latest timestamp.
   if (hookErrors.last1h > 0) {
     const top = hookErrors.recentTopErrors[0];
     const detail = top ? `: top '${top.error.slice(0, 80)}' x${top.count} (${top.phase})` : "";
-    anomalies.push(`agent-hook errored ${hookErrors.last1h}x in the last hour${detail}`);
+    findings.push(`agent-hook errored ${hookErrors.last1h}x in the last hour${detail}`);
   }
   if (stream.cursor_backlog > 500) {
-    anomalies.push(
+    findings.push(
       `projection cursor is ${stream.cursor_backlog} events behind; drain lagging (stop projection may be failing)`,
     );
   }
-  // Raw V3 stream size is not an anomaly; catalog rotation bounds readers.
+  // Raw V3 stream size is not a finding; catalog rotation bounds readers.
   if ((sweptByReason.unparseable ?? 0) > 0) {
-    anomalies.push(
+    findings.push(
       `${sweptByReason.unparseable} heartbeat(s) swept as unparseable in ${opts.since}; possible corruption or a non-atomic writer`,
     );
   }
-  if (zombieCount > 0) {
-    anomalies.push(
-      `${zombieCount} zombie heartbeat(s) in active/ (${zombieSamples.join(", ")}); broken files the sweep isn't reaping`,
+  if (cacheIssueCount > 0) {
+    findings.push(
+      `${cacheIssueCount} heartbeat cache issue(s) in active/ (${cacheIssueSamples.join(", ")}); ` +
+        "rows the last sweep deliberately kept (malformed but mtime-fresh, or neither audit " +
+        "write could persist), or that aged past the freshness cutoff since it ran",
     );
   }
   if (stopRemediation.total > 0) {
@@ -3947,7 +4053,7 @@ function runHealth(opts: { since: string; json?: boolean }): void {
       stopRemediation.sessions.length > 0
         ? ` (sessions: ${stopRemediation.sessions.map((s) => s.slice(0, 8)).join(", ")})`
         : "";
-    anomalies.push(
+    findings.push(
       `stop-hook remediation cap exhausted ${stopRemediation.total}x in ${opts.since}${who}; these sessions ended turns without the end-of-turn ritual — check why their evidence never lands`,
     );
   }
@@ -3962,17 +4068,17 @@ function runHealth(opts: { since: string; json?: boolean }): void {
         (sum, generation) => sum + generation.span_count,
         0,
       );
-      anomalies.push(
+      findings.push(
         `${orphanSpans} open tool span(s) across ${orphanGenerations.length} generation(s) with no open turn; orphaned spans block clean session end`,
       );
     }
     for (const pressure of eventLedger.span_pressure) {
-      anomalies.push(
+      findings.push(
         `${pressure.instance_id} (${pressure.generation_id}) holds ${pressure.span_count} open spans (soft watermark ${SPAN_PRESSURE_SOFT_WATERMARK}; the reader's 256-span cap makes the state unreadable)`,
       );
     }
     for (const collectionError of eventLedger.collection_errors) {
-      anomalies.push(`event-ledger health: ${collectionError}`);
+      findings.push(`event-ledger health: ${collectionError}`);
     }
   }
 
@@ -4017,14 +4123,14 @@ function runHealth(opts: { since: string; json?: boolean }): void {
       recent_top_errors: hookErrors.recentTopErrors,
     },
     stream,
-    zombies: { count: zombieCount, samples: zombieSamples },
+    heartbeat_cache_issues: { count: cacheIssueCount, samples: cacheIssueSamples },
     event_ledger: eventLedger,
     stop_remediation: {
       total: stopRemediation.total,
       latest_at: stopRemediation.latestAt,
       sessions: stopRemediation.sessions,
     },
-    anomalies,
+    findings,
   };
 
   if (opts.json) {
@@ -4095,7 +4201,7 @@ function renderHealthBox(report: HealthReport): void {
       `open spans ${ledger.open_spans.total}${orphanGenerations > 0 ? ` (${orphanGenerations} gen turn-closed)` : ""}`,
       `pending ends ${ledger.pending_finalizations.length}${pendingAges ? ` (${pendingAges})` : ""}`,
       `intake ${ledger.intake_spool.total}`,
-      `diagnostics ${ledger.diagnostics_spool.total} (${ledger.diagnostics_spool.last_1h} in 1h / ${ledger.diagnostics_spool.last_24h} in 24h)`,
+      `diagnostics ${ledger.diagnostics_spool.total}${ledger.diagnostics_spool.summarized_total > 0 ? ` (${ledger.diagnostics_spool.loose_total} loose + ${ledger.diagnostics_spool.summarized_total} summarized)` : ""} (${ledger.diagnostics_spool.last_1h} in 1h / ${ledger.diagnostics_spool.last_24h} in 24h)`,
     ].join(" · ");
   }
 
@@ -4116,13 +4222,13 @@ function renderHealthBox(report: HealthReport): void {
     ["stream", streamStr],
     ["event ledger", ledgerStr],
     [
-      "zombies",
-      report.zombies.count === 0
+      "cache issues",
+      report.heartbeat_cache_issues.count === 0
         ? "0"
-        : `${report.zombies.count} (${report.zombies.samples.join(", ")})`,
+        : `${report.heartbeat_cache_issues.count} (${report.heartbeat_cache_issues.samples.join(", ")})`,
     ],
     ["councils", councilParts.join(", ")],
-    ["anomalies", report.anomalies.length === 0 ? "(clean)" : `${report.anomalies.length} flagged`],
+    ["findings", report.findings.length === 0 ? "(clean)" : `${report.findings.length} flagged`],
   ];
 
   const localTime = formatLocalTime(new Date(report.generated_at));
@@ -4130,9 +4236,9 @@ function renderHealthBox(report: HealthReport): void {
 
   process.stdout.write(`${formatBox(title, rows)}\n`); // lint-ok-emission: chat-paste path; mirrors runStatus's direct write so the box surfaces in both TTY + harn-session-teed contexts
 
-  if (report.anomalies.length > 0) {
+  if (report.findings.length > 0) {
     process.stdout.write("\n"); // lint-ok-emission: same chat-paste path
-    for (const a of report.anomalies) {
+    for (const a of report.findings) {
       process.stdout.write(`  ! ${a}\n`); // lint-ok-emission: same
     }
   }
@@ -4552,24 +4658,66 @@ function runPing(name: string, message: string, opts: { json?: boolean }): void
   }
   const myOwner = resolveOwner();
   if (!myOwner) {
-    emit.error({
-      code: "no_pidmap_entry",
-      message: "not in an agent session; ppid walk found no pid-map entry",
-    });
+    const root = monorepoRoot();
+    emit.error(
+      root
+        ? sessionResolutionFailure(
+            root,
+            "not in an agent session; ppid walk found no pid-map entry",
+          )
+        : {
+            code: "no_pidmap_entry",
+            message: "not in an agent session; ppid walk found no pid-map entry",
+          },
+    );
     process.exit(1);
   }
+  const coordRoot = monorepoRoot();
   const peerOwner = resolveOwnerByName(name);
-  if (!peerOwner) {
+
+  // A name with no live session is the common case, not an error: the agent it
+  // refers to may have ended minutes ago and may come back under the same name.
+  // Refuse only a name that no agent has ever held, which is a typo — queueing
+  // that would swallow the message silently.
+  if (!peerOwner && coordRoot && !isAddressableName(coordRoot, name)) {
+    const suggestions = suggestNames(coordRoot, name);
     emit.error({
-      code: "no_peer",
-      message: `no live agent named "${name}" (case-insensitive). Run \`${resolveBinName()} agents list\` to see who's active.`,
+      code: "unknown_agent",
+      message:
+        `no agent has ever been named "${name}". ` +
+        (suggestions.length > 0 ? `Did you mean ${suggestions.join(", ")}? ` : "") +
+        `Run \`${resolveBinName()} agents list\` for live sessions.`,
     });
     process.exit(1);
   }
+
   const myHb = readCurrentCoordinationRow(myOwner);
   const fromName = myHb?.name ?? "anonymous";
   const body = `from agent-${fromName}: ${message.trim()}`;
-  const doc = appendEntry(peerOwner, "handoff", body);
+
+  // A live recipient gets the journal entry immediately, so a peer reading
+  // their own journal mid-session sees it without waiting for a prompt. A
+  // dormant recipient has no journal to write to yet; the drain writes it into
+  // whichever session picks the message up.
+  const doc = peerOwner ? appendEntry(peerOwner, "handoff", body) : null;
+
+  let queued: QueueResult;
+  try {
+    queued = queueMailboxMessage({
+      coordRoot: coordRoot ?? process.cwd(),
+      toName: name,
+      fromName,
+      fromInstanceId: myOwner,
+      body: message.trim(),
+      journaled: Boolean(peerOwner),
+    });
+  } catch (error) {
+    if (error instanceof MailboxCapacityError) {
+      emit.error({ code: `mailbox_${error.reason_code}`, message: error.message });
+      process.exit(1);
+    }
+    throw error;
+  }
 
   // Canonical delivery record: sender is the envelope owner, recipient rides
   // in data, so read-only observers can render the communication without
@@ -4581,18 +4729,21 @@ function runPing(name: string, message: string, opts: { json?: boolean }): void
     observation: {
       event_type: "coord.message_observed",
       direction: "sent",
-      subject: peerOwner,
+      subject: peerOwner ?? `name:${queued.message.to_name}`,
       body: message.trim(),
     },
   });
 
   const data = {
-    peer: name,
+    peer: queued.message.to_name,
     peer_instance_id: peerOwner,
+    delivery: peerOwner ? ("live" as const) : ("queued" as const),
+    message_id: queued.message.message_id,
+    pending: queued.pending,
     from: fromName,
     body,
-    journal_path: doc.path,
-    journal_bytes: doc.bytes,
+    journal_path: doc?.path ?? null,
+    journal_bytes: doc?.bytes ?? null,
   };
 
   if (opts.json) {
@@ -4601,7 +4752,11 @@ function runPing(name: string, message: string, opts: { json?: boolean }): void
     return;
   }
   emit.data(data);
-  emit.text(`pinged agent-${name}: "${truncate(message.trim(), 80)}"\n`);
+  emit.text(
+    peerOwner
+      ? `delivered to agent-${data.peer} (live; they see it on their next prompt): "${truncate(message.trim(), 80)}"\n`
+      : `queued for agent-${data.peer} (no live session; delivered when a session of that name next starts): "${truncate(message.trim(), 80)}"\n`,
+  );
 }
 
 async function runWait(
@@ -4722,21 +4877,22 @@ function emitWaitResult(
 }
 
 function runHeal(opts: {
-  owner: string;
-  kind: string;
+  owner?: string;
+  kind?: string;
   sessionId?: string;
   adapter?: string;
   pid?: string;
+  quarantineTransaction?: string;
+  approvalRecordId?: string;
+  yes?: boolean;
   json?: boolean;
 }): void {
   if (opts.json) emit.config({ format: "json" });
 
-  const owner = opts.owner.trim();
-  const kind = opts.kind.trim();
-  if (!owner) {
-    emit.error({ code: "missing_owner", message: "--owner is required" });
-    process.exit(1);
-  }
+  const requestedOwner = opts.owner?.trim() ?? "";
+  const quarantineTransaction = opts.quarantineTransaction?.trim() ?? "";
+  const approvalRecordId = opts.approvalRecordId?.trim() ?? "";
+  const kind = opts.kind?.trim() || "cache";
   if (kind !== "pidmap" && kind !== "cache") {
     emit.error({
       code: "bad_kind",
@@ -4744,6 +4900,30 @@ function runHeal(opts: {
     });
     process.exit(1);
   }
+  if (quarantineTransaction) {
+    if (opts.kind || opts.pid) {
+      emit.error({
+        code: "conflicting_recovery_options",
+        message: "--quarantine-transaction cannot be combined with --kind or --pid",
+      });
+      process.exit(1);
+    }
+    if (!opts.yes || !approvalRecordId) {
+      emit.error({
+        code: "transaction_quarantine_confirmation_required",
+        message:
+          "--quarantine-transaction requires --approval-record-id <id> and --yes; " +
+          "the command abandons one uncommitted authority mutation while preserving its record",
+      });
+      process.exit(1);
+    }
+  } else if (approvalRecordId || opts.yes) {
+    emit.error({
+      code: "transaction_quarantine_target_required",
+      message: "--approval-record-id and --yes require --quarantine-transaction <id>",
+    });
+    process.exit(1);
+  }
   if (
     opts.adapter &&
     opts.adapter !== "claude-code" &&
@@ -4766,7 +4946,52 @@ function runHeal(opts: {
     process.exit(1);
   }
 
-  const action = kind === "pidmap" ? "heal-pidmap" : "repair-coordination-cache";
+  const currentSessionRepair =
+    kind === "cache" &&
+    opts.owner === undefined &&
+    opts.sessionId === undefined &&
+    opts.adapter === undefined &&
+    !quarantineTransaction;
+
+  const ownerResolution = resolveOwnerWithSource();
+  const bootstrapIdentity = currentSessionRepair ? commandSessionBootstrap() : null;
+  const resolvedCurrentOwner =
+    bootstrapIdentity &&
+    (ownerResolution.source === "none" || ownerResolution.source === "active_singleton")
+      ? bootstrapIdentity.sessionId
+      : ownerResolution.owner;
+  const owner = requestedOwner || resolvedCurrentOwner || sessionIdentityFromEnv() || "";
+  if (!owner) {
+    emit.error({
+      code: "session_identity_missing",
+      message:
+        `could not resolve the current session; run ${resolveBinName()} doctor, or pass ` +
+        "--owner <instance-id> --session-id <native-session-id> --adapter <adapter>",
+    });
+    process.exit(1);
+  }
+
+  const currentRow = readLiveCoordinationRow(root, owner);
+  const inferredAdapter = normalizeAdapter(
+    opts.adapter?.trim() || currentRow?.platform || commandSessionBootstrap()?.adapter,
+  );
+  const sessionId =
+    opts.sessionId?.trim() ||
+    (currentSessionRepair ? sessionIdentityFromEnv() : null) ||
+    nativeSessionIdentity(currentRow, owner);
+
+  if (kind === "cache") {
+    const refusal = cacheHealAuthorityRefusal(root, owner, sessionId, inferredAdapter, currentRow);
+    if (refusal) {
+      emitHealFailure(refusal.reason, refusal.message);
+    }
+  }
+
+  const action = quarantineTransaction
+    ? "quarantine-authority-transaction"
+    : kind === "pidmap"
+      ? "heal-pidmap"
+      : "repair-coordination-cache";
 
   // Refuse to materialize a V3 cache at a truncated owner id.
   //
@@ -4809,23 +5034,72 @@ function runHeal(opts: {
   //   heal-pidmap <instance_id> [<pid>]
   //   repair-coordination-cache <instance_id> [<session_id>]
   const helperArgs: string[] = [action, owner];
-  if (kind === "pidmap" && opts.pid) helperArgs.push(opts.pid);
-  if (kind === "cache" && opts.sessionId) helperArgs.push(opts.sessionId);
-  if (kind === "cache" && opts.adapter) helperArgs.push(`--adapter=${opts.adapter}`);
+  if (quarantineTransaction) {
+    helperArgs.push(
+      quarantineTransaction,
+      approvalRecordId,
+      sessionId,
+      `--adapter=${inferredAdapter}`,
+    );
+  } else {
+    if (kind === "pidmap" && opts.pid) helperArgs.push(opts.pid);
+    if (kind === "cache") helperArgs.push(sessionId, `--adapter=${inferredAdapter}`);
+  }
 
   // Both recovery actions are handled by the bundled agent-coord binary.
   const helper = agentCoordOrExit(root);
-  const proc = spawnSync(helper, helperArgs, {
+  let proc = spawnSync(helper, helperArgs, {
     encoding: "utf8",
     ...coordHelperOpts(root),
   });
 
-  if (proc.status !== 0) {
-    emit.error({
-      code: "heal_failed",
-      message: spawnFailureMessage(proc, `agent-coord ${action}`),
+  let bootstrapState: "created" | "reused" | undefined;
+  if (
+    proc.status !== 0 &&
+    currentSessionRepair &&
+    missingAuthorityForCurrentSessionBootstrap(root, owner, sessionId)
+  ) {
+    const bootstrap = commandSessionBootstrap();
+    if (
+      !bootstrap ||
+      bootstrap.sessionId !== sessionId ||
+      bootstrap.sessionId !== owner ||
+      bootstrap.adapter !== inferredAdapter
+    ) {
+      emitHealFailure(
+        "native_identity_unverified",
+        "the current adapter did not provide one matching native session id and adapter",
+      );
+    }
+    try {
+      const bootstrapped = bootstrapLiveCoordinationAuthorityV3({
+        coordRoot: root,
+        owner,
+        nativeSessionId: bootstrap.sessionId,
+        adapter: bootstrap.adapter,
+      });
+      bootstrapState = bootstrapped.state;
+    } catch (error) {
+      const reason =
+        error instanceof LiveCoordinationAuthorityV3Error
+          ? error.reason
+          : "authority_bootstrap_failed";
+      emitHealFailure(
+        reason,
+        "the current native session could not establish authority; no fallback cache was accepted",
+      );
+    }
+    proc = spawnSync(helper, helperArgs, {
+      encoding: "utf8",
+      ...coordHelperOpts(root),
     });
-    process.exit(1);
+  }
+
+  if (proc.status !== 0) {
+    emitHealFailure(
+      healFailureReason(root, owner, sessionId, inferredAdapter),
+      spawnFailureMessage(proc, `agent-coord ${action}`),
+    );
   }
 
   // Read the derived cache to surface post-action state.
@@ -4836,8 +5110,9 @@ function runHeal(opts: {
     after = null;
   }
 
-  const outcome =
-    kind === "pidmap"
+  const outcome = quarantineTransaction
+    ? "transaction_quarantined"
+    : kind === "pidmap"
       ? proc.status === 0
         ? "ok"
         : "failed"
@@ -4852,10 +5127,15 @@ function runHeal(opts: {
         action,
         outcome,
         after,
+        ...(quarantineTransaction ? { recovery: JSON.parse(proc.stdout.trim()) as unknown } : {}),
       },
     ],
     meta: {
       kind,
+      automatic: currentSessionRepair && !quarantineTransaction,
+      authority: "event-ledger-v3",
+      adapter: kind === "cache" ? inferredAdapter : undefined,
+      bootstrap: bootstrapState,
       // The path actually spawned, not a guess at the layout: the helper is
       // resolved from harnery's own package location, which differs between a
       // submodule, an installed dependency, and a standalone checkout.
@@ -4863,10 +5143,18 @@ function runHeal(opts: {
     },
   });
   if (!opts.json) {
-    if (kind === "pidmap") {
+    if (quarantineTransaction) {
+      emit.text(
+        `coordination recovered: ${quarantineTransaction} quarantined with approval ${approvalRecordId}; ` +
+          `cache ${after ? "present" : "absent"} (${inferredAdapter})\n`,
+      );
+    } else if (kind === "pidmap") {
       emit.text(`agent-coord ${action} ok\n`);
     } else {
-      emit.text(`agent-coord ${action} ok: cache ${after ? "present" : "absent"} after\n`);
+      emit.text(
+        `coordination repaired: V3 authority live; ${currentSessionRepair ? "current-session " : ""}` +
+          `cache ${after ? "present" : "absent"} (${inferredAdapter})\n`,
+      );
     }
   }
 
@@ -4877,6 +5165,98 @@ function runHeal(opts: {
   // unconditionally on every `harn agents heal`, which over-counted no-op heals.)
 }
 
+type HealAuthorityRefusal = {
+  reason: "adapter_mismatch" | "owner_mismatch" | "session_mismatch" | "terminal_generation";
+  message: string;
+};
+
+function cacheHealAuthorityRefusal(
+  root: string,
+  owner: string,
+  sessionId: string,
+  adapter: "claude-code" | "cursor" | "codex",
+  currentRow: LiveCoordinationRow | null,
+): HealAuthorityRefusal | null {
+  if (currentRow && normalizeAdapter(currentRow.platform) !== adapter) {
+    return {
+      reason: "adapter_mismatch",
+      message: `the live generation belongs to adapter ${normalizeAdapter(currentRow.platform)}, not ${adapter}`,
+    };
+  }
+  let producer: ReturnType<typeof readHookProducerStateV3>;
+  try {
+    producer = readHookProducerStateV3(root, adapter, sessionId);
+  } catch {
+    return {
+      reason: "session_mismatch",
+      message: "the native session producer state could not be read safely",
+    };
+  }
+  if (producer?.terminal) {
+    return {
+      reason: "terminal_generation",
+      message: "the matching generation is terminal and cannot be repaired or reopened by heal",
+    };
+  }
+  if (producer && producer.instance_id !== liveInstanceIdV3(owner)) {
+    return {
+      reason: "owner_mismatch",
+      message: "the native session is bound to a different instance owner",
+    };
+  }
+  if (currentRow && (!producer || producer.generation_id !== currentRow.v3_generation_id)) {
+    return {
+      reason: "session_mismatch",
+      message: "the native session does not bind to the requested live generation",
+    };
+  }
+  return null;
+}
+
+function missingAuthorityForCurrentSessionBootstrap(
+  root: string,
+  owner: string,
+  sessionId: string,
+): boolean {
+  if (readLiveCoordinationRow(root, owner)) return false;
+  try {
+    const nativeSessionHasProducer = (["claude-code", "codex", "cursor"] as const).some(
+      (adapter) => readHookProducerStateV3(root, adapter, sessionId) !== undefined,
+    );
+    if (nativeSessionHasProducer) return false;
+    const instanceId = liveInstanceIdV3(owner);
+    return !listHookProducerStateRecordsV3(root, { includeTerminal: true }).some(
+      ({ state }) => state.instance_id === instanceId,
+    );
+  } catch {
+    return false;
+  }
+}
+
+function healFailureReason(
+  root: string,
+  owner: string,
+  sessionId: string,
+  adapter: "claude-code" | "cursor" | "codex",
+): string {
+  const refusal = cacheHealAuthorityRefusal(
+    root,
+    owner,
+    sessionId,
+    adapter,
+    readLiveCoordinationRow(root, owner),
+  );
+  return refusal?.reason ?? "authority_missing";
+}
+
+function emitHealFailure(reason: string, message: string): never {
+  emit.error({
+    code: "heal_failed",
+    message: `coordination heal refused (reason=${reason}): ${message}`,
+  });
+  process.exit(1);
+}
+
 /**
  * Emit one V3 council audit transition keyed to the exact durable manifest.
  * Falls through silently when no live session can attest the observation.