harnery 0.34.1 → 0.36.0

package/dist/commands/agents.js

@@ -13,15 +13,16 @@
  *   harn agents health --since 7d --json
  */
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { coordBinPath } from "../core/agents/coord-bin.js";
 import { checkGitFinalization, formatGitFinalizationFailure, readSessionWriteClaims, } from "../core/agents/finalization.js";
-import { emitEventV3, monorepoRoot, normalizeAdapter, resolveOwner, resolveOwnerBySessionEnv, resolveOwnerWithSource, sessionIdentityFromEnv, } from "../core/agents/index.js";
-import { reopenLiveCoordinationGenerationV3 } from "../core/agents/live-authority-v3.js";
+import { emitEventV3, monorepoRoot, nativeSessionIdentity, normalizeAdapter, resolveOwner, resolveOwnerBySessionEnv, resolveOwnerWithSource, sessionIdentityFromEnv, } from "../core/agents/index.js";
+import { bootstrapLiveCoordinationAuthorityV3, LiveCoordinationAuthorityV3Error, reopenLiveCoordinationGenerationV3, } from "../core/agents/live-authority-v3.js";
 import { listSessionFinalizationRequestsV3, observeHostDisappearedV3, reconcileSessionFinalizationV3, requestSessionEndExplicitV3, } from "../core/agents/session-finalizer-v3.js";
-import { SESSION_NAME_DISPLAY_NOTE } from "../core/agents/session-name-display.js";
+import { SESSION_NAME_DISPLAY_NOTE, sessionNameDisplayPending, } from "../core/agents/session-name-display.js";
+import { agentDisplayName } from "../core/agents/state/activity-log.js";
 import { buildLifecycleSuggestedName, buildSuggestedName, readHeartbeat as readHeartbeatCache, } from "../core/agents/state/heartbeat-writer.js";
 import { readLiveCoordinationRow, readLiveCoordinationRows, } from "../core/agents/state/live-coordination-view.js";
 import { foldSessionState, } from "../core/agents/state/session-state.js";
@@ -29,11 +30,13 @@ import { coordFreshnessSeconds, resolveBinName, sessionFinalizationConfig, } fro
 import { readEventV3ControlState } from "../core/events/v3/control.js";
 import { projectCoordinationViewV3 } from "../core/events/v3/coordination-view.js";
 import { liveInstanceIdV3 } from "../core/events/v3/live-routing.js";
+import { countSummarizedSinceV3, listDiagnosticSummariesV3, } from "../core/events/v3/producers/diagnostic-summaries.js";
 import { listHookIntakeGroupsV3, listHookIntakeRecordsV3, } from "../core/events/v3/producers/intake.js";
 import { listHookProducerStateRecordsV3, readHookProducerStateV3, } from "../core/events/v3/producers/recorder.js";
 import { readLedgerV3 } from "../core/events/v3/reader.js";
 import { EVENT_V3_LEDGER_RELATIVE_ROOT } from "../core/events/v3/writer.js";
 import { evaluateRunQualityIfDue } from "../core/guard/index.js";
+import { readRuntimeContextTelemetry, readRuntimeContextUsage, } from "../core/hooks/adapter/runtime-telemetry.js";
 import { readRemoteMachines } from "../core/presence/index.js";
 import { registerContextCommand } from "./context.js";
 function readCurrentCoordinationRow(instanceId) {
@@ -57,9 +60,8 @@ import { displayName as displayAgentName, ensureIdentity, listIdentities, lookup
 function freshnessCutoffSecs() {
     return coordFreshnessSeconds();
 }
-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.";
+const SUBAGENT_NOTE = "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
  * command already resolved (git-superproject-aware via `monorepoRoot()`), so
@@ -122,24 +124,13 @@ function activityOf(hb) {
 function taskStateOf(hb) {
     return hb.task_state ?? "active";
 }
-/** Producer joins use the private native session ID; `session_id` is the canonical V3 fingerprint. */
-export function nativeSessionIdentity(row, fallback) {
-    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) {
     const state = taskStateOf(hb);
     return state === "blocked" && hb.task_state_reason ? `${state}: ${hb.task_state_reason}` : state;
 }
 let emit;
-export function registerAgentsCommand(program, emitParam, programContext) {
+export function registerAgentsCommand(program, emitParam, programContext, binName = resolveBinName()) {
     emit = emitParam;
     const cmd = program
         .command("agents")
@@ -176,9 +167,9 @@ export function registerAgentsCommand(program, emitParam, programContext) {
     cmd
         .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("--session-id <id>", "Lookup the V3 generation by session_id directly, bypassing the ppid walk.")
         .action((description, opts) => {
@@ -218,7 +209,7 @@ export function registerAgentsCommand(program, emitParam, programContext) {
         .command("set-task <text...>")
         .description("Declare what this agent is currently working on. Visible to peers in the " +
         "per-prompt snapshot. Pass an empty string ('') to clear.")
-        .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\`.`)
+        .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 \`${binName} agents list --json\`.`)
         .action((text, opts) => {
         runSetTask(text.join(" "), opts);
     });
@@ -285,7 +276,7 @@ export function registerAgentsCommand(program, emitParam, programContext) {
     });
     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.`)
+        .description(`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>", "Wait only for these specific paths (repeatable)", collectPath, [])
         .option("--timeout <dur>", "Give up after this duration; suffix s/m/h/d is required (e.g. 30s, 5m, 1h). Default 60m.", "60m")
         .option("--poll-secs <n>", "Poll interval in seconds (default 5)", "5")
@@ -330,11 +321,10 @@ export function registerAgentsCommand(program, emitParam, programContext) {
     });
     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).")
-        .requiredOption("--owner <id>", "Target agent's instance_id")
-        .requiredOption("--kind <kind>", "pidmap | cache")
+        .description("Repair the current session's disposable coordination cache from V3. " +
+        "Use explicit options to target another generation or repair process attribution.")
+        .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.")
         .option("--adapter <id>", "(--kind cache) adapter used to validate the authoritative V3 generation: " +
         "claude-code | cursor | codex.")
@@ -342,6 +332,9 @@ export function registerAgentsCommand(program, emitParam, programContext) {
         "this shell's ppid chain for a claude process. Pass explicitly " +
         "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) => {
         runHeal(opts);
@@ -616,13 +609,10 @@ function runIdentityAssume(target, opts) {
         process.exit(1);
     }
     if (!opts.sessionId)
-        ensureCursorSession(root);
+        ensureAdapterSession(root);
     const owner = opts.sessionId ?? resolveOwner();
     if (!owner) {
-        emit.error({
-            code: "no_pidmap_entry",
-            message: "not in an agent session; ppid walk found no pid-map entry (pass --session-id to bypass)",
-        });
+        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 {
@@ -802,14 +792,11 @@ function runWhoami(opts) {
         });
         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);
     }
     const hb = readLiveCoordinationRow(root, myOwner);
@@ -1242,49 +1229,88 @@ function cursorEnvSessionId() {
         return null;
     return raw.startsWith("bc-") && raw.length > 3 ? raw.slice(3) : raw;
 }
-function shouldBootstrapCursorSession() {
-    return process.env.CURSOR_AGENT === "1" && cursorEnvSessionId() !== null;
+function commandSessionBootstrap() {
+    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 ensureCursorSession(root) {
-    if (!shouldBootstrapCursorSession())
+function ensureAdapterSession(root) {
+    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())
+    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, fallbackMessage) {
+    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) {
     const root = monorepoRoot();
     if (!root) {
@@ -1296,10 +1322,7 @@ function runReleaseClaim(path) {
     }
     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;
@@ -1340,13 +1363,10 @@ function runSetTask(task, opts) {
     // 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);
+        ensureAdapterSession(root);
     const myOwner = opts?.sessionId ?? resolveOwner() ?? sessionIdentityFromEnv();
     if (!myOwner) {
-        emit.error({
-            code: "no_pidmap_entry",
-            message: "not in an agent session; no session-id environment identity and the ppid walk found no pid-map entry (pass --session-id to bypass)",
-        });
+        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);
     }
     // Snapshot BEFORE the mutation: the writer stamps `suggested_session_name`
@@ -1378,24 +1398,17 @@ function runSetTask(task, opts) {
     // 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,
         name: hb?.name ?? null,
@@ -1434,13 +1447,10 @@ function runLifecycle(rawState, opts) {
         return;
     }
     if (!opts.sessionId)
-        ensureCursorSession(root);
+        ensureAdapterSession(root);
     const myOwner = opts.sessionId ?? resolveOwner() ?? sessionIdentityFromEnv();
     if (!myOwner) {
-        emit.error({
-            code: "no_pidmap_entry",
-            message: "not in an agent session; ppid walk found no pid-map entry (pass --session-id to bypass)",
-        });
+        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;
     }
@@ -1599,23 +1609,23 @@ function runSuggestName(descriptionParts, opts) {
     // 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);
+        ensureAdapterSession(root);
     const myOwner = opts.sessionId ?? resolveOwner();
     if (!myOwner) {
-        emit.error({
-            code: "no_pidmap_entry",
-            message: "not in an agent session; ppid walk found no pid-map entry (pass --session-id to bypass)",
-        });
+        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",
@@ -1630,6 +1640,7 @@ function runSuggestName(descriptionParts, opts) {
         emit.data({
             name: displayName,
             suggested_session_name: suggestedName,
+            session_name_retry: pendingName === suggestedName,
             agent_name: agentName,
             description,
         });
@@ -1662,13 +1673,10 @@ 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);
+        ensureAdapterSession(root);
     const myOwner = opts.sessionId ?? resolveOwner();
     if (!myOwner) {
-        emit.error({
-            code: "no_pidmap_entry",
-            message: "not in an agent session; ppid walk found no pid-map entry (pass --session-id from a hook payload)",
-        });
+        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);
     }
     const hb = readCurrentCoordinationRow(myOwner);
@@ -1699,7 +1707,7 @@ function runStatus(opts) {
             return;
         }
     }
-    emitEventV3({
+    const statusEmitted = emitEventV3({
         owner: myOwner,
         session: nativeSessionIdentity(hb, myOwner),
         adapter: normalizeAdapter(hb.platform),
@@ -1708,6 +1716,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;
     if (opts.endSession) {
         const canonicalInstanceId = liveInstanceIdV3(hb.instance_id);
@@ -1767,16 +1785,13 @@ function runStatus(opts) {
         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)}%)`;
     }
     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.
     // Best-effort: fails silently if .harnery/councils/ doesn't exist.
@@ -1819,8 +1834,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 } : {}),
@@ -1938,15 +1953,15 @@ function formatPeers(peers, cap, staleCount, remoteMachines = []) {
     }
     return main;
 }
-export function collectStatusPeerHealth(root, myOwner, nowMs = Date.now()) {
+export function collectStatusPeerHealth(root, myOwner, nowMs = Date.now(), readRows = readLiveCoordinationRows, freshnessSeconds = freshnessCutoffSecs()) {
     let rows = [];
     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 = [];
     let stale = 0;
     for (const peer of rows) {
@@ -1974,216 +1989,21 @@ function readContextUsage(sessionId, platform) {
     // 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 readCodexContextUsage(sessionId);
-    if (platform === "cursor")
-        return readCursorContextUsage(sessionId);
-    return readClaudeContextUsage(sessionId);
-}
-function readCursorContextUsage(sessionId) {
-    // 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 = [];
-    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;
-        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();
-                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) {
-    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;
-    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) {
-    // 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;
-    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) {
-    // Candidate roots in priority order.
-    const homeRoot = resolve(homedir(), ".codex", "sessions");
-    const wslRoots = [];
-    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 = [root];
-            while (stack.length) {
-                const dir = stack.pop();
-                let entries;
-                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
-        }
+        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) {
     // "Sat, May 9, 2026, 3:48 AM CDT", rendered in the Chicago timezone.
@@ -2620,6 +2440,47 @@ export function collectEventLedgerHealthV3(root, nowMs = Date.now()) {
     catch (error) {
         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,
@@ -2630,7 +2491,10 @@ export function collectEventLedgerHealthV3(root, nowMs = Date.now()) {
         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)
@@ -2638,11 +2502,59 @@ export function collectEventLedgerHealthV3(root, nowMs = Date.now()) {
                 : 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, cutoffMs) {
+    const p = resolve(root, ".harnery", "debug", "agent-hook.ndjson");
+    if (!existsSync(p))
+        return { total: 0, latestAt: null, sessions: [] };
+    let raw;
+    try {
+        raw = readFileSync(p, "utf8");
+    }
+    catch {
+        return { total: 0, latestAt: null, sessions: [] };
+    }
+    let total = 0;
+    let latestMs = Number.NEGATIVE_INFINITY;
+    const sessions = new Set();
+    for (const line of raw.split("\n")) {
+        if (!line.includes("stop-remediation-cap-exhausted"))
+            continue;
+        try {
+            const e = JSON.parse(line);
+            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, ...}. */
@@ -3041,13 +2953,13 @@ function runTrace(name, opts) {
 /**
  * V3 generations, not disposable heartbeat caches, are the active-agent authority.
  */
-export function collectActiveAgentHealth(root, nowMs = Date.now()) {
+export function collectActiveAgentHealth(root, nowMs = Date.now(), readRows = readLiveCoordinationRows, freshnessSeconds = freshnessCutoffSecs()) {
     const source = "event-ledger-v3";
     let heartbeats = [];
     try {
         const control = readEventV3ControlState(root);
         if (control.state === "candidate" || control.state === "active") {
-            heartbeats = readLiveCoordinationRows(root);
+            heartbeats = readRows(root);
         }
     }
     catch {
@@ -3073,7 +2985,7 @@ export function collectActiveAgentHealth(root, nowMs = Date.now()) {
         const ageMs = Number.isFinite(lastObservedMs)
             ? nowMs - lastObservedMs
             : Number.POSITIVE_INFINITY;
-        if (ageMs > freshnessCutoffSecs() * 1000)
+        if (ageMs > freshnessSeconds * 1000)
             stale += 1;
     }
     return {
@@ -3085,6 +2997,17 @@ export function collectActiveAgentHealth(root, nowMs = Date.now()) {
         stale,
     };
 }
+/** Classify a parseable heartbeat cache file without conflating age with corruption. */
+export function classifyHeartbeatCacheIssue(heartbeat, nowMs, staleAgeMs) {
+    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) {
     if (opts.json)
         emit.config({ format: "json" });
@@ -3144,6 +3067,7 @@ function runHealth(opts) {
         }
     }
     const hookErrors = readHookErrors(root, cutoffMs, nowMs);
+    const stopRemediation = readStopRemediationExhaustions(root, cutoffMs);
     const stream = readStreamStats(root);
     const eventLedger = collectEventLedgerHealthV3(root);
     // Canonical health.* events carry the full instance_id, already resolved to
@@ -3164,12 +3088,12 @@ function runHealth(opts) {
         .slice(0, 5)
         .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 = [];
-    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"))
@@ -3188,15 +3112,11 @@ function runHealth(opts) {
                     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})`);
                 }
             }
         }
@@ -3246,7 +3166,13 @@ function runHealth(opts) {
         anomalies.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`);
+        anomalies.push(`${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") {
         // Open spans whose generation has no open turn: the turn ended without its
@@ -3306,6 +3232,11 @@ function runHealth(opts) {
         stream,
         zombies: { count: zombieCount, samples: zombieSamples },
         event_ledger: eventLedger,
+        stop_remediation: {
+            total: stopRemediation.total,
+            latest_at: stopRemediation.latestAt,
+            sessions: stopRemediation.sessions,
+        },
         anomalies,
     };
     if (opts.json) {
@@ -3364,7 +3295,7 @@ function renderHealthBox(report) {
             `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(" · ");
     }
     const rows = [
@@ -3384,7 +3315,7 @@ function renderHealthBox(report) {
         ["stream", streamStr],
         ["event ledger", ledgerStr],
         [
-            "zombies",
+            "cache issues",
             report.zombies.count === 0
                 ? "0"
                 : `${report.zombies.count} (${report.zombies.samples.join(", ")})`,
@@ -3768,10 +3699,13 @@ function runPing(name, message, opts) {
     }
     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);
@@ -3913,12 +3847,10 @@ function emitWaitResult(data, opts) {
 function runHeal(opts) {
     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",
@@ -3926,6 +3858,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" &&
         opts.adapter !== "cursor" &&
@@ -3944,7 +3900,42 @@ 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.
     //
     // Heartbeats are keyed by the whole instance_id, so healing at an
@@ -3983,24 +3974,54 @@ function runHeal(opts) {
     //   heal-pidmap <instance_id> [<pid>]
     //   repair-coordination-cache <instance_id> [<session_id>]
     const helperArgs = [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;
+    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.
     let after = null;
@@ -4010,13 +4031,15 @@ function runHeal(opts) {
     catch {
         after = null;
     }
-    const outcome = kind === "pidmap"
-        ? proc.status === 0
-            ? "ok"
-            : "failed"
-        : after
-            ? "cache_present"
-            : "cache_absent";
+    const outcome = quarantineTransaction
+        ? "transaction_quarantined"
+        : kind === "pidmap"
+            ? proc.status === 0
+                ? "ok"
+                : "failed"
+            : after
+                ? "cache_present"
+                : "cache_absent";
     emit.data({
         rows: [
             {
@@ -4024,10 +4047,15 @@ function runHeal(opts) {
                 action,
                 outcome,
                 after,
+                ...(quarantineTransaction ? { recovery: JSON.parse(proc.stdout.trim()) } : {}),
             },
         ],
         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.
@@ -4035,11 +4063,16 @@ 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`);
         }
     }
     // Canonical health.* emission is owned by the cache writer, so it fires
@@ -4048,6 +4081,68 @@ function runHeal(opts) {
     // event when an already-correct heal no-ops. (Previously emitted here
     // unconditionally on every `harn agents heal`, which over-counted no-op heals.)
 }
+function cacheHealAuthorityRefusal(root, owner, sessionId, adapter, currentRow) {
+    if (currentRow && normalizeAdapter(currentRow.platform) !== adapter) {
+        return {
+            reason: "adapter_mismatch",
+            message: `the live generation belongs to adapter ${normalizeAdapter(currentRow.platform)}, not ${adapter}`,
+        };
+    }
+    let producer;
+    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, owner, sessionId) {
+    if (readLiveCoordinationRow(root, owner))
+        return false;
+    try {
+        const nativeSessionHasProducer = ["claude-code", "codex", "cursor"].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, owner, sessionId, adapter) {
+    const refusal = cacheHealAuthorityRefusal(root, owner, sessionId, adapter, readLiveCoordinationRow(root, owner));
+    return refusal?.reason ?? "authority_missing";
+}
+function emitHealFailure(reason, message) {
+    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.