harnery 0.34.1 → 0.36.0

package/src/commands/agents.ts

@@ -21,10 +21,9 @@ import {
   readdirSync,
   readFileSync,
   rmSync,
-  statSync,
   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";
@@ -38,13 +37,18 @@ import {
 import {
   emitEventV3,
   monorepoRoot,
+  nativeSessionIdentity,
   normalizeAdapter,
   resolveOwner,
   resolveOwnerBySessionEnv,
   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 {
   listSessionFinalizationRequestsV3,
   observeHostDisappearedV3,
@@ -52,7 +56,11 @@ import {
   requestSessionEndExplicitV3,
   type SessionFinalizationRequestV3,
 } from "../core/agents/session-finalizer-v3.ts";
-import { SESSION_NAME_DISPLAY_NOTE } from "../core/agents/session-name-display.ts";
+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,
@@ -77,6 +85,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,
@@ -89,6 +101,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 {
+  readRuntimeContextTelemetry,
+  readRuntimeContextUsage,
+} from "../core/hooks/adapter/runtime-telemetry.ts";
 import { type RemoteMachine, readRemoteMachines } from "../core/presence/index.ts";
 import { registerContextCommand } from "./context.ts";
 
@@ -152,9 +168,8 @@ function freshnessCutoffSecs(): number {
 }
 
 const SUBAGENT_NOTE =
-  "Bash identity is process-level; if you're running inside a subagent, " +
-  "this resolves to the parent group's name, not the subagent's. A subagent-aware " +
-  "bridge (per-shell marker file at .harnery/shells/<pid>) is out of scope.";
+  "Native adapter subagents resolve to their own child generation after the hook bridge " +
+  "observes delegation. An unbridged subprocess shell still resolves through its parent.";
 
 /**
  * Spawn options for agent-coord child processes: pin the coord root the
@@ -248,19 +263,7 @@ function taskStateOf(hb: Pick<Heartbeat, "task_state">): TaskState {
   return hb.task_state ?? "active";
 }
 
-/** Producer joins use the private native session ID; `session_id` is the canonical V3 fingerprint. */
-export function nativeSessionIdentity(
-  row: Pick<Heartbeat, "native_session_id" | "session_id"> | null | undefined,
-  fallback: string,
-): string {
-  if (row?.native_session_id) return row.native_session_id;
-  // A projection-only row carries the privacy-safe canonical session
-  // fingerprint, not the adapter's native session ID needed to join the hook
-  // producer. Until a disposable cache exists, the resolved owner is the only
-  // native identity available to command surfaces such as `agents status`.
-  if (row?.session_id && !/^sid_[a-f0-9]{64}$/.test(row.session_id)) return row.session_id;
-  return fallback;
-}
+export { nativeSessionIdentity };
 
 function lifecycleLabel(hb: Pick<Heartbeat, "task_state" | "task_state_reason">): string {
   const state = taskStateOf(hb);
@@ -273,6 +276,7 @@ export function registerAgentsCommand(
   program: Command,
   emitParam: EmitContext,
   programContext?: HarneryProgramContext,
+  binName = resolveBinName(),
 ): void {
   emit = emitParam;
   const cmd = program
@@ -329,9 +333,9 @@ export function registerAgentsCommand(
     .command("suggest-name [description...]")
     .description(
       'Reprint a session name ("Agent <you> - <description>") for the operator to set as their ' +
-        "adapter tab title. With no arg, derives it from your current task. The primary naming path " +
+        "adapter tab title. With no arg, prefers the exact pending name, then derives from your current task. The primary naming path " +
         "is set-task (it suggests a name on the first focus declaration); reach for this to reprint " +
-        "or re-suggest after a topic pivot. Read-only.",
+        "or to create an explicit pending-display retry with --json. Read-only.",
     )
     .option("--json", "JSON output instead of the bare name")
     .option(
@@ -394,7 +398,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);
@@ -493,7 +497,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>",
@@ -576,12 +580,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.",
@@ -598,14 +601,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);
@@ -944,14 +959,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 {
@@ -1223,14 +1239,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);
   }
 
@@ -1712,49 +1727,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) {
@@ -1766,10 +1828,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;
@@ -1810,14 +1871,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);
   }
 
@@ -1854,27 +1916,18 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
   // the first time. `first_of_session: true` means exactly "this call produced
   // the session name" — it is never true with a null name (an empty first
   // declaration or a `--session-id` relay both keep the window open instead).
-  const firstSuggestedName =
-    !priorHb?.suggested_session_name && hb?.suggested_session_name
-      ? hb.suggested_session_name
-      : null;
-
-  // A readable but misclassified first display would otherwise leave the
-  // session permanently latched: set-task is allowed through the gate, but a
-  // normal repeat used to return no name and therefore could not establish a
-  // fresh ordered transcript boundary. Re-emit the unchanged pending name as
-  // an explicit retry. This does not rename the session or claim that the
-  // display was seen; it only gives the next exact block new mint evidence.
-  const retriedSuggestedName =
-    !firstSuggestedName &&
-    priorHb?.suggested_session_name &&
-    priorHb.session_name_seen_for !== priorHb.suggested_session_name &&
-    hb?.suggested_session_name === priorHb.suggested_session_name
-      ? hb.suggested_session_name
-      : null;
-  const suggestedName = firstSuggestedName ?? retriedSuggestedName;
+  // A native generation restart may rebuild the current cache during the
+  // mutation and carry an already-seen suggestion from the prior generation.
+  // That title is continuity evidence, not a new display request.
+  const pendingName = sessionNameDisplayPending(hb);
+  const firstSuggestedName = !priorHb?.suggested_session_name && pendingName ? pendingName : null;
+
+  // Routine focus declarations stay title-silent. A pending display no longer
+  // turns every repeated set-task into a fresh name instruction; explicit
+  // recovery belongs to `agents suggest-name --json`.
+  const suggestedName = firstSuggestedName;
   const firstOfSession = firstSuggestedName !== null;
-  const sessionNameRetry = retriedSuggestedName !== null;
+  const sessionNameRetry = false;
 
   emit.data({
     instance_id: myOwner,
@@ -1915,14 +1968,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;
   }
@@ -2097,25 +2151,30 @@ 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);
   }
 
   const hb = readCurrentCoordinationRow(myOwner);
   const agentName = hb?.name || "unknown";
-  // Description resolution: an explicit arg wins; with no arg, fall back to the
-  // agent's current declared task, so a bare `suggest-name` reprints the running
-  // session's name (handy after a topic pivot). Read-only — mutates no state;
-  // the primary naming path is set-task's first-of-session suggestion.
+  // A bare suggest-name must prefer the exact pending suggestion over rebuilding
+  // from the current task. The task may have changed since the title was minted;
+  // reconstructing it would produce a block the display latch can never accept.
+  // An explicit description keeps the read-only re-suggest behavior.
+  const pendingName = sessionNameDisplayPending(hb);
   const parts = descriptionParts.length > 0 ? descriptionParts : hb?.task ? [hb.task] : [];
-  const built = buildSuggestedName(agentName, parts);
+  const built =
+    descriptionParts.length === 0 && pendingName
+      ? { suggestedName: pendingName, description: hb?.task ?? pendingName }
+      : buildSuggestedName(agentName, parts);
   if (!built) {
     emit.error({
       code: "no_description",
@@ -2132,6 +2191,7 @@ function runSuggestName(
     emit.data({
       name: displayName,
       suggested_session_name: suggestedName,
+      session_name_retry: pendingName === suggestedName,
       agent_name: agentName,
       description,
     });
@@ -2171,14 +2231,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);
   }
 
@@ -2220,7 +2281,7 @@ function runStatus(opts: {
     }
   }
 
-  emitEventV3({
+  const statusEmitted = emitEventV3({
     owner: myOwner,
     session: nativeSessionIdentity(hb, myOwner),
     adapter: normalizeAdapter(hb.platform),
@@ -2229,6 +2290,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 }
@@ -2298,10 +2369,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,
@@ -2309,7 +2377,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.
@@ -2353,8 +2421,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 } : {}),
@@ -2498,15 +2566,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) {
@@ -2528,205 +2598,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).
-  if (platform === "codex") return readCodexContextUsage(sessionId);
-  if (platform === "cursor") return readCursorContextUsage(sessionId);
-  return readClaudeContextUsage(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.
-      }
-    }
-  }
-  return null;
-}
-
-function readClaudeContextUsage(sessionId: string): { used: number; window: number } | null {
-  const root = monorepoRoot();
-  if (!root) return null;
-  // Claude Code's project dir scheme: prepend "-", replace "/" → "-".
-  const encoded = `-${root.replace(/^\//, "").replace(/\//g, "-")}`;
-  const transcriptPath = resolve(homedir(), ".claude", "projects", encoded, `${sessionId}.jsonl`);
-  if (!existsSync(transcriptPath)) return null;
-  let raw: string;
-  try {
-    raw = readFileSync(transcriptPath, "utf8");
-  } catch {
-    return null;
-  }
-  const lines = raw.split("\n");
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i].trim();
-    if (!line) continue;
-    try {
-      const entry = JSON.parse(line);
-      const usage = entry?.message?.usage;
-      if (entry?.type === "assistant" && usage) {
-        const used =
-          (usage.input_tokens ?? 0) +
-          (usage.cache_creation_input_tokens ?? 0) +
-          (usage.cache_read_input_tokens ?? 0);
-        // Window: hardcode 1M for Opus 4.7 1M (current default). Refine to
-        // model-aware lookup when other models become routine.
-        return { used, window: 1000000 };
-      }
-    } catch {
-      // skip malformed line
-    }
-  }
-  return null;
-}
-
-function readCodexContextUsage(sessionId: string): { used: number; window: number } | null {
-  // Codex transcripts: ~/.codex/sessions/YYYY/MM/DD/rollout-<TS>-<sessionId>.jsonl
-  // On WSL the active install often lives on the Windows side under
-  // /mnt/c/Users/<user>/.codex/sessions/; both are searched.
-  const path = findCodexTranscript(sessionId);
-  if (!path) return null;
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return null;
-  }
-  const lines = raw.split("\n");
-  // Walk backwards: most recent token_count event wins.
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i].trim();
-    if (!line) continue;
-    try {
-      const entry = JSON.parse(line);
-      if (entry?.type === "event_msg" && entry?.payload?.type === "token_count") {
-        const info = entry.payload.info;
-        const used = info?.last_token_usage?.input_tokens;
-        const window = info?.model_context_window;
-        if (typeof used === "number" && typeof window === "number" && window > 0) {
-          return { used, window };
-        }
-      }
-    } catch {
-      // skip malformed line
-    }
-  }
-  return null;
-}
-
-function findCodexTranscript(sessionId: string): string | null {
-  // Candidate roots in priority order.
-  const homeRoot = resolve(homedir(), ".codex", "sessions");
-  const wslRoots: string[] = [];
-  try {
-    if (existsSync("/mnt/c/Users")) {
-      for (const entry of readdirSync("/mnt/c/Users")) {
-        wslRoots.push(`/mnt/c/Users/${entry}/.codex/sessions`);
-      }
-    }
-  } catch {
-    // ignore
-  }
-  const roots = [homeRoot, ...wslRoots];
-  const suffix = `-${sessionId}.jsonl`;
-  for (const root of roots) {
-    if (!existsSync(root)) continue;
-    try {
-      // Recursive scan: sessions are partitioned by YYYY/MM/DD/, so depth
-      // is bounded at 3 + one file per session. Cheap enough at status time.
-      const stack: string[] = [root];
-      while (stack.length) {
-        const dir = stack.pop()!;
-        let entries: string[];
-        try {
-          entries = readdirSync(dir);
-        } catch {
-          continue;
-        }
-        for (const name of entries) {
-          const full = `${dir}/${name}`;
-          try {
-            const stat = statSync(full);
-            if (stat.isDirectory()) {
-              stack.push(full);
-            } else if (name.endsWith(suffix)) {
-              return full;
-            }
-          } catch {
-            // ignore
-          }
-        }
-      }
-    } catch {
-      // ignore root scan failures
-    }
+  // 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") {
+    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 {
@@ -3126,9 +3019,9 @@ 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.
+  // 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.
   zombies: {
     count: number;
     samples: string[];
@@ -3136,6 +3029,15 @@ interface HealthReport {
   // V3 event-ledger producer health: open tool spans, pending finalization
   // requests, intake/diagnostics spool depth, span-count pressure.
   event_ledger: EventLedgerHealthV3;
+  // Stop-hook remediation cap exhaustions in the window: sessions whose
+  // end-of-turn evidence never landed, so the hook stopped bouncing them and
+  // let the turn end unenforced. Each one is a session that could not comply —
+  // the signal that used to be visible only as a repeating notification sound.
+  stop_remediation: {
+    total: number;
+    latest_at: string | null;
+    sessions: string[];
+  };
   anomalies: string[];
 }
 
@@ -3173,12 +3075,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[];
@@ -3318,6 +3229,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,
@@ -3328,7 +3280,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)
@@ -3336,12 +3291,57 @@ 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,
   };
 }
 
+/**
+ * Tally stop-hook remediation-cap exhaustions in the window from
+ * `.harnery/debug/agent-hook.ndjson` (rows with
+ * `skipped: "stop-remediation-cap-exhausted"`). Each one is a session whose
+ * end-of-turn evidence never landed, so the Stop hook gave up bouncing it and
+ * let the turn end unenforced — a compliance gap an operator should see
+ * without grepping the debug ledger.
+ */
+export function readStopRemediationExhaustions(
+  root: string,
+  cutoffMs: number,
+): { total: number; latestAt: string | null; sessions: string[] } {
+  const p = resolve(root, ".harnery", "debug", "agent-hook.ndjson");
+  if (!existsSync(p)) return { total: 0, latestAt: null, sessions: [] };
+  let raw: string;
+  try {
+    raw = readFileSync(p, "utf8");
+  } catch {
+    return { total: 0, latestAt: null, sessions: [] };
+  }
+  let total = 0;
+  let latestMs = Number.NEGATIVE_INFINITY;
+  const sessions = new Set<string>();
+  for (const line of raw.split("\n")) {
+    if (!line.includes("stop-remediation-cap-exhausted")) continue;
+    try {
+      const e = JSON.parse(line) as { ts?: string; skipped?: string; session_id?: string };
+      if (e.skipped !== "stop-remediation-cap-exhausted") continue;
+      const tsMs = e.ts ? Date.parse(e.ts) : Number.NaN;
+      if (!Number.isFinite(tsMs) || tsMs < cutoffMs) continue;
+      total++;
+      latestMs = Math.max(latestMs, tsMs);
+      if (e.session_id && sessions.size < 5) sessions.add(e.session_id);
+    } catch {
+      /* skip malformed */
+    }
+  }
+  return {
+    total,
+    latestAt: Number.isFinite(latestMs) ? new Date(latestMs).toISOString() : null,
+    sessions: [...sessions],
+  };
+}
+
 /** Tally agent-hook failures (.harnery/debug/agent-hook.errors.ndjson) in the
  * window by exact error and phase, while separating current-hour failures from
  * historical rows. Each line is {ts, error, phase, ...}. */
@@ -3797,13 +3797,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
@@ -3829,7 +3831,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,
@@ -3841,6 +3843,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" });
 
@@ -3902,6 +3920,7 @@ function runHealth(opts: { since: string; json?: boolean }): void {
   }
 
   const hookErrors = readHookErrors(root, cutoffMs, nowMs);
+  const stopRemediation = readStopRemediationExhaustions(root, cutoffMs);
   const stream = readStreamStats(root);
   const eventLedger = collectEventLedgerHealthV3(root);
 
@@ -3924,12 +3943,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.
+  // 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 zombieCount = 0;
   const zombieSamples: string[] = [];
-  const ABSURD_AGE_MS = 24 * 60 * 60 * 1000; // > 1 day = clearly not a live, self-healing agent
+  const STALE_HEARTBEAT_AGE_MS = 24 * 60 * 60 * 1000;
   if (existsSync(activeDir)) {
     for (const file of readdirSync(activeDir)) {
       if (!file.endsWith(".json")) continue;
@@ -3946,15 +3965,11 @@ function runHealth(opts: { since: string; json?: boolean }): void {
           zombieSamples.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) {
+      const cacheIssue = classifyHeartbeatCacheIssue(hb, nowMs, STALE_HEARTBEAT_AGE_MS);
+      if (cacheIssue) {
         zombieCount++;
         if (zombieSamples.length < 5) {
-          const why = !hb.name || hb.name === "unknown" ? "no-name" : "epoch-age";
-          zombieSamples.push(`${idFromFile.slice(0, 12)} (${why})`);
+          zombieSamples.push(`${idFromFile.slice(0, 12)} (${cacheIssue})`);
         }
       }
     }
@@ -4018,7 +4033,16 @@ function runHealth(opts: { since: string; json?: boolean }): void {
   }
   if (zombieCount > 0) {
     anomalies.push(
-      `${zombieCount} zombie heartbeat(s) in active/ (${zombieSamples.join(", ")}); broken files the sweep isn't reaping`,
+      `${zombieCount} heartbeat cache issue(s) in active/ (${zombieSamples.join(", ")}); stale or malformed files the sweep isn't reaping`,
+    );
+  }
+  if (stopRemediation.total > 0) {
+    const who =
+      stopRemediation.sessions.length > 0
+        ? ` (sessions: ${stopRemediation.sessions.map((s) => s.slice(0, 8)).join(", ")})`
+        : "";
+    anomalies.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`,
     );
   }
   if (eventLedger.state === "live") {
@@ -4089,6 +4113,11 @@ function runHealth(opts: { since: string; json?: boolean }): void {
     stream,
     zombies: { count: zombieCount, samples: zombieSamples },
     event_ledger: eventLedger,
+    stop_remediation: {
+      total: stopRemediation.total,
+      latest_at: stopRemediation.latestAt,
+      sessions: stopRemediation.sessions,
+    },
     anomalies,
   };
 
@@ -4160,7 +4189,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(" · ");
   }
 
@@ -4181,7 +4210,7 @@ function renderHealthBox(report: HealthReport): void {
     ["stream", streamStr],
     ["event ledger", ledgerStr],
     [
-      "zombies",
+      "cache issues",
       report.zombies.count === 0
         ? "0"
         : `${report.zombies.count} (${report.zombies.samples.join(", ")})`,
@@ -4617,10 +4646,18 @@ 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 peerOwner = resolveOwnerByName(name);
@@ -4787,21 +4824,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",
@@ -4809,6 +4847,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" &&
@@ -4831,7 +4893,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.
   //
@@ -4874,23 +4981,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.
@@ -4901,8 +5057,9 @@ function runHeal(opts: {
     after = null;
   }
 
-  const outcome =
-    kind === "pidmap"
+  const outcome = quarantineTransaction
+    ? "transaction_quarantined"
+    : kind === "pidmap"
       ? proc.status === 0
         ? "ok"
         : "failed"
@@ -4917,10 +5074,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.
@@ -4928,10 +5090,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`,
+      );
     }
   }
 
@@ -4942,6 +5112,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.