pi-crew 0.11.20 → 0.11.22

package/src/extension/team-tool/dispatch/status.ts

@@ -8,6 +8,7 @@
  * Inline cases (graph, search, onboard, explain, cache, checkpoint, recommend,
  * help) are moved verbatim from the former handleTeamTool switch.
  */
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { allAgents, discoverAgents } from "../../../agents/discover-agents.ts";
 import { loadConfig } from "../../../config/config.ts";
@@ -16,6 +17,7 @@ import { getSkillCacheStats } from "../../../runtime/skill-instructions.ts";
 import type { TeamToolParamsValue } from "../../../schema/team-tool-schema.ts";
 import { computeRunCacheKey, getCachedRun, getCacheStats } from "../../../state/stores/run-cache.ts";
 import { listRunGraphs, loadRunGraph } from "../../../state/stores/run-graph.ts";
+import type { TaskCheckpointState } from "../../../state/types.ts";
 import { allTeams, discoverTeams } from "../../../teams/discover-teams.ts";
 import { searchAgents, searchTeams } from "../../../utils/bm25-search.ts";
 import { projectCrewRoot } from "../../../utils/paths.ts";
@@ -200,14 +202,27 @@ export async function handleStatusDomain(params: TeamToolParamsValue, ctx: TeamC
 			assertSafePathId("runId", params.runId);
 			assertSafePathId("taskId", params.taskId);
 			const stateRoot = path.join(projectCrewRoot(ctx.cwd), "state", "runs", params.runId);
+			// R7-8 (DR-04 round-7): `task.checkpoint` in tasks.json is the REAL
+			// production source — `checkpointTask` (task-runner/state-helpers.ts)
+			// writes the checkpoint into the task record and persists it via
+			// saveRunTasks. FileCheckpointStore is only a fallback for runs whose
+			// task record carries no checkpoint. The output says which source won.
+			const taskCheckpoint = readTaskCheckpointFromTasksJson(stateRoot, params.taskId);
+			if (taskCheckpoint) {
+				return result(
+					`Checkpoint (source: task.checkpoint in tasks.json): phase=${taskCheckpoint.phase}, updatedAt=${taskCheckpoint.updatedAt}` +
+						(taskCheckpoint.childPid !== undefined ? `, childPid=${taskCheckpoint.childPid}` : ""),
+					{ action: "checkpoint", status: "ok", data: { source: "task-record", checkpoint: taskCheckpoint } },
+				);
+			}
 			const store = new FileCheckpointStore(stateRoot);
 			const checkpoint = store.load(params.runId, params.taskId);
 			if (!checkpoint) {
 				return result("No checkpoint found.", { action: "checkpoint", status: "error" }, true);
 			}
 			return result(
-				`Checkpoint: step=${checkpoint.step}, progress=${checkpoint.progress}, savedAt=${new Date(checkpoint.savedAt).toISOString()}`,
-				{ action: "checkpoint", status: "ok", data: { checkpoint } },
+				`Checkpoint (source: checkpoint store): step=${checkpoint.step}, progress=${checkpoint.progress}, savedAt=${new Date(checkpoint.savedAt).toISOString()}`,
+				{ action: "checkpoint", status: "ok", data: { source: "checkpoint-store", checkpoint } },
 			);
 		}
 		default: {
@@ -221,3 +236,28 @@ export async function handleStatusDomain(params: TeamToolParamsValue, ctx: TeamC
 		}
 	}
 }
+
+/**
+ * R7-8 (DR-04 round-7): read `task.checkpoint` from tasks.json — the source
+ * production writers actually use (`checkpointTask` persists the checkpoint
+ * into the task record via saveRunTasks). Read-only and tolerant on purpose:
+ * a status query must never mutate run state (no quarantine/reconstruction),
+ * so a missing/corrupt tasks.json simply falls through to the store fallback.
+ * Handles both on-disk shapes: bare `TeamTaskState[]` (v0, current writer) and
+ * the defensive `{ schemaVersion, tasks }` envelope (see manifest-io.ts).
+ */
+function readTaskCheckpointFromTasksJson(stateRoot: string, taskId: string): TaskCheckpointState | undefined {
+	try {
+		const parsed: unknown = JSON.parse(fs.readFileSync(path.join(stateRoot, "tasks.json"), "utf-8"));
+		const tasks: unknown = Array.isArray(parsed) ? parsed : (parsed as { tasks?: unknown }).tasks;
+		if (!Array.isArray(tasks)) return undefined;
+		for (const task of tasks) {
+			if (task === null || typeof task !== "object" || (task as { id?: unknown }).id !== taskId) continue;
+			const checkpoint = (task as { checkpoint?: unknown }).checkpoint;
+			return checkpoint !== null && typeof checkpoint === "object" ? (checkpoint as TaskCheckpointState) : undefined;
+		}
+		return undefined;
+	} catch {
+		return undefined; // ENOENT / corrupt tasks.json → caller falls back to the store
+	}
+}

package/src/extension/team-tool.ts

@@ -954,11 +954,33 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 	);
 }
 
+// R5-6 (DR-02 round-5): send-side clamp for `team steer` bodies. The
+// worker-side receiver (prompt-runtime sanitizeSteerMessage) clamps too (its
+// rejection of >4096-char steers was terminal — the poll cursor advanced
+// past the line, so an oversized leader steer was silently dropped), but the
+// send-side clamp means pendingSteers, the steering JSONL, and the
+// task.steer_queued event all already carry a receiver-safe body with the
+// truncation marker visible to the leader's audit trail. Deliberately
+// duplicated from prompt-runtime's clampSteerMessage (same rationale as the
+// estimateHandoffTokens duplication in task-output-context.ts): importing
+// prompt-runtime here would pull the broker-client/scratchpad/surface-worker
+// graph into the extension registration path (cold-start). Keep the two
+// clamps in sync.
+const TEAM_STEER_MAX_MESSAGE_LENGTH = 4096;
+const TEAM_STEER_TRUNCATION_MARKER = `\n[message truncated at ${TEAM_STEER_MAX_MESSAGE_LENGTH} chars]`;
+function clampSteerBody(message: string): string {
+	if (message.length <= TEAM_STEER_MAX_MESSAGE_LENGTH) return message;
+	return `${message.slice(0, TEAM_STEER_MAX_MESSAGE_LENGTH - TEAM_STEER_TRUNCATION_MARKER.length)}${TEAM_STEER_TRUNCATION_MARKER}`;
+}
+
 export function handleSteer(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
-	const { runId, taskId, message } = params;
-	if (!runId || !taskId || !message) {
+	const { runId, taskId } = params;
+	const rawMessage = params.message;
+	if (!runId || !taskId || !rawMessage) {
 		return result("steer requires runId, taskId, and message", { action: "steer", status: "error" }, true);
 	}
+	// R5-6: clamp BEFORE any sink (pending queue, JSONL, event) sees the body.
+	const message = clampSteerBody(String(rawMessage));
 	const runCwd = locateRunCwd(runId, ctx.cwd);
 	if (!runCwd) return result(`Run '${runId}' not found`, { action: "steer", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency

package/src/prompt/inbox-poll.ts

@@ -23,12 +23,19 @@
  *     must be dropped at consume time);
  *   - dedup by message id across polls via a caller-owned seen-set and/or a
  *     `sinceTs` watermark — one message delivers once;
- *   - U5 (2026-10-10): dedup is ALSO durable across restarts — every picked
- *     row is recorded in delivery.json (`messages[id]="acknowledged"` +
+ *   - U5 (2026-10-10): dedup is ALSO durable across restarts — delivered
+ *     rows are recorded in delivery.json (`messages[id]="acknowledged"` +
  *     `${direction}:${requestId}` index) and re-read on the next poll, so a
  *     worker that restarts mid-run (fresh process, EMPTY seen-set) never
  *     re-delivers. A resend carrying the same requestId is dropped by the
  *     same index; duplicate rows under one requestId deliver exactly once.
+ *   - R5-1 (DR-02, 2026-10-15): the durable record is written in TWO PHASES.
+ *     `pollWorkerInbox` only picks rows and marks the IN-MEMORY seen-set;
+ *     the durable "acknowledged" write lives in
+ *     `acknowledgeWorkerInboxDelivery`, which the delivery loop calls ONLY
+ *     after `pi.sendMessage` succeeded. A send that throws must instead call
+ *     `unmarkSeenInboxIds` so the next tick re-picks the batch — at-least-once
+ *     beats the pre-fix at-most-once-with-a-false-"delivered"-audit-record.
  */
 import * as path from "node:path";
 import {
@@ -125,13 +132,22 @@ function emitPickupEvent(stateRoot: string, runId: string, taskId: string, picke
 
 /**
  * Read the worker's inbox mailbox and return the messages that should be
- * surfaced as fenced context on the next turn.
+ * surfaced as fenced context on the next turn. PICKUP PHASE ONLY (R5-1):
+ * picked rows are marked in the caller-owned in-memory seen-set, but the
+ * durable delivery record is NOT written here — the caller must run
+ * {@link acknowledgeWorkerInboxDelivery} after its send succeeded, and
+ * {@link unmarkSeenInboxIds} when the send threw.
+ *
+ * `limit` (R5-2, DR-02): pick at most this many rows per call (callers pass
+ * their per-tick batch cap). Leftover rows are simply not picked — not
+ * marked, in memory or durably — and flow on a later tick.
  *
  * Stateless apart from the optional caller-owned `seenIds`/`sinceTs` — safe
- * to call on every 500ms poll tick. U5: picked rows are ALSO recorded in the
- * durable delivery state (delivery.json), so dedup survives a restart.
+ * to call on every 500ms poll tick. U5: the durable dedup-read checks
+ * (acknowledged rows / delivered requestIds) still run here so dedup
+ * survives a restart.
  */
-export function pollWorkerInbox(pickup: WorkerInboxPickup): MailboxMessage[] {
+export function pollWorkerInbox(pickup: WorkerInboxPickup, limit?: number): MailboxMessage[] {
 	const { stateRoot, runId, taskId } = pickup;
 	if (!stateRoot || !runId || !taskId) return [];
 	const manifest = { stateRoot, runId } as unknown as TeamRunManifest;
@@ -157,6 +173,11 @@ export function pollWorkerInbox(pickup: WorkerInboxPickup): MailboxMessage[] {
 	const byId = new Set<string>();
 	const byRequestId = new Set<string>();
 	for (const m of messages) {
+		// R5-2 (DR-02): enforce the batch cap AT PICKUP, not at the send site —
+		// every picked row must also be a row the caller can actually send (and
+		// later acknowledge). The pre-fix shape picked N rows, durably acked all
+		// N, then sliced 8 for the send — the surplus was never re-delivered.
+		if (limit !== undefined && picked.length >= limit) break;
 		// Kind gate: only durable `message`s (per §15.2). Notify is
 		// fire-and-forget (its own channel), steer/response/follow-up are
 		// other delivery paths.
@@ -204,25 +225,56 @@ export function pollWorkerInbox(pickup: WorkerInboxPickup): MailboxMessage[] {
 		seen?.add(m.id);
 		picked.push(m);
 	}
-	if (picked.length > 0) {
-		// U5: persist the pickup — the durable record that powers the two
-		// layers above after a restart. Best-effort on failure: the in-memory
-		// seen-set still dedups within THIS process, and logInternalError
-		// makes the lost-durability window visible.
-		try {
-			recordMailboxRequestIdDelivery(
-				manifest,
-				picked.map((m) => ({
-					direction: m.direction,
-					messageId: m.id,
-					requestId: messageIdempotencyKey(m),
-				})),
-			);
-			emitPickupEvent(stateRoot, runId, taskId, picked);
-		} catch (error) {
-			logInternalError("inbox-poll.record-delivery", error, `runId=${runId} taskId=${taskId}`);
-		}
-	}
 	// Deterministic delivery order (same sort readAllMailboxMessages applies).
 	return picked;
 }
+
+/**
+ * R5-1 (DR-02, 2026-10-15): durable-ack phase of the pickup, split OUT of
+ * `pollWorkerInbox`. The caller invokes this ONLY after the picked rows were
+ * successfully delivered (`pi.sendMessage` returned) — the durable
+ * "acknowledged" record and the pickup audit event must never precede a send
+ * that can fail (the pre-fix bug wrote them BEFORE the send, so a send
+ * failure produced a permanent false "delivered" record plus silent message
+ * loss). Mid-batch all-or-nothing: recordMailboxRequestIdDelivery is a single
+ * locked RMW, so acks are atomic per call.
+ *
+ * Best-effort on failure (never throws into the poll tick): the in-memory
+ * seen-set still dedups within THIS process, and logInternalError makes the
+ * lost-durability window visible.
+ */
+export function acknowledgeWorkerInboxDelivery(
+	pickup: Pick<WorkerInboxPickup, "stateRoot" | "runId" | "taskId">,
+	picked: MailboxMessage[],
+): void {
+	const { stateRoot, runId, taskId } = pickup;
+	if (!stateRoot || !runId || !taskId || picked.length === 0) return;
+	const manifest = { stateRoot, runId } as unknown as TeamRunManifest;
+	try {
+		// U5: persist the delivery — the durable record that powers the two
+		// dedup layers above after a restart.
+		recordMailboxRequestIdDelivery(
+			manifest,
+			picked.map((m) => ({
+				direction: m.direction,
+				messageId: m.id,
+				requestId: messageIdempotencyKey(m),
+			})),
+		);
+		emitPickupEvent(stateRoot, runId, taskId, picked);
+	} catch (error) {
+		logInternalError("inbox-poll.record-delivery", error, `runId=${runId} taskId=${taskId}`);
+	}
+}
+
+/**
+ * R5-1 (DR-02): release the in-memory seen marks for a batch whose
+ * `pi.sendMessage` THREW, so the next poll tick re-picks and re-delivers it
+ * (at-least-once beats at-most-once with a false "delivered" audit record).
+ * Mirrors the steer channel's `seenSteers.unmark` + offset-rewind
+ * compensation in prompt-runtime.ts pollSteering.
+ */
+export function unmarkSeenInboxIds(seen: Set<string> | undefined, picked: MailboxMessage[]): void {
+	if (!seen) return;
+	for (const m of picked) seen.delete(m.id);
+}

package/src/prompt/message-tool.ts

@@ -24,6 +24,7 @@
  * sending, so two workers cannot loop message each other to death.
  */
 
+import { createHash } from "node:crypto";
 import { type Static, Type } from "@sinclair/typebox";
 import { getCrewEnv } from "../config/env-vars.ts";
 import { CrewBrokerClient } from "../runtime/broker/crew-broker-client.ts";
@@ -38,6 +39,14 @@ const MSG_TO_MAX_CHARS = 256;
 /** §15.2 rate-limit: 10 messages/min/task, sliding window. */
 const MSG_RATE_LIMIT_MAX = 10;
 const MSG_RATE_LIMIT_WINDOW_MS = 60_000;
+/** R6-6 (DR-03 round-6 2026-10-16): explicit per-request timeout for
+ *  msg.send. The client's 15s default (REQUEST_TIMEOUT_DEFAULT_MS) turns a
+ *  merely-slow durable send (multi-recipient chunked appends + fsync + audit
+ *  event) into a reported "NOT sent" — and the model's natural retry into a
+ *  duplicate delivery. 60s matches the worst bounded fanout (64 recipients,
+ *  8-wide chunks) with headroom while staying below the tool's own "never a
+ *  hang" budget (the request still resolves via this timeout, never hangs). */
+export const MSG_SEND_TIMEOUT_MS = 60_000;
 
 export const MessageToolParamsSchema = Type.Object({
 	to: Type.Union([Type.Literal("parent"), Type.Literal("group"), Type.String({ minLength: 1, maxLength: MSG_TO_MAX_CHARS })]),
@@ -49,12 +58,46 @@ export const MessageToolParamsSchema = Type.Object({
 export type MessageToolParams = Static<typeof MessageToolParamsSchema>;
 
 /** Minimal broker-client surface the message tool needs (structural subset of
- *  CrewBrokerClient — tests substitute a recorder). */
+ *  CrewBrokerClient — tests substitute a recorder). R6-6: the optional third
+ *  argument carries the per-request timeout; existing 2-arg recorders remain
+ *  structurally assignable. */
 export interface MessageBrokerClientSurface {
-	request(method: string, params: unknown): Promise<{ ok: true; value: unknown } | { ok: false; fallback?: boolean; errorCode?: string }>;
+	request(
+		method: string,
+		params: unknown,
+		opts?: { timeoutMs?: number },
+	): Promise<{ ok: true; value: unknown } | { ok: false; fallback?: boolean; errorCode?: string }>;
 	close?(): Promise<void>;
 }
 
+/** R6-6: stable idempotency key derived from message identity. A retry of
+ *  the same logical message (same sender, target, kind, content — e.g. the
+ *  model re-invoking `message` after a lost/slow ack) computes the SAME
+ *  requestId, and the broker's U5 durable (direction, requestId) index in
+ *  delivery.json + appendMailboxMessageIdempotentAsync turn the resend into
+ *  a no-op instead of a duplicate row. Pure content hash: matches the
+ *  request-parsers `^[\\w:.-]{1,256}$` requestId charset (hex + `-`). */
+export function computeMessageRequestId(identity: {
+	runId: string;
+	taskId: string;
+	to: string;
+	kind: string;
+	body: string;
+	subject?: string;
+	priority?: string;
+}): string {
+	const material = JSON.stringify([
+		identity.runId,
+		identity.taskId,
+		identity.to,
+		identity.kind,
+		identity.body,
+		identity.subject ?? null,
+		identity.priority ?? null,
+	]);
+	return `msgtool-${createHash("sha256").update(material).digest("hex").slice(0, 32)}`;
+}
+
 export interface MessageToolDeps {
 	/** Env source override (tests). Production reads via getCrewEnv. */
 	env?: NodeJS.ProcessEnv;
@@ -137,11 +180,26 @@ export function createMessageTool(deps: MessageToolDeps = {}): MessageTool {
 						return new CrewBrokerClient({ runId, taskId, socketPath, token });
 					})();
 			if (!client) return brokerUnavailable();
-			const requestParams: Record<string, unknown> = { to: params.to, kind: params.kind, body: params.body };
+			// R6-6: stable requestId (idempotency across retries) + explicit
+			// timeoutMs (a slow durable ack is NOT a failure).
+			const requestParams: Record<string, unknown> = {
+				to: params.to,
+				kind: params.kind,
+				body: params.body,
+				requestId: computeMessageRequestId({
+					runId,
+					taskId,
+					to: params.to,
+					kind: params.kind,
+					body: params.body,
+					subject: params.subject,
+					priority: params.priority,
+				}),
+			};
 			if (params.subject) requestParams.subject = params.subject;
 			if (params.priority) requestParams.priority = params.priority;
 			try {
-				const sent = await client.request("msg.send", requestParams);
+				const sent = await client.request("msg.send", requestParams, { timeoutMs: MSG_SEND_TIMEOUT_MS });
 				if (!sent.ok) {
 					// Broker rejection (role gate / policy / auth / fallback) — all
 					// fast-fail, non-blocking.

package/src/prompt/prompt-runtime.ts

@@ -12,7 +12,7 @@ import { appendEventFireAndForget } from "../state/event-log/event-log.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
-import { pollWorkerInbox } from "./inbox-poll.ts";
+import { acknowledgeWorkerInboxDelivery, pollWorkerInbox, unmarkSeenInboxIds } from "./inbox-poll.ts";
 import { createMessageTool, type MessageToolParams as MessageToolInputs, shouldRegisterMessageTool } from "./message-tool.ts";
 import { registerScratchpadLifecycle } from "./scratchpad-lifecycle.ts";
 import { createWorkerActivityTracker, registerSurfaceWorkerLifecycle, trackToolActivity } from "./surface-worker.ts";
@@ -32,13 +32,31 @@ const DATE_HEADER = "\nCurrent date:";
 // ── FIX-02: Steering content sanitization limits ──────────────────────────
 // Bounded to keep a malformed/malicious steer entry from blowing up the
 // worker's prompt budget or smuggling control sequences into the agent.
-const MAX_STEER_MESSAGE_LENGTH = 4096;
+export const MAX_STEER_MESSAGE_LENGTH = 4096;
 const MAX_STEER_MESSAGE_NEWLINES = 50;
 // C0 control characters minus the printable whitespace (\t \n \r). These
 // are the bytes most useful for ANSI escapes, terminal-control tricks, and
 // NUL-injection attacks when steer content reaches the worker's UI.
 const STEER_CONTROL_CHAR_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
 
+/** R5-6 (DR-02 round-5): truncation marker for oversized steer bodies —
+ *  mirrors renderInboxMessage's 8192-char marker pattern below. The clamp
+ *  slices so the FINAL message (slice + marker) stays ≤
+ *  {@link MAX_STEER_MESSAGE_LENGTH}, keeping the receiver's length invariant
+ *  honest. */
+const STEER_TRUNCATION_MARKER = `\n[message truncated at ${MAX_STEER_MESSAGE_LENGTH} chars]`;
+
+/** R5-6 (DR-02 round-5): clamp a steer body to
+ *  {@link MAX_STEER_MESSAGE_LENGTH} with a truncation marker. The send side
+ *  (team-tool handleSteer) clamps at dispatch; this helper is the receiver's
+ *  clean seam — every delivery path (file poll AND broker push) funnels
+ *  through `sanitizeSteerMessage`, so an oversized steer from ANY writer is
+ *  delivered truncated-with-marker instead of rejected-and-dropped. */
+export function clampSteerMessage(message: string): string {
+	if (message.length <= MAX_STEER_MESSAGE_LENGTH) return message;
+	return `${message.slice(0, MAX_STEER_MESSAGE_LENGTH - STEER_TRUNCATION_MARKER.length)}${STEER_TRUNCATION_MARKER}`;
+}
+
 export interface SteerSanitizeResult {
 	valid: boolean;
 	reason?: string;
@@ -118,25 +136,28 @@ export function createSeenSteerIdSet(): {
 
 /**
  * Validate a single steering-file entry before forwarding it to
- * `pi.sendMessage`. FIX-02: reject oversized payloads, excessive newlines,
- * or control characters that could be used to confuse the worker UI.
- */
+ * `pi.sendMessage`. FIX-02: reject excessive newlines or control characters
+ * that could be used to confuse the worker UI. R5-6 (DR-02 round-5): an
+ * OVERSIZED payload (>4096 chars) is no longer rejected-and-dropped — the
+ * rejection was terminal (the poll cursor advanced past the line, warn-only)
+ * and the send side had no clamp, so a leader steer over the limit silently
+ * vanished. It is now truncated-with-marker ({@link clampSteerMessage}) and
+ * delivered; the newline/control-char rejections remain terminal (different
+ * failure modes — UI confusion / escape smuggling, not length). */
 export function sanitizeSteerMessage(entry: SteerEntry): SteerSanitizeResult {
 	const message = entry.message;
 	if (typeof message !== "string" || message.length === 0) {
 		return { valid: false, reason: "missing-or-empty-message" };
 	}
-	if (message.length > MAX_STEER_MESSAGE_LENGTH) {
-		return { valid: false, reason: `message-too-long:${message.length}` };
-	}
-	const newlineCount = (message.match(/\n/g) ?? []).length;
+	const clamped = clampSteerMessage(message);
+	const newlineCount = (clamped.match(/\n/g) ?? []).length;
 	if (newlineCount > MAX_STEER_MESSAGE_NEWLINES) {
 		return { valid: false, reason: `too-many-newlines:${newlineCount}` };
 	}
-	if (STEER_CONTROL_CHAR_PATTERN.test(message)) {
+	if (STEER_CONTROL_CHAR_PATTERN.test(clamped)) {
 		return { valid: false, reason: "contains-control-characters" };
 	}
-	return { valid: true, message };
+	return { valid: true, message: clamped };
 }
 
 // ── FIX-03: Steering file path containment validation ─────────────────────
@@ -1067,45 +1088,74 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 	// (`deliverAs:"steer"`, customType "crew-inbox") so the model sees
 	// conversations between agents. Dormant-until-env: only when this worker
 	// carries broker credentials (child-pi-spawn sets them for every worker)
-	// + a state root. A message is delivered EXACTLY ONCE via a seen-id set
-	// owned by this loop (the same keying that guards cross-channel steer
-	// dedup; here the durable mailbox is the only channel).
+	// + a state root. R5-1/R5-2 (DR-02, 2026-10-15): delivery is ack-AFTER-send
+	// — the poll picks (in-memory seen-set) up to INBOX_BATCH_MAX rows, the
+	// DURABLE "acknowledged" record is written (acknowledgeWorkerInboxDelivery)
+	// only after pi.sendMessage succeeded; a send throw unmarks the batch
+	// (unmarkSeenInboxIds) so the next tick re-delivers it. Pickup is thus
+	// at-least-once across send failures and exactly-once once the durable
+	// ack lands (it also survives a restart — U5 semantics).
 	const inboxBrokerRunId = getCrewEnv(PI_CREW_BROKER_RUN_ID_ASK_ENV);
 	const inboxStateRoot = getCrewEnv(PI_CREW_STATE_ROOT_ENV);
 	const inboxTaskId = getCrewEnv(PI_CREW_TASK_ID_ASK_ENV) ?? getCrewEnv(PI_CREW_BROKER_TASK_ID_ASK_ENV);
 	if (inboxBrokerRunId && inboxStateRoot && inboxTaskId) {
 		const seenInboxIds = new Set<string>();
 		// Batch cap per tick: bounds a single steer frame that could otherwise
-		// pile up many fenced messages in one delivery.
+		// pile up many fenced messages in one delivery. R5-2 (DR-02): the cap
+		// is enforced AT PICKUP (pollWorkerInbox `limit`) so every picked row is
+		// also a row actually sent + acked — the pre-fix shape acked N rows
+		// durably but sliced 8 for the send, orphaning the surplus forever.
 		const INBOX_BATCH_MAX = 8;
 		const pollInbox = (): void => {
 			try {
-				const picked = pollWorkerInbox({
-					stateRoot: inboxStateRoot,
-					runId: inboxBrokerRunId,
-					taskId: inboxTaskId,
-					seenIds: seenInboxIds,
-				});
+				const picked = pollWorkerInbox(
+					{
+						stateRoot: inboxStateRoot,
+						runId: inboxBrokerRunId,
+						taskId: inboxTaskId,
+						seenIds: seenInboxIds,
+					},
+					INBOX_BATCH_MAX,
+				);
 				if (picked.length === 0) return;
-				const batch = picked.slice(0, INBOX_BATCH_MAX);
 				// §15.2 trust boundary: the sender's body is DATA, never
 				// instructions. pollWorkerInbox hands back raw mailbox entries —
 				// fence each body (control chars stripped, closing fence
 				// neutralized, length capped) before it reaches the agent.
-				const fenced = batch.map((m) => ({
+				const fenced = picked.map((m) => ({
 					from: m.from,
 					to: m.to,
 					body: renderInboxMessage(m),
 				}));
-				pi.sendMessage(
-					{
-						customType: "crew-inbox",
-						content: fenced.map((e) => e.body).join("\n"),
-						display: false,
-						details: { messages: fenced, count: batch.length },
-					},
-					{ deliverAs: "steer" },
-				);
+				try {
+					pi.sendMessage(
+						{
+							customType: "crew-inbox",
+							content: fenced.map((e) => e.body).join("\n"),
+							display: false,
+							details: { messages: fenced, count: picked.length },
+						},
+						{ deliverAs: "steer" },
+					);
+				} catch (sendErr) {
+					// R5-1: the send FAILED (e.g. pre-bind notInitialized — exactly
+					// what the registration-time synchronous pollInbox() below can
+					// hit). No durable ack was written yet, so there is no false
+					// "delivered" record; release the seen marks so the next tick
+					// re-picks and re-delivers the batch — mirrors seenSteers.unmark
+					// + offset rewind in pollSteering above (at-least-once).
+					unmarkSeenInboxIds(seenInboxIds, picked);
+					logInternalError(
+						"prompt-runtime.inbox-delivery-failed",
+						sendErr instanceof Error ? sendErr : new Error(String(sendErr)),
+						`runId=${inboxBrokerRunId} taskId=${inboxTaskId} count=${picked.length}`,
+						"warn",
+					);
+					return;
+				}
+				// R5-1: the durable "acknowledged" record + pickup audit event
+				// happen ONLY after a successful send — never before it.
+				acknowledgeWorkerInboxDelivery({ stateRoot: inboxStateRoot, runId: inboxBrokerRunId, taskId: inboxTaskId }, picked);
 			} catch {
 				// A transient mailbox read error must never break the tick — the
 				// next 500ms (or 50ms under live-session realtime) poll retries.