harnery 0.35.0 → 0.37.0

package/src/core/agents/mailbox.ts

@@ -0,0 +1,373 @@
+/**
+ * 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.ts";
+import { resolveBinName } from "../config.ts";
+import { readLiveCoordinationRows } from "./state/live-coordination-view.ts";
+import { COORD_NAMES } from "./state/names.ts";
+
+export const MAILBOX_MESSAGE_SCHEMA = "harnery.mailbox-message/v1" as const;
+
+/** 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 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 class MailboxCapacityError extends Error {
+  constructor(
+    readonly reason_code: MailboxCapacityReason,
+    readonly current: number,
+    readonly limit: number,
+  ) {
+    super(
+      `mailbox capacity ${reason_code}: ${current}/${limit}; write the payload to a managed artifact and send its path instead`,
+    );
+    this.name = "MailboxCapacityError";
+  }
+}
+
+/** Strip an `agent-` prefix and normalize to the registry's bare form. */
+export function bareAgentName(raw: string): string {
+  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: string): string {
+  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: string): string {
+  return resolve(coordRoot, ".harnery", "mailbox");
+}
+
+export function mailboxPath(coordRoot: string, name: string): string {
+  return join(mailboxDir(coordRoot), `${slugFor(name)}.jsonl`);
+}
+
+function deliveredPath(coordRoot: string, name: string): string {
+  return join(mailboxDir(coordRoot), "delivered", `${slugFor(name)}.jsonl`);
+}
+
+function parseLines(content: string): MailboxMessageV1[] {
+  const out: MailboxMessageV1[] = [];
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed) as MailboxMessageV1;
+      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: string, name: string): boolean {
+  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: string, name: string, limit = 5): string[] {
+  const bare = bareAgentName(name).toLowerCase();
+  const known = new Set<string>(COORD_NAMES);
+  try {
+    for (const row of readLiveCoordinationRows(coordRoot)) if (row.name) known.add(row.name);
+  } catch {
+    /* live rows are advisory here */
+  }
+  const scored: Array<{ name: string; distance: number }> = [];
+  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: string, b: string): number {
+  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]!;
+}
+
+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 function queueMailboxMessage(input: QueueInput): QueueResult {
+  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: MailboxMessageV1 = {
+    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: string, name: string): MailboxMessageV1[] {
+  let path: string;
+  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: string, name: string): MailboxMessageV1[] {
+  let path: string;
+  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: MailboxMessageV1[] = [];
+  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: string): void {
+  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: number;
+      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: string): void {
+  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: string,
+  messages: readonly MailboxMessageV1[],
+): string {
+  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: string): string {
+  return text
+    .split("\n")
+    .map((line) => `    ${line}`)
+    .join("\n");
+}

package/src/core/agents/reconcile-coordination-v3.ts

@@ -0,0 +1,77 @@
+/**
+ * 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,
+  reconcileSessionFinalizationV3,
+} from "./session-finalizer-v3.ts";
+import { staleSweep } from "./state/stale-sweep.ts";
+
+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 function reconcileCoordinationV3(
+  coordRoot: string,
+  options: ReconcileSessionFinalizationOptionsV3 = {},
+): ReconcileCoordinationResultV3 {
+  let sweptHeartbeats = 0;
+  let sweptPidmaps = 0;
+  let sweptPeerHashes = 0;
+  const sweepDiagnostics: string[] = [];
+  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/src/core/agents/render/prompt-context.ts

@@ -1,8 +1,8 @@
 /**
  * UserPromptSubmit UX renderer. Combines the peer-refresh dedup, the
  * council-pending hash-dedup, the cross-adapter first-session naming nudge,
- * the Cursor/Codex set-task staleness nudge, and the Codex status-footer
- * reminder.
+ * the Cursor/Codex set-task staleness nudge, a host-configured prompt reminder,
+ * and the Codex status-footer reminder.
  * agent-hook's turn.started post-emit handler calls this
  * and forwards the result as the adapter-shaped additionalContext payload.
  *
@@ -18,7 +18,10 @@
  *      Cursor/Codex additionally get the existing unset/stale-task reminder
  *      because their Stop hooks do not enforce task declarations as reliably
  *      as Claude Code's.
- *   4. Codex status footer: a non-deduplicated reminder to put the live status
+ *   4. Host prompt reminder: a project-owned, non-deduplicated line for
+ *      adapters whose prompt hook can inject context and which lack a native
+ *      reminder mechanism. Hook routing decides which adapters enable it.
+ *   5. Codex status footer: a non-deduplicated reminder to put the live status
  *      box after the substantive answer. Stop stays observe-only, so missing the
  *      footer can never trigger a replacement response.
  *
@@ -43,15 +46,18 @@ import {
 import { join } from "node:path";
 
 import { coordEnv } from "../../../lib/env.ts";
-import { endOfTurnStatusCommand, resolveBinName } from "../../config.ts";
+import type { Adapter } from "../../adapter.ts";
+import { endOfTurnStatusCommand, hostPromptReminder, resolveBinName } from "../../config.ts";
+import { canReceiveContext } from "../../hooks/adapter/output.ts";
 import { type RemoteMachine, readRemoteMachines } from "../../presence/index.ts";
+import { drainMailbox, formatMailboxDelivery } from "../mailbox.ts";
 import { sessionNameDisplayBlock, sessionNameDisplayPending } from "../session-name-display.ts";
 import {
   readLiveCoordinationRow,
   readLiveCoordinationRows,
 } from "../state/live-coordination-view.ts";
 import type { AgentActivity, TaskState } from "../state/session-state.ts";
-import { formatPendingCouncils } from "./session-context.ts";
+import { formatPendingCouncils, recordDeliveredMessages } from "./session-context.ts";
 
 interface HeartbeatRow {
   instance_id?: string;
@@ -83,9 +89,17 @@ export interface PromptContextOpts {
   /** When true, run the unset/stale-task check after the first set-task.
    * Cursor/Codex use this; Claude Code has Stop-hook transcript enforcement. */
   taskNudge?: boolean;
+  /** When true, append the project-configured prompt reminder without hash
+   * deduplication. The caller enables this only on supported adapter routes. */
+  hostPromptReminder?: boolean;
   /** 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
@@ -110,22 +124,46 @@ export function renderPromptContext(opts: PromptContextOpts): string {
     agentName,
     sessionNameNudge,
     taskNudge,
+    hostPromptReminder: promptReminderEnabled,
     statusFooterNudge,
     turnRitualNudge,
+    adapter,
   } = opts;
   const sections: string[] = [];
 
-  // 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 as 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) {
@@ -136,7 +174,15 @@ export function renderPromptContext(opts: PromptContextOpts): string {
     if (nudgeMsg) sections.push(nudgeMsg);
   }
 
-  // 4. Codex gets this on every prompt. It is intentionally not hash-deduped:
+  // 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) {
+    const reminder = renderHostPromptReminder(coordRoot, instanceId);
+    if (reminder) sections.push(reminder);
+  }
+
+  // 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) {
@@ -144,7 +190,7 @@ export function renderPromptContext(opts: PromptContextOpts): string {
     if (statusMsg) sections.push(statusMsg);
   }
 
-  // 5. 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
@@ -157,6 +203,12 @@ export function renderPromptContext(opts: PromptContextOpts): string {
   return sections.join("\n\n");
 }
 
+function renderHostPromptReminder(coordRoot: string, selfInstanceId: string): string {
+  const hb = readLiveCoordinationRow(coordRoot, selfInstanceId);
+  if (!hb || hb.kind === "subagent" || hb.kind === "transient" || hb.workflow_run_id) return "";
+  return hostPromptReminder(coordRoot) ?? "";
+}
+
 function renderTurnRitualReminder(
   coordRoot: string,
   selfInstanceId: string,
@@ -167,10 +219,9 @@ function renderTurnRitualReminder(
 
   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.
+  // Claude Code and Cursor can both enforce completed assistant reply text.
   const paste =
-    adapter === "claude-code"
+    adapter === "claude-code" || adapter === "cursor"
       ? " and paste its output verbatim in a fenced code block at the end of your reply"
       : "";
   return (

package/src/core/agents/render/session-context.ts

@@ -12,7 +12,9 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { resolveBinName, resolveHooksSetupHint } from "../../config.ts";
 import { harneryVersion, loadAdapterWiring } from "../../hooks/adapter/wiring.ts";
+import { appendEntry } from "../../journal/index.ts";
 import { readRemoteMachines } from "../../presence/index.ts";
+import { drainMailbox, formatMailboxDelivery, type MailboxMessageV1 } from "../mailbox.ts";
 import { readLiveCoordinationRows } from "../state/live-coordination-view.ts";
 import { readForkParent } from "../state/names.ts";
 import type { AgentActivity, TaskState } from "../state/session-state.ts";
@@ -82,13 +84,24 @@ export function renderSessionContext(opts: RenderOpts): string {
     );
   }
 
-  // 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);
@@ -99,7 +112,7 @@ export function renderSessionContext(opts: RenderOpts): string {
     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).
@@ -125,6 +138,27 @@ export function renderSessionContext(opts: RenderOpts): string {
   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: string,
+  messages: readonly MailboxMessageV1[],
+): void {
+  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: string): string {
   try {