harnery 0.43.0 → 0.45.0

package/src/commands/turn-rollback.ts

@@ -0,0 +1,111 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { monorepoRoot } from "../core/agents/index.ts";
+import {
+  applyTurnRollback,
+  beginTurnRollback,
+  inspectTurnRollback,
+  prepareTurnRollback,
+  sealTurnRollback,
+  type TurnRollbackPlan,
+} from "../core/turn-rollback/index.ts";
+import { readJsonRecord } from "../core/workflow/durable-record.ts";
+import { readWorkspaceBinding } from "../core/workflow/workspaces/state.ts";
+
+/** Explicit turn boundaries; hooks cannot infer provider ownership or path scope. */
+export function registerTurnRollbackCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  const command = program
+    .command("turn-rollback")
+    .description("Capture and review exact-path content rollback in an owned workspace");
+  type Options = {
+    binding: string;
+    turn?: string;
+    generation?: string;
+    path?: string[];
+    yes?: boolean;
+    actor?: string;
+    reason?: string;
+    plan?: string;
+  };
+  const run =
+    (operation: (coordRoot: string, options: Options) => unknown | Promise<unknown>) =>
+    async (options: Options) => {
+      try {
+        const coordRoot = context?.resolveCoordRoot?.() ?? context?.repoRoot ?? monorepoRoot();
+        if (!coordRoot) throw new Error("project coordination root is unavailable");
+        emit.config({ format: "json" });
+        const result = await operation(coordRoot, options);
+        emit.data(result);
+        if (
+          result &&
+          typeof result === "object" &&
+          "status" in result &&
+          result.status === "unknown"
+        )
+          emit.setExitCode(1);
+      } catch (error) {
+        emit.error({ code: "turn_rollback_refused", message: String(error) });
+        emit.setExitCode(1);
+      }
+    };
+  const binding = (root: string, options: Options) => {
+    const value = readWorkspaceBinding(root, "local-git-worktree", options.binding);
+    if (!value) throw new Error("immutable workspace binding was not found");
+    return value;
+  };
+  command
+    .command("begin")
+    .description("Capture exact literal paths before a turn")
+    .requiredOption("--binding <id>", "Owned workspace binding ID")
+    .requiredOption("--turn <id>", "Caller turn identity")
+    .requiredOption("--generation <number>", "Increasing turn generation")
+    .requiredOption("--path <file...>", "Exact relative file paths, including planned new files")
+    .action(
+      run((root, options) =>
+        beginTurnRollback(root, {
+          binding: binding(root, options),
+          turn: { turn_id: options.turn!, generation: Number(options.generation) },
+          paths: options.path!,
+        }),
+      ),
+    );
+  for (const operation of ["seal", "prepare", "show"] as const) {
+    command
+      .command(`${operation} <capture-id>`)
+      .description(`${operation} an exact turn capture`)
+      .requiredOption("--binding <id>", "Owned workspace binding ID")
+      .action((id: string, options: Options) =>
+        run((root, opts) => {
+          const input = { binding: binding(root, opts), capture_id: id };
+          return operation === "seal"
+            ? sealTurnRollback(root, input)
+            : operation === "prepare"
+              ? prepareTurnRollback(root, input)
+              : inspectTurnRollback(root, input);
+        })(options),
+      );
+  }
+  command
+    .command("apply")
+    .description("Preview a saved proposal, or apply it after exact confirmation")
+    .requiredOption("--binding <id>", "Owned workspace binding ID")
+    .requiredOption("--plan <file>", "Saved JSON proposal returned by prepare")
+    .option("--yes", "Apply this exact proposal; preview is the default")
+    .option("--actor <name>", "Who authorized the restore")
+    .option("--reason <text>", "Why this turn is being restored")
+    .action(
+      run((root, options) =>
+        applyTurnRollback(root, {
+          binding: binding(root, options),
+          plan: readJsonRecord<TurnRollbackPlan>(options.plan!, "rollback proposal"),
+          yes: options.yes,
+          actor: options.actor,
+          reason: options.reason,
+        }),
+      ),
+    );
+}

package/src/commands/workflow.ts

@@ -73,6 +73,15 @@ interface WorkflowConfirmedMutationOpts {
 
 interface WorkflowReclaimOpts extends WorkflowConfirmedMutationOpts {
   discard?: boolean;
+  unknownLiveness?: string;
+  actor?: string;
+  reason?: string;
+}
+
+interface WorkflowUnlockOpts extends WorkflowConfirmedMutationOpts {
+  lockSha256?: string;
+  actor?: string;
+  reason?: string;
 }
 
 export function registerWorkflowCommand(program: Command, emit: EmitContext): void {
@@ -618,11 +627,17 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
   workflow
     .command("reclaim <run-id>")
     .description(
-      "Resolve a workspace preserved because it was dirty: salvage the work to its branch, then release.",
+      "Preview reclaim of an inactive owned workspace, or confirm salvage or discard and release.",
     )
     .option("--yes", "Confirm that this commits or discards uncommitted work, then releases")
     .option("--discard", "Throw the uncommitted work away instead of salvaging it")
-    .option("--json", "Emit the reclaim preparation and cleanup result as JSON")
+    .option(
+      "--unknown-liveness <sha256>",
+      "Recover unknown evidence pinned by the preview digest; active evidence still refuses",
+    )
+    .option("--actor <id>", "Actor responsible for an audited recovery")
+    .option("--reason <text>", "Reason for an audited recovery")
+    .option("--json", "Emit the reclaim preview or confirmed result as JSON")
     .action(async (runId: string, opts: WorkflowReclaimOpts) => {
       const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
@@ -632,53 +647,97 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
         });
         process.exit(1);
       }
-      if (!opts.yes) {
-        emit.error({
-          code: "reclaim_confirmation_required",
-          message: opts.discard
-            ? "reclaim --discard permanently destroys uncommitted work; pass --yes to confirm"
-            : "workspace reclaim commits uncommitted work to its branch and then releases the worktree; pass --yes to confirm",
-        });
-        process.exit(1);
-      }
       try {
-        const { inspectWorkflowWorkspace, prepareReclaim, cleanupWorkspace } = await import(
+        const { createLocalGitWorktreeProvider, readWorkflowRunManifest } = await import(
           "../core/workflow/index.ts"
         );
-        const inspection = inspectWorkflowWorkspace(coordRoot, runId);
-        if (!inspection.ok) {
-          emit.error({ code: "workflow_reclaim_failed", message: inspection.error });
-          process.exit(1);
-        }
-        const allocation = inspection.value.allocation;
-        if (!allocation) {
+        const binding = readWorkflowRunManifest(coordRoot, runId).execution.workspace_binding;
+        if (binding?.provider.id !== "local-git-worktree") {
           emit.error({
             code: "workflow_reclaim_unavailable",
             message: `run ${runId} has no provider-owned Git workspace to reclaim`,
           });
           process.exit(1);
         }
-        const preparation = prepareReclaim({
-          worktreePath: allocation.active_root,
+        const provider = createLocalGitWorktreeProvider({ coordRoot });
+        const result = await provider.reclaim(binding, {
           mode: opts.discard ? "discard" : "salvage",
-          runId,
+          yes: opts.yes,
+          unknownLiveness: opts.unknownLiveness
+            ? {
+                evidenceSha256: opts.unknownLiveness,
+                actor: opts.actor!,
+                reason: opts.reason!,
+              }
+            : undefined,
         });
-        // Cleanup still owns removal. Reclaim only changes whether the tree it
-        // finds is dirty, so there is one audited release path, not two.
-        const provider = await builtInProviderForRun(coordRoot, runId);
-        const cleanup = await cleanupWorkspace({ coordRoot, runId, provider });
         if (opts.json) {
           emit.config({ format: "json" });
-          emit.data({ preparation, cleanup });
+          emit.data(result);
+          return;
+        }
+        if (result.action === "preview") {
+          const holders = result.lease_holder.map(
+            (holder) =>
+              `${holder.scope}: ${holder.owner_id ?? "unknown"}${holder.pid ? ` (pid ${holder.pid})` : ""}${holder.detail ? `; ${holder.detail}` : ""}`,
+          );
+          emit.text(
+            `reclaim preview: ${result.run_id}\n` +
+              `mode: ${result.mode}\nliveness: ${result.liveness}\nownership: ${result.ownership}\n` +
+              `evidence sha256: ${result.evidence_sha256}\n` +
+              `lease holder: ${holders.length > 0 ? holders.join(", ") : "none observed"}\n` +
+              `dirty paths: ${result.dirty_paths === null ? "unknown" : result.dirty_paths.length > 0 ? result.dirty_paths.join(", ") : "none"}\n` +
+              (result.ownership_detail ? `ownership detail: ${result.ownership_detail}\n` : "") +
+              `Pass --yes to confirm ${result.mode} and release after all checks pass.\n`,
+          );
+          return;
+        }
+        emit.text(
+          `reclaim ${result.preparation.action}: ${result.preparation.detail}\n` +
+            `workspace cleanup ${result.cleanup.status}: ${result.cleanup.binding_id}\n`,
+        );
+      } catch (error) {
+        emit.error({
+          code:
+            error instanceof Error && "code" in error && typeof error.code === "string"
+              ? error.code
+              : "workflow_reclaim_failed",
+          message: error instanceof Error ? error.message : String(error),
+        });
+        process.exit(1);
+      }
+    });
+
+  workflow
+    .command("unlock <run-id>")
+    .description(
+      "Preview or explicitly retire one exact resume lock whose local owner is proven dead.",
+    )
+    .option("--lock-sha256 <sha256>", "Exact lock identity digest returned by the preview")
+    .option("--actor <id>", "Actor responsible for the recovery")
+    .option("--reason <text>", "Reason for the recovery")
+    .option("--yes", "Confirm removal after dead-owner and exact-lock checks")
+    .option("--json", "Emit the recovery preview or result as JSON")
+    .action(async (runId: string, opts: WorkflowUnlockOpts) => {
+      try {
+        const coordRoot = resolveCoordRoot();
+        if (!coordRoot) throw new Error("no .harnery/ coordination root found");
+        const { recoverWorkflowResumeLease } = await import("../core/workflow/index.ts");
+        const result = recoverWorkflowResumeLease(coordRoot, runId, opts);
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(result);
           return;
         }
         emit.text(
-          `reclaim ${preparation.action}: ${preparation.detail}\n` +
-            `workspace cleanup ${cleanup.status}: ${cleanup.binding_id}\n`,
+          `resume lock ${result.action}: ${runId}\nowner: ${result.owner_state}\nlock sha256: ${result.lock_sha256 ?? "absent"}\n` +
+            (result.action === "preview"
+              ? "Pass --lock-sha256, --actor, --reason and --yes to confirm exact dead-owner recovery.\n"
+              : `recovery: ${result.recovery_id}\n`),
         );
       } catch (error) {
         emit.error({
-          code: "workflow_reclaim_failed",
+          code: "workflow_resume_unlock_failed",
           message: error instanceof Error ? error.message : String(error),
         });
         process.exit(1);

package/src/core/agents/coord-client.ts

@@ -265,7 +265,27 @@ export function parsePidmapRowStartToken(row: string): string | undefined {
  * a test can hold this one against `processStartToken` and fail on drift.
  */
 export function pidStartToken(pid: number): string | null {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
   const forced = process.env.HARNERY_PID_PROBE;
+  if (process.platform === "win32" && forced !== "procfs" && forced !== "ps") {
+    try {
+      const out = spawnSync(
+        "powershell.exe",
+        [
+          "-NoLogo",
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          `$process = [Diagnostics.Process]::GetProcessById(${pid}); try { 'w' + $process.StartTime.ToFileTimeUtc().ToString([Globalization.CultureInfo]::InvariantCulture) } finally { $process.Dispose() }`,
+        ],
+        { encoding: "utf8", timeout: 10_000, windowsHide: true },
+      );
+      const token = String(out.stdout ?? "").trim();
+      return out.status === 0 && /^w\d+$/.test(token) ? token : null;
+    } catch {
+      return null;
+    }
+  }
   const useProcfs = forced === "procfs" || (forced !== "ps" && existsSync("/proc/self/stat"));
   // One machine, one probe. Falling back to the other on a read failure would
   // answer in the wrong dialect and read as a recycled pid.

package/src/core/agents/live-authority-v3.ts

@@ -88,6 +88,7 @@ interface LiveAuthorityBaseV3 {
   nativeSessionId: string;
   adapter: Adapter;
   observationId?: string;
+  expectedGenerationId?: `gen_${string}`;
 }
 
 /**
@@ -648,6 +649,13 @@ function recordLiveAuthority<S extends CoordinationAuthoritySignalV3>(
     platform: livePlatformV3(),
     expected_prior_state_digest: coordinationAuthorityStateDigestV3(expected),
     desired_state_digest: coordinationAuthorityStateDigestV3(desired),
+    expected_generation_id:
+      input.expectedGenerationId ??
+      ((subject === input.owner
+        ? expected.v3_generation_id
+        : readLiveCoordinationRow(input.coordRoot, input.owner)?.v3_generation_id) as
+        | `gen_${string}`
+        | undefined),
     reconciler: {
       readStateDigest: () => {
         const heartbeat = readHeartbeat(input.coordRoot, subject);
@@ -681,6 +689,12 @@ export function liveCoordinationWriteModeV3(coordRoot: string): EventV3WriteMode
 }
 
 function requireHeartbeat(input: LiveAuthorityBaseV3, owner: string): Heartbeat {
+  if (
+    input.expectedGenerationId &&
+    readLiveCoordinationRow(input.coordRoot, owner)?.v3_generation_id !== input.expectedGenerationId
+  ) {
+    throw new LiveCoordinationAuthorityV3Error("expected_generation_changed");
+  }
   const heartbeat = ensureLiveCoordinationHeartbeat(
     input.coordRoot,
     owner,
@@ -688,6 +702,9 @@ function requireHeartbeat(input: LiveAuthorityBaseV3, owner: string): Heartbeat
     input.adapter,
   );
   if (!heartbeat) throw new LiveCoordinationAuthorityV3Error(`heartbeat_missing:${owner}`);
+  if (input.expectedGenerationId && heartbeat.v3_generation_id !== input.expectedGenerationId) {
+    throw new LiveCoordinationAuthorityV3Error("expected_generation_changed");
+  }
   return heartbeat;
 }
 

package/src/core/agents/live-lifecycle-v3.ts

@@ -5,6 +5,7 @@ import { normalizeNativeIdV3 } from "../events/v3/canonical.ts";
 import type { EventV3 } from "../events/v3/contract.ts";
 import { readEventV3ControlState } from "../events/v3/control.ts";
 import { fingerprintContextV3 } from "../events/v3/fingerprint-keys.ts";
+import { withGenerationCustodyV3 } from "../events/v3/generation-custody.ts";
 import {
   liveInstanceIdV3,
   livePlatformV3,
@@ -25,17 +26,34 @@ interface LiveLifecycleObservationBaseV3 {
   observedAt?: string;
 }
 
+interface LiveSweepObservationV3Input extends LiveLifecycleObservationBaseV3 {
+  expectedGenerationId: `gen_${string}` | null;
+  observation: "stale_heartbeat" | "killed" | "unparseable_heartbeat" | "missing_timestamp";
+  ageMs: number;
+}
+
 export function recordLiveSweepObservationV3(
-  input: LiveLifecycleObservationBaseV3 & {
-    observation: "stale_heartbeat" | "killed" | "unparseable_heartbeat" | "missing_timestamp";
-    ageMs: number;
-  },
+  input: LiveSweepObservationV3Input,
 ): LiveLifecycleObservationV3Result {
-  return recordObservation(input, "lifecycle.sweep_observed", {
-    subject_instance_id: liveInstanceIdV3(input.owner),
-    observation: input.observation,
-    provisional: true,
-    age_ms: Math.max(0, Math.floor(input.ageMs)),
+  input = { ...input };
+  // Reject stale observations before preparing durable custody state. The
+  // in-custody checks cover replacement while acquiring custody and reentry.
+  requireSweepHookState(input);
+  return withGenerationCustodyV3(input.coordRoot, [liveInstanceIdV3(input.owner)], () => {
+    requireSweepHookState(input);
+    return recordObservation(
+      input,
+      "lifecycle.sweep_observed",
+      {
+        subject_instance_id: liveInstanceIdV3(input.owner),
+        observation: input.observation,
+        provisional: true,
+        age_ms: Math.max(0, Math.floor(input.ageMs)),
+      },
+      () => {
+        requireSweepHookState(input);
+      },
+    );
   });
 }
 
@@ -44,11 +62,16 @@ export function recordLiveResumeObservationV3(
 ): LiveLifecycleObservationV3Result {
   const normalized = withAttestedAdapter(input);
   const hook = requireHookState(normalized);
-  return recordObservation(normalized, "session.resumed", {
-    prior_generation_id: hook.generation_id,
-    continuity: "native",
-    evidence_reference: "heartbeat_recreated",
-  });
+  return recordObservation(
+    normalized,
+    "session.resumed",
+    {
+      prior_generation_id: hook.generation_id,
+      continuity: "native",
+      evidence_reference: "heartbeat_recreated",
+    },
+    () => {},
+  );
 }
 
 function recordObservation<T extends "lifecycle.sweep_observed" | "session.resumed">(
@@ -66,6 +89,7 @@ function recordObservation<T extends "lifecycle.sweep_observed" | "session.resum
         continuity: "native";
         evidence_reference: string;
       },
+  beforeWrite: () => void,
 ): LiveLifecycleObservationV3Result {
   const route = resolveLiveEventLedgerRouteV3(input.coordRoot);
   if (route.state === "blocked") throw new LiveCoordinationAuthorityV3Error(route.reason);
@@ -121,6 +145,7 @@ function recordObservation<T extends "lifecycle.sweep_observed" | "session.resum
     monotonic_ns: process.hrtime.bigint().toString(),
   };
   const event = buildEventV3(eventType, { ...common, payload } as never) as EventV3;
+  beforeWrite();
   const durability = writeEventV3(input.coordRoot, event, {
     expectedGenesisId: control.genesis.event.payload.genesis_id as `gex_${string}`,
   });
@@ -130,6 +155,19 @@ function recordObservation<T extends "lifecycle.sweep_observed" | "session.resum
   return { state: "recorded", event };
 }
 
+function requireSweepHookState(input: LiveSweepObservationV3Input): void {
+  if (
+    typeof input.expectedGenerationId !== "string" ||
+    !/^gen_[a-zA-Z0-9._-]+$/.test(input.expectedGenerationId)
+  ) {
+    throw new LiveCoordinationAuthorityV3Error("hook_generation_not_joinable");
+  }
+  const hook = requireHookState(withAttestedAdapter(input));
+  if (hook.generation_id !== input.expectedGenerationId) {
+    throw new LiveCoordinationAuthorityV3Error("expected_generation_changed");
+  }
+}
+
 function withAttestedAdapter<T extends LiveLifecycleObservationBaseV3>(input: T): T {
   const adapter = liveCoordinationAdapterV3(input.coordRoot, input.owner);
   if (!adapter) return input;

package/src/core/agents/mailbox.ts

@@ -9,13 +9,14 @@
  * 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.
+ * message can be queued before its recipient exists. The recipient's next
+ * SessionStart or prompt can drain the queue for injection. A drain does not
+ * confirm that the adapter emitted the context or that anyone read it.
  *
  * 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.
+ * by senders and removed by an atomic claim on the recipient's side. Drained
+ * records are appended to `.harnery/mailbox/delivered/<slug>.jsonl` for audit,
+ * with injection explicitly unconfirmed.
  *
  * Related but distinct: `core/inbox` is an instance-keyed transport with a
  * storage-framework service behind it. This mailbox is name-keyed, file-only,
@@ -48,8 +49,8 @@ export const MAILBOX_MESSAGE_SCHEMA = "harnery.mailbox-message/v1" as const;
 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;
+/** Drain-archive ceiling; the file is truncated from the head past this. */
+const MAX_ARCHIVE_BYTES = 256 * 1024;
 
 export interface MailboxMessageV1 {
   schema: typeof MAILBOX_MESSAGE_SCHEMA;
@@ -104,7 +105,7 @@ export function mailboxPath(coordRoot: string, name: string): string {
   return join(mailboxDir(coordRoot), `${slugFor(name)}.jsonl`);
 }
 
-function deliveredPath(coordRoot: string, name: string): string {
+function archivePath(coordRoot: string, name: string): string {
   return join(mailboxDir(coordRoot), "delivered", `${slugFor(name)}.jsonl`);
 }
 
@@ -243,10 +244,10 @@ export 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 claim is an atomic rename, so two sessions sharing a name cannot claim
  * 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.
+ * are archived before the claim file is removed. The archive records only the
+ * drain; output, recipient read, and turn completion remain unconfirmed.
  */
 export function drainMailbox(coordRoot: string, name: string): MailboxMessageV1[] {
   let path: string;
@@ -279,12 +280,20 @@ export function drainMailbox(coordRoot: string, name: string): MailboxMessageV1[
 
   if (messages.length > 0) {
     try {
-      const archive = deliveredPath(coordRoot, name);
+      const archive = archivePath(coordRoot, name);
       mkdirSync(join(mailboxDir(coordRoot), "delivered"), { recursive: true });
-      const deliveredAt = new Date().toISOString();
+      const drainedAt = new Date().toISOString();
       appendFileSync(
         archive,
-        `${messages.map((m) => JSON.stringify({ ...m, delivered_at: deliveredAt })).join("\n")}\n`,
+        `${messages
+          .map((m) =>
+            JSON.stringify({
+              ...m,
+              drained_at: drainedAt,
+              delivery_status: "injection-unconfirmed",
+            }),
+          )
+          .join("\n")}\n`,
         "utf8",
       );
       trimArchive(archive);
@@ -336,7 +345,7 @@ function sweepStaleClaims(coordRoot: string): void {
 
 function trimArchive(path: string): void {
   try {
-    if (statSync(path).size <= MAX_DELIVERED_BYTES) return;
+    if (statSync(path).size <= MAX_ARCHIVE_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");
@@ -354,8 +363,8 @@ export function formatMailboxDelivery(
   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):`;
+      ? `Message from a peer agent (prepared for injection, recorded in your journal):`
+      : `${messages.length} messages from peer agents (prepared for injection, recorded in your journal):`;
   const body = messages
     .map((m) => {
       const when = m.created_at.replace("T", " ").replace(/\.\d+Z$/, "Z");

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

@@ -48,9 +48,9 @@ import { join } from "node:path";
 import { coordEnv } from "../../../lib/env.ts";
 import { endOfTurnStatusCommand, hostPromptReminder, resolveBinName } from "../../config.ts";
 import type { PressureWorkloadClass } from "../../diagnostics/contract.ts";
+import { formatPeerInbox, peerInbox } from "../../inbox/peer-messages.ts";
 import { type RemoteMachine, readRemoteMachines } from "../../presence/index.ts";
 import { readResourceStatus } from "../../resources/status.ts";
-import { drainMailbox, formatMailboxDelivery } from "../mailbox.ts";
 import { sessionNameDisplayBlock, sessionNameDisplayPending } from "../session-name-display.ts";
 import { heartbeatPath } from "../state/heartbeat-reader.ts";
 import {
@@ -59,7 +59,7 @@ import {
 } from "../state/live-coordination-view.ts";
 import { forkRelationLabels } from "../state/names.ts";
 import type { AgentActivity, TaskState } from "../state/session-state.ts";
-import { formatPendingCouncils, recordDeliveredMessages } from "./session-context.ts";
+import { formatPendingCouncils } from "./session-context.ts";
 
 interface HeartbeatRow {
   instance_id?: string;
@@ -103,6 +103,8 @@ export interface PromptContextOpts {
    * being bounced into a retry. Not hash-deduped, same rationale as the
    * status footer. */
   turnRitualNudge?: string;
+  /** The emitter acknowledges exactly these IDs only after output succeeds. */
+  onInboxPrepared?: (messageIds: readonly string[]) => void;
 }
 
 /**
@@ -132,16 +134,12 @@ export function renderPromptContext(opts: PromptContextOpts): string {
   // 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.
-  //
-  if (resolvedName) {
-    const delivered = drainMailbox(coordRoot, resolvedName);
-    if (delivered.length > 0) {
-      recordDeliveredMessages(instanceId, delivered);
-      sections.push(formatMailboxDelivery(coordRoot, delivered));
-    }
+  // 1. Instance-bound messages. Rendering is read-only; failed output leaves
+  // this same batch pending rather than losing it before a prompt sees it.
+  const delivered = peerInbox(coordRoot).prepareSurface(instanceId);
+  if (delivered.length > 0) {
+    opts.onInboxPrepared?.(delivered.map(({ message_id }) => message_id));
+    sections.push(formatPeerInbox(coordRoot, delivered));
   }
 
   // 2. Peer table with hash dedup.