pi-crew 0.11.47 → 0.11.49

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-crew",
-	"version": "0.11.47",
+	"version": "0.11.49",
 	"description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
 	"author": "baphuongna",
 	"license": "MIT",

package/skills/real-test-pi-crew/SKILL.md

@@ -197,6 +197,11 @@ End-to-end verification discipline for pi-crew changes. Distilled from the broke
 
 > **2026-10-24 update (wave 12 — test-fixture teardown, commits `75542295`→`a97714d2` + wave-12c F4/F6; spec `fixwave12-fixture-teardown-2026-10-24/SPEC.md`)**: lớp leak THỨ HAI, khác wave 11: 2 process `node -e "process.on('SIGTERM',()=>{}); setInterval(...)"` sống >6 h sau khi run `team_20261024024905_4cf882558c7c2b6d` completed — **test fixture**, không phải worker descendant: spawn `detached:true` (group riêng ⇒ group kill của runner không tới được) + teardown pid-only `child.kill()` (vô hiệu trước fixture nuốt SIGTERM) + không handle ⇒ không ai reap. Wave-11 sweep từ chối reap là **hành vi ĐÚNG** (không proof descent). (1) **Surface mới `test/helpers/fixture-process.ts`** — `spawnFixture` (THROW khi `detached:false`: child non-detached chia sẻ group của RUNNER, group kill sẽ giết runner + mọi file sibling; snapshot `readProcIdentity` NGAY sau spawn, normalise pgid=pid), `reapFixture` (group reap + escalation SIGTERM→SIGKILL, refusal chứng minh pid lạ ⇒ KHÔNG signal gì, pid-fallback cho non-Linux, không bao giờ throw), `registerFixtureTrap` (`after()` + `process.on("exit")` sync flush cho cửa sổ abort sớm). Rule viết 1 lần: `test/helpers/README.md`. (2) **GAP-1 (HIGH, wave 12c-F3)** — `background-runner-sigint-cleanup`: grandchild detached của harness giờ được reap theo group trong `finally` (harness giữ pid-only ĐÚNG — non-detached). (3) **GAP-2/GAP-3 (wave 12c-F3)** — fake `rg` tự ghi pid + reap group; `inference-broker` giữ `ChildProcess`, spawn detached + `reapFixture`/trap. (4) **GAP-4 (wave 12c-F4)** — `reap-group.test.ts`: teardown qua `reapTree` (leader-snapshot + group reap **TRƯỚC**, rồi pid kills idempotent) và `spawnTree()` tự reap group trên đường FAIL (timeout 15 s / spawn error / JSON hỏng) — trước đó leader biết, kids không ⇒ mồ côi toàn bộ. GAP-5 sweep: `guest-zombie` (detached thật) chuyển sang helper; 4 file còn lại là NON-detached ⇒ giữ pid kill + comment `// non-detached: pid-only by design (shares runner's group)`. (5) **Wave-12a bug tự gây** — thêm `test/unit/helpers/` mà không đăng ký shard weight ⇒ 4 test shard-partition fail (`ebe0138c`). (6) Battery cho wave này: T1 từng file đã sửa ×2 + `pgrep -af "setInterva[l]"` RỖNG + `test:unit` không tăng fail so baseline. (7) **Wave 12d lesson** — teardown test có async writer (`appendEventAsync` → `fs.promises.mkdir`) phải dùng `removeDirWithRetry` (`test/helpers/rm-retry.ts`: settle 250 ms + retry EBUSY/EPERM/ENOTEMPTY); `rmSync` trần ⇒ `ENOTEMPTY` dưới load vì writer tái tạo `runs/<runId>/` sau khi dir đã bị xoá.
 
+> **2026-10-28 update (incident 0.11.46/0.11.47 silent-worker + v0.11.48 hotfix + battery HARD-GATE, commits `eed005b3`(46)/`68788df4`(47)/`d55632d0`+`840900b3`(48)/`85de1893`(gate))**: (1) **INCIDENT (live-caught bởi chính tier này)** — LOW-1 stdin handshake (0.11.46) ship default-ON: reader worker-side `startChildBrokerClientAsync` → `readStdinFirstLine` (env broker identity + KHÔNG env token) làm toàn bộ `pi --mode json -p` worker **exit 0 với 0 byte stdout trong ~1.2s**; mọi team run/subagent trên 0.11.46–0.11.47 chết. **Fingerprint regression trong events: `empty-or-stderr-only-result`** — T7 giờ PHẢI grep chuỗi này trong events của run smoke (judge từ DISK, không tin prose report của pi -p). CI mù hoàn toàn: unit dùng seam `readStdinLine` (không chạy process.stdin thật trong pi thật), integration chạy fake-pi. (2) **v0.11.48 flip** — `PI_CREW_BROKER_STDIN` giờ **OPT-IN** (`=1` bật stdin route; unset/`0` = legacy env route bit-for-bit pre-0.11.46, cả 2 phía — `resolveBrokerStdinHandshakeEnabled` child-pi-spawn.ts + `resolveBrokerStdinFallbackEnabled` crew-broker-child.ts). LOW-1 code giữ nguyên chờ root-cause reader (strace: DNS → HTTPS :443 Cloudflare → rt_sigaction SIGTERM → exit_group(0) — ĐÃ giải thích + fix: xem update 2026-10-28-b bên dưới). Regression live test mới: `test/integration/broker-stdin-reader-liveworker.test.ts` (spawn pi thật + env shape chết, assert stdout>0, tự-skip khi không có `pi`). (3) **BATTERY HARD-GATE** — `scripts/pre-publish-battery.mjs` cắm vào `.githooks/pre-push` (sau unit, push main) + `prepublish-ci.mjs` (trước `npm run ci`): T1/T3/T11j luôn + T7 path-triggered từ diff tag-trước→HEAD; skip-không-pi CHỈ qua `PI_CREW_BATTERY_SKIP=1` (ghi audit `.crew/audit/battery.jsonl`; skip im lặng = ĐỎ); quy tắc **gate KHÔNG CHẠY = KHÔNG PUBLISH**. Script là lớp AUTO — battery thủ công theo decision table (tier còn lại: T2/T4/T5/T6/T8/T9/T10/T11c/T12/T13) VẪN bắt buộc theo changed paths và KHÔNG được cherry-pick tier rẻ. (4) **META-RULE (bài học 2 bản sót liền)** — đổi code ảnh hưởng behavior mà skill này mô tả ⇒ **update SKILL.md TRONG CộNG WAVE, TRƯỚC khi chạy battery**; battery chạy FULL decision-table cho mọi changed path. Gate prose bị bỏ 2/2 lần dưới áp lực; chỉ gate script (exit-code) sống sót — đó là lý do (3) tồn tại.
+
+
+> **2026-10-28-b update (ROOT-CAUSE CLOSED + fd3 transport + review-wave fixes, commits `38d5ed58`..`5190e66b`, cold-verified review + 3-agent verification)**: (1) **ROOT-CAUSE incident 0.11.46/47 (đóng)** — pi's `readPipedStdin` (pi@1.0.4 `dist/main.js:52-65`) đọc TOÀN BỘ piped stdin làm PROMPT CONTENT trong mọi mode trừ `--mode=rpc` ⇒ handshake fd0 race 3 cách: token JSON thành literal prompt text (SECRET LEAK — chứng minh trên transcript thật), stream-ended creds-less câm lặng, reader `pause()` trước EOF drain → pi boot await deadlock → **TỰ exit 0** (KHÔNG phải parent SIGTERM — strace cũ misread) + takeOverStdout buffer ⇒ ~0 bytes. **Fix: handshake dời sang fd3** (stdio entry 4 `['ignore','pipe','pipe','pipe']`, `readFirstLineFromFd(BROKER_HANDSHAKE_FD=3)`; fd0 về `"ignore"` — shape pre-0.11.46); detached runner GIỮ fd0 (node process, không race). Gate `PI_CREW_BROKER_STDIN` vẫn OPT-IN. Evidence: pre-fix pi@1.0.4 gate-ON 5/5 chết (~1s, 0B) → post-fix 2/2 sống (106-110KB, ~3.2s, 0 leak); integration live-worker giờ assert CẢ gate-ON liveness (bỏ comment "DO NOT assert liveness") + leak-check `v":2` không xuất hiện trong output. **Contract nền: fd0 KHÔNG BAO GIỜ là kênh sideband của extension khi spawn pi binary — dùng stdio entry 4+ (fd3).** (2) **T7 judge mechanics ĐỔI** — dispatch goal giờ mang nonce `[t7-nonce:<uuid>]`, judge CHỈ dirs có nonce trong events.jsonl (hết race newest-mtime với run đồng thời); non-terminal run = FAIL (check TRƯỚC killed-branch); stdout/stderr của dispatch được capture (cap 64KB) vào failure reason + audit. (3) **T7 triggers mở rộng** — thêm `src/(state|utils|agents|teams|workflows|hooks|observability)/` + `scripts/` (gate changes live-test the gate). (4) diff-base tag filter `^v\d+\.\d+\.\d+$` + porcelain rename both-sides; `PI_CREW_BATTERY_SKIP` giờ sống qua prepublishOnly path. (5) maxTasksPerRun admission cap tại createRunManifest (pre-dispatch); seam fix gate đọc `options.env ?? process.env` (test inject được — hết mutate process.env); `buildBrokerStdinLine` warn >60KiB (reader abort ~131KiB thực tế Linux — pipe chunks). (6) **CI 'Checks' step có gates NGOÀI battery list** (`check:env-vars`, `check:decision-drift`) — thêm vào leader local gate list sau mọi src edit.
+
 ## Core principle: disk ≠ live Pi
 
 Two locations hold pi-crew state:

package/src/config/env-allowlist-registry.ts

@@ -199,8 +199,8 @@ const CREW_ENV_FORWARDING_DECL: Record<string, CrewEnvForwardDecision> = {
 	},
 	PI_CREW_BROKER_TASK_ID: { kind: "child-write", reason: "child-pi-spawn broker handshake" },
 	PI_CREW_BROKER_STDIN: {
-		kind: "host-only",
-		reason: "LOW-1 closure broker-credential transport gate — read by the host spawner (child-pi-spawn .resolveBrokerStdinHandshakeEnabled) to pick env vs stdin route; the worker-side mirror read (crew-broker-child .resolveBrokerStdinFallbackEnabled) is defense-in-depth for the rollback case and needs NO ambient forwarding (parent decision fully determines the route; forwarding would churn the pinned BASE_ALLOWLIST)",
+		kind: "child-write",
+		reason: "LOW-1 broker-credential transport gate — read by the HOST spawner (child-pi-spawn .resolveBrokerStdinHandshakeEnabled) to pick env vs stdin route, then RE-WRITTEN by that spawner into every brokered child's built.env ('1') so the worker-side mirror gate (crew-broker-child .resolveBrokerStdinFallbackEnabled, which reads its OWN process.env) actually sees it — ambient forwarding never reaches the child, so child-write is the only channel that wires the route through (FIX-1 2026-10-28). Never ambient-allowlisted: route selection is per-spawn",
 	},
 	PI_CREW_INFERENCE_BROKER: {
 		kind: "gap",

package/src/config/env-vars.ts

@@ -668,7 +668,7 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	},
 	PI_CREW_BROKER_STDIN: {
 		name: "PI_CREW_BROKER_STDIN",
-		doc: "LOW-1 closure (2026-10-27) broker-credential transport gate: unset/non-'0' (default) sends the per-task compound PI_CREW_BROKER_TOKEN to the headless JSON worker over the spawn STDIN pipe (one buildBrokerStdinLine v2 payload; heap → pipe → heap — child-pi-spawn.ts writer, crew-broker-child.ts startChildBrokerClientAsync reader) so the token never appears in the child env; '0' rolls back to the legacy env route (token in built.env, stdin stays 'ignore') on BOTH sides. RPC-mode workers and surface TUI panes are unaffected (they keep the env route; the worker-side stdin read skips --mode rpc argv and TTY stdin by design)",
+		doc: "LOW-1 closure (2026-10-27) broker-credential transport gate, OPT-IN since v0.11.48 (2026-10-28): '1' sends the per-task compound PI_CREW_BROKER_TOKEN to the headless JSON worker over a DEDICATED fd3 spawn pipe (one buildBrokerStdinLine v2 payload on stdio entry 4; heap → fd3 → heap — child-pi-spawn.ts writer, crew-broker-child.ts startChildBrokerClientAsync reader; fd0 stays 'ignore') so the token never appears in the child env; unset/any-other-value (default) keeps the LEGACY ENV ROUTE (token in built.env) on BOTH sides — the original fd0 variant was caught by the live battery (real-test-pi-crew T7) killing real headless workers with a silent exit 0 (root cause: pi@1.0.4 readPipedStdin consumes all piped fd0 as prompt content); the fd3 transport removes that race. RPC-mode workers and surface TUI panes are unaffected (they keep the env route; the worker-side fd3 read skips --mode rpc argv by design)",
 	},
 	PI_CREW_GUEST: {
 		name: "PI_CREW_GUEST",

package/src/extension/autonomous-policy.ts

@@ -202,8 +202,15 @@ export function registerAutonomousPolicy(pi: ExtensionAPI): void {
 		const autonomous = effectiveAutonomousConfig(loaded.config.autonomous);
 		if (!autonomous.enabled) return undefined;
 		if (!autonomous.injectPolicy) return undefined;
+		const prompt = typeof event.prompt === "string" ? event.prompt : "";
+		// `prompt` is absent on turns with no user text (bg-task notifications, goal
+		// continuations, timer turns); unguarded it reaches prompt.toLowerCase() and throws.
+		// FIX-8 (GH #64 wave, defense-in-depth): `systemPrompt` is typed `string`
+		// and the runner always sets it, but coerce anyway — the output is built
+		// FROM it, so an undefined would stringify as a literal "undefined" prefix.
+		const systemPrompt = typeof event.systemPrompt === "string" ? event.systemPrompt : "";
 		return {
-			systemPrompt: appendAutonomousPolicy(event.systemPrompt, event.prompt, autonomous, cwd),
+			systemPrompt: appendAutonomousPolicy(systemPrompt, prompt, autonomous, cwd),
 		};
 	});
 }

package/src/extension/knowledge-injection.ts

@@ -474,6 +474,10 @@ export function registerKnowledgeInjection(pi: ExtensionAPI): void {
 		const cwd = typeof options.cwd === "string" ? options.cwd : process.cwd();
 		const fragment = buildKnowledgeFragment(cwd);
 		if (!fragment) return undefined;
-		return { systemPrompt: `${event.systemPrompt}${fragment}` };
+		// FIX-8 (GH #64 wave, defense-in-depth): `systemPrompt` is typed `string`
+		// and the runner always sets it, but coerce anyway — the output is built
+		// FROM it, so an undefined would stringify as a literal "undefined" prefix.
+		const systemPrompt = typeof event.systemPrompt === "string" ? event.systemPrompt : "";
+		return { systemPrompt: `${systemPrompt}${fragment}` };
 	});
 }

package/src/prompt/prompt-runtime.ts

@@ -1191,10 +1191,11 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 	// deliver pushed steers with the SAME sanitize + pi.sendMessage path as the
 	// file poll above. The file poll remains the durable fallback; a broker
 	// connect failure is invisible to the worker.
-	// LOW-1 closure: the registration hook is SYNC, but the credential source
-	// may now be the spawn stdin pipe (one buildBrokerStdinLine line) — resolve
+	// LOW-1 closure → FD-3: the registration hook is SYNC, but the credential
+	// source may now be the DEDICATED fd3 spawn pipe (one buildBrokerStdinLine
+	// line — fd0 stays "ignore"; pi@1.0.4 readPipedStdin owns fd0) — resolve
 	// the async bootstrap into a placeholder handle and swap it in when ready.
-	// A session_shutdown racing the (bounded ≤2s) stdin read closes whichever
+	// A session_shutdown racing the (bounded ≤2s) fd3 read closes whichever
 	// handle is live at that moment, and the late arrival closes itself.
 	let brokerHandle: ChildBrokerClientHandle = { active: false, close: async () => undefined };
 	let brokerShutdownSeen = false;
@@ -1356,6 +1357,13 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 
 	// ── Prompt rewriting (existing) ────────────────────────────────────────
 	pi.on("before_agent_start", (event) => {
+		// FIX-8 (GH #64 wave, defense-in-depth): `systemPrompt` is typed `string`
+		// and the runner always sets it. If a host ever hands a non-string through,
+		// SKIP the rewrite entirely — coercing "" here would REPLACE the real
+		// system prompt with a blank one (this handler strips sections), unlike
+		// the append-only hooks (autonomous-policy / knowledge-injection) which
+		// safely coerce "".
+		if (typeof event.systemPrompt !== "string") return;
 		const inheritProjectContext = readBooleanEnvAny(PI_CREW_INHERIT_PROJECT_CONTEXT_ENV, PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV);
 		const inheritSkills = readBooleanEnvAny(PI_CREW_INHERIT_SKILLS_ENV, PI_TEAMS_INHERIT_SKILLS_ENV);
 		if (inheritProjectContext === undefined && inheritSkills === undefined) return;

package/src/prompt/surface-worker.ts

@@ -182,7 +182,7 @@ export function parentAlive(pid: number, expectedStartTime: string | undefined,
 		// workers at the first 5s tick.
 		readerThrew = true;
 	}
-	if (readerThrew) return expectedStartTime ? false : true;
+	if (readerThrew) return !expectedStartTime;
 	// Reader returned "no entry" (default /proc reader ENOENT = dead on
 	// Linux) — dead-parent detection stays intact.
 	if (stat === undefined) return false;

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

@@ -17,7 +17,7 @@
 import type * as net from "node:net";
 import { getCrewEnv } from "../../config/env-vars.ts";
 import { type BrokerEventFrame, CrewBrokerClient, type CrewBrokerClientOptions } from "./crew-broker-client.ts";
-import { parseStdinBrokerPayload, readStdinFirstLine } from "./stdin-handshake.ts";
+import { BROKER_HANDSHAKE_FD, parseStdinBrokerPayload, readFirstLineFromFd } from "./stdin-handshake.ts";
 
 export interface ChildBrokerClientHandle {
 	/** True once the client has completed the handshake. */
@@ -39,9 +39,10 @@ export interface StartChildBrokerClientOptions {
 	netModule?: typeof net;
 	/** Test seam: override client construction. */
 	clientFactory?: (opts: CrewBrokerClientOptions) => CrewBrokerClient;
-	/** Test seam: override the stdin first-line read for the LOW-1 fallback
-	 *  (defaults to stdin-handshake.readStdinFirstLine on real process.stdin). */
-	readStdinLine?: () => Promise<string | undefined>;
+	/** Test seam: override the handshake first-line read for the LOW-1 fd3
+	 *  fallback (defaults to stdin-handshake.readFirstLineFromFd(3) on the
+	 *  dedicated spawn stdio pipe — NOT fd0, which pi owns for its prompt). */
+	readHandshakeLine?: () => Promise<string | undefined>;
 }
 
 const NOOP_HANDLE: ChildBrokerClientHandle = {
@@ -51,10 +52,10 @@ const NOOP_HANDLE: ChildBrokerClientHandle = {
 
 export function startChildBrokerClient(options: StartChildBrokerClientOptions = {}): ChildBrokerClientHandle {
 	const env = options.env ?? process.env;
-	const socketPath = env.PI_CREW_BROKER_SOCKET;
-	const token = env.PI_CREW_BROKER_TOKEN;
-	const runId = env.PI_CREW_BROKER_RUN_ID;
-	const taskId = env.PI_CREW_BROKER_TASK_ID;
+	const socketPath = getCrewEnv("PI_CREW_BROKER_SOCKET", env);
+	const token = getCrewEnv("PI_CREW_BROKER_TOKEN", env);
+	const runId = getCrewEnv("PI_CREW_BROKER_RUN_ID", env);
+	const taskId = getCrewEnv("PI_CREW_BROKER_TASK_ID", env);
 	if (!socketPath || !token || !runId || !taskId) {
 		return NOOP_HANDLE;
 	}
@@ -96,33 +97,56 @@ export function startChildBrokerClient(options: StartChildBrokerClientOptions =
  * its stdin IS the JSONL protocol channel and must never be consumed by the
  * credential handshake. Those spawns keep the token in env (the RPC branch of
  * child-pi.ts never strips it), so the fallback below is unreachable there
- * anyway — this guard is defense-in-depth against hybrid/old-parent skew. */
+ * anyway — this guard is defense-in-depth against hybrid/old-parent skew.
+ * FIX-2 (2026-10-28): match BOTH argv spellings — the pi-args builder emits
+ * the two-argv form ("--mode rpc"), but wrappers/users can pass the equals
+ * form ("--mode=rpc"); a spelling miss here would let the fallback eat a
+ * protocol line off the RPC JSONL channel. */
 function argvIndicatesRpcMode(): boolean {
-	return process.argv.includes("--mode") && process.argv.includes("rpc");
+	return process.argv.includes("--mode=rpc") || (process.argv.includes("--mode") && process.argv.includes("rpc"));
 }
 
 /** LOW-1 residual closure (2026-10-27): async wrapper used by the worker
  * bootstrap (prompt-runtime Feature 2b). Identical contract to
  * {@link startChildBrokerClient}, plus: when the env token is ABSENT but the
- * socket/run/task identity env IS present (new parent on the stdin-handshake
- * default), read the single buildBrokerStdinLine payload off stdin (bounded,
- * never throws) and merge the per-task token into a COPY of the env before
- * connecting. Ordering matrix:
- *   - new parent + new worker → token via stdin (env stays secret-free);
- *   - old parent → new worker → env token present → env route, stdin untouched;
- *   - new parent + PI_CREW_BROKER_STDIN=0 → env token present → env route;
- *   - payload missing/invalid/wrong-run/socket-mismatch → creds-less no-op
- *     handle (same as today), never a throw.
+ * socket/run/task identity env IS present (opt-in parent on the fd3 route —
+ * FIX-1 re-writes the flag into the child's built.env, without which this
+ * fallback was dead-wired), read the single buildBrokerStdinLine payload off
+ * the DEDICATED fd3 handshake pipe (bounded, never throws) and merge the
+ * per-task token into a COPY of the env before connecting. FD-3
+ * (2026-10-28, root-cause fix): pi@1.0.4 readPipedStdin consumes ALL piped
+ * fd0 bytes as PROMPT CONTENT in every mode except --mode rpc — the old
+ * fd0 handshake raced it three ways (token JSON leaked into the worker
+ * prompt; creds-less silence; pause() deadlock → SIGTERM exit 0 with ~0
+ * stdout — the 0.11.46/47 live incident), so the spawner now writes the
+ * payload to a dedicated stdio[3] pipe and this reader reads fd 3, never
+ * fd0. Ordering matrix (post FIX-1, 2026-10-28 — the gate is OPT-IN and the
+ * spawner writes flag + token into built.env for every brokered spawn; only
+ * the headless JSON compose strips the token):
+ *   - opt-in parent (PI_CREW_BROKER_STDIN=1) + headless JSON worker → flag
+ *     set, token ABSENT from env → token via fd3 (env stays secret-free);
+ *   - opt-in parent + RPC / surface worker → flag set, token PRESENT in env
+ *     → env route, fd3 untouched (their stdin is the protocol channel/TTY);
+ *   - legacy parent (gate off/unset) → env token present → env route;
+ *   - payload missing/invalid/wrong-run/socket-mismatch/unreadable fd3 →
+ *     creds-less no-op handle (same as today), never a throw.
  * The sync {@link startChildBrokerClient} stays untouched (env-only) so every
  * existing caller/test keeps its exact behavior. */
 export async function startChildBrokerClientAsync(options: StartChildBrokerClientOptions = {}): Promise<ChildBrokerClientHandle> {
 	let env = options.env ?? process.env;
-	const socketPath = env.PI_CREW_BROKER_SOCKET;
-	const runId = env.PI_CREW_BROKER_RUN_ID;
-	const taskId = env.PI_CREW_BROKER_TASK_ID;
-	if (socketPath && runId && taskId && !env.PI_CREW_BROKER_TOKEN && resolveBrokerStdinFallbackEnabled() && !argvIndicatesRpcMode()) {
+	const socketPath = getCrewEnv("PI_CREW_BROKER_SOCKET", env);
+	const runId = getCrewEnv("PI_CREW_BROKER_RUN_ID", env);
+	const taskId = getCrewEnv("PI_CREW_BROKER_TASK_ID", env);
+	if (
+		socketPath &&
+		runId &&
+		taskId &&
+		!getCrewEnv("PI_CREW_BROKER_TOKEN", env) &&
+		resolveBrokerStdinFallbackEnabled(env) &&
+		!argvIndicatesRpcMode()
+	) {
 		try {
-			const raw = await (options.readStdinLine ?? readStdinFirstLine)();
+			const raw = await (options.readHandshakeLine ?? (() => readFirstLineFromFd(BROKER_HANDSHAKE_FD)))();
 			const payload = raw ? parseStdinBrokerPayload(raw, runId) : undefined;
 			// socketPath cross-check: the payload must describe the SAME socket the
 			// parent announced via env (both are parent-controlled, but a mismatch
@@ -139,8 +163,19 @@ export async function startChildBrokerClientAsync(options: StartChildBrokerClien
 }
 
 /** Worker-side mirror of the parent gate (child-pi-spawn
- * .resolveBrokerStdinHandshakeEnabled): PI_CREW_BROKER_STDIN=0 keeps the
- * fallback OFF so a forced rollback is env-only on both sides. Default ON. */
-function resolveBrokerStdinFallbackEnabled(): boolean {
-	return getCrewEnv("PI_CREW_BROKER_STDIN") !== "0";
+ * .resolveBrokerStdinHandshakeEnabled). **OPT-IN since v0.11.48** (live
+ * battery caught the reader path killing real headless workers — see the
+ * parent gate's doc block): the default is OFF, so a legacy parent that set
+ * the env token travels the legacy env route. PI_CREW_BROKER_STDIN=1 opts
+ * BOTH sides into the stdin route — FIX-1 (2026-10-28): the spawner now
+ * re-writes the flag into the child's built.env ("child-write" registry
+ * kind), so an opt-in parent actually reaches this mirror gate (previously
+ * the flag died with the ambient-env strip and this fallback was dead-wired).
+ * Seam (2026-10-28): the gate reads the RESOLVED env — the same source as
+ * the identity vars above (`options.env ?? process.env`, threaded through
+ * getCrewEnv's env param) — so spawn-env delivery (FIX-1 writes the flag
+ * into the child's built.env) is pinnable in tests via options.env without
+ * mutating process.env. */
+function resolveBrokerStdinFallbackEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	return getCrewEnv("PI_CREW_BROKER_STDIN", env) === "1";
 }

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

@@ -43,14 +43,14 @@ import { loadRunManifestById, saveRunTasks } from "../../state/stores/state-stor
 import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 import { type GrandchildSpawnResult, spawnDelegateGrandchild } from "../delegate-spawn.ts";
 import { resolveCrewMaxDepth } from "../model/pi-args.ts";
-import { NestedSlotBudget } from "../scheduling/nested-slots.ts";
+import type { NestedSlotBudget } from "../scheduling/nested-slots.ts";
 import { evaluateDelegateAdmission } from "../spawn-policy.ts";
-import { DelegateAbortRegistry } from "./delegate/delegate-abort.ts";
-import { type DelegateEventTarget, type DelegateEventType } from "./delegate/delegate-event.ts";
+import type { DelegateAbortRegistry } from "./delegate/delegate-abort.ts";
+import type { DelegateEventTarget, DelegateEventType } from "./delegate/delegate-event.ts";
 import { delegateTerminalEvent, finalizeDelegateResult } from "./delegate/delegate-finalize.ts";
 import { promoteShadowToRunning } from "./delegate/shadow-lifecycle.ts";
-import { type CrewBrokerOptions, type ServerConnection } from "./protocol/connection-state.ts";
-import { type LockBusyOutcome } from "./protocol/lock-busy.ts";
+import type { CrewBrokerOptions, ServerConnection } from "./protocol/connection-state.ts";
+import type { LockBusyOutcome } from "./protocol/lock-busy.ts";
 import { parseDelegateRequestParams } from "./protocol/request-parsers.ts";
 
 /** Options slice the delegate handler reads off the broker's RESOLVED

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

@@ -12,9 +12,29 @@
  *
  * 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 runner. buildBrokerStdinLine additionally carries ONE LOUD oversize
+ * diagnostic (FIX-3, 2026-10-28) — stderr-only, never throws, never blocks
+ * the write.
+ *
+ * FD-3 TRANSPORT (2026-10-28, LOW-1 root-cause fix): brokered child-pi
+ * workers (real `pi` processes) CANNOT use fd0 for this handshake — pi@1.0.4
+ * `readPipedStdin()` (dist/main.js:52-65) consumes ALL piped stdin as PROMPT
+ * CONTENT in every mode except --mode rpc, so an fd0 handshake raced it
+ * three ways (token JSON merged into the prompt = secret leak; stream-ended
+ * creds-less silence; reader pause() before EOF → pi's await readPipedStdin()
+ * deadlock → SIGTERM exit 0 with ~0 stdout — the 0.11.46/47 live incident).
+ * The spawn side therefore adds a DEDICATED pipe as stdio entry 4 (fd 3) and
+ * writes the payload there (child-pi-spawn.ts/child-pi.ts); readFirstLineFromFd
+ * below is the worker-side reader for that pipe. fd0 stays "ignore"
+ * (pre-0.11.46 shape). The detached background RUNNER keeps the fd0 route —
+ * it is a plain node process whose stdin is dedicated to the handshake
+ * (readStdinFirstLine, unchanged); only the child-pi (pi binary) path needed
+ * the dedicated fd.
  */
 
+import * as fs from "node:fs";
+import { logInternalError } from "../../utils/internal-error.ts";
+
 /** 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
@@ -56,27 +76,62 @@ export function parseStdinBrokerPayload(raw: string, expectedRunId: string): Std
  * the detached background runner AND the main child-pi spawn path — share the
  * pure protocol piece and cannot drift from the reader parser below (a
  * writer/reader drift silently breaks coordination). Compound (runId+taskId)
- * tokens only: wait.* rejects bare-runId tokens (ADR-0 item 6). */
+ * tokens only: wait.* rejects bare-runId tokens (ADR-0 item 6).
+ *
+ * FIX-3 (2026-10-28): LOUD oversize diagnostic at the single construction
+ * point shared by BOTH writers. The worker-side reader (readStdinFirstLine)
+ * aborts once its buffer passes 64 KiB without a newline — a payload built
+ * from ~2.5k tasks (~131 KiB observed live) silently loses EVERY task's
+ * broker creds (ask/message/mailbox/steer degrade to file-poll) with zero
+ * trace in production. Warn at 60 KiB (below the reader cap, far above any
+ * sane task fanout) — NOT gated on PI_CREW_DEBUG: this is a "your creds
+ * will be lost" operational alarm, not a debug trace. The line is still
+ * returned (and written by the caller) — never blocked. */
+export const BROKER_STDIN_LINE_WARN_BYTES = 60 * 1024;
+
 export function buildBrokerStdinLine(runId: string, socketPath: string, tasks: Record<string, string>): string {
-	return `${JSON.stringify({ v: 2, runId, socketPath, tasks })}\n`;
+	const line = `${JSON.stringify({ v: 2, runId, socketPath, tasks })}\n`;
+	if (line.length > BROKER_STDIN_LINE_WARN_BYTES) {
+		logInternalError(
+			"stdin-handshake.oversize-payload",
+			new Error(
+				`broker stdin handshake line is ${line.length} bytes — the worker reader aborts past 64 KiB, so EVERY task loses its broker creds (ask/message/mailbox/steer fall back to file-poll)`,
+			),
+			`${Object.keys(tasks).length} tasks on run ${runId}; shrink the task fanout or split the run`,
+			"warn",
+		);
+	}
+	return line;
 }
 
-/** 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> {
+/** Dedicated handshake fd for brokered child-pi workers: spawn stdio entry
+ *  4 (spawnOptions.stdio = ["ignore","pipe","pipe","pipe"]). fd0 stays
+ *  "ignore" — the pre-0.11.46 shape — so pi@1.0.4 readPipedStdin can never
+ *  race or merge the credential into the worker prompt (LOW-1 root cause,
+ *  see the module docblock). */
+export const BROKER_HANDSHAKE_FD = 3;
+
+/** Read the FIRST line off a byte stream with a hard cap. Shared core of
+ * BOTH transports (fd0 for the detached runner, fd3 for child-pi workers).
+ * Resolves undefined for: silence past the timeout / oversize / stream
+ * error / empty EOF. Never throws, never destroys the stream (pauses it
+ * only after a first line was consumed — probe-verified 2026-10-28:
+ * destroy()/closeSync on an fs fd-stream is fragile on the error path
+ * (SIGABRT on EINVAL with autoClose) and a plain pause releases the loop on
+ * the payload/EOF shapes; the only shape that outlives the timeout is an
+ * open silent pipe, which a same-version parent can never produce — the
+ * spawner writes payload + end() synchronously in the spawn tick). */
+function readFirstLineFromStream(
+	stream: Pick<NodeJS.ReadableStream, "on" | "removeListener" | "pause">,
+	timeoutMs: number,
+): 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);
+			stream.removeListener("data", onData);
 			resolve(value);
 		};
 		const timer = setTimeout(() => finish(undefined), timeoutMs);
@@ -85,14 +140,55 @@ export function readStdinFirstLine(timeoutMs = 2000): Promise<string | undefined
 			buf += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
 			const nl = buf.indexOf("\n");
 			if (nl >= 0) {
-				stdin.pause();
+				stream.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));
+		stream.on("data", onData);
+		stream.on("end", () => finish(buf.length > 0 ? buf : undefined));
+		stream.on("error", () => finish(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). Detached
+ * background-runner transport ONLY (see module docblock — pi workers read
+ * the dedicated fd3 pipe via readFirstLineFromFd). */
+export function readStdinFirstLine(timeoutMs = 2000): Promise<string | undefined> {
+	const stdin = process.stdin;
+	if (!stdin || stdin.isTTY || stdin.destroyed || !stdin.readable) {
+		return Promise.resolve(undefined);
+	}
+	return readFirstLineFromStream(stdin, timeoutMs);
+}
+
+/** Read the FIRST line from a raw file descriptor — the worker-side reader
+ * of the DEDICATED fd3 handshake pipe (BROKER_HANDSHAKE_FD). Same bounded
+ * contract as readStdinFirstLine (2s default timeout, 64 KiB cap, never
+ * throws): a missing/closed/unreadable fd (old-parent skew: gate flag set
+ * but no 4th stdio entry), an EINVAL read on a non-readable fd, silence
+ * past the timeout, oversize, or error all resolve undefined — the caller
+ * proceeds creds-less exactly like a broker-less spawn. win32: immediate
+ * undefined (extra-fd spawn plumbing differs there and the broker is
+ * auto-disabled on Windows anyway). The fd is never closed by this reader
+ * (autoClose: false — it belongs to the spawn stdio table, and closing an
+ * fd under an active stream poll is what crashes Node's fs streams). */
+export function readFirstLineFromFd(fd: number, timeoutMs = 2000): Promise<string | undefined> {
+	if (process.platform === "win32") {
+		return Promise.resolve(undefined);
+	}
+	return new Promise((resolve) => {
+		let stream: fs.ReadStream;
+		try {
+			// fd option ⇒ the path argument is only a label, never opened.
+			stream = fs.createReadStream("", { fd, autoClose: false });
+		} catch {
+			resolve(undefined);
+			return;
+		}
+		readFirstLineFromStream(stream, timeoutMs).then(resolve, () => resolve(undefined));
 	});
 }

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

@@ -46,17 +46,42 @@ import {
 // NOT set this (their sessions persist and benefit from long-lived cache).
 export const PI_CACHE_RETENTION_ENV = "PI_CACHE_RETENTION";
 
-/** LOW-1 residual closure (2026-10-27): when the inter-pi broker credentials
- * are present, the per-task compound TOKEN travels over the spawn stdin pipe
- * (one `buildBrokerStdinLine` payload, heap → pipe → heap — same shape as the
- * F4 background-runner handshake) instead of the child env. Set
- * PI_CREW_BROKER_STDIN=0 to roll back to the legacy env route (token in
- * built.env, stdin stays "ignore"). Default ON. Only the headless JSON spawn
- * branch consumes the payload: the RPC branch (stdin is the JSONL protocol
- * channel) and the surface TUI panes keep the env route, so their env is
- * untouched. */
+/** LOW-1 residual closure (2026-10-27, DISABLED-DEFAULT 2026-10-28 v0.11.48):
+ * when the inter-pi broker credentials are present, the per-task compound TOKEN
+ * can travel over a DEDICATED fd3 spawn pipe (one `buildBrokerStdinLine`
+ * payload, heap → stdio[3] → heap — fd0 stays "ignore") instead of the child
+ * env. **EXPERIMENTAL / OPT-IN since v0.11.48**: the first attempt (v0.11.46/47)
+ * rode fd0 and was caught by the live battery (real-test-pi-crew T7) making
+ * REAL headless JSON workers exit 0 silently with zero stdout. Root cause
+ * (2026-10-28): pi@1.0.4 `readPipedStdin()` (dist/main.js:52-65) consumes ALL
+ * piped stdin as PROMPT CONTENT in every mode except --mode rpc — the fd0
+ * handshake raced it three ways (token JSON merged into the prompt = secret
+ * leak; stream-ended creds-less silence; reader pause() before EOF → pi's
+ * await readPipedStdin() deadlock → SIGTERM exit 0 with takeOverStdout
+ * buffering stdout to ~0 bytes). The fix moves the handshake to fd3
+ * (stdio entry 4); fd0 returns to "ignore" (pre-0.11.46 shape), killing every
+ * race ordering. Unit tests missed the original because they inject the
+ * `readHandshakeLine` seam instead of running the fd reader in a real pi
+ * process. The gate stays OPT-IN (legacy env route bit-for-bit pre-0.11.46);
+ * set PI_CREW_BROKER_STDIN=1 to opt the parent into the fd3 route.
+ *
+ * FIX-1 dead-wire repair (2026-10-28): when this gate is ON and broker
+ * credentials exist, prepareSpawnContext (1) WRITES PI_CREW_BROKER_STDIN="1"
+ * into built.env — the registry classifies the var "child-write" so ambient
+ * forwarding never carries it, and the worker-side mirror gate
+ * (crew-broker-child.resolveBrokerStdinFallbackEnabled) reads ITS OWN
+ * process.env; before the fix the flag never reached the child, so the
+ * fallback NEVER activated and every opt-in spawn stayed creds-less;
+ * (2) puts the TOKEN in built.env for BOTH branches — the RPC branch (stdin
+ * is the JSONL protocol channel) and surface TUI panes compose WITHOUT the
+ * payload, so only that env write hands them the credential (a token in
+ * their env also disarms the worker fd3 fallback — safe by design).
+ * Only the headless JSON branch composes WITH ctx.brokerStdinPayload, and
+ * buildFinalChildPiSpawnOptions strips the token from the FINAL env there
+ * (defense-in-depth) — on that branch alone the token rides the fd3 pipe.
+ * Gate OFF: no flag, no payload, token via env — bit-for-bit legacy. */
 export function resolveBrokerStdinHandshakeEnabled(): boolean {
-	return getCrewEnv("PI_CREW_BROKER_STDIN") !== "0";
+	return getCrewEnv("PI_CREW_BROKER_STDIN") === "1";
 }
 
 // ── Env allowlist (base set always passed to children) ──────────────────
@@ -303,15 +328,23 @@ export function buildFinalChildPiSpawnOptions(
 	if (workerCacheSplit) {
 		spawnOptions.env[PI_CACHE_RETENTION_ENV] = "short";
 	}
-	// (d) LOW-1 closure: when the caller will hand the broker token to the child
-	// over the stdin pipe (headless JSON branch — it passes the payload it got
-	// from prepareSpawnContext), switch stdin from "ignore" to "pipe" and strip
-	// the secret from the env as defense-in-depth (prepareSpawnContext already
-	// omits it; the delete guards direct builtEnv constructions in tests/callers
-	// that still carry it). RPC branch / surface workerEnv snapshots call
-	// WITHOUT this param → env keeps the token and nothing else changes.
+	// (d) LOW-1 closure → FD-3 (2026-10-28): when the caller will hand the
+	//     broker token to the headless JSON child over the DEDICATED fd3 pipe
+	//     (it passes the payload it got from prepareSpawnContext), add the 4th
+	//     stdio entry ("pipe") and strip the secret from the env as
+	//     defense-in-depth (prepareSpawnContext already omits it; the delete
+	//     guards direct builtEnv constructions in tests/callers that still
+	//     carry it). fd0 stays "ignore" — the pre-0.11.46 shape: pi@1.0.4
+	//     readPipedStdin (dist/main.js:52-65) consumes ALL piped fd0 bytes as
+	//     PROMPT CONTENT in every mode except --mode rpc, so the earlier fd0
+	//     handshake raced it three ways (token JSON merged into the prompt =
+	//     secret leak; creds-less silence; pause() → readPipedStdin deadlock →
+	//     SIGTERM exit 0 with ~0 stdout — the 0.11.46/47 live incident).
+	//     fd0=ignore kills every ordering: fd3 is a dedicated pipe pi never
+	//     touches. RPC branch / surface workerEnv snapshots call WITHOUT this
+	//     param → env keeps the token, 3-entry stdio, nothing else changes.
 	if (stdinBrokerPayload !== undefined) {
-		spawnOptions.stdio = ["pipe", "pipe", "pipe"];
+		spawnOptions.stdio = ["ignore", "pipe", "pipe", "pipe"];
 		delete spawnOptions.env.PI_CREW_BROKER_TOKEN;
 	}
 	// (e) Return the composed SpawnOptions for spawn(...).
@@ -338,10 +371,14 @@ export interface SpawnContext {
 	/** v0.11.31: inference-broker worker key that owns this spawn's token (cleanup/revoke bookkeeping). */
 	inferenceWorkerKey?: string;
 	/** LOW-1 closure: one-line broker credential payload to write to the
-	 * child's stdin right after spawn (headless JSON branch ONLY — the RPC
-	 * branch owns stdin for its JSONL protocol and surface panes are TTY).
-	 * Present ⇒ PI_CREW_BROKER_TOKEN is NOT in builtEnv (token travels
-	 * heap → pipe → heap instead). Undefined ⇒ legacy env route. */
+	 * child's DEDICATED fd3 pipe (stdio entry 4) right after spawn — headless
+	 * JSON branch ONLY (the RPC branch owns stdin for its JSONL protocol and
+	 * surface panes are TTY; fd0 stays "ignore" for every branch). Present ⇒
+	 * the headless compose adds the 4th stdio entry and strips
+	 * PI_CREW_BROKER_TOKEN from the FINAL child env
+	 * (buildFinalChildPiSpawnOptions); builtEnv still carries the token for
+	 * the RPC/surface call sites, which compose WITHOUT this payload and keep
+	 * the env route. Undefined ⇒ env route everywhere, 3-entry stdio. */
 	brokerStdinPayload?: string;
 }
 
@@ -452,21 +489,40 @@ export function prepareSpawnContext(
 	// safe under assertOnlyControlEnvKeys). Only when the parent broker issued
 	// credentials for this run — i.e. the broker is enabled AND this run is
 	// eligible. NEVER persisted to disk.
-	// LOW-1 closure: by default the TOKEN leaves the env entirely — it rides the
-	// spawn stdin pipe as a single buildBrokerStdinLine payload (ctx
-	// .brokerStdinPayload; the headless JSON branch pipes stdin and writes it
-	// right after spawn). SOCKET/RUN_ID/TASK_ID stay in env (non-secret, needed
-	// by the worker bootstrap to bind + validate the stdin payload). Rollback
-	// gate PI_CREW_BROKER_STDIN=0 (or a legacy shape without runId/taskId to
-	// bind the payload to) keeps the env route bit-for-bit.
+	// LOW-1 closure (OPT-IN since v0.11.48; FIX-1 dead-wire repair 2026-10-28;
+	// FD-3 transport 2026-10-28): when PI_CREW_BROKER_STDIN=1 the headless
+	// JSON spawn branch delivers the token over a DEDICATED fd3 pipe (4th
+	// stdio entry; ctx.brokerStdinPayload — fd0 stays "ignore") as a single
+	// buildBrokerStdinLine payload, and buildFinalChildPiSpawnOptions strips
+	// it from the FINAL env there. The token still lands in built.env for
+	// every brokered spawn — the RPC/surface call sites compose without the
+	// payload and need the env credential. SOCKET/RUN_ID/TASK_ID stay in env
+	// (non-secret, needed by the worker bootstrap to bind and validate the
+	// fd3 payload). Default (gate off) keeps the env route bit-for-bit.
 	if (input.brokerSpawn?.socketPath && input.brokerSpawn.token) {
 		built.env.PI_CREW_BROKER_SOCKET = input.brokerSpawn.socketPath;
-		if (resolveBrokerStdinHandshakeEnabled() && input.runId && input.agentId) {
+		const brokerStdinRoute = resolveBrokerStdinHandshakeEnabled();
+		if (brokerStdinRoute) {
+			// FIX-1: the worker-side mirror gate reads PI_CREW_BROKER_STDIN from
+			// the CHILD's own process.env; the registry classifies the var
+			// "child-write" (ambient forwarding never carries it), so the spawner
+			// MUST write it here — before the fix the flag never reached the
+			// child and the stdin fallback NEVER activated (creds-less NOOP).
+			built.env.PI_CREW_BROKER_STDIN = "1";
+		}
+		// FIX-1: the token is written into built.env for BOTH branches. The RPC
+		// branch (child-pi-rpc.ts) and surface TUI panes (child-pi.ts
+		// trySurfaceBranch) compose WITHOUT the payload — their stdin is the
+		// JSONL protocol channel / a TTY — so only this env write hands them the
+		// credential (a token in their env also disarms the worker fd3 fallback
+		// — safe). The headless JSON branch composes WITH the payload below, and
+		// buildFinalChildPiSpawnOptions strips the token from the FINAL env
+		// there — on that branch alone the token rides the fd3 pipe.
+		built.env.PI_CREW_BROKER_TOKEN = input.brokerSpawn.token;
+		if (brokerStdinRoute && input.runId && input.agentId) {
 			brokerStdinPayload = buildBrokerStdinLine(input.runId, input.brokerSpawn.socketPath, {
 				[input.agentId]: input.brokerSpawn.token,
 			});
-		} else {
-			built.env.PI_CREW_BROKER_TOKEN = input.brokerSpawn.token;
 		}
 		// runId/taskId are threaded unconditionally above (I5); nothing to add here.
 	}