pi-crew 0.10.4 → 0.10.6

package/src/runtime/async-runner.ts

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { pathToFileURL } from "node:url";
 import { getCrewEnv } from "../config/env-vars.ts";
 import { appendEventAsync } from "../state/event-log/event-log.ts";
 import type { TeamRunManifest } from "../state/types.ts";
@@ -26,17 +26,14 @@ export type LoaderSpec = { kind: "jiti"; path: string } | { kind: "strip-types"
 
 type LoaderInput = LoaderSpec | string | false | undefined;
 
-function packageRootFromRuntime(): string {
-	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
-}
-
 function jitiRegisterPathFromPackageJson(packageJsonPath: string): string {
 	return path.join(path.dirname(packageJsonPath), "lib", "jiti-register.mjs");
 }
 
-export function resolveJitiRegisterPath(packageRoot = packageRootFromRuntime(), exists: FileExists = fs.existsSync): string | undefined {
-	// Walk upward from packageRoot looking for node_modules/jiti/lib/jiti-register.mjs
-	let current = path.resolve(packageRoot);
+export function resolveJitiRegisterPath(pkgRoot: string | undefined, exists: FileExists = fs.existsSync): string | undefined {
+	const effectiveRoot = pkgRoot ?? packageRoot();
+	// Walk upward from effectiveRoot looking for node_modules/jiti/lib/jiti-register.mjs
+	let current = path.resolve(effectiveRoot);
 	const root = path.parse(current).root;
 	while (true) {
 		const candidate = path.join(current, "node_modules", "jiti", "lib", "jiti-register.mjs");
@@ -115,7 +112,7 @@ export function getBackgroundRunnerCommand(
 	reportDirectory?: string,
 ): { args: string[]; loader: "jiti" | "strip-types" } {
 	const loader = normalizeLoaderInput(loaderInput);
-	if (!loader) throw new Error(buildLoaderUnavailableMessage(packageRootFromRuntime()));
+	if (!loader) throw new Error(buildLoaderUnavailableMessage(packageRoot()));
 	// Limit V8 heap to 512MB for the background runner to avoid triggering the
 	// Linux OOM killer. The runner itself is lightweight — it delegates work to
 	// child Pi processes — so 512MB is generous. Without this limit, Node.js
@@ -256,6 +253,15 @@ export function buildBackgroundRunnerEnv(env: NodeJS.ProcessEnv): NodeJS.Process
 	return { ...env, PI_CREW_ASYNC_RUN: "1" };
 }
 
+/** F4 v2: the ONE line written to the background-runner's stdin carrying
+ * PER-TASK compound broker tokens (see stdin-handshake.ts for why compound —
+ * ADR-0 item 6 rejects bare-runId tokens for wait.*). Kept pure + exported so
+ * tests pin the WRITER format against the READER parser — a drift between
+ * the two silently breaks coordination for every async run. */
+export function buildBrokerStdinLine(runId: string, socketPath: string, tasks: Record<string, string>): string {
+	return `${JSON.stringify({ v: 2, runId, socketPath, tasks })}\n`;
+}
+
 export async function spawnBackgroundTeamRun(manifest: TeamRunManifest): Promise<SpawnBackgroundTeamRunResult> {
 	// FIX (2026-07-02, perf review F-critical): use packageRoot() instead of
 	// import.meta.url-relative path. The previous path.resolve walks
@@ -289,7 +295,7 @@ export async function spawnBackgroundTeamRun(manifest: TeamRunManifest): Promise
 
 	const loader = resolveTypeScriptLoader();
 	if (!loader) {
-		const message = buildLoaderUnavailableMessage(packageRootFromRuntime());
+		const message = buildLoaderUnavailableMessage(packageRoot());
 		// FIX-08: use async event append to avoid sleepSync event-loop blocking.
 		await appendEventAsync(manifest.eventsPath, {
 			type: "async.failed",
@@ -318,11 +324,69 @@ export async function spawnBackgroundTeamRun(manifest: TeamRunManifest): Promise
 		cwd: manifest.cwd,
 		detached: true,
 		setsid: true,
-		stdio: ["ignore", "pipe", "pipe"],
+		// F4 (2026-09-12 live battery): stdin is a PIPE — broker credentials
+		// travel heap → pipe → heap right after spawn (see below). Previously
+		// "ignore", which (together with the env allowlist and the missing
+		// runner-side issuer) left EVERY async worker broker-less: ask/message
+		// fell back to "proceed with best judgment" silently.
+		stdio: ["pipe", "pipe", "pipe"],
 		env: childEnv,
 		windowsHide: true,
 	} as unknown as Parameters<typeof spawn>[2];
 	const child = spawn(process.execPath, command.args, spawnOpts);
+	// F4: hand the runner a per-run broker credential over stdin. The env
+	// route is CLOSED BY DESIGN — BACKGROUND_RUNNER_ENV_ALLOWLIST cannot carry
+	// PI_CREW_BROKER_TOKEN (secret-suffixed names are rejected by the
+	// sanitizeEnvSecrets validator, and a PI_CREW_BROKER_* glob is flagged
+	// isDangerousGlob). The token never touches disk (invariant,
+	// lifecycle-handlers.ts:990) and dies with the parent session (heap-only
+	// registry). issuer(runId) without taskId mints the LEGACY per-run token,
+	// which the registry accepts for any task of the run via its bare-runId
+	// fallback (crew-broker-tokens.ts get()). Best-effort: any failure here
+	// leaves the runner creds-less (= previous behavior), never throws.
+	try {
+		let line: string;
+		// LAZY: broker issuer only when a handshake payload needs minting.
+		const { getActiveBrokerIssuer } = await import("./broker/broker-issuer.ts");
+		const issuer = getActiveBrokerIssuer();
+		if (issuer) {
+			// F4 v2: pre-mint a COMPOUND (runId+taskId) token for every task of the
+			// run — wait.* rejects bare-runId tokens (ADR-0 item 6), so the legacy
+			// issuer(runId) shortcut left every park forbidden. Tasks are persisted
+			// BEFORE dispatch (tasksPath exists on the manifest); dynamic workflows
+			// that plan tasks inside the runner get no creds (follow-up: broker-side
+			// mint RPC).
+			// LAZY: state-store pulls the whole stores chain into the async runner.
+			const { loadRunManifestByIdAsync } = await import("../state/stores/state-store.ts");
+			const loaded = await loadRunManifestByIdAsync(manifest.cwd, manifest.runId);
+			const runTasks = loaded?.tasks ?? [];
+			const tasks: Record<string, string> = {};
+			let socketPath: string | undefined;
+			for (const task of runTasks) {
+				if (!task?.id) continue;
+				const creds = await issuer(manifest.runId, task.id);
+				if (creds) {
+					tasks[task.id] = creds.token;
+					socketPath ??= creds.socketPath;
+				}
+			}
+			if (socketPath && Object.keys(tasks).length > 0) {
+				line = buildBrokerStdinLine(manifest.runId, socketPath, tasks);
+				child.stdin?.write(line);
+			} else {
+				child.stdin?.write("\n");
+			}
+		} else {
+			child.stdin?.write("\n");
+		}
+	} catch {
+		/* best-effort: runner proceeds creds-less */
+	}
+	try {
+		child.stdin?.end();
+	} catch {
+		/* EPIPE: runner already died — the spawn error handling below owns that */
+	}
 	// Round 27 (BUG 3) history: the piped stdout/stderr were previously destroyed
 	// immediately to avoid a pipe-buffer deadlock (child writes >64KB with nobody
 	// draining → hang). BUT destroying stderr ALSO swallowed native crash

package/src/runtime/background-runner.ts

@@ -10,7 +10,6 @@ import { createRunPaths, loadRunManifestById, saveRunManifestAsync, updateRunSta
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
 import { errorMessage } from "../utils/guards.ts";
-import { projectCrewRoot } from "../utils/paths.ts";
 import { assertSafePathId } from "../utils/safe-paths.ts";
 import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
 // Heavy runtime — lazy-loaded to avoid pulling team-runner into background-runner
@@ -42,6 +41,10 @@ async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Pro
 
 import { logInternalError } from "../utils/internal-error.ts";
 import { writeAsyncStartMarker } from "./async-marker.ts";
+// F4: broker creds handshake helpers live in broker/stdin-handshake.ts
+// (pure module — background-runner runs await main() at module scope, so
+// importing THIS file from tests would boot the runner).
+import { parseStdinBrokerPayload, readStdinFirstLine } from "./broker/stdin-handshake.ts";
 import { terminateActiveChildPiProcesses } from "./child-pi/child-pi.ts";
 import { directTeamAndWorkflowFromRun } from "./direct-run.ts";
 import { resolveCrewRuntime, runtimeResolutionState } from "./model/runtime-resolver.ts";
@@ -160,6 +163,27 @@ export function signalEventType(sig: string): "async.signal" | "async.failed" {
 	return BENIGN_SIGNALS.has(sig) ? "async.signal" : "async.failed";
 }
 
+/**
+ * Scope-aware diagnostic paths for the background runner (issue #55, follows
+ * the #54 fix in run-tracker.ts). Runs created in a markerless (non-git) cwd
+ * live under userCrewRoot() — resolved via the same createRunPaths/
+ * scopeBaseRoot chain used at run CREATION — while project cwds keep .crew/ or
+ * the .pi/teams/ fallback (issue #29). Pure path math: createRunPaths asserts
+ * the runId (R11-2 boundary hardening preserved) and never touches the fs.
+ *
+ * These must stay (cwd, runId)-derived: both sites run BEFORE the manifest is
+ * loaded (the console redirect is the FIRST thing main() does; exitCodePath is
+ * computed at module load), so manifest.stateRoot is not available yet.
+ */
+export function backgroundLogPath(cwd: string, runId: string): string {
+	return path.join(createRunPaths(cwd, runId).stateRoot, "background.log");
+}
+
+/** exit-code.txt sibling of background.log — same scope resolution (#55). */
+export function backgroundExitCodePath(cwd: string, runId: string): string {
+	return path.join(createRunPaths(cwd, runId).stateRoot, "exit-code.txt");
+}
+
 /**
  * Fire-and-forget event log for signal handlers. Extracted to module level
  * (from inside main()) so the exported SIGINT handler installer (test seam)
@@ -421,10 +445,12 @@ async function main(): Promise<void> {
 		// best-effort try/catch so the hardening is never silently swallowed).
 		assertSafePathId("runId", _runId);
 		try {
-			// Use projectCrewRoot() so the background log lives next to the
-			// manifest in either .crew/state/runs/ or .pi/teams/state/runs/
-			// depending on the project's chosen layout (issue #29).
-			const logPath = path.join(projectCrewRoot(_cwd), "state", "runs", _runId, "background.log");
+			// Scope-aware (issue #55): resolve via createRunPaths so the log lands
+			// next to the manifest for BOTH project cwds (.crew/ or the .pi/teams/
+			// fallback, issue #29) and markerless cwds (user scope, issue #54). The
+			// previous projectCrewRoot join silently dropped the console redirect
+			// for user-scope runs — exactly the log needed to diagnose them.
+			const logPath = backgroundLogPath(_cwd, _runId);
 			logFd = fs.openSync(logPath, "a");
 			const origWrite =
 				(_prefix: string) =>
@@ -478,8 +504,11 @@ async function main(): Promise<void> {
 		// IIFE runs at MODULE LOAD, so an unsafe runId throws before the runner
 		// starts (intended fail-fast, matching run-import.ts:105 pattern).
 		assertSafePathId("runId", runId);
-		// Use projectCrewRoot() to honour the .pi/teams/ fallback (issue #29).
-		return path.join(projectCrewRoot(cwd), "state", "runs", runId, "exit-code.txt");
+		// Scope-aware (issue #55): same resolution as backgroundLogPath — project
+		// scope (.crew/ or .pi/teams/, issue #29) or user scope (#54). The
+		// previous projectCrewRoot join never landed exit-code.txt for user-scope
+		// runs, hiding non-zero exit diagnostics.
+		return backgroundExitCodePath(cwd, runId);
 	})();
 	if (exitCodePath) {
 		process.on("exit", (code) => {
@@ -498,6 +527,43 @@ async function main(): Promise<void> {
 	const cwd = argValue("--cwd");
 	const runId = argValue("--run-id");
 	if (!cwd || !runId) throw new Error("Usage: background-runner.ts --cwd <cwd> --run-id <runId>");
+	// F4 (2026-09-12 live battery): broker creds arrive on STDIN from the
+	// dispatching session (heap → pipe → heap; token never written to disk).
+	// Without this, every async worker loses ask/message/mailbox/steer — the
+	// env route is closed (allowlist rejects secret-suffixed tokens) and no
+	// extension lifecycle runs here to register an issuer. Best-effort:
+	// absent/invalid payload = creds-less runner = previous behavior.
+	try {
+		const raw = await readStdinFirstLine();
+		const payload = raw ? parseStdinBrokerPayload(raw, runId) : undefined;
+		if (payload) {
+			// LAZY: broker issuer module has process-level side effects at load.
+			const { setActiveBrokerIssuer } = await import("./broker/broker-issuer.ts");
+			// LAZY: pi-args pulls the model registry chain.
+			const { resolveCrewMaxDepth } = await import("./model/pi-args.ts");
+			// Static issuer scoped to THIS run, serving PRE-MINTED per-task COMPOUND
+			// tokens — wait.* rejects bare-runId tokens (ADR-0 item 6), so the v1
+			// single-token shortcut left every park forbidden. Unknown taskIds
+			// (dynamic workflows planned in-runner) get NO creds — follow-up:
+			// broker-side mint RPC. Depth-cap parity with the parent-side
+			// issueForChild gate (lifecycle-handlers.ts:1130-1136).
+			setActiveBrokerIssuer(async (rid, taskId, childDepth) => {
+				if (rid !== payload.runId) return undefined;
+				if (childDepth !== undefined && childDepth >= resolveCrewMaxDepth(undefined)) return undefined;
+				if (!taskId) return undefined;
+				const token = payload.tasks[taskId];
+				if (!token) return undefined;
+				return { socketPath: payload.socketPath, token };
+			});
+			debugLog(
+				`[broker] stdin handshake accepted for run ${runId} (${Object.keys(payload.tasks).length} task tokens, socket ${payload.socketPath})`,
+			);
+		} else {
+			debugLog(`[broker] no stdin creds payload — runner proceeds broker-less (pre-F4 behavior)`);
+		}
+	} catch {
+		/* best-effort: never fail boot over coordination creds */
+	}
 	// FIX Issue #3: Wrap in withRunLockSync to prevent concurrent background-runners
 	// for the same runId from reading stale manifest state. If lock cannot be
 	// be acquired within 5s, fail immediately rather than proceeding with stale data.

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

@@ -42,6 +42,14 @@ const BROKER_PROTOCOL = 1;
 /** Per-attempt timeout for connect + hello. */
 const CONNECT_HELLO_TIMEOUT_MS = 5_000;
 
+/** F5 (2026-09-12 live probe): default per-request RPC timeout. A response
+ * frame lost on a half-dead socket (no close event — observed live: worker
+ * stuck inside `await client.request("wait.request")` past its own ask
+ * deadline, because the deadline check lives AFTER the request resolves)
+ * would otherwise hang the caller forever. Callers with a longer natural
+ * cap (ask: timeoutSec) pass their own timeoutMs. */
+const REQUEST_TIMEOUT_DEFAULT_MS = 15_000;
+
 /** Bounded backoff schedule (ms). At most 4 attempts means 3 retries after
  *  the first failure. Jitter is ±25%. */
 const BACKOFF_SCHEDULE_MS: readonly number[] = [50, 100, 200, 400, 800] as const;
@@ -83,6 +91,8 @@ interface PendingRequest {
 	method: string;
 	resolve: (value: unknown) => void;
 	reject: (err: Error) => void;
+	/** F5: per-request timeout timer; cleared on settle + close. */
+	timer?: NodeJS.Timeout;
 }
 
 export class CrewBrokerClient {
@@ -153,7 +163,7 @@ export class CrewBrokerClient {
 	 * Never throws. The caller can continue using file-based fallback paths
 	 * without unwrapping anything.
 	 */
-	async request<T = unknown>(method: string, params: unknown): Promise<BrokerClientResult<T>> {
+	async request<T = unknown>(method: string, params: unknown, opts?: { timeoutMs?: number }): Promise<BrokerClientResult<T>> {
 		if (this._mode === "fallback") {
 			return { ok: false, fallback: true, errorCode: "fallback-sticky" };
 		}
@@ -176,9 +186,26 @@ export class CrewBrokerClient {
 		// Send the request. Send a frame FIRST so the server's hello gate
 		// cannot reject it as "method other than hello".
 		const id = `r-${randomUUID()}`;
+		let entry: PendingRequest | undefined;
 		const promise = new Promise<unknown>((resolve, reject) => {
-			this.pending.set(id, { id, method, resolve, reject });
+			entry = { id, method, resolve, reject };
+			this.pending.set(id, entry);
 		});
+		// F5: arm the per-request timeout BEFORE the write — a frame lost on a
+		// half-dead socket produces neither a response nor a close, and the
+		// caller would hang forever (observed live on a parked ask worker).
+		// Rejecting the pending entry funnels into the existing catch below
+		// (typed errorCode + enterFallbackOnce), so no new code path is needed.
+		const timeoutMs = opts?.timeoutMs ?? REQUEST_TIMEOUT_DEFAULT_MS;
+		const requestTimer: NodeJS.Timeout = (this.options.setTimeoutFn ?? ((cb: () => void, ms: number) => setTimeout(cb, ms)))(
+			() => {
+				const pendingEntry = this.pending.get(id);
+				this.pending.delete(id);
+				pendingEntry?.reject(new BrokerError("request-timeout", `no response for ${method} within ${timeoutMs}ms`));
+			},
+			Math.max(1, Math.floor(timeoutMs)),
+		);
+		if (entry) entry.timer = requestTimer;
 		try {
 			const frame = encodeBrokerFrame({ id, method, params });
 			// Write may emit EPIPE etc. We don't await drain here — the response
@@ -206,6 +233,15 @@ export class CrewBrokerClient {
 			const code = err instanceof BrokerError ? err.code : "request-failed";
 			this.enterFallbackOnce(code, err);
 			return { ok: false, fallback: true, errorCode: code };
+		} finally {
+			// F5: disarm the per-request timeout on ANY settle path (response,
+			// broker-error envelope, socket rejection) so late timer fires cannot
+			// reject an already-consumed pending entry.
+			try {
+				(this.options.clearTimeoutFn ?? ((t: NodeJS.Timeout) => clearTimeout(t)))(requestTimer);
+			} catch {
+				/* best-effort */
+			}
 		}
 	}
 
@@ -278,6 +314,13 @@ export class CrewBrokerClient {
 		// Resolving with undefined would have made request() return
 		// {ok:true, value:undefined}, which is misleading.
 		for (const [, p] of this.pending) {
+			if (p.timer) {
+				try {
+					(this.options.clearTimeoutFn ?? ((t: NodeJS.Timeout) => clearTimeout(t)))(p.timer);
+				} catch {
+					/* best-effort */
+				}
+			}
 			p.reject(new BrokerError("close", "client closed"));
 		}
 		this.pending.clear();

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

@@ -58,6 +58,7 @@ import {
 	WAIT_REQUEST_TIMEOUT_SEC_MAX,
 } from "./protocol/request-parsers.ts";
 import { recordWaitPolicyRejection, waitAuthError } from "./protocol/wait-auth.ts";
+import { pushWaitingToForegroundWaiter } from "./wait-push.ts";
 import { WaitStatusCache } from "./wait-status-cache.ts";
 
 /** Protocol version negotiated at `hello` time. Bump on breaking change.
@@ -1194,22 +1195,13 @@ export class CrewBroker {
 		await pollUntilDone();
 	}
 
-	/**
-	 * Phase 3: steer.push — push steering message to a running worker.
-	 *
-	 * Dual-write strategy for durability:
-	 *  1. Mailbox append (appendMailboxMessageAsync) — feeds the live broker
-	 *     fanout to connected subscribers AND persists to the mailbox inbox
-	 *     JSONL for later read.
-	 *  2. Steering-file append — writes the steer body to
-	 *     ${artifactsRoot}/steering/${taskId}.jsonl, the same file the
-	 *     child's pollSteering() polls via PI_CREW_STEERING_FILE. This is
-	 *     the durable fallback: even if the recipient child's broker connection is down, the
-	 *     child picks up the steer on its next poll tick.
-	 *
-	 * A steering-file write failure does NOT fail the steer push — the
-	 * mailbox write (1) has already succeeded.
-	 */
+	/** Phase 3: steer.push — push steering message to a running worker.
+	 *  Dual-write for durability: (1) mailbox append feeds the live broker
+	 *  fanout AND persists to the inbox JSONL; (2) steering-file append writes
+	 *  ${artifactsRoot}/steering/${taskId}.jsonl — the durable fallback the
+	 *  child's pollSteering() polls via PI_CREW_STEERING_FILE even when its
+	 *  broker connection is down. A steering-file write failure does NOT fail
+	 *  the push — the mailbox write has already succeeded. */
 	private async handleSteerPush(conn: ServerConnection, id: string, params: unknown): Promise<void> {
 		if (conn.role !== "orchestrator") {
 			this.sendError(conn, id, "forbidden", "steer.push requires orchestrator role");
@@ -1873,6 +1865,17 @@ export class CrewBroker {
 			timeoutSec: clampSec,
 			clamped,
 		});
+		// F1 (2026-09-12 live battery): release the sync foreground waiter with
+		// the question (evidence + design notes in broker/wait-push.ts).
+		await pushWaitingToForegroundWaiter({
+			cwd: this.options.cwd,
+			runId,
+			taskId,
+			questionId,
+			question: parsed.question,
+			deadline,
+			...(parsed.options ? { options: parsed.options } : {}),
+		});
 	}
 
 	/** WP-2/R2: terminal report of the parked `ask` tool — flips the task
@@ -1986,14 +1989,6 @@ export class CrewBroker {
 // Type guards (no `any`)
 // ============================================================================
 
-/** Moved to ./protocol/request-parsers.ts (M4 / WI-4.1):
- *   - isRequestObject
- *   - isHelloParams + BROKER_PROTOCOL
- *   - parseMsgSendParams + MsgSendParams
- *   - parseMsgInboxParams + MsgInboxParams
- *   - parseWaitRequestParams + WaitRequestParams
- *   - parseWaitResolveParams + WaitResolveParams
- *   - safeStringify
- *   - WAIT_* constants
- *  Removed from this file; re-exported via "./protocol/request-parsers.ts".
- */
+/** Parsers/constants moved to ./protocol/request-parsers.ts (M4 / WI-4.1):
+ *  hello/msg/wait params + safeStringify + WAIT_* constants — re-exported
+ *  from there. */

package/src/runtime/broker/protocol/request-parsers.ts

@@ -118,8 +118,16 @@ export function safeStringify(value: unknown): string {
  *  timeoutSec may NEVER exceed 1h — an unbounded timeout would pin slots and
  *  amplify I/O. Applied as deadline = now + min(timeoutSec, 3600). */
 export const WAIT_REQUEST_TIMEOUT_SEC_MAX = 3600;
-/** Default ask timeout when the caller omits timeoutSec (ADR item 1). */
-export const WAIT_REQUEST_TIMEOUT_SEC_DEFAULT = 600;
+/** Default ask timeout when the caller omits timeoutSec (ADR item 1).
+ * F2 (2026-09-12 live battery): MUST stay strictly below the worker response
+ * watchdog (`DEFAULT_CHILD_PI.responseTimeoutMs` = 600s). A parked worker
+ * emits NO output, so the watchdog counts the whole park; at 600==600 the
+ * kill raced the wake and the worker died at its own deadline
+ * (team_20260912014448: parked 01:46:01, response_timeout 01:56:01). 480s
+ * leaves 120s grace for the worker to wake, answer its fallback, and finish
+ * the turn. MAX stays 3600 (ADR P2-7) — a park longer than ~600s needs
+ * PI_TEAMS_CHILD_RESPONSE_TIMEOUT_MS raised to survive the watchdog. */
+export const WAIT_REQUEST_TIMEOUT_SEC_DEFAULT = 480;
 /** Bounded question payload (defense-in-depth under the 256 KiB frame cap). */
 export const WAIT_QUESTION_MAX_CHARS = 8192;
 /** Bounded answer-choice list: at most 16 options, 256 chars each. */

package/src/runtime/broker/stdin-handshake.ts

@@ -0,0 +1,87 @@
+/**
+ * stdin-handshake.ts — F4 (2026-09-12 live battery): broker credentials for
+ * the DETACHED background runner travel on STDIN (heap → pipe → heap).
+ *
+ * Why stdin: the env route is CLOSED BY DESIGN — BACKGROUND_RUNNER_ENV_ALLOWLIST
+ * cannot carry PI_CREW_BROKER_TOKEN (secret-suffixed names are rejected by the
+ * sanitizeEnvSecrets validator, and a PI_CREW_BROKER_* glob is flagged
+ * isDangerousGlob), and the token must NEVER be written to disk (invariant,
+ * lifecycle-handlers.ts:990). Without this handshake every async-run worker
+ * loses ask/message/mailbox/steer coordination and silently falls back to
+ * "proceed with best judgment".
+ *
+ * Pure protocol pieces live here (not in background-runner.ts, which runs
+ * `await main()` at module scope) so tests can import them without booting
+ * the runner.
+ */
+
+/** The one-line payload async-runner writes to the runner's stdin carrying
+ * PER-TASK compound tokens. v2 (ADR-0 2026-08-17 item 6): wait.* accepts
+ * task-scoped (compound) tokens ONLY — the legacy bare-runId token
+ * authenticates the connection but waitAuthError rejects its parks with
+ * `forbidden`. The dispatching session pre-mints a compound token for every
+ * task in the manifest (they exist before dispatch); dynamic-workflow tasks
+ * planned inside the runner get NO creds (follow-up: broker mint RPC). */
+export interface StdinBrokerPayload {
+	v: 2;
+	runId: string;
+	socketPath: string;
+	tasks: Record<string, string>;
+}
+
+/** Parse + validate one handshake line. Rejects wrong version, wrong run
+ * (cross-run containment), and missing/empty fields. Pure. */
+export function parseStdinBrokerPayload(raw: string, expectedRunId: string): StdinBrokerPayload | undefined {
+	try {
+		const obj: unknown = JSON.parse(raw.trim());
+		if (!obj || typeof obj !== "object") return undefined;
+		const o = obj as Record<string, unknown>;
+		if (o.v !== 2) return undefined;
+		if (o.runId !== expectedRunId) return undefined;
+		if (typeof o.socketPath !== "string" || o.socketPath.length === 0) return undefined;
+		const tasks = o.tasks;
+		if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) return undefined;
+		for (const [id, tok] of Object.entries(tasks)) {
+			if (id.length === 0 || typeof tok !== "string" || tok.length === 0) return undefined;
+		}
+		return { v: 2, runId: o.runId, socketPath: o.socketPath, tasks: tasks as Record<string, string> };
+	} catch {
+		return undefined;
+	}
+}
+
+/** Read the FIRST stdin line with a hard cap. Resolves undefined for: no
+ * stdin / TTY / silence past the timeout / oversize / error. Never throws,
+ * never destroys stdin (leaves it paused for the rest of boot). */
+export function readStdinFirstLine(timeoutMs = 2000): Promise<string | undefined> {
+	return new Promise((resolve) => {
+		const stdin = process.stdin;
+		if (!stdin || stdin.isTTY || stdin.destroyed || !stdin.readable) {
+			resolve(undefined);
+			return;
+		}
+		let settled = false;
+		const finish = (value: string | undefined): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			stdin.removeListener("data", onData);
+			resolve(value);
+		};
+		const timer = setTimeout(() => finish(undefined), timeoutMs);
+		let buf = "";
+		const onData = (chunk: Buffer | string): void => {
+			buf += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+			const nl = buf.indexOf("\n");
+			if (nl >= 0) {
+				stdin.pause();
+				finish(buf.slice(0, nl));
+			} else if (buf.length > 64 * 1024) {
+				finish(undefined);
+			}
+		};
+		stdin.on("data", onData);
+		stdin.on("end", () => finish(buf.length > 0 ? buf : undefined));
+		stdin.on("error", () => finish(undefined));
+	});
+}

package/src/runtime/broker/wait-push.ts

@@ -0,0 +1,45 @@
+import { loadRunManifestById } from "../../state/stores/state-store.ts";
+
+/** F1 (2026-09-12 live battery): release the sync foreground waiter with the
+ *  parked question. Without this push, the only entity that can answer (the
+ *  leader LLM) stays suspended inside its own `team` tool call until the
+ *  response watchdog kills the parked worker (evidence: team_20260912014448 —
+ *  parked 01:46:01, response_timeout 01:56:01, tool call returned only after
+ *  the failure; refuted-fix round 2 evidence: team_20260912053049).
+ *
+ *  resolveRunPromise is a no-op when no waiter is registered (async/detached
+ *  runs poll instead). Best-effort by design: a failure here must not fail
+ *  the park itself. Kept in its own module (LAZY-imported from the broker) so
+ *  crew-broker.ts stays under the M4 2000-line gate and no static
+ *  broker→run-tracker edge exists at module load (there is no cycle —
+ *  run-tracker has no broker import). */
+export async function pushWaitingToForegroundWaiter(params: {
+	cwd: string | undefined;
+	runId: string;
+	taskId: string;
+	questionId: string;
+	question: string;
+	deadline: number;
+	options?: string[];
+}): Promise<void> {
+	try {
+		// LAZY: run-tracker import kept lazy — see the module doc above.
+		const { resolveRunPromise } = await import("../run-tracker.ts");
+		const freshPark = loadRunManifestById(params.cwd ?? process.cwd(), params.runId);
+		if (freshPark) {
+			resolveRunPromise(params.runId, {
+				manifest: freshPark.manifest,
+				tasks: freshPark.tasks,
+				waiting: {
+					taskId: params.taskId,
+					questionId: params.questionId,
+					question: params.question,
+					deadline: params.deadline,
+					...(params.options ? { options: params.options } : {}),
+				},
+			});
+		}
+	} catch {
+		/* best-effort push: a failure here must not fail the park itself */
+	}
+}

package/src/runtime/detached-run-results.ts

@@ -11,21 +11,31 @@
  * The registry is in-process; a pending result is parked while an agent view is
  * open so the worker's own view session never receives the parent's report.
  */
+
 import { loadRunManifestById } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 import { isFinishedRunStatus } from "./process-status.ts";
 
 interface DetachedRun {
 	runId: string;
 	cwd: string;
+	/** Delivery attempts (P2-7). Each peek of a finished run is one attempt;
+	 * a successful send forgets the entry, so the counter only accumulates on
+	 * repeated send failures. Bounded at MAX_DELIVERY_ATTEMPTS to stop an
+	 * indefinitely-failing send from retrying every tick forever. */
+	attempts: number;
 }
 
+/** P2-7: give up after this many delivery attempts and log the drop. */
+const MAX_DELIVERY_ATTEMPTS = 3;
+
 const detachedRuns = new Map<string, DetachedRun>();
 
 /** Record a run whose foreground waiter was released by a view switch. */
 export function markRunDetached(runId: string, cwd: string): void {
 	if (!runId || !cwd) return;
-	detachedRuns.set(runId, { runId, cwd });
+	detachedRuns.set(runId, { runId, cwd, attempts: 0 });
 }
 
 /** Cheap guard for hot paths (render tick): nothing to do when empty. */
@@ -84,6 +94,20 @@ export function peekFinishedDetachedRunResults(options: { inViewSession?: boolea
 			continue;
 		}
 		if (!isFinishedRunStatus(loaded.manifest.status)) continue;
+		// P2-7: bounded delivery — drop after MAX_DELIVERY_ATTEMPTS failed
+		// cycles (a successful send forgets the entry, so reaching here again
+		// means the previous send threw).
+		entry.attempts += 1;
+		if (entry.attempts > MAX_DELIVERY_ATTEMPTS) {
+			detachedRuns.delete(entry.runId);
+			logInternalError(
+				"detached-run-results.delivery-gave-up",
+				new Error("delivery attempts exceeded"),
+				`runId=${entry.runId} attempts=${entry.attempts} — dropped after ${MAX_DELIVERY_ATTEMPTS} failed sends`,
+				"warn",
+			);
+			continue;
+		}
 		ready.push({ runId: entry.runId, text: formatDetachedRunResult(loaded.manifest, loaded.tasks) });
 	}
 	return ready;