pi-crew 0.11.21 → 0.11.22

package/src/runtime/broker/crew-broker.ts

@@ -1,24 +1,39 @@
 /**
  * crew-broker.ts — Root-only local socket server for cross-process pi-worker
- *                  message transport. PHASE 0 skeleton (sub-task 0.4).
+ *                  message transport (grew out of the Phase 0 skeleton,
+ *                  sub-task 0.4 — see history note below).
  *
  *  - Bound to a `node:net` Unix domain socket or Windows named pipe.
  *  - One broker per root session; per-run token auth on first `hello`.
  *  - NDJSON framing, 256 KiB UTF-8 cap, 1s hello deadline.
- *  - Per-connection outbound queue cap (default 256) with drop-newest +
- *    `needsResync` marker.
- *  - Phase 0 dispatches ONLY `hello` and `ping`. All other methods return
- *    a typed `not-implemented` response (preserves forward-compat without
- *    pretending Phase 1 methods are live).
+ *  - Per-connection outbound queue cap (default 256). Fanout/event frames
+ *    are drop-newest at cap, and the drop now CLOSES the connection with a
+ *    typed `protocol.close` reason ("outbound-overflow-resync") so the
+ *    client reconnects and replays (R6-5). Request RESPONSE frames
+ *    (sendResult/sendError acks) bypass the cap — bounded by in-flight
+ *    request count, never the fanout storm.
+ *  - Dispatches 12 methods post-hello: `ping`, `hello`, `msg.send`,
+ *    `msg.inbox`, `events.since`, `events.subscribe`, `task.waitStatus`,
+ *    `steer.push`, `escalate`, `wait.request`/`wait.resolve`
+ *    (capability-gated via `options.waitMethodsEnabled`, fail-closed), and
+ *    `delegate.request` (governed-nesting grandchild spawn through
+ *    `delegate-spawn.ts`, capability-gated via `options.nestingEnabled`,
+ *    fail-closed). Unknown methods return a typed `not-implemented`.
+ *  - Mailbox/event persistence flows through the `src/state/` stores
+ *    (`appendMailboxMessage*`, event-log) — the broker itself keeps no
+ *    durable state of its own.
  *  - Token map is HEAP ONLY; cleared on `stop()`. Never serialized.
  *  - `stop()` is idempotent. Never calls `process.kill`.
  *  - All log/error scopes use `crew-broker.*` prefix; every diagnostic
  *    passes through `redactSecretString` from `src/utils/redaction.ts`.
  *
- *  NO outbound TCP. NO persistence. NO children. NO process killing.
+ *  NO outbound TCP. NO process killing.
  *
- *  See `reports/inter-pi-broker-impl-plan-2026-07-21.md` §"0.4" for the
- *  full contract and acceptance criteria.
+ *  History: the Phase 0 contract (hello/ping only, no persistence, no
+ *  children) lives in `reports/inter-pi-broker-impl-plan-2026-07-21.md` §0.4;
+ *  the 12-method surface above supersedes it. DR-01 (2026-10-14) rewrote
+ *  this header after it had drifted ~1900 LOC past the skeleton it
+ *  described.
  */
 
 import { randomUUID } from "node:crypto";
@@ -53,6 +68,7 @@ import { handleEventsSince } from "./protocol/events-replay.ts";
 import { DEFAULT_LOCK_BUSY_RETRY_DELAYS_MS, type LockBusyOutcome, withRunLockBusyRetry } from "./protocol/lock-busy.ts";
 import { loadRunForHello } from "./protocol/manifest-loader.ts";
 import { handleMsgInbox } from "./protocol/msg-inbox.ts";
+import { resolveMsgSendTargets } from "./protocol/msg-send-targets.ts";
 import {
 	BROKER_PROTOCOL,
 	isHelloParams,
@@ -93,6 +109,26 @@ const STALE_RUN_STATUSES: ReadonlySet<string> = new Set(["completed", "failed",
 /** Default per-connection outbound queue cap (events). */
 const DEFAULT_OUTBOUND_QUEUE_CAP = 256;
 
+/** R6-5 (2026-10-16): typed protocol close-reason sent as a best-effort
+ *  `protocol.close` event frame (direct write, jumps the saturated queue)
+ *  before the connection is closed after a fanout/event frame was dropped
+ *  at the queue cap. Clients observe the reason, reconnect, and replay via
+ *  `events.since` (Phase 1.5). */
+export const OUTBOUND_OVERFLOW_RESYNC_CLOSE_REASON = "outbound-overflow-resync";
+
+/** R6-5: admission class for an outbound frame.
+ *  - `false`  — fanout/event class: drop-newest at cap → resync close.
+ *  - `true`   — close-reason class: bypass the cap, attempt an immediate
+ *    direct write (existing `sendErrorAndClose` behavior).
+ *  - `"response"` — request-response class (sendResult/sendError acks):
+ *    bypass the drop-newest cap but stay IN the queue (ordering preserved,
+ *    backpressure honored). Bounded by the client's in-flight request count
+ *    — one response frame per request — so it can never storm the way a
+ *    fanout burst can. Kept a `boolean | "response"` union (not a fresh
+ *  enum) so the external FanoutWriters interface (mailbox-fanout.ts) keeps
+ *  its `(conn, buf, force: boolean)` shape. */
+type OutboundAdmission = boolean | "response";
+
 export class CrewBroker {
 	private readonly options: Required<Pick<CrewBrokerOptions, "sessionId" | "enabled" | "waitMethodsEnabled" | "nestingEnabled">> &
 		Pick<
@@ -750,7 +786,7 @@ export class CrewBroker {
 	 *  truth for authentication). */
 	// loadRunForHello: inlined at the 2 call sites (was a 5-line method; M4/WI-4.1).
 
-	// Outbound queue + drop-newest + needsResync
+	// Outbound queue + drop-newest + resync-close (R6-5)
 
 	private sendResult(conn: ServerConnection, id: string, result: unknown): void {
 		this.enqueueFrame(conn, { id, result });
@@ -787,13 +823,27 @@ export class CrewBroker {
 			);
 			return;
 		}
-		this.writeOrQueue(conn, buf, /*force*/ false);
+		// R6-5: request responses (the acks for ping/msg.send/wait.request/…)
+		// are response-class — they bypass the drop-newest cap so a saturated
+		// fanout queue can no longer swallow an ack and leave the caller to its
+		// request-timeout (a delivered send reported "NOT sent").
+		this.writeOrQueue(conn, buf, "response");
 	}
 
-	private writeOrQueue(conn: ServerConnection, buf: Buffer, force: boolean): void {
+	private writeOrQueue(conn: ServerConnection, buf: Buffer, force: OutboundAdmission): void {
 		if (conn.closed) return;
 		const cap = this.options.outboundQueueCap ?? DEFAULT_OUTBOUND_QUEUE_CAP;
 		if (conn.outbound.length >= cap) {
+			if (force === "response") {
+				// R6-5(a): response frames queue PAST the cap instead of being
+				// drop-newest'd. Bounded: at most one response per in-flight
+				// request, and the client's request pipeline is serial — this can
+				// never grow unbounded the way a fanout burst can. Ordering is
+				// preserved (pushed at the tail; drainOutbound honors backpressure).
+				conn.outbound.push(buf);
+				this.drainOutbound(conn);
+				return;
+			}
 			if (force) {
 				// Forced sends (e.g. close-reason) bypass the cap and attempt
 				// to flush directly; if the socket is busy they may still drop.
@@ -804,13 +854,13 @@ export class CrewBroker {
 				}
 				return;
 			}
-			// Drop-newest: do NOT add the new frame, mark needsResync, and stop
-			// further live fanout for this connection. The client must reconnect
-			// and replay (Phase 1: via events.since; Phase 0: protocol error).
-			conn.needsResync = true;
-			// We do NOT revoke auth — the connection is still authenticated; we
-			// simply pause live frame production. The client is expected to
-			// notice the queue-depth and resync.
+			// R6-5(b): fanout/event frame dropped at cap (drop-newest). The old
+			// `needsResync` marker was write-only (set, never read) — the claimed
+			// "pause + client notices" recovery did not exist, so live frames
+			// were silently dropped for the connection's remaining lifetime.
+			// Now the drop CLOSES the connection with a typed close-reason so
+			// the client reconnects and replays (events.since / msg.inbox).
+			this.handleOutboundOverflow(conn);
 			return;
 		}
 		conn.outbound.push(buf);
@@ -841,6 +891,33 @@ export class CrewBroker {
 		}
 	}
 
+	/** R6-5(b): a fanout/event frame was dropped at the outbound queue cap.
+	 *  Close the connection with a typed protocol close-reason so the client
+	 *  can reconnect + replay instead of silently missing live frames
+	 *  forever. The reason frame is written DIRECTLY (jumps the saturated
+	 *  queue — those frames are already doomed once we close) and delivery
+	 *  is best-effort, exactly like `sendErrorAndClose`. */
+	private handleOutboundOverflow(conn: ServerConnection): void {
+		// Single-flight: fanoutMailboxMessage iterates a snapshot of the run's
+		// connections, so one burst can re-enter here for an already-overflowing
+		// conn before `closeConnection`'s `closed` guard becomes visible. The
+		// flag is the "close already initiated" bit (its only read).
+		if (conn.needsResync) return;
+		conn.needsResync = true;
+		logInternalError(
+			"crew-broker.outbound.overflow",
+			new Error("outbound queue overflow — closing connection for resync"),
+			`sessionId=${this.options.sessionId} runId=${conn.runId ?? "?"} queued=${conn.outbound.length} seq=${conn.outboundSeq}`,
+		);
+		try {
+			const buf = encodeBrokerFrame({ event: "protocol.close", data: { reason: OUTBOUND_OVERFLOW_RESYNC_CLOSE_REASON } });
+			conn.socket.write(buf);
+		} catch {
+			/* socket may be dead; closeConnection below sweeps regardless */
+		}
+		this.closeConnection(conn);
+	}
+
 	// Phase 1: msg.send + msg.inbox handlers
 
 	/** Phase 1.1: direct or broadcast mailbox write via the durable append path. */
@@ -894,67 +971,25 @@ export class CrewBroker {
 			this.sendError(conn, id, "no-manifest", (err as Error).message);
 			return;
 		}
-		// ── Recipient resolution ──────────────────────────────────────────────
-		// Each target is {label, mailboxTaskId}: `label` is echoed in the ack
-		// and message id, `mailboxTaskId` is the mailbox file the append lands
-		// in (undefined = run-level inbox, which the orchestrator consumes).
-		let targets: Array<{ label: string; mailboxTaskId: string | undefined }>;
-		// Task 5b (spec §15.2 wake): set when a worker addresses the parent —
-		// the durable write alone would sit unread in the run-level inbox.
-		let sentToParent = false;
-		if (isWorker) {
-			// Worker constraint (1): from is ALWAYS the authenticated taskId.
-			// Worker constraint (2): to is limited to parent | valid sibling
-			// taskId | group.
-			if (!conn.taskId) {
-				this.sendError(conn, id, "forbidden", "msg.send worker requires a task-scoped identity");
-				return;
-			}
-			const to = typeof parsed.to === "string" ? parsed.to : undefined;
-			if (to === "parent") {
-				// Run-level inbox (taskId undefined) → the orchestrator session.
-				targets = [{ label: "parent", mailboxTaskId: undefined }];
-				sentToParent = true;
-			} else if (to === "group") {
-				targets = taskIds.map((t) => ({ label: t, mailboxTaskId: t }));
-			} else if (to !== undefined && taskIds.includes(to)) {
-				targets = [{ label: to, mailboxTaskId: to }];
-			} else {
-				this.sendError(conn, id, "forbidden", `msg.send: worker cannot target '${to}'`);
-				return;
-			}
-			if (targets.length === 0 || targets.length > 64) {
-				this.sendError(conn, id, "bad-params", "msg.send: recipient count out of range");
-				return;
-			}
-		} else {
-			const recipients: string[] = Array.isArray(parsed.to)
-				? (parsed.to as string[])
-				: parsed.to === "all"
-					? taskIds
-					: [parsed.to as string];
-			if (recipients.length === 0 || recipients.length > 64) {
-				this.sendError(conn, id, "bad-params", "msg.send: recipient count out of range");
-				return;
-			}
-			targets = recipients.map((recipient) => ({ label: recipient, mailboxTaskId: recipient }));
+		// ── Recipient resolution: pure D9/§15.2 matrix in protocol/msg-send-targets.ts (wc-gate).
+		const resolved = resolveMsgSendTargets({ isWorker, connTaskId: conn.taskId, to: parsed.to, taskIds });
+		if (!resolved.ok) {
+			this.sendError(conn, id, resolved.code, resolved.message);
+			return;
 		}
+		const { targets, sentToParent } = resolved;
 		const messageId = `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 		const fromField = isWorker ? conn.taskId! : (conn.taskId ?? conn.runId);
-		// U5 (2026-10-10): every send carries a unique requestId — client-supplied
-		// (idempotent retries reuse the SAME one) or broker-generated
-		// `{runId}:{sender}:{uuid}`. The durable (direction, requestId) index in
-		// delivery.json + the idempotent append below make resend-after-resume a
-		// no-op instead of a duplicate delivery.
+		// U5: every send carries a unique requestId — client-supplied (idempotent
+		// retries reuse the SAME one) or broker-generated. The durable
+		// (direction, requestId) index makes resend-after-resume a no-op.
 		const requestId = parsed.requestId ?? `${manifest.runId}:${fromField}:${randomUUID()}`;
 		let dedupedRecipients = 0;
 		let durable = false;
 		try {
-			// PERF (2026-08-24): to:"all" with 50 tasks used to run 50 sequential
-			// awaited locked appends (~70 syscalls + 2 fsync each) while the
-			// connection's frames queued behind it. Chunked fan-out — independent
-			// mailbox files append concurrently; delivery.json stays serialized by
-			// its own lock.
+			// PERF: to:"all" with 50 tasks used to run 50 sequential awaited locked
+			// appends while the connection's frames queued behind it. Chunked
+			// fan-out — independent mailbox files append concurrently.
 			const CHUNK = 8;
 			for (let i = 0; i < targets.length; i += CHUNK) {
 				const results = await Promise.allSettled(
@@ -985,10 +1020,9 @@ export class CrewBroker {
 			this.sendError(conn, id, "durable-failed", (err as Error).message);
 			return;
 		}
-		// U5: one bounded audit event per send — requestId + dedup count make the
-		// exactly-once chain auditable end-to-end (mailbox.send → worker
-		// mailbox.pickup → mailbox.pickup_deduped). Never the body. Failure is
-		// non-fatal: the mailbox rows are the source of truth.
+		// U5: one bounded audit event per send — requestId + dedup count make
+		// the exactly-once chain auditable. Never the body; mailbox rows are
+		// the source of truth.
 		try {
 			await appendEventAsync(manifest.eventsPath, {
 				type: "mailbox.send",

package/src/runtime/broker/protocol/msg-send-targets.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure recipient resolution for the broker's `msg.send` handler.
+ *
+ * Extracted from crew-broker.ts (DR-03 wave, wc-gate: no module over 2000
+ * lines — same precedent as live-session/usage-bridge.ts): the worker/
+ * orchestrator recipient matrices are pure functions of
+ * {role, taskId, parsed.to, taskIds} — no broker state involved.
+ *
+ * Worker constraints (D9/§15.2): from is always the authenticated taskId;
+ * to is limited to `parent` | valid sibling taskId | `group`; kind limited
+ * to notify|message (checked by the caller BEFORE resolution).
+ * Orchestrator keeps the full prior surface (arrays / "all" / arbitrary
+ * recipient sets).
+ */
+
+export type MsgSendTarget = { label: string; mailboxTaskId: string | undefined };
+
+export type MsgSendTargetResolution =
+	| { ok: true; targets: MsgSendTarget[]; sentToParent: boolean }
+	| { ok: false; code: "forbidden" | "bad-params"; message: string };
+
+/** Max recipients per send (both roles) — matches the historical inline check. */
+export const MSG_SEND_MAX_RECIPIENTS = 64;
+
+/**
+ * Resolve `parsed.to` into mailbox targets.
+ *
+ * Each target is `{label, mailboxTaskId}`: `label` is echoed in the ack and
+ * message id; `mailboxTaskId` is the mailbox file the append lands in
+ * (undefined = run-level inbox, which the orchestrator consumes).
+ * `sentToParent` is set when a worker addresses the parent — the durable
+ * write alone would sit unread in the run-level inbox (spec §15.2 wake).
+ */
+export function resolveMsgSendTargets(input: {
+	isWorker: boolean;
+	connTaskId: string | undefined;
+	to: unknown;
+	taskIds: string[];
+}): MsgSendTargetResolution {
+	const { isWorker, connTaskId, taskIds } = input;
+
+	if (isWorker) {
+		// Worker constraint (1): from is ALWAYS the authenticated taskId.
+		if (!connTaskId) {
+			return { ok: false, code: "forbidden", message: "msg.send worker requires a task-scoped identity" };
+		}
+		// Worker constraint (2): to is limited to parent | valid sibling
+		// taskId | group.
+		const to = typeof input.to === "string" ? input.to : undefined;
+		let targets: MsgSendTarget[];
+		let sentToParent = false;
+		if (to === "parent") {
+			// Run-level inbox (taskId undefined) → the orchestrator session.
+			targets = [{ label: "parent", mailboxTaskId: undefined }];
+			sentToParent = true;
+		} else if (to === "group") {
+			targets = taskIds.map((t) => ({ label: t, mailboxTaskId: t }));
+		} else if (to !== undefined && taskIds.includes(to)) {
+			targets = [{ label: to, mailboxTaskId: to }];
+		} else {
+			return { ok: false, code: "forbidden", message: `msg.send: worker cannot target '${to}'` };
+		}
+		if (targets.length === 0 || targets.length > MSG_SEND_MAX_RECIPIENTS) {
+			return { ok: false, code: "bad-params", message: "msg.send: recipient count out of range" };
+		}
+		return { ok: true, targets, sentToParent };
+	}
+
+	const recipients: string[] = Array.isArray(input.to) ? (input.to as string[]) : input.to === "all" ? taskIds : [input.to as string];
+	if (recipients.length === 0 || recipients.length > MSG_SEND_MAX_RECIPIENTS) {
+		return { ok: false, code: "bad-params", message: "msg.send: recipient count out of range" };
+	}
+	return { ok: true, targets: recipients.map((recipient) => ({ label: recipient, mailboxTaskId: recipient })), sentToParent: false };
+}

package/src/runtime/broker/wait-status-cache.ts

@@ -119,9 +119,18 @@ export class WaitStatusCache {
 	/**
 	 * Stat-gated load. Fast path (stamp unchanged): 2 statSync calls, zero
 	 * parses. Slow path (first sight or changed mtime/size): delegate to the
-	 * loader, then record the POST-load stamp so a concurrent writer that
-	 * landed between our pre-load stat and the parse forces the next tick to
-	 * reload instead of serving a stale entry.
+	 * loader, then record the PRE-load stamp (H5, DR-03 round-6 2026-10-16).
+	 *
+	 * Why PRE-load: keying the entry on the POST-load stamp had a
+	 * parse→stat TOCTOU bug — a writer landing between the parse and the
+	 * after-stat produced an entry whose stamp was FRESH while its cached
+	 * value was STALE, and every later tick with an unchanged disk served
+	 * the stale value forever (stale-under-fresh pinning). With the PRE-load
+	 * stamp, a writer that lands anywhere between the pre-stat and the parse
+	 * leaves the entry keyed on the OLDER stamp, so the very next tick sees
+	 * the stamp change and reloads. Worst case is one spurious reload
+	 * (writer landed before the parse — the loaded value was already fresh),
+	 * never a missed one.
 	 */
 	load(cwd: string, runId: string): LoadedRun {
 		// Same path derivation as resolveRunStateRoot inside
@@ -135,13 +144,13 @@ export class WaitStatusCache {
 		}
 		const loaded = this.loader(cwd, runId);
 		this.reloadsValue += 1;
-		const after = statStamp(paths.manifestPath, paths.tasksPath);
 		if (this.entries.size >= WAIT_STATUS_CACHE_MAX && !this.entries.has(runId)) {
 			// Map preserves insertion order — evict the oldest entry.
 			const oldest = this.entries.keys().next().value;
 			if (oldest !== undefined) this.entries.delete(oldest);
 		}
-		this.entries.set(runId, { ...after, loaded });
+		// H5: key on the PRE-load stamp (`before`), NOT a post-load re-stat.
+		this.entries.set(runId, { ...before, loaded });
 		return loaded;
 	}
 

package/src/runtime/child-pi/child-pi-spawn.ts

@@ -21,7 +21,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { childPiBaseAllowlist } from "../../config/env-allowlist-registry.ts";
 import { isScratchpadEnabledForRole } from "../../config/role-tools.ts";
-import { buildScopedAllowList, sanitizeEnvSecrets } from "../../utils/env-filter.ts";
+import { buildScopedAllowList, providerEnvKeys, sanitizeEnvSecrets } from "../../utils/env-filter.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 import { buildPiWorkerArgs, createSafeTempDir, getPiTempBase } from "../model/pi-args.ts";
@@ -48,8 +48,23 @@ export const BASE_ALLOWLIST: string[] = childPiBaseAllowlist();
  *   4. Add PI_CREW_PARENT_PID for the child-side parent-guard (consumed by the
  *      reactive zombie-scanner + background-runner parent-guard; unused only by
  *      the pi dist binary — see note at the PI_CREW_PARENT_PID assignment below).
+ *
+ * R6-8 (DR-03 round-6): `modelChain` threads the task's model CANDIDATE CHAIN
+ * (primary + fallbacks, e.g. modelRouting.candidates) so the allowlist is
+ * scoped to the UNION of the chain's providers. Previously only the single
+ * current model was passed: a bare-id primary (no "provider/" prefix)
+ * resolved to ZERO provider env keys → the child failed auth with a
+ * non-retryable /api key/i error → the loop broke even though qualified
+ * fallbacks were queued (the env-filter.ts doc contract already promised
+ * "primary + fallbacks"). Scoping is NEVER weakened by this: keys stay
+ * limited to the chain's providers ONLY — never all-providers.
  */
-export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv, model?: string): SpawnOptions {
+export function buildChildPiSpawnOptions(
+	cwd: string,
+	env: NodeJS.ProcessEnv,
+	model?: string,
+	modelChain?: (string | undefined)[],
+): SpawnOptions {
 	// SECURITY FIX (Issue #1): Validate cwd before passing to spawn.
 	// If cwd comes from an untrusted source (user input, workspace config), a malicious cwd
 	// could cause the child process to operate in an attacker-controlled directory,
@@ -81,9 +96,33 @@ export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv, mo
 	// Bug #12 fix: essential env vars (PATH, HOME, etc.) are always preserved so child can find npm/node.
 	//
 	// PER-TASK KEY SCOPING: when a model is provided, only the env keys for that
-	// provider are injected (via buildScopedAllowList). When no model is given,
-	// only BASE_ALLOWLIST system vars pass through — no provider keys leak.
-	const allowList = model ? buildScopedAllowList(BASE_ALLOWLIST, [model]) : BASE_ALLOWLIST;
+	// provider are injected (via buildScopedAllowList). R6-8: when the caller
+	// threads the model CANDIDATE CHAIN (primary + fallbacks), keys are scoped
+	// to the UNION of the chain's providers so a fallback attempt on a second
+	// provider does not spawn keyless. When no model is given, only
+	// BASE_ALLOWLIST system vars pass through — no provider keys leak.
+	const scopeModels: (string | undefined)[] = modelChain && modelChain.length > 0 ? modelChain : model !== undefined ? [model] : [];
+	const allowList = scopeModels.length > 0 ? buildScopedAllowList(BASE_ALLOWLIST, scopeModels) : BASE_ALLOWLIST;
+	// R6-8: warn when the scoped models resolve to ZERO provider env keys AND at
+	// least one is a truly-bare id (no "provider/" prefix) — env-key auth + bare
+	// id means the child worker will very likely fail authentication (observed as
+	// the R6-8 stall: bare id → zero keys → /api key/i non-retryable → chain break
+	// even though qualified fallbacks were queued). NOT an error, and it never
+	// widens the allowlist: users authenticating via auth.json (or custom
+	// providers with non-env credentials) are unaffected — the child reads
+	// auth.json credentials exactly like the parent process does. Qualified
+	// unknown providers ("custom/foo") do not warn: that is a deliberate
+	// custom-provider choice, not a likely misconfiguration.
+	const anyProviderKeys = scopeModels.some((scoped) => providerEnvKeys(scoped).length > 0);
+	const anyBareId = scopeModels.some((scoped) => typeof scoped === "string" && !scoped.includes("/"));
+	if (scopeModels.length > 0 && anyBareId && !anyProviderKeys) {
+		logInternalError(
+			"child-pi-spawn.bare-model-no-provider-keys",
+			undefined,
+			`model "${model ?? scopeModels.find((scoped) => typeof scoped === "string")}" is a bare id (no provider prefix) and resolved zero provider env keys — the child worker gets no provider API key via env; env-key users should qualify the model id (e.g. "openai/<id>") or configure a fallback chain (auth.json users are unaffected)`,
+			"warn",
+		);
+	}
 	const filteredEnv = sanitizeEnvSecrets(env, { allowList });
 	// FIX: Removed delete workarounds — with explicit allowlist, these vars
 	// are no longer auto-leaked. The wildcard approach was fragile.
@@ -192,12 +231,14 @@ export function buildFinalChildPiSpawnOptions(
 	mergedEnv: NodeJS.ProcessEnv,
 	builtEnv: Record<string, string | undefined>,
 	model?: string,
+	modelChain?: (string | undefined)[],
 ): SpawnOptions {
 	// (a) Canary: builtEnv must contain ONLY PI_CREW_*/PI_TEAMS_* keys.
 	assertOnlyControlEnvKeys(builtEnv);
 	// (b) Build the allowlist-filtered base SpawnOptions (cwd validation, env
 	//     filtering, provider-key scoping when model is set, NODE_PATH guard).
-	const spawnOptions = buildChildPiSpawnOptions(cwd, mergedEnv, model);
+	//     R6-8: modelChain threads the candidate chain for provider-key scoping.
+	const spawnOptions = buildChildPiSpawnOptions(cwd, mergedEnv, model, modelChain);
 	// (c) Spread builtEnv back on top — the allowlist in step (b) intentionally
 	//     strips PI_CREW_*/PI_TEAMS_* keys, so without this spread the child
 	//     process would never see steering file, kind, role, or broker creds.
@@ -395,6 +436,3 @@ export function prepareSpawnContext(
 		},
 	};
 }
-
-// Silence unused-import warning for logInternalError if not consumed by future helpers.
-void logInternalError;

package/src/runtime/child-pi/child-pi.ts

@@ -170,6 +170,18 @@ export interface ChildPiRunInput {
 	task: string;
 	agent: AgentConfig;
 	model?: string;
+	/**
+	 * R6-8 (DR-03 round-6): the task's model CANDIDATE CHAIN (primary +
+	 * fallbacks, e.g. modelRouting.candidates / the executor's attemptModels)
+	 * for provider env-key scoping in buildChildPiSpawnOptions. Scopes the
+	 * allowlist to the UNION of the chain's providers — never all-providers —
+	 * so a fallback attempt on a second provider does not spawn keyless, and
+	 * a bare-id primary no longer means zero provider keys when a qualified
+	 * fallback exists. Absent/empty → single-model scoping (previous
+	 * behavior); a truly-bare single model then warns (env-key auth + bare id
+	 * is a likely misconfiguration; auth.json users are unaffected).
+	 */
+	modelChain?: (string | undefined)[];
 	skillPaths?: string[];
 	signal?: AbortSignal;
 	transcriptPath?: string;
@@ -474,7 +486,12 @@ async function trySurfaceBranch(
 			// child's built env whose PI_CREW_DEPTH is parentDepth+1 — layer-1
 			// guard would misfire on our own tier-1 workers.
 			env: depthEnv ?? process.env,
-			workerEnv: buildFinalChildPiSpawnOptions(input.cwd, mergedEnv, builtEnv, input.model).env as Record<string, string>,
+			// R6-8: thread the model candidate chain so the surface pane's worker env
+			// is provider-key scoped to primary + fallbacks (same as the headless path).
+			workerEnv: buildFinalChildPiSpawnOptions(input.cwd, mergedEnv, builtEnv, input.model, input.modelChain).env as Record<
+				string,
+				string
+			>,
 			config: surfaceConfig,
 			role: input.role ?? input.agent.name,
 			livePaneCount: degradeController ? degradeController.livePaneCount() : (surfaceOpts?.livePaneCount ?? 0),
@@ -801,7 +818,8 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 		return await new Promise<ChildPiRunResult>((resolve) => {
 			// Compose the final SpawnOptions: canary + filter + spread are now
 			// owned by buildFinalChildPiSpawnOptions (see child-pi-spawn.ts, BLOCKER 2 / S5).
-			const spawnOptions = buildFinalChildPiSpawnOptions(input.cwd, mergedEnv, builtEnv, input.model);
+			// R6-8: modelChain threads the candidate chain for provider-key scoping.
+			const spawnOptions = buildFinalChildPiSpawnOptions(input.cwd, mergedEnv, builtEnv, input.model, input.modelChain);
 			const child = spawn(spawnSpec.command, spawnSpec.args, spawnOptions);
 			if (child.pid) {
 				registerActiveChild(child.pid, child);

package/src/runtime/child-pi/mock-fixtures.ts

@@ -68,6 +68,29 @@ export async function runMockChildPi(
 		return { exitCode: 0, stdout, stderr: "" };
 	}
 
+	if (mock === "json-429-empty-settle") {
+		// DR-01 P0 test seam: reproduces the live 429-exhaustion shape (runs
+		// team_20261014082741 / team_20261014093334): opening assistant text +
+		// tool results, then EMPTY assistant message_end events between
+		// auto-retry cycles, ending agent_settled — exit 0, NO stopReason error,
+		// and finalText keeps the early opening sentence ("finalText lies").
+		const opening = JSON.stringify({
+			type: "message_end",
+			message: { role: "assistant", content: [{ type: "text", text: `[MOCK] Starting work for ${input.agent.name}` }] },
+		});
+		const toolResult = JSON.stringify({
+			type: "message_end",
+			message: { role: "toolResult", content: [{ type: "text", text: "[MOCK] tool output" }] },
+		});
+		const emptyAssistant = JSON.stringify({
+			type: "message_end",
+			message: { role: "assistant", content: [], usage: { input: 0, output: 0 } },
+		});
+		const stdout = [opening, toolResult, emptyAssistant, emptyAssistant, JSON.stringify({ type: "agent_settled" })].join("\n") + "\n";
+		await observe(input, stdout);
+		return { exitCode: 0, stdout, stderr: "" };
+	}
+
 	if (mock === "json-success" || mock === "adaptive-plan") {
 		const text =
 			mock === "adaptive-plan" && effectiveTask.includes("ADAPTIVE_PLAN_JSON_START")

package/src/runtime/compaction/compact-stages/truncation-stage.ts

@@ -12,6 +12,17 @@
  * their distinct separators. Defaults match `compactString`'s pre-P0-A output
  * exactly so that callers that do not opt into additional stages get
  * bit-identical output (L4 backward-compat safety).
+ *
+ * K6 (DR-03 round-6): budget accounting. The kept important lines are part
+ * of the OUTPUT, so their joined length (+ the "\n" seam) is reserved OUT
+ * of the head+tail budget (`splitWithImportantLines` `reserveChars`). The
+ * composed result therefore fits `maxChars` + {@link TRUNCATION_MARKER_ALLOWANCE}
+ * (marker budget) instead of the pre-K6 ~1.15×maxChars, where head+tail
+ * alone consumed the full budget and the important-line slack stacked on
+ * top unbudgeted. When no important lines are kept, sizing is bit-identical
+ * to the legacy behavior (no reserve). The stage's own monotonic-shrink
+ * invariant is preserved: if the composed result would be ≥ the input, the
+ * input is returned unchanged.
  */
 import type { ICompactStage } from "../compact-pipeline.ts";
 import { splitWithImportantLines } from "../important-line-classifier.ts";
@@ -34,6 +45,15 @@ const DEFAULT_MARKER: TruncationMarkerConfig = {
 	tailSeparator: "\n",
 };
 
+/**
+ * K6 "small constant" = the marker budget: the longest marker template
+ * (with-important-lines variant, 6-digit counters) plus separators plus
+ * digit drift. The head+tail budget absorbs the kept-important-line content
+ * (joined length + seam), so the composed result exceeds `maxChars` by at
+ * most this marker budget — never by the old unbudgeted ~15% slack.
+ */
+export const TRUNCATION_MARKER_ALLOWANCE = 160;
+
 export class TruncationStage implements ICompactStage {
 	readonly id = "truncation";
 	private readonly maxChars: number;
@@ -55,19 +75,41 @@ export class TruncationStage implements ICompactStage {
 	}
 	apply(text: string): string {
 		if (text.length <= this.maxChars) return text;
-		const { head, tail, importantLines, baseDropped } = splitWithImportantLines(text, this.maxChars, {
+		// K6: two-pass budget accounting.
+		// Pass 1 (today's semantics, full-budget split) learns which important
+		// lines are kept — their joined length is part of the OUTPUT and must be
+		// reserved out of the head+tail budget instead of stacking on top.
+		const pass1 = splitWithImportantLines(text, this.maxChars, {
 			preserveImportant: this.preserveImportant,
 		});
+		const joined = pass1.importantLines.join("\n");
+		// Reserve exactly the kept content (+ the "\n" seam between marker and
+		// joined lines). The marker text + separators stay as the tolerated
+		// TRUNCATION_MARKER_ALLOWANCE overhead; when no important lines are
+		// kept the reserve is 0 and sizing is bit-identical to legacy.
+		const reserve = joined.length > 0 ? joined.length + 1 : 0;
+		// Pass 2 re-slices head+tail against the shrunken budget. It is a pure
+		// budgeted slice: preserveImportant:false skips the (already done)
+		// scan, and pass-1's lines are guaranteed to sit inside pass-2's
+		// dropped middle — the pass-2 middle is a superset of pass-1's because
+		// the shrunken head/tail regions are subsets of pass-1's.
+		const { head, tail, baseDropped } = splitWithImportantLines(text, this.maxChars, {
+			preserveImportant: false,
+			reserveChars: reserve,
+		});
+		const importantLines = pass1.importantLines;
 		let result: string;
 		if (importantLines.length === 0) {
 			result = `${head}${this.marker.headSeparator}...[pi-crew ${this.marker.verb} ${baseDropped} ${this.marker.unit}, head+tail preserved]...${this.marker.tailSeparator}${tail}`;
 		} else {
-			const joined = importantLines.join("\n");
 			const remaining = text.length - head.length - tail.length - joined.length;
 			result = `${head}${this.marker.headSeparator}...[pi-crew ${this.marker.verb} ${baseDropped} ${this.marker.unit}, head+tail + ${importantLines.length} important lines preserved, ${remaining} ${this.marker.unit} remaining dropped]...\n${joined}${this.marker.tailSeparator}${tail}`;
 		}
 		// Defense-in-depth: this stage's own monotonic-shrink invariant. The
-		// pipeline gate is a SECOND line of defense.
+		// pipeline gate is a SECOND line of defense. With the K6 budget the
+		// composed result is ≤ maxChars + marker budget, so this guard only
+		// fires for inputs barely over maxChars (where returning the input
+		// verbatim is still within the allowance) or arithmetic bugs.
 		if (result.length >= text.length) return text;
 		return result;
 	}