harnery 0.35.0 → 0.36.0

package/dist/commands/agents.js

@@ -14,14 +14,15 @@
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+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, nativeSessionIdentity, normalizeAdapter, resolveOwner, resolveOwnerBySessionEnv, resolveOwnerWithSource, sessionIdentityFromEnv, } from "../core/agents/index.js";
-import { reopenLiveCoordinationGenerationV3 } from "../core/agents/live-authority-v3.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, 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,12 +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 { readRuntimeContextUsage } from "../core/hooks/adapter/runtime-telemetry.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) {
@@ -128,7 +130,7 @@ function lifecycleLabel(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")
@@ -207,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);
     });
@@ -274,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")
@@ -319,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.")
@@ -331,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);
@@ -605,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 {
@@ -791,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);
@@ -1231,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) {
@@ -1285,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;
@@ -1329,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`
@@ -1416,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;
     }
@@ -1581,13 +1609,10 @@ 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);
@@ -1648,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);
@@ -1685,7 +1707,7 @@ function runStatus(opts) {
             return;
         }
     }
-    emitEventV3({
+    const statusEmitted = emitEventV3({
         owner: myOwner,
         session: nativeSessionIdentity(hb, myOwner),
         adapter: normalizeAdapter(hb.platform),
@@ -1694,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);
@@ -1753,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.
@@ -1805,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 } : {}),
@@ -1924,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) {
@@ -1960,85 +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 readRuntimeContextUsage("codex", sessionId);
-    if (platform === "cursor")
-        return readCursorContextUsage(sessionId);
-    return readRuntimeContextUsage("claude-code", 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.
-            }
-        }
+    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.
@@ -2475,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,
@@ -2485,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)
@@ -2493,6 +2502,7 @@ 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,
@@ -2943,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 {
@@ -2975,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 {
@@ -2987,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" });
@@ -3067,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"))
@@ -3091,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})`);
                 }
             }
         }
@@ -3149,7 +3166,7 @@ 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
@@ -3278,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 = [
@@ -3298,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(", ")})`,
@@ -3682,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);
@@ -3827,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",
@@ -3840,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" &&
@@ -3858,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
@@ -3897,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;
@@ -3924,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: [
             {
@@ -3938,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.
@@ -3949,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
@@ -3962,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.