harnery 0.36.0 → 0.37.0

package/dist/commands/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/commands/supervisor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAe1E,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAwGN"}

package/dist/commands/supervisor.js

@@ -0,0 +1,101 @@
+import { resolve } from "node:path";
+import { readSupervisorHookHealth } from "../core/supervisor/hook-health-storage.js";
+import { requestSupervisorStop, runSupervisor, spawnSupervisor, } from "../core/supervisor/service.js";
+import { readSupervisorStatus } from "../core/supervisor/status.js";
+import { readSupervisorFindings, readSupervisorHistory, readSupervisorLogFeed, readSupervisorSnapshot, } from "../core/supervisor/storage.js";
+export function registerSupervisorCommand(program, emit, context) {
+    const supervisor = program
+        .command("supervisor")
+        .description("Run Harnery's optional local diagnostic supervisor");
+    supervisor
+        .command("start")
+        .description("Start the detached local supervisor")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--interval-ms <milliseconds>", "Collection interval from 500 to 60000 ms", integer)
+        .option("--idle-exit-ms <milliseconds>", "Exit after this long without a live dashboard consumer or attributed agent", integer)
+        .option("--keep-alive", "Remain resident until explicitly stopped")
+        .action(async (options) => {
+        try {
+            emit.data(await spawnSupervisor(resolve(options.root ?? coordRoot(context)), {
+                intervalMs: options.intervalMs,
+                idleExitMs: options.idleExitMs,
+                keepAlive: options.keepAlive,
+            }));
+        }
+        catch (error) {
+            fail(emit, "supervisor_start_failed", error);
+        }
+    });
+    supervisor
+        .command("status")
+        .description("Show supervisor liveness and its latest bounded projections")
+        .option("--root <path>", "Explicit coordination root")
+        .action((options) => {
+        try {
+            const root = resolve(options.root ?? coordRoot(context));
+            emit.data({
+                service: readSupervisorStatus(root),
+                snapshot: readSupervisorSnapshot(root),
+                history: readSupervisorHistory(root),
+                findings: readSupervisorFindings(root),
+                hook_health: readSupervisorHookHealth(root),
+                log_feed: readSupervisorLogFeed(root),
+            });
+        }
+        catch (error) {
+            fail(emit, "supervisor_status_failed", error);
+        }
+    });
+    supervisor
+        .command("stop")
+        .description("Request a graceful supervisor stop")
+        .option("--root <path>", "Explicit coordination root")
+        .action(async (options) => {
+        try {
+            const root = resolve(options.root ?? coordRoot(context));
+            let status = requestSupervisorStop(root);
+            const deadline = Date.now() + 5_000;
+            while (status.running && Date.now() < deadline) {
+                await new Promise((done) => setTimeout(done, 50));
+                status = readSupervisorStatus(root);
+            }
+            emit.data(status);
+        }
+        catch (error) {
+            fail(emit, "supervisor_stop_failed", error);
+        }
+    });
+    supervisor
+        .command("daemon", { hidden: true })
+        .description("Internal detached local supervisor entrypoint")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--interval-ms <milliseconds>", "Collection interval", integer)
+        .option("--idle-exit-ms <milliseconds>", "Idle exit interval", integer)
+        .option("--keep-alive", "Remain resident until explicitly stopped")
+        .action(async (options) => {
+        try {
+            emit.data(await runSupervisor({
+                coordRoot: resolve(options.root ?? coordRoot(context)),
+                intervalMs: options.intervalMs,
+                idleExitMs: options.idleExitMs,
+                keepAlive: options.keepAlive,
+            }));
+        }
+        catch (error) {
+            fail(emit, "supervisor_daemon_failed", error);
+        }
+    });
+}
+function coordRoot(context) {
+    return context?.resolveCoordRoot?.() ?? context?.repoRoot ?? process.cwd();
+}
+function integer(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed))
+        throw new Error(`expected an integer, got ${value}`);
+    return parsed;
+}
+function fail(emit, code, error) {
+    emit.error({ code, message: error instanceof Error ? error.message : String(error) });
+    emit.setExitCode(1);
+}

package/dist/commands/web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/commands/web.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAyCnD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKrE;AAED,iFAAiF;AACjF,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAKhF;AAED,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAC9D,MAAM,CAQR;AAyCD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAevE;AAsBD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAuN5E"}
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/commands/web.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA8CnD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKrE;AAED,iFAAiF;AACjF,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAKhF;AAED,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAC9D,MAAM,CAQR;AAmDD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAevE;AAsBD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA2N5E"}

package/dist/commands/web.js

@@ -6,6 +6,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.js";
 import { ensureSemanticServiceRunning } from "../core/semantic/service.js";
 import { processLogDestination } from "../core/storage/process-log.js";
+import { ensureSupervisorRunning } from "../core/supervisor/service.js";
+import { registerSupervisorConsumer, unregisterSupervisorConsumer, } from "../core/supervisor/services.js";
 import { parsePerformanceWindow, readWebPerformanceReport, WEB_PERFORMANCE_LOG, } from "../lib/web-performance.js";
 import { lazyFetchWebRoot, webRunner } from "./web-fetch.js";
 /**
@@ -100,6 +102,17 @@ async function startSemanticServiceWithWeb(coordRoot, emit) {
         emit.log(`semantic reader · unavailable (${result.error ?? "startup failed"})`, "warn");
     }
 }
+async function startSupervisorWithWeb(coordRoot, emit) {
+    registerSupervisorConsumer(coordRoot, { id: "dashboard" });
+    const result = await ensureSupervisorRunning(coordRoot);
+    if (result.state === "started")
+        emit.log("local supervisor · started automatically", "info");
+    if (result.state === "running")
+        emit.log("local supervisor · already running", "info");
+    if (result.state === "unavailable") {
+        emit.log(`local supervisor · unavailable (${result.error})`, "warn");
+    }
+}
 /**
  * Resolve the web app root. A local `web/` (source checkout / submodule) wins.
  * Otherwise, on an npm install, lazy-fetch it (clone + install) unless the
@@ -203,6 +216,7 @@ export function registerWebCommand(program, emit) {
         }
         if (!(await requireAvailablePort(emit, port)))
             return;
+        await startSupervisorWithWeb(coordRoot, emit);
         await startSemanticServiceWithWeb(coordRoot, emit);
         const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
         const nodeOptions = nodeOptionsWithWebDiagnostics(root, heapMb);
@@ -232,6 +246,7 @@ export function registerWebCommand(program, emit) {
         process.on("SIGINT", () => cleanup("SIGINT"));
         process.on("SIGTERM", () => cleanup("SIGTERM"));
         child.on("exit", (code, sig) => {
+            unregisterSupervisorConsumer(coordRoot, "dashboard");
             if (sig) {
                 emit.log(`web exited on ${sig}`, "info");
             }
@@ -292,6 +307,7 @@ export function registerWebCommand(program, emit) {
         }
         if (!(await requireAvailablePort(emit, port)))
             return;
+        await startSupervisorWithWeb(coordRoot, emit);
         await startSemanticServiceWithWeb(coordRoot, emit);
         const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
         const nodeOptions = nodeOptionsWithWebDiagnostics(root, heapMb);
@@ -320,6 +336,7 @@ export function registerWebCommand(program, emit) {
         process.on("SIGINT", () => cleanup("SIGINT"));
         process.on("SIGTERM", () => cleanup("SIGTERM"));
         child.on("exit", (code) => {
+            unregisterSupervisorConsumer(coordRoot, "dashboard");
             process.exitCode = code ?? 0;
         });
     });

package/dist/commands/workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../src/commands/workflow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAyEnD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA4uBjF"}
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../src/commands/workflow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA0EnD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAmvBjF"}

package/dist/commands/workflow.js

@@ -24,6 +24,7 @@ export function registerWorkflowCommand(program, emit) {
         .description("Workflow script (plain JS: `export default async ({agent, parallel, stage, log, evidence, authorize}) => …`)")
         .option("--max-agents <n>", "Total-agent ceiling for the run (default 50)")
         .option("--concurrency <n>", "Concurrent-subagent cap (default 4)")
+        .option("--observe-pressure", "Record observer-only local pressure before the first real child dispatch")
         .option("--cwd <dir>", "Working directory children spawn in (default: coord root)")
         .option("--adapter <name>", `Default adapter for agent() calls: ${adapters.join(" | ")} (default claude-code); scripts can override per agent via opts.adapter`)
         .option("--resume-from <run-id>", "Reuse completed agent results from a prior run's transcript; only changed/failed calls re-run")
@@ -94,6 +95,9 @@ export function registerWorkflowCommand(program, emit) {
                 allowApiBilling: opts.allowApiBilling,
                 maxAgents: opts.maxAgents ? Number.parseInt(opts.maxAgents, 10) : undefined,
                 concurrency: opts.concurrency ? Number.parseInt(opts.concurrency, 10) : undefined,
+                diagnosticAdmission: opts.observePressure
+                    ? { schema_version: 1, mode: "shadow" }
+                    : undefined,
                 cwd: opts.cwd,
                 ...adapterProofInputs(registry.list().map((adapter) => adapter.profile), { versionProbe: probeBinaryVersion }),
                 policy: opts.policy ? loadPolicyFile(opts.policy) : undefined,

package/dist/core/agents/cli.js

@@ -621,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;
 }
@@ -671,6 +673,7 @@ 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";
@@ -679,7 +682,7 @@ async function handlePromptContext(root, rest) {
     // 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] [--host-prompt-reminder] [--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");
@@ -693,6 +696,7 @@ async function handlePromptContext(root, rest) {
         hostPromptReminder,
         statusFooterNudge,
         turnRitualNudge,
+        adapter,
     });
     process.stdout.write(text);
     return 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/mailbox.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Name-addressed durable mailbox.
+ *
+ * Peer messaging used to require a live recipient: the sender resolved a name
+ * to a running instance and wrote into that instance's journal. Two failures
+ * followed from that. A message to a name whose session had ended was refused
+ * outright, so the sender spent a long sequence of discovery calls looking for
+ * somewhere else to put it. A message to a live peer was accepted but never
+ * shown to them, because nothing surfaces another session's journal.
+ *
+ * This module addresses the durable persona name instead of the instance, so a
+ * message can be queued before its recipient exists. Delivery happens on the
+ * recipient's side: their next SessionStart or prompt drains the queue, shows
+ * the messages, and records them in their journal.
+ *
+ * Storage: `.harnery/mailbox/<slug>.jsonl`, one JSON record per line, appended
+ * by senders and removed by an atomic claim on the recipient's side. Delivered
+ * records are appended to `.harnery/mailbox/delivered/<slug>.jsonl` for audit.
+ *
+ * Related but distinct: `core/inbox` is an instance-keyed transport with a
+ * storage-framework service behind it. This mailbox is name-keyed, file-only,
+ * and follows the same shape as council manifests and journals.
+ */
+export declare const MAILBOX_MESSAGE_SCHEMA: "harnery.mailbox-message/v1";
+/** Per-message body ceiling. Larger payloads belong in a managed artifact, with
+ * the path sent as the message. */
+export declare const MAX_BODY_BYTES = 4000;
+/** Pending messages held for one name before senders are refused. */
+export declare const MAX_PENDING = 25;
+export interface MailboxMessageV1 {
+    schema: typeof MAILBOX_MESSAGE_SCHEMA;
+    message_id: string;
+    /** Bare display name the sender addressed (registry casing when known). */
+    to_name: string;
+    from_name: string;
+    from_instance_id: string;
+    created_at: string;
+    body: string;
+    /** True when the sender already appended this to a live recipient's journal,
+     * so the drain surfaces it without writing a duplicate entry. */
+    journaled: boolean;
+}
+export type MailboxCapacityReason = "body_limit" | "pending_limit";
+export declare class MailboxCapacityError extends Error {
+    readonly reason_code: MailboxCapacityReason;
+    readonly current: number;
+    readonly limit: number;
+    constructor(reason_code: MailboxCapacityReason, current: number, limit: number);
+}
+/** Strip an `agent-` prefix and normalize to the registry's bare form. */
+export declare function bareAgentName(raw: string): string;
+export declare function mailboxDir(coordRoot: string): string;
+export declare function mailboxPath(coordRoot: string, name: string): string;
+/** Every name a message may be addressed to: live sessions, the durable
+ * identity registry, and the built-in name pool. A name outside all three is a
+ * typo, and queueing it would silently swallow the message. */
+export declare function isAddressableName(coordRoot: string, name: string): boolean;
+/** Names close enough to a miss to be worth suggesting (prefix or one edit). */
+export declare function suggestNames(coordRoot: string, name: string, limit?: number): string[];
+export interface QueueInput {
+    coordRoot: string;
+    toName: string;
+    fromName: string;
+    fromInstanceId: string;
+    body: string;
+    journaled?: boolean;
+}
+export interface QueueResult {
+    message: MailboxMessageV1;
+    path: string;
+    pending: number;
+}
+/**
+ * Append one message to a name's mailbox. Throws `MailboxCapacityError` when
+ * the body or the pending queue is over its ceiling; the caller turns that into
+ * an actionable CLI error.
+ */
+export declare function queueMailboxMessage(input: QueueInput): QueueResult;
+/** Pending messages for a name, without claiming them. */
+export declare function peekMailbox(coordRoot: string, name: string): MailboxMessageV1[];
+/**
+ * Claim and return every pending message for a name.
+ *
+ * The claim is an atomic rename, so two sessions sharing a name cannot deliver
+ * the same message twice: whichever rename wins owns the batch. Claimed records
+ * are appended to the delivered archive before the claim file is removed, so a
+ * crash between the two leaves an auditable copy rather than a silent loss.
+ */
+export declare function drainMailbox(coordRoot: string, name: string): MailboxMessageV1[];
+/** Render a drained batch as the context block a recipient reads. */
+export declare function formatMailboxDelivery(coordRoot: string, messages: readonly MailboxMessageV1[]): string;
+//# sourceMappingURL=mailbox.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.d.ts","sourceRoot":"","sources":["../../../src/core/agents/mailbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAqBH,eAAO,MAAM,sBAAsB,EAAG,4BAAqC,CAAC;AAE5E;mCACmC;AACnC,eAAO,MAAM,cAAc,OAAO,CAAC;AACnC,qEAAqE;AACrE,eAAO,MAAM,WAAW,KAAK,CAAC;AAI9B,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb;qEACiE;IACjE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,eAAe,CAAC;AAEnE,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,WAAW,EAAE,qBAAqB;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAFb,WAAW,EAAE,qBAAqB,EAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM;CAOzB;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGjD;AAYD,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnE;AAqBD;;+DAE+D;AAC/D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAU1E;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,EAAE,CAiBjF;AAiBD,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CA6BlE;AAED,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAa/E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAmDhF;AA8CD,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,MAAM,CAcR"}