harnery 0.35.0 → 0.37.0

package/dist/core/agents/cli.js

@@ -6,10 +6,29 @@
  * Phase 2 replaces the no-op branches with real state projection + CLI
  * handlers; Phase 4 flips the default so `harn agents …` shims through here.
  */
+import { createHash } from "node:crypto";
 import { appendFileSync, existsSync } from "node:fs";
 import { appendFile, mkdir } from "node:fs/promises";
+import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { coordEnv } from "../../lib/env.js";
+import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.js";
+import { acquireNoClobberLease } from "../workflow/workspaces/leases.js";
+function sharedDiagnostic(root, event, fields, error) {
+    if (coordEnv("SHARED_LOGS") === "0")
+        return false;
+    try {
+        const logger = processLogger(root, "agent-coord");
+        if (error === undefined)
+            logger.debug(event, legacyLogFields(fields));
+        else
+            logger.error(event, legacyLogFields(fields), error);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function findCoordRoot(start) {
     // HARNERY_COORD_ROOT_OVERRIDE: the bash side's test-mode escape hatch. agent-coord
     // honors the same env so sandboxed test runs don't get derailed when cwd
@@ -39,8 +58,6 @@ async function readStdin() {
     return Buffer.concat(chunks).toString("utf8");
 }
 async function logNoop(root, subcommand, argv) {
-    const logPath = join(root, ".harnery", "debug", "agent-coord.ndjson");
-    await mkdir(dirname(logPath), { recursive: true });
     const entry = {
         ts: new Date().toISOString(),
         note: "called, no-op",
@@ -50,6 +67,10 @@ async function logNoop(root, subcommand, argv) {
         pid: process.pid,
         ppid: process.ppid,
     };
+    if (sharedDiagnostic(root, "agent_coord.noop", entry))
+        return;
+    const logPath = join(root, ".harnery", "debug", "agent-coord.ndjson");
+    await mkdir(dirname(logPath), { recursive: true });
     await appendFile(logPath, `${JSON.stringify(entry)}\n`, "utf8");
 }
 /**
@@ -62,8 +83,6 @@ async function logNoop(root, subcommand, argv) {
  */
 async function handleVerdict(root) {
     const raw = await readStdin();
-    const logPath = join(root, ".harnery", "debug", "agent-coord-verdict.ndjson");
-    await mkdir(dirname(logPath), { recursive: true });
     let parsed = {};
     let parseErr = null;
     try {
@@ -103,11 +122,12 @@ async function handleVerdict(root) {
             reason: `no evaluator for rule=${parsed.rule ?? "<missing>"} (fail-open)`,
         };
     }
-    await appendFile(logPath, `${JSON.stringify({
-        ts: new Date().toISOString(),
-        request_preview: raw.slice(0, 500),
-        verdict,
-    })}\n`, "utf8");
+    const diagnostic = { request_preview: raw.slice(0, 500), verdict };
+    if (!sharedDiagnostic(root, "agent_coord.verdict", diagnostic)) {
+        const logPath = join(root, ".harnery", "debug", "agent-coord-verdict.ndjson");
+        await mkdir(dirname(logPath), { recursive: true });
+        await appendFile(logPath, `${JSON.stringify({ ts: new Date().toISOString(), ...diagnostic })}\n`, "utf8");
+    }
     process.stdout.write(`${JSON.stringify(verdict)}\n`);
     return 0;
 }
@@ -139,6 +159,57 @@ function adapterFromPlatform(platform) {
         return "codex";
     return "claude-code";
 }
+const coordinationRetryCell = new Int32Array(new SharedArrayBuffer(4));
+const COORDINATION_RETRY_ATTEMPTS = 240;
+const COORDINATION_RETRY_DELAY_MS = 25;
+function isRetryableCoordinationContention(error) {
+    return (error instanceof Error &&
+        error.message.includes("lease event-v3-coordination-producer is held by a live or unexpired owner"));
+}
+function waitForCoordinationLease() {
+    Atomics.wait(coordinationRetryCell, 0, 0, COORDINATION_RETRY_DELAY_MS);
+}
+function pidIsAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+// The V3 producer lease begins after its caller has materialized and read the
+// disposable heartbeat. Serialize that larger registration boundary per owner
+// so overlapping first declarations cannot both derive state from an unnamed,
+// missing heartbeat and then strand a conflicting authority transaction.
+function acquireSetTaskLease(root, owner) {
+    const leasePath = join(root, ".harnery", "active", ".set-task-leases", `${owner}.lease`);
+    const authoritySha256 = createHash("sha256")
+        .update(resolve(root))
+        .update("\0")
+        .update(owner)
+        .digest("hex");
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            return acquireNoClobberLease({
+                path: leasePath,
+                scope: "agent-set-task",
+                authoritySha256,
+                staleAfterMs: 5_000,
+                validateStaleOwner: (leaseOwner) => leaseOwner.host === hostname() && !pidIsAlive(leaseOwner.pid),
+            });
+        }
+        catch (error) {
+            const busy = error instanceof Error &&
+                error.message.includes("lease agent-set-task is held by a live or unexpired owner");
+            if (!busy || attempt >= COORDINATION_RETRY_ATTEMPTS - 1)
+                throw error;
+            waitForCoordinationLease();
+        }
+    }
+}
 async function handleStateAction(root, action, rest) {
     const writer = await import("./state/heartbeat-writer.js");
     const [owner, ...args] = rest;
@@ -149,31 +220,79 @@ async function handleStateAction(root, action, rest) {
     switch (action) {
         case "set-task": {
             const task = args.join(" ");
-            const before = writer.readHeartbeat(root, owner);
-            let hb;
+            let setTaskLease;
             try {
-                const { recordLiveTaskChangeV3 } = await import("./live-authority-v3.js");
-                recordLiveTaskChangeV3({
-                    coordRoot: root,
-                    owner,
-                    nativeSessionId: before?.session_id ?? owner,
-                    adapter: adapterFromPlatform(before?.platform),
-                    task,
-                });
-                hb = writer.readHeartbeat(root, owner);
+                setTaskLease = acquireSetTaskLease(root, owner);
             }
             catch (error) {
-                process.stderr.write(`agent-coord set-task: V3 authority refused (${error instanceof Error ? error.message : String(error)})\n`);
+                process.stderr.write(`agent-coord set-task: registration lease refused (${error instanceof Error ? error.message : String(error)})\n`);
                 return 1;
             }
-            if (!hb) {
-                // Name the RESOLVED root: when a nested .harnery/ shadows the real
-                // coordination home, the full path is what makes that diagnosable.
-                process.stderr.write(`agent-coord set-task: no heartbeat at ${root}/.harnery/active/${owner}.json\n`);
-                return 1;
+            try {
+                let before = writer.readHeartbeat(root, owner);
+                const humanFacing = before?.kind !== "subagent" && before?.kind !== "transient" && !before?.workflow_run_id;
+                // A mid-flight-onboarded generation can exist before SessionStart's
+                // assign-name step ran. Repair that private display metadata before the
+                // first non-empty task mints its operator-facing title. assignName is the
+                // same durable, idempotent pool path used by normal SessionStart.
+                if (task && before && humanFacing && !before.name?.trim()) {
+                    const { assignName } = await import("./state/names.js");
+                    const name = assignName(root, owner, "session");
+                    before = writer.setAssignedNameCache(root, owner, name, "session");
+                    if (!before) {
+                        process.stderr.write(`agent-coord set-task: could not restore assigned name for ${owner}\n`);
+                        return 1;
+                    }
+                }
+                let hb;
+                try {
+                    const { recordLiveTaskChangeV3 } = await import("./live-authority-v3.js");
+                    for (let attempt = 0;; attempt += 1) {
+                        try {
+                            recordLiveTaskChangeV3({
+                                coordRoot: root,
+                                owner,
+                                nativeSessionId: before?.session_id ?? owner,
+                                adapter: adapterFromPlatform(before?.platform),
+                                task,
+                            });
+                            break;
+                        }
+                        catch (error) {
+                            if (!isRetryableCoordinationContention(error) ||
+                                attempt >= COORDINATION_RETRY_ATTEMPTS - 1) {
+                                throw error;
+                            }
+                            waitForCoordinationLease();
+                        }
+                    }
+                    hb = writer.readHeartbeat(root, owner);
+                    const currentHumanFacing = hb?.kind !== "subagent" && hb?.kind !== "transient" && !hb?.workflow_run_id;
+                    if (task &&
+                        hb &&
+                        currentHumanFacing &&
+                        (!hb.name?.trim() || /^Agent unknown - /.test(hb.suggested_session_name ?? ""))) {
+                        const { assignName } = await import("./state/names.js");
+                        const name = hb.name?.trim() || assignName(root, owner, "session");
+                        hb = writer.setAssignedNameCache(root, owner, name, "session");
+                    }
+                }
+                catch (error) {
+                    process.stderr.write(`agent-coord set-task: V3 authority refused (${error instanceof Error ? error.message : String(error)})\n`);
+                    return 1;
+                }
+                if (!hb) {
+                    // Name the RESOLVED root: when a nested .harnery/ shadows the real
+                    // coordination home, the full path is what makes that diagnosable.
+                    process.stderr.write(`agent-coord set-task: no heartbeat at ${root}/.harnery/active/${owner}.json\n`);
+                    return 1;
+                }
+                process.stdout.write(`${JSON.stringify({ instance_id: owner, task: hb.task ?? null, cleared: !task })}\n`);
+                return 0;
+            }
+            finally {
+                setTaskLease.release();
             }
-            process.stdout.write(`${JSON.stringify({ instance_id: owner, task: hb.task ?? null, cleared: !task })}\n`);
-            return 0;
         }
         case "release-claim": {
             const path = args[0];
@@ -250,8 +369,8 @@ async function handleStateAction(root, action, rest) {
                         adapter: adapterFromPlatform(adapter),
                     });
                 }
-                const { ensureLiveCoordinationHeartbeat } = await import("./state/live-coordination-view.js");
-                hb = ensureLiveCoordinationHeartbeat(root, owner, sessionId ?? owner, adapterFromPlatform(adapter), model);
+                const { repairLiveCoordinationHeartbeat } = await import("./state/live-coordination-writer.js");
+                hb = repairLiveCoordinationHeartbeat(root, owner, sessionId ?? owner, adapterFromPlatform(adapter), model);
             }
             catch (error) {
                 process.stderr.write(`agent-coord repair-coordination-cache: V3 route refused (${error instanceof Error ? error.message : String(error)})\n`);
@@ -260,6 +379,45 @@ async function handleStateAction(root, action, rest) {
             process.stdout.write(`${JSON.stringify({ instance_id: owner, recreated: !!hb })}\n`);
             return hb ? 0 : 1;
         }
+        case "quarantine-authority-transaction": {
+            const adapter = args.find((a) => a.startsWith("--adapter="))?.slice("--adapter=".length);
+            const positional = args.filter((a) => !a.startsWith("--"));
+            const [transactionId, approvalRecordId, sessionId] = positional;
+            if (!transactionId || !approvalRecordId) {
+                process.stderr.write("agent-coord quarantine-authority-transaction: missing <transaction-id> or <approval-record-id>\n");
+                return 2;
+            }
+            try {
+                const { coordinationAuthorityStateDigestV3, liveCoordinationWriteModeV3 } = await import("./live-authority-v3.js");
+                liveCoordinationWriteModeV3(root);
+                const { liveInstanceIdV3 } = await import("../events/v3/live-routing.js");
+                const { repairLiveCoordinationHeartbeat } = await import("./state/live-coordination-writer.js");
+                const heartbeat = repairLiveCoordinationHeartbeat(root, owner, sessionId ?? owner, adapterFromPlatform(adapter));
+                if (!heartbeat) {
+                    throw new Error("authoritative coordination cache could not be materialized");
+                }
+                const { quarantineConflictingCoordinationTransactionV3 } = await import("../events/v3/coordination-transaction-recovery.js");
+                const receipt = quarantineConflictingCoordinationTransactionV3(root, {
+                    transaction_id: transactionId,
+                    actor_instance_id: liveInstanceIdV3(owner),
+                    observed_current_state_digest: coordinationAuthorityStateDigestV3(heartbeat),
+                    approval_record_id: approvalRecordId,
+                });
+                const repaired = repairLiveCoordinationHeartbeat(root, owner, sessionId ?? owner, adapterFromPlatform(adapter));
+                process.stdout.write(`${JSON.stringify({
+                    instance_id: owner,
+                    receipt,
+                    heartbeat: repaired
+                        ? { task_state: repaired.task_state, files_touched: repaired.files_touched }
+                        : null,
+                })}\n`);
+                return repaired ? 0 : 1;
+            }
+            catch (error) {
+                process.stderr.write(`agent-coord quarantine-authority-transaction: recovery refused (${error instanceof Error ? error.message : String(error)})\n`);
+                return 1;
+            }
+        }
         default:
             process.stderr.write(`agent-coord: unknown state action ${action}\n`);
             return 2;
@@ -463,8 +621,10 @@ async function handleStaleSweep(root, _rest) {
     return 0;
 }
 async function handleReconcileFinalization(root) {
-    const { reconcileSessionFinalizationV3 } = await import("./session-finalizer-v3.js");
-    const result = reconcileSessionFinalizationV3(root);
+    // Shares the supervisor composition with `agents reconcile` so session start
+    // sweeps the stale cache in the same pass, as ADR 0077 specified.
+    const { reconcileCoordinationV3 } = await import("./reconcile-coordination-v3.js");
+    const result = reconcileCoordinationV3(root);
     process.stdout.write(`${JSON.stringify(result)}\n`);
     return result.diagnostics.some((item) => item === "ledger_not_authority_safe") ? 2 : 0;
 }
@@ -513,14 +673,16 @@ async function handlePromptContext(root, rest) {
     const instanceId = args.instance;
     const sessionId = args.session ?? instanceId;
     const agentName = args.name;
+    const adapter = args.adapter;
     const sessionNameNudge = args["session-name-nudge"] === "true";
     const taskNudge = args["task-nudge"] === "true";
+    const hostPromptReminder = args["host-prompt-reminder"] === "true";
     const statusFooterNudge = args["status-footer-nudge"] === "true";
     // Value is the adapter id; a bare flag (parsed as "true") still enables the
     // reminder with the adapter-neutral wording.
     const turnRitualNudge = args["turn-ritual-nudge"] === "true" ? "generic" : args["turn-ritual-nudge"];
     if (!instanceId) {
-        process.stderr.write("agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--session-name-nudge] [--task-nudge] [--status-footer-nudge] [--turn-ritual-nudge <adapter>]\n");
+        process.stderr.write("agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--adapter <id>] [--session-name-nudge] [--task-nudge] [--host-prompt-reminder] [--status-footer-nudge] [--turn-ritual-nudge <adapter>]\n");
         return 2;
     }
     const { renderPromptContext } = await import("./render/prompt-context.js");
@@ -531,8 +693,10 @@ async function handlePromptContext(root, rest) {
         agentName,
         sessionNameNudge,
         taskNudge,
+        hostPromptReminder,
         statusFooterNudge,
         turnRitualNudge,
+        adapter,
     });
     process.stdout.write(text);
     return 0;
@@ -726,9 +890,12 @@ async function handleGitHook(fallbackRoot, rest) {
             });
             // Forensics channel shared with the stdin `verdict` path.
             try {
-                const logPath = join(root, ".harnery", "debug", "agent-coord-verdict.ndjson");
-                await mkdir(dirname(logPath), { recursive: true });
-                await appendFile(logPath, `${JSON.stringify({ ts: new Date().toISOString(), via: "git-hook", staged, verdict: result })}\n`);
+                const diagnostic = { via: "git-hook", staged, verdict: result };
+                if (!sharedDiagnostic(root, "agent_coord.git_hook_verdict", diagnostic)) {
+                    const logPath = join(root, ".harnery", "debug", "agent-coord-verdict.ndjson");
+                    await mkdir(dirname(logPath), { recursive: true });
+                    await appendFile(logPath, `${JSON.stringify({ ts: new Date().toISOString(), ...diagnostic })}\n`);
+                }
             }
             catch {
                 /* diagnostics never break a verdict */
@@ -809,7 +976,8 @@ async function main() {
     if (subcommand === "set-task" ||
         subcommand === "release-claim" ||
         subcommand === "heal-pidmap" ||
-        subcommand === "repair-coordination-cache") {
+        subcommand === "repair-coordination-cache" ||
+        subcommand === "quarantine-authority-transaction") {
         return handleStateAction(root, subcommand, rest);
     }
     if (subcommand === "append-journal" || subcommand === "edit-journal") {
@@ -859,17 +1027,23 @@ async function main() {
     return 0;
 }
 main()
-    .then((code) => process.exit(code))
-    .catch((err) => {
+    .then(async (code) => {
+    await closeProcessLoggers();
+    process.exit(code);
+})
+    .catch(async (err) => {
     try {
         const root = findCoordRoot(process.cwd());
         if (root) {
-            const path = join(root, ".harnery", "debug", "agent-coord.errors.ndjson");
-            appendFileSync(path, `${JSON.stringify({ ts: new Date().toISOString(), error: String(err) })}\n`);
+            if (!sharedDiagnostic(root, "agent_coord.error", {}, err)) {
+                const path = join(root, ".harnery", "debug", "agent-coord.errors.ndjson");
+                appendFileSync(path, `${JSON.stringify({ ts: new Date().toISOString(), error: String(err) })}\n`);
+            }
         }
     }
     catch {
         /* swallow */
     }
+    await closeProcessLoggers();
     process.exit(0);
 });

package/dist/core/agents/health.d.ts

@@ -0,0 +1,17 @@
+import type { SupervisorCapability, SupervisorSourceReference } from "../supervisor/contract.js";
+export interface CoordinationHealthDiagnostic {
+    code: "malformed_json" | "invalid_contract";
+    byte_offset: number;
+    segment_ordinal: number;
+    event_id?: string;
+}
+export interface CoordinationHealthSnapshot {
+    observed_at: string;
+    capability: SupervisorCapability;
+    recent_events: readonly SupervisorSourceReference[];
+    diagnostics: readonly CoordinationHealthDiagnostic[];
+    omitted_event_count: number;
+}
+/** Read bounded V3 references without retaining event payloads or the full ledger reader. */
+export declare function collectCoordinationHealthSnapshot(coordRoot: string, now?: Date): CoordinationHealthSnapshot;
+//# sourceMappingURL=health.d.ts.map

package/dist/core/agents/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/core/agents/health.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAEjG,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,oBAAoB,CAAC;IACjC,aAAa,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACpD,WAAW,EAAE,SAAS,4BAA4B,EAAE,CAAC;IACrD,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAMD,6FAA6F;AAC7F,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,MAAM,EACjB,GAAG,OAAa,GACf,0BAA0B,CA4C5B"}

package/dist/core/agents/health.js

@@ -0,0 +1,109 @@
+import { closeSync, existsSync, lstatSync, openSync, readSync } from "node:fs";
+import { join, resolve } from "node:path";
+const MAX_EVENT_REFERENCES = 64;
+const MAX_DIAGNOSTICS = 16;
+const MAX_TAIL_BYTES = 256 * 1_024;
+/** Read bounded V3 references without retaining event payloads or the full ledger reader. */
+export function collectCoordinationHealthSnapshot(coordRoot, now = new Date()) {
+    const observedAt = now.toISOString();
+    const active = join(resolve(coordRoot), ".harnery", "ledgers", "v3", "active.ndjson");
+    if (!existsSync(active))
+        return unavailable(observedAt, "ledger-missing");
+    let handle;
+    try {
+        const stat = lstatSync(active);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            return unavailable(observedAt, "ledger-unsafe");
+        if (stat.size === 0)
+            return available(observedAt, [], [], 0);
+        const start = Math.max(0, stat.size - MAX_TAIL_BYTES);
+        const bytes = Buffer.allocUnsafe(stat.size - start);
+        handle = openSync(active, "r");
+        const count = readSync(handle, bytes, 0, bytes.length, start);
+        const lines = bytes.subarray(0, count).toString("utf8").split("\n");
+        if (start > 0)
+            lines.shift();
+        const completeLines = lines.filter((line) => line.length > 0);
+        const diagnostics = [];
+        const references = [];
+        let byteOffset = start;
+        for (const line of completeLines) {
+            const reference = parseReference(line);
+            if (reference)
+                references.push(reference);
+            else if (diagnostics.length < MAX_DIAGNOSTICS) {
+                diagnostics.push({
+                    code: line.trimStart().startsWith("{") ? "invalid_contract" : "malformed_json",
+                    byte_offset: byteOffset,
+                    segment_ordinal: 1,
+                });
+            }
+            byteOffset += Buffer.byteLength(line) + 1;
+        }
+        const recent = references.slice(-MAX_EVENT_REFERENCES);
+        return available(observedAt, recent, diagnostics, Math.max(0, references.length - recent.length) + (start > 0 ? 1 : 0));
+    }
+    catch {
+        return unavailable(observedAt, "tail-read-failed", "error");
+    }
+    finally {
+        if (handle !== undefined)
+            closeSync(handle);
+    }
+}
+function parseReference(line) {
+    try {
+        const value = JSON.parse(line);
+        const contract = object(value.contract);
+        const time = object(value.time);
+        const producer = object(value.producer);
+        if (contract.major !== 3 ||
+            typeof value.event_id !== "string" ||
+            typeof value.event_type !== "string" ||
+            typeof time.observed_at !== "string" ||
+            typeof producer.sequence !== "number" ||
+            !Number.isSafeInteger(producer.sequence))
+            return undefined;
+        return {
+            id: `v3:${value.event_id}`,
+            source_kind: "coordination.v3",
+            source_id: value.event_type,
+            record_id: value.event_id,
+            sequence: producer.sequence,
+            schema_version: 3,
+            observed_at: time.observed_at,
+            capability: "supported",
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function object(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function available(observedAt, recentEvents, diagnostics, omittedEventCount) {
+    const state = diagnostics.length === 0 ? "supported" : "partial";
+    return {
+        observed_at: observedAt,
+        capability: {
+            source_kind: "coordination.v3.references",
+            state,
+            ...(state === "partial" ? { reason_code: diagnostics[0]?.code ?? "tail-invalid" } : {}),
+        },
+        recent_events: recentEvents.map((reference) => ({ ...reference, capability: state })),
+        diagnostics,
+        omitted_event_count: omittedEventCount,
+    };
+}
+function unavailable(observedAt, reasonCode, state = "unsupported") {
+    return {
+        observed_at: observedAt,
+        capability: { source_kind: "coordination.v3.references", state, reason_code: reasonCode },
+        recent_events: [],
+        diagnostics: [],
+        omitted_event_count: 0,
+    };
+}

package/dist/core/agents/live-authority-v3.d.ts

@@ -1,6 +1,7 @@
 import type { Adapter } from "../adapter.js";
-import type { EventV3WriteMode } from "../events/v3/control.js";
+import { type EventV3WriteMode } from "../events/v3/control.js";
 import { type RecordCoordinationAuthorityV3Result } from "../events/v3/producers/coordination-recorder.js";
+import { type Heartbeat } from "./state/heartbeat-writer.js";
 export declare const LIVE_COORDINATION_V3_PRODUCER_ID: "prd_agent-coord";
 export declare class LiveCoordinationAuthorityV3Error extends Error {
     readonly reason: string;
@@ -18,6 +19,18 @@ export interface ReopenedLiveCoordinationGenerationV3 {
     prior_generation_id: `gen_${string}`;
     generation_id: `gen_${string}`;
 }
+export interface BootstrappedLiveCoordinationAuthorityV3 {
+    state: "created" | "reused";
+    adapter: Adapter;
+    generation_id: `gen_${string}`;
+    heartbeat: Heartbeat;
+}
+export interface RestoredLiveCoordinationStateV3 {
+    state: "unchanged" | "restored";
+    task: boolean;
+    claims: number;
+    lifecycle: boolean;
+}
 interface LiveAuthorityBaseV3 {
     coordRoot: string;
     owner: string;
@@ -26,6 +39,38 @@ interface LiveAuthorityBaseV3 {
     adapter: Adapter;
     observationId?: string;
 }
+/**
+ * Establish the missing generation authority for one adapter-native session,
+ * then reconstruct its disposable heartbeat cache.
+ *
+ * This is intentionally narrower than mid-flight hook onboarding. The caller
+ * must supply an already validated native session, adapter, and current
+ * instance identity. Existing authority is reused only when all three bind to
+ * the same non-terminal producer generation. A terminal generation, an
+ * adapter/session collision, or any disagreement between private producer
+ * control and the public projection fails closed. No turn is synthesized.
+ */
+export declare function bootstrapLiveCoordinationAuthorityV3(input: {
+    coordRoot: string;
+    owner: string;
+    nativeSessionId: string;
+    adapter: Adapter;
+}): BootstrappedLiveCoordinationAuthorityV3;
+/**
+ * Reapply private, generation-bound coordination state after a runtime epoch
+ * replaces the canonical ledger. The old heartbeat is only accepted for the
+ * same native session and a different V3 generation. Its task prose and
+ * lifecycle reason remain in the disposable cache; canonical events retain
+ * only the privacy-safe authority signals.
+ */
+export declare function restoreLiveCoordinationStateAfterEpochV3(input: {
+    coordRoot: string;
+    owner: string;
+    nativeSessionId: string;
+    adapter: Adapter;
+    prior: Heartbeat | null;
+    currentGenerationId?: `gen_${string}`;
+}): RestoredLiveCoordinationStateV3;
 /**
  * Open a fresh derived generation for a human-facing session that is executing
  * again after an authoritative terminal. The terminal generation is never
@@ -55,5 +100,6 @@ export declare function recordLiveIdentityChangeV3(input: LiveAuthorityBaseV3 &
     identityId: string;
 }): LiveCoordinationAuthorityV3Result;
 export declare function liveCoordinationWriteModeV3(coordRoot: string): EventV3WriteMode;
+export declare function coordinationAuthorityStateDigestV3(heartbeat: Heartbeat): `sha256:${string}`;
 export {};
 //# sourceMappingURL=live-authority-v3.d.ts.map

package/dist/core/agents/live-authority-v3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"live-authority-v3.d.ts","sourceRoot":"","sources":["../../../src/core/agents/live-authority-v3.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAehE,OAAO,EACL,KAAK,mCAAmC,EAEzC,MAAM,iDAAiD,CAAC;AAqBzD,eAAO,MAAM,gCAAgC,EAAG,iBAA0B,CAAC;AAE3E,qBAAa,gCAAiC,SAAQ,KAAK;aAC7B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAI3C;AAED,MAAM,MAAM,iCAAiC,GACzC;IAAE,KAAK,EAAE,WAAW,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,mCAAmC,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,oCAAoC;IACnD,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,mBAAmB,EAAE,OAAO,MAAM,EAAE,CAAC;IACrC,aAAa,EAAE,OAAO,MAAM,EAAE,CAAC;CAChC;AAED,UAAU,mBAAmB;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAAC,KAAK,EAAE;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,oCAAoC,CAkDvC;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,mBAAmB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C,iCAAiC,CAiCnC;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,mBAAmB,GAAG;IAC3B,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,iCAAiC,CAmCnC;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,mBAAmB,GAAG;IAC3B,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B,GACA,iCAAiC,CAuCnC;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,mBAAmB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAChE,iCAAiC,CAuBnC;AAuDD,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAI/E"}
+{"version":3,"file":"live-authority-v3.d.ts","sourceRoot":"","sources":["../../../src/core/agents/live-authority-v3.ts"],"names":[],"mappings":"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"}