harnery 0.36.0 → 0.37.0

package/dist/core/agents/mailbox.js

@@ -0,0 +1,325 @@
+/**
+ * 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.
+ */
+import { randomUUID } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { lookupByName } from "../../lib/identities/index.js";
+import { resolveBinName } from "../config.js";
+import { readLiveCoordinationRows } from "./state/live-coordination-view.js";
+import { COORD_NAMES } from "./state/names.js";
+export 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 const MAX_BODY_BYTES = 4000;
+/** Pending messages held for one name before senders are refused. */
+export const MAX_PENDING = 25;
+/** Delivered-archive ceiling; the file is truncated from the head past this. */
+const MAX_DELIVERED_BYTES = 256 * 1024;
+export class MailboxCapacityError extends Error {
+    reason_code;
+    current;
+    limit;
+    constructor(reason_code, current, limit) {
+        super(`mailbox capacity ${reason_code}: ${current}/${limit}; write the payload to a managed artifact and send its path instead`);
+        this.reason_code = reason_code;
+        this.current = current;
+        this.limit = limit;
+        this.name = "MailboxCapacityError";
+    }
+}
+/** Strip an `agent-` prefix and normalize to the registry's bare form. */
+export function bareAgentName(raw) {
+    const trimmed = raw.trim();
+    return trimmed.toLowerCase().startsWith("agent-") ? trimmed.slice("agent-".length) : trimmed;
+}
+/** Filesystem-safe slug for a name. Rejects anything that could escape the
+ * mailbox directory rather than sanitizing it into a different agent's file. */
+function slugFor(name) {
+    const bare = bareAgentName(name).toLowerCase();
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(bare)) {
+        throw new Error(`invalid agent name for mailbox addressing: ${JSON.stringify(name)}`);
+    }
+    return bare;
+}
+export function mailboxDir(coordRoot) {
+    return resolve(coordRoot, ".harnery", "mailbox");
+}
+export function mailboxPath(coordRoot, name) {
+    return join(mailboxDir(coordRoot), `${slugFor(name)}.jsonl`);
+}
+function deliveredPath(coordRoot, name) {
+    return join(mailboxDir(coordRoot), "delivered", `${slugFor(name)}.jsonl`);
+}
+function parseLines(content) {
+    const out = [];
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed?.schema === MAILBOX_MESSAGE_SCHEMA)
+                out.push(parsed);
+        }
+        catch {
+            /* skip a torn line rather than losing the whole mailbox */
+        }
+    }
+    return out;
+}
+/** 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 function isAddressableName(coordRoot, name) {
+    const bare = bareAgentName(name).toLowerCase();
+    if (!bare)
+        return false;
+    if (COORD_NAMES.some((n) => n.toLowerCase() === bare))
+        return true;
+    if (lookupByName(bare, coordRoot))
+        return true;
+    try {
+        return readLiveCoordinationRows(coordRoot).some((r) => (r.name ?? "").toLowerCase() === bare);
+    }
+    catch {
+        return false;
+    }
+}
+/** Names close enough to a miss to be worth suggesting (prefix or one edit). */
+export function suggestNames(coordRoot, name, limit = 5) {
+    const bare = bareAgentName(name).toLowerCase();
+    const known = new Set(COORD_NAMES);
+    try {
+        for (const row of readLiveCoordinationRows(coordRoot))
+            if (row.name)
+                known.add(row.name);
+    }
+    catch {
+        /* live rows are advisory here */
+    }
+    const scored = [];
+    for (const candidate of known) {
+        const lower = candidate.toLowerCase();
+        if (lower.startsWith(bare.slice(0, 2)) || editDistance(lower, bare) <= 2) {
+            scored.push({ name: candidate, distance: editDistance(lower, bare) });
+        }
+    }
+    scored.sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+    return scored.slice(0, limit).map((s) => s.name);
+}
+function editDistance(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let prev = Array.from({ length: cols }, (_, i) => i);
+    for (let i = 1; i < rows; i++) {
+        const curr = [i, ...Array.from({ length: cols - 1 }, () => 0)];
+        for (let j = 1; j < cols; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        prev = curr;
+    }
+    return prev[cols - 1];
+}
+/**
+ * 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 function queueMailboxMessage(input) {
+    const body = input.body.trim();
+    const bodyBytes = Buffer.byteLength(body, "utf8");
+    if (bodyBytes > MAX_BODY_BYTES) {
+        throw new MailboxCapacityError("body_limit", bodyBytes, MAX_BODY_BYTES);
+    }
+    const path = mailboxPath(input.coordRoot, input.toName);
+    mkdirSync(mailboxDir(input.coordRoot), { recursive: true });
+    const existing = existsSync(path) ? parseLines(readFileSync(path, "utf8")) : [];
+    if (existing.length >= MAX_PENDING) {
+        throw new MailboxCapacityError("pending_limit", existing.length, MAX_PENDING);
+    }
+    // Preserve registry casing when the persona is known, so the recipient sees
+    // their own name spelled the way it is everywhere else.
+    const identity = lookupByName(input.toName, input.coordRoot);
+    const message = {
+        schema: MAILBOX_MESSAGE_SCHEMA,
+        message_id: randomUUID(),
+        to_name: identity?.name ?? bareAgentName(input.toName),
+        from_name: input.fromName,
+        from_instance_id: input.fromInstanceId,
+        created_at: new Date().toISOString(),
+        body,
+        journaled: input.journaled ?? false,
+    };
+    appendFileSync(path, `${JSON.stringify(message)}\n`, "utf8");
+    return { message, path, pending: existing.length + 1 };
+}
+/** Pending messages for a name, without claiming them. */
+export function peekMailbox(coordRoot, name) {
+    let path;
+    try {
+        path = mailboxPath(coordRoot, name);
+    }
+    catch {
+        return [];
+    }
+    if (!existsSync(path))
+        return [];
+    try {
+        return parseLines(readFileSync(path, "utf8"));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 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 function drainMailbox(coordRoot, name) {
+    let path;
+    try {
+        path = mailboxPath(coordRoot, name);
+    }
+    catch {
+        return [];
+    }
+    // Heal first: a claim file left by a crashed reader may hold the only copy of
+    // a message for this very name, and sweeping after the existence check would
+    // skip it whenever the live queue is empty.
+    sweepStaleClaims(coordRoot);
+    if (!existsSync(path))
+        return [];
+    const claim = `${path}.claim-${process.pid}-${Date.now()}`;
+    try {
+        renameSync(path, claim);
+    }
+    catch {
+        // Another reader claimed it first, or the file vanished. Either way there
+        // is nothing for this caller to deliver.
+        return [];
+    }
+    let messages = [];
+    try {
+        messages = parseLines(readFileSync(claim, "utf8"));
+    }
+    catch {
+        messages = [];
+    }
+    if (messages.length > 0) {
+        try {
+            const archive = deliveredPath(coordRoot, name);
+            mkdirSync(join(mailboxDir(coordRoot), "delivered"), { recursive: true });
+            const deliveredAt = new Date().toISOString();
+            appendFileSync(archive, `${messages.map((m) => JSON.stringify({ ...m, delivered_at: deliveredAt })).join("\n")}\n`, "utf8");
+            trimArchive(archive);
+        }
+        catch {
+            /* audit copy is best-effort; never block delivery on it */
+        }
+    }
+    try {
+        unlinkSync(claim);
+    }
+    catch {
+        /* a leftover claim is re-queued by the next drain's sweep */
+    }
+    return messages;
+}
+/** Re-queue any claim file left behind by a crashed reader (older than 5 min),
+ * so a killed session cannot strand a message. Runs at the head of every drain. */
+function sweepStaleClaims(coordRoot) {
+    const dir = mailboxDir(coordRoot);
+    if (!existsSync(dir))
+        return;
+    const cutoff = Date.now() - 5 * 60_000;
+    try {
+        for (const file of readdirSync(dir)) {
+            const marker = file.indexOf(".jsonl.claim-");
+            if (marker === -1)
+                continue;
+            const full = join(dir, file);
+            let mtime;
+            try {
+                mtime = statSync(full).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            if (mtime > cutoff)
+                continue;
+            const owner = join(dir, `${file.slice(0, marker)}.jsonl`);
+            try {
+                const content = readFileSync(full, "utf8");
+                if (content.trim())
+                    appendFileSync(owner, content.endsWith("\n") ? content : `${content}\n`);
+                unlinkSync(full);
+            }
+            catch {
+                /* skip; next sweep retries */
+            }
+        }
+    }
+    catch {
+        /* directory read is best-effort */
+    }
+}
+function trimArchive(path) {
+    try {
+        if (statSync(path).size <= MAX_DELIVERED_BYTES)
+            return;
+        const lines = readFileSync(path, "utf8").split("\n").filter(Boolean);
+        const keep = lines.slice(Math.floor(lines.length / 2));
+        writeFileSync(path, `${keep.join("\n")}\n`, "utf8");
+    }
+    catch {
+        /* trimming is housekeeping, never load-bearing */
+    }
+}
+/** Render a drained batch as the context block a recipient reads. */
+export function formatMailboxDelivery(coordRoot, messages) {
+    if (messages.length === 0)
+        return "";
+    const bin = resolveBinName(coordRoot);
+    const header = messages.length === 1
+        ? `Message from a peer agent (delivered now, recorded in your journal):`
+        : `${messages.length} messages from peer agents (delivered now, recorded in your journal):`;
+    const body = messages
+        .map((m) => {
+        const when = m.created_at.replace("T", " ").replace(/\.\d+Z$/, "Z");
+        return `  from agent-${m.from_name} (${when}):\n${indent(m.body)}`;
+    })
+        .join("\n\n");
+    return `${header}\n\n${body}\n\nReply with \`${bin} agents ping ${messages[0].from_name} "<your reply>"\`; it reaches them whether or not their session is still running.`;
+}
+function indent(text) {
+    return text
+        .split("\n")
+        .map((line) => `    ${line}`)
+        .join("\n");
+}

package/dist/core/agents/reconcile-coordination-v3.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The canonical supervisor reconcile pass.
+ *
+ * Two things have to happen together, in this order:
+ *
+ *   1. `staleSweep` prunes the disposable coordination cache under
+ *      `.harnery/active` (plus orphaned pid-map and `.last-peer-hash` files)
+ *      and leaves a durable lifecycle observation for every deletion.
+ *   2. `reconcileSessionFinalizationV3` turns those observations, along with
+ *      archive/idle/run/host signals, into session finalization requests.
+ *
+ * Running the sweep first is what makes a single pass self-contained: the
+ * `lifecycle.sweep_observed` rows it writes are visible to the finalizer in
+ * the same pass, so a stale session is both reaped and finalized without
+ * waiting for a later invocation.
+ *
+ * ADR 0077 already specified that `agents reconcile` and session start
+ * discover stale-sweep in the same pass. Both entry points had drifted to
+ * calling only the finalizer, so the sweep never ran outside its own
+ * subcommand. This module is the single composition both now share; adding a
+ * caller means calling this, not re-composing the two halves.
+ */
+import { type ReconcileSessionFinalizationOptionsV3, type ReconcileSessionFinalizationResultV3 } from "./session-finalizer-v3.js";
+export interface ReconcileCoordinationResultV3 extends ReconcileSessionFinalizationResultV3 {
+    /** Heartbeat cache files deleted from `.harnery/active` by the sweep. */
+    swept_heartbeats: number;
+    /** Orphaned `.harnery/pid-map` entries deleted by the sweep. */
+    swept_pidmaps: number;
+    /** Dead-owner `.last-peer-hash.*` files deleted by the sweep. */
+    swept_peer_hashes: number;
+}
+/**
+ * Sweep the disposable coordination cache, then reconcile session
+ * finalization, and report both sets of counts.
+ *
+ * The sweep owns its own safety contract (configured coordination freshness
+ * for valid rows, an additional stale-mtime gate for malformed or missing
+ * timestamps, and a durable audit record before any deletion, failing closed
+ * when neither can be written). Nothing here loosens it, and a sweep failure
+ * never blocks finalization: the cache is a projection that heals on the
+ * owning agent's next tool call, while the V3 ledger is authoritative.
+ */
+export declare function reconcileCoordinationV3(coordRoot: string, options?: ReconcileSessionFinalizationOptionsV3): ReconcileCoordinationResultV3;
+//# sourceMappingURL=reconcile-coordination-v3.d.ts.map

package/dist/core/agents/reconcile-coordination-v3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile-coordination-v3.d.ts","sourceRoot":"","sources":["../../../src/core/agents/reconcile-coordination-v3.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,KAAK,qCAAqC,EAC1C,KAAK,oCAAoC,EAE1C,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,6BAA8B,SAAQ,oCAAoC;IACzF,yEAAyE;IACzE,gBAAgB,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,qCAA0C,GAClD,6BAA6B,CAuB/B"}

package/dist/core/agents/reconcile-coordination-v3.js

@@ -0,0 +1,58 @@
+/**
+ * The canonical supervisor reconcile pass.
+ *
+ * Two things have to happen together, in this order:
+ *
+ *   1. `staleSweep` prunes the disposable coordination cache under
+ *      `.harnery/active` (plus orphaned pid-map and `.last-peer-hash` files)
+ *      and leaves a durable lifecycle observation for every deletion.
+ *   2. `reconcileSessionFinalizationV3` turns those observations, along with
+ *      archive/idle/run/host signals, into session finalization requests.
+ *
+ * Running the sweep first is what makes a single pass self-contained: the
+ * `lifecycle.sweep_observed` rows it writes are visible to the finalizer in
+ * the same pass, so a stale session is both reaped and finalized without
+ * waiting for a later invocation.
+ *
+ * ADR 0077 already specified that `agents reconcile` and session start
+ * discover stale-sweep in the same pass. Both entry points had drifted to
+ * calling only the finalizer, so the sweep never ran outside its own
+ * subcommand. This module is the single composition both now share; adding a
+ * caller means calling this, not re-composing the two halves.
+ */
+import { reconcileSessionFinalizationV3, } from "./session-finalizer-v3.js";
+import { staleSweep } from "./state/stale-sweep.js";
+/**
+ * Sweep the disposable coordination cache, then reconcile session
+ * finalization, and report both sets of counts.
+ *
+ * The sweep owns its own safety contract (configured coordination freshness
+ * for valid rows, an additional stale-mtime gate for malformed or missing
+ * timestamps, and a durable audit record before any deletion, failing closed
+ * when neither can be written). Nothing here loosens it, and a sweep failure
+ * never blocks finalization: the cache is a projection that heals on the
+ * owning agent's next tool call, while the V3 ledger is authoritative.
+ */
+export function reconcileCoordinationV3(coordRoot, options = {}) {
+    let sweptHeartbeats = 0;
+    let sweptPidmaps = 0;
+    let sweptPeerHashes = 0;
+    const sweepDiagnostics = [];
+    try {
+        const sweep = staleSweep(coordRoot);
+        sweptHeartbeats = sweep.heartbeatsRemoved.length;
+        sweptPidmaps = sweep.pidmapsRemoved;
+        sweptPeerHashes = sweep.peerHashesRemoved;
+    }
+    catch (error) {
+        sweepDiagnostics.push(`stale_sweep_failed:${error instanceof Error ? error.message : String(error)}`);
+    }
+    const result = reconcileSessionFinalizationV3(coordRoot, options);
+    return {
+        ...result,
+        diagnostics: [...sweepDiagnostics, ...result.diagnostics],
+        swept_heartbeats: sweptHeartbeats,
+        swept_pidmaps: sweptPidmaps,
+        swept_peer_hashes: sweptPeerHashes,
+    };
+}

package/dist/core/agents/render/prompt-context.d.ts

@@ -49,6 +49,11 @@ export interface PromptContextOpts {
     /** When true, append the non-deduplicated Codex status-footer reminder.
      * The caller enables this only for human-facing Codex sessions. */
     statusFooterNudge?: boolean;
+    /** Adapter id this prompt is being rendered for. Gates the mailbox drain:
+     * an adapter that cannot receive UserPromptSubmit context must not consume
+     * messages here, or they are removed from the queue and never shown. When
+     * omitted, delivery is attempted (the default route can receive). */
+    adapter?: string;
     /** Adapter id whose Stop hook ENFORCES the end-of-turn ritual (task_set +
      * status check). When set, append a fresh per-prompt reminder of that
      * contract so the model satisfies it before ending the turn instead of

package/dist/core/agents/render/prompt-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/prompt-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AA4CH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;8EAC0E;IAC1E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;kFAC8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;kFAC8E;IAC9E,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;uEACmE;IACnE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;wBAIoB;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CA8DnE"}
+{"version":3,"file":"prompt-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/prompt-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AA+CH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;8EAC0E;IAC1E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;kFAC8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;kFAC8E;IAC9E,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;uEACmE;IACnE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;yEAGqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;wBAIoB;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAqFnE"}

package/dist/core/agents/render/prompt-context.js

@@ -37,10 +37,12 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, w
 import { join } from "node:path";
 import { coordEnv } from "../../../lib/env.js";
 import { endOfTurnStatusCommand, hostPromptReminder, resolveBinName } from "../../config.js";
+import { canReceiveContext } from "../../hooks/adapter/output.js";
 import { readRemoteMachines } from "../../presence/index.js";
+import { drainMailbox, formatMailboxDelivery } from "../mailbox.js";
 import { sessionNameDisplayBlock, sessionNameDisplayPending } from "../session-name-display.js";
 import { readLiveCoordinationRow, readLiveCoordinationRows, } from "../state/live-coordination-view.js";
-import { formatPendingCouncils } from "./session-context.js";
+import { formatPendingCouncils, recordDeliveredMessages } from "./session-context.js";
 /**
  * Build the combined UserPromptSubmit additionalContext string. Returns "" when
  * nothing has changed since the last call (so the caller can skip the JSON emit).
@@ -50,19 +52,39 @@ import { formatPendingCouncils } from "./session-context.js";
  * councils are pending, matching the bash behavior).
  */
 export function renderPromptContext(opts) {
-    const { coordRoot, instanceId, sessionId, agentName, sessionNameNudge, taskNudge, hostPromptReminder: promptReminderEnabled, statusFooterNudge, turnRitualNudge, } = opts;
+    const { coordRoot, instanceId, sessionId, agentName, sessionNameNudge, taskNudge, hostPromptReminder: promptReminderEnabled, statusFooterNudge, turnRitualNudge, adapter, } = opts;
     const sections = [];
-    // 1. Peer table with hash dedup.
+    // The hook route does not pass --name, so resolve it from the heartbeat.
+    // Every name-addressed section below (messages, councils) is silently
+    // skipped without it.
+    const resolvedName = agentName ?? readLiveCoordinationRow(coordRoot, instanceId)?.name;
+    // 1. Peer messages. Drained first and never deduped: a message is delivered
+    // exactly once, and it is the one section here that carries new information
+    // from another agent rather than a reminder.
+    //
+    // Draining is gated on the adapter being able to receive this event's
+    // context. Cursor cannot, so draining there would empty the queue into output
+    // that is discarded; those sessions get their messages at SessionStart, which
+    // Cursor does deliver.
+    const canDeliverHere = !adapter || canReceiveContext(adapter, "UserPromptSubmit");
+    if (resolvedName && canDeliverHere) {
+        const delivered = drainMailbox(coordRoot, resolvedName);
+        if (delivered.length > 0) {
+            recordDeliveredMessages(instanceId, delivered);
+            sections.push(formatMailboxDelivery(coordRoot, delivered));
+        }
+    }
+    // 2. Peer table with hash dedup.
     const peerTable = computePeerTableIfChanged(coordRoot, instanceId, sessionId);
     if (peerTable)
         sections.push(peerTable);
-    // 2. Council pending with hash dedup.
-    if (agentName) {
-        const councilMsg = computeCouncilPendingIfChanged(coordRoot, instanceId, agentName);
+    // 3. Council pending with hash dedup.
+    if (resolvedName) {
+        const councilMsg = computeCouncilPendingIfChanged(coordRoot, instanceId, resolvedName);
         if (councilMsg)
             sections.push(councilMsg);
     }
-    // 3. First-session naming for every adapter, plus unset/stale-task reminders
+    // 4. First-session naming for every adapter, plus unset/stale-task reminders
     // for Cursor/Codex. One state machine avoids a second generic "task unset"
     // reminder immediately after the first-session reminder has been deduped.
     if (sessionNameNudge || taskNudge) {
@@ -73,7 +95,7 @@ export function renderPromptContext(opts) {
         if (nudgeMsg)
             sections.push(nudgeMsg);
     }
-    // 4. A supported adapter gets the host reminder on every prompt. The text is
+    // 5. A supported adapter gets the host reminder on every prompt. The text is
     // intentionally not hash-deduped or persisted into runtime state: freshness
     // is the feature, and the project config remains its only durable copy.
     if (promptReminderEnabled) {
@@ -81,7 +103,7 @@ export function renderPromptContext(opts) {
         if (reminder)
             sections.push(reminder);
     }
-    // 5. Codex gets this on every prompt. It is intentionally not hash-deduped:
+    // 6. Codex gets this on every prompt. It is intentionally not hash-deduped:
     // the reminder must be fresh in the model's context when it writes the reply.
     // Missing it is harmless because Codex Stop enforcement remains observe-only.
     if (statusFooterNudge) {
@@ -89,7 +111,7 @@ export function renderPromptContext(opts) {
         if (statusMsg)
             sections.push(statusMsg);
     }
-    // 6. Adapters whose Stop hook ENFORCES the turn ritual get a fresh reminder
+    // 7. Adapters whose Stop hook ENFORCES the turn ritual get a fresh reminder
     // on every prompt. Reminding before the reply is drafted is far cheaper than
     // the bounce-and-retry the Stop hook otherwise forces: enforcement-only
     // compliance was measured missing on a double-digit share of turns. Not
@@ -113,9 +135,8 @@ function renderTurnRitualReminder(coordRoot, selfInstanceId, adapter) {
         return "";
     const bin = resolveBinName(coordRoot);
     const statusCommand = endOfTurnStatusCommand(coordRoot);
-    // Claude Code renders the status box only if the reply carries it; Cursor
-    // shows the box inline on its own, so it is never asked for a second copy.
-    const paste = adapter === "claude-code"
+    // Claude Code and Cursor can both enforce completed assistant reply text.
+    const paste = adapter === "claude-code" || adapter === "cursor"
         ? " and paste its output verbatim in a fenced code block at the end of your reply"
         : "";
     return (`Turn ritual (Stop-enforced): on any turn that uses tools, run \`${bin} agents set-task "<short focus>"\` at some point during the turn (required every turn, even when the focus is unchanged; pass an empty string when there is no meaningful focus), then make \`${statusCommand}\` your final tool call${paste}. ` +

package/dist/core/agents/render/session-context.d.ts

@@ -7,6 +7,7 @@
  * string.
  */
 import { statSync } from "node:fs";
+import { type MailboxMessageV1 } from "../mailbox.js";
 export interface RenderOpts {
     coordRoot: string;
     instanceId: string;
@@ -21,6 +22,13 @@ export interface RenderOpts {
  * string (or "" if there's nothing to say).
  */
 export declare function renderSessionContext(opts: RenderOpts): string;
+/**
+ * Write delivered peer messages into the recipient's own journal, so they
+ * survive context compaction the way any other coordination breadcrumb does.
+ * A message the sender already journaled (the recipient was live when it was
+ * sent) is skipped to avoid a duplicate entry.
+ */
+export declare function recordDeliveredMessages(instanceId: string, messages: readonly MailboxMessageV1[]): void;
 /**
  * Returns a list of commit-guard wiring issues (empty when wired). Portable
  * across host projects: it asserts the FUNCTIONAL property ("does this repo's

package/dist/core/agents/render/session-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAyC,QAAQ,EAAE,MAAM,SAAS,CAAC;AAwB1E,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+BAC2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CA6E7D;AAkID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAwBvD;AA0DD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAiDlF;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,iBAAW,CAAC"}
+{"version":3,"file":"session-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAyC,QAAQ,EAAE,MAAM,SAAS,CAAC;AAM1E,OAAO,EAAuC,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAoB3F,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+BAC2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAwF7D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,IAAI,CAUN;AAkID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAwBvD;AA0DD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAiDlF;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,iBAAW,CAAC"}

package/dist/core/agents/render/session-context.js

@@ -11,7 +11,9 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { resolveBinName, resolveHooksSetupHint } from "../../config.js";
 import { harneryVersion, loadAdapterWiring } from "../../hooks/adapter/wiring.js";
+import { appendEntry } from "../../journal/index.js";
 import { readRemoteMachines } from "../../presence/index.js";
+import { drainMailbox, formatMailboxDelivery } from "../mailbox.js";
 import { readLiveCoordinationRows } from "../state/live-coordination-view.js";
 import { readForkParent } from "../state/names.js";
 /**
@@ -50,13 +52,23 @@ export function renderSessionContext(opts) {
     if (isLinkedWorktree(coordRoot)) {
         messages.push(`Running inside worktree ${process.cwd()}. The coord layer is scoped to this worktree only; use \`${resolveBinName(coordRoot)} worktree diff\` to check for conflicts against sibling worktrees.`);
     }
-    // 3. Council invites
+    // 3. Peer messages queued for this name while no session held it. Draining
+    // here is what makes `agents ping` safe to use on a dormant agent: the sender
+    // never has to know whether the recipient is running.
+    if (agentName) {
+        const delivered = drainMailbox(coordRoot, agentName);
+        if (delivered.length > 0) {
+            recordDeliveredMessages(instanceId, delivered);
+            messages.push(formatMailboxDelivery(coordRoot, delivered));
+        }
+    }
+    // 4. Council invites
     if (agentName) {
         const councilMsg = formatPendingCouncils(coordRoot, agentName);
         if (councilMsg)
             messages.push(councilMsg);
     }
-    // 4. Commit-guard wiring check
+    // 5. Commit-guard wiring check
     const wiringIssues = checkWiring(coordRoot);
     if (wiringIssues.length > 0) {
         const hint = resolveHooksSetupHint(coordRoot);
@@ -66,7 +78,7 @@ export function renderSessionContext(opts) {
         const wiringSummary = `Coordination hooks are NOT wired: the E-guard will not block conflicting commits, and post-commit claim pruning will not run. ${fix} Detected:\n${wiringIssues.map((i) => `  - ${i}`).join("\n")}`;
         messages.push(wiringSummary);
     }
-    // 5. Adapter-hook drift: a harnery upgrade changed the hook set, but this
+    // 6. Adapter-hook drift: a harnery upgrade changed the hook set, but this
     // project's settings file hasn't been re-wired. Only fires for a adapter the
     // project already opted into (≥1 hook wired), so it never nags a project that
     // simply has a settings file. Remedy is always `<bin> init` (idempotent).
@@ -89,6 +101,25 @@ export function renderSessionContext(opts) {
     }
     return messages.join("\n\n");
 }
+/**
+ * Write delivered peer messages into the recipient's own journal, so they
+ * survive context compaction the way any other coordination breadcrumb does.
+ * A message the sender already journaled (the recipient was live when it was
+ * sent) is skipped to avoid a duplicate entry.
+ */
+export function recordDeliveredMessages(instanceId, messages) {
+    for (const m of messages) {
+        if (m.journaled)
+            continue;
+        try {
+            appendEntry(instanceId, "handoff", `from agent-${m.from_name}: ${m.body}`);
+        }
+        catch {
+            // A journal write failure must never cost the delivery itself; the
+            // message is already in the rendered context the model reads.
+        }
+    }
+}
 /** One-line-per-agent view of sessions on other machines (presence refs). */
 function formatRemoteMachines(coordRoot) {
     try {

package/dist/core/agents/rules/commit-conflict.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commit-conflict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/commit-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAkBH,UAAU,QAAQ;IAChB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;wEACoE;IACpE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,oBAAoB,GAAG,mBAAmB,CAuHhG"}
+{"version":3,"file":"commit-conflict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/commit-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAoBH,UAAU,QAAQ;IAChB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;wEACoE;IACpE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,oBAAoB,GAAG,mBAAmB,CAgIhG"}