pi-crew 0.11.11 → 0.11.13

package/src/prompt/inbox-poll.ts

@@ -22,10 +22,25 @@
  *     authenticated taskId, so a group broadcast returns to its sender and
  *     must be dropped at consume time);
  *   - dedup by message id across polls via a caller-owned seen-set and/or a
- *     `sinceTs` watermark — one message delivers once.
+ *     `sinceTs` watermark — one message delivers once;
+ *   - U5 (2026-10-10): dedup is ALSO durable across restarts — every picked
+ *     row is recorded in delivery.json (`messages[id]="acknowledged"` +
+ *     `${direction}:${requestId}` index) and re-read on the next poll, so a
+ *     worker that restarts mid-run (fresh process, EMPTY seen-set) never
+ *     re-delivers. A resend carrying the same requestId is dropped by the
+ *     same index; duplicate rows under one requestId deliver exactly once.
  */
-import { type MailboxMessage, readAllMailboxMessages } from "../state/coordination/mailbox.ts";
+import * as path from "node:path";
+import {
+	type MailboxDeliveryState,
+	type MailboxMessage,
+	readAllMailboxMessages,
+	readDeliveryState,
+	recordMailboxRequestIdDelivery,
+} from "../state/coordination/mailbox.ts";
+import { appendEventFireAndForget } from "../state/event-log/event-log.ts";
 import type { TeamRunManifest } from "../state/types.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 
 export interface WorkerInboxPickup {
 	stateRoot: string;
@@ -37,23 +52,99 @@ export interface WorkerInboxPickup {
 	seenIds?: Set<string>;
 }
 
+/** U5: requestId of a row — the U5 top-level field with the legacy
+ *  `data.requestId` shape (group_join) as fallback. */
+function messageIdempotencyKey(message: MailboxMessage): string | undefined {
+	if (message.requestId) return message.requestId;
+	const fromData = message.data?.requestId;
+	return typeof fromData === "string" ? fromData : undefined;
+}
+
+// U5: in-process throttle for `mailbox.pickup_deduped` audit events — a
+// restarted worker re-scans the same durable rows on EVERY 500ms tick, so an
+// un-throttled per-skip event would spam the log (2/s/row). One event per
+// (run, task, key) per process lifetime is the audit signal ("redelivery was
+// prevented by the durable record"); bounded FIFO like the parse caches.
+const DEDUP_EVENT_KEYS_MAX = 512;
+const dedupEventKeys = new Map<string, true>();
+
+function shouldEmitDedupEvent(runId: string, taskId: string, key: string): boolean {
+	const mapKey = `${runId}:${taskId}:${key}`;
+	if (dedupEventKeys.has(mapKey)) return false;
+	dedupEventKeys.set(mapKey, true);
+	while (dedupEventKeys.size > DEDUP_EVENT_KEYS_MAX) {
+		const oldest = dedupEventKeys.keys().next().value;
+		if (oldest === undefined) break;
+		dedupEventKeys.delete(oldest);
+	}
+	return true;
+}
+
+/** U5: audit event for a redelivery that the DURABLE record prevented (the
+ *  in-memory seen-set alone could not — this is exactly the restart window). */
+function emitPickupDedupedEvent(stateRoot: string, runId: string, taskId: string, message: MailboxMessage, layer: string): void {
+	if (!shouldEmitDedupEvent(runId, taskId, `${layer}:${message.id}`)) return;
+	try {
+		appendEventFireAndForget(path.join(stateRoot, "events.jsonl"), {
+			type: "mailbox.pickup_deduped",
+			runId,
+			taskId,
+			message: `Dropped duplicate inbox delivery (${layer}) for task ${taskId}.`,
+			data: {
+				layer,
+				messageId: message.id,
+				requestId: messageIdempotencyKey(message),
+				from: message.from,
+				kind: message.kind,
+			},
+		});
+	} catch (error) {
+		logInternalError("inbox-poll.pickup-deduped-event", error, `runId=${runId} taskId=${taskId}`);
+	}
+}
+
+/** U5: audit event for a successful pickup — with the requestId, the event
+ *  log is sufficient to audit the dedup chain end-to-end (broker
+ *  `mailbox.send` → worker `mailbox.pickup` → `mailbox.pickup_deduped`). */
+function emitPickupEvent(stateRoot: string, runId: string, taskId: string, picked: MailboxMessage[]): void {
+	try {
+		appendEventFireAndForget(path.join(stateRoot, "events.jsonl"), {
+			type: "mailbox.pickup",
+			runId,
+			taskId,
+			message: `Picked up ${picked.length} inbox message(s) for task ${taskId}.`,
+			data: {
+				messageIds: picked.map((m) => m.id),
+				requestIds: picked.map((m) => messageIdempotencyKey(m) ?? null),
+			},
+		});
+	} catch (error) {
+		logInternalError("inbox-poll.pickup-event", error, `runId=${runId} taskId=${taskId}`);
+	}
+}
+
 /**
  * Read the worker's inbox mailbox and return the messages that should be
  * surfaced as fenced context on the next turn.
  *
  * Stateless apart from the optional caller-owned `seenIds`/`sinceTs` — safe
- * to call on every 500ms poll tick.
+ * to call on every 500ms poll tick. U5: picked rows are ALSO recorded in the
+ * durable delivery state (delivery.json), so dedup survives a restart.
  */
 export function pollWorkerInbox(pickup: WorkerInboxPickup): MailboxMessage[] {
 	const { stateRoot, runId, taskId } = pickup;
 	if (!stateRoot || !runId || !taskId) return [];
 	const manifest = { stateRoot, runId } as unknown as TeamRunManifest;
 	let messages: MailboxMessage[];
+	let delivery: MailboxDeliveryState;
 	try {
 		// readAllMailboxMessages already merges run-level inbox + every task
 		// mailbox; we route TO this worker below (never trust a caller-scoped
 		// file path).
 		messages = readAllMailboxMessages(manifest, "inbox");
+		// U5: the durable delivery record (mtime-cached read — cheap on the
+		// 500ms tick) is the restart-safe dedup source of truth.
+		delivery = readDeliveryState(manifest);
 	} catch {
 		// Transient read error (lock contention, rotated file) — never throw
 		// out of a poll tick; the next 500ms tick retries.
@@ -61,8 +152,10 @@ export function pollWorkerInbox(pickup: WorkerInboxPickup): MailboxMessage[] {
 	}
 
 	const seen = pickup.seenIds;
+	const deliveredRequestIds = delivery.requestIds ?? {};
 	const picked: MailboxMessage[] = [];
 	const byId = new Set<string>();
+	const byRequestId = new Set<string>();
 	for (const m of messages) {
 		// Kind gate: only durable `message`s (per §15.2). Notify is
 		// fire-and-forget (its own channel), steer/response/follow-up are
@@ -81,10 +174,55 @@ export function pollWorkerInbox(pickup: WorkerInboxPickup): MailboxMessage[] {
 		if (seen?.has(m.id)) continue;
 		// Within-call id dedup (duplicate file rows → one delivery).
 		if (byId.has(m.id)) continue;
+		// ── U5 durable dedup (2026-10-10) ──────────────────────────────────
+		// These two layers survive a worker restart (delivery.json); the
+		// in-memory gates above cannot. Every skip here is a redelivery that
+		// was PREVENTED — audited via mailbox.pickup_deduped (once per key
+		// per process so the 500ms re-scan cannot spam the event log).
+		const requestId = messageIdempotencyKey(m);
+		const dedupKey = requestId !== undefined ? `${m.direction}:${requestId}` : undefined;
+		if (dedupKey !== undefined) {
+			// (direction, requestId) index — catches resends carrying the same
+			// requestId AND duplicate rows under one requestId.
+			if (deliveredRequestIds[dedupKey] !== undefined) {
+				emitPickupDedupedEvent(stateRoot, runId, taskId, m, "requestId");
+				continue;
+			}
+			// Within-call requestId dedup (two rows, one requestId → first wins).
+			if (byRequestId.has(dedupKey)) continue;
+		}
+		// Acknowledged delivery entry = the F09 durable "handled" record; the
+		// inbox line itself keeps `status:"queued"` forever, so WITHOUT this
+		// check a restarted worker re-delivers every already-consumed row
+		// (legacy rows without a requestId land here too).
+		if (delivery.messages[m.id] === "acknowledged") {
+			emitPickupDedupedEvent(stateRoot, runId, taskId, m, "acknowledged");
+			continue;
+		}
 		byId.add(m.id);
+		if (dedupKey !== undefined) byRequestId.add(dedupKey);
 		seen?.add(m.id);
 		picked.push(m);
 	}
+	if (picked.length > 0) {
+		// U5: persist the pickup — the durable record that powers the two
+		// layers above after a restart. Best-effort on failure: the in-memory
+		// seen-set still dedups within THIS process, and logInternalError
+		// makes the lost-durability window visible.
+		try {
+			recordMailboxRequestIdDelivery(
+				manifest,
+				picked.map((m) => ({
+					direction: m.direction,
+					messageId: m.id,
+					requestId: messageIdempotencyKey(m),
+				})),
+			);
+			emitPickupEvent(stateRoot, runId, taskId, picked);
+		} catch (error) {
+			logInternalError("inbox-poll.record-delivery", error, `runId=${runId} taskId=${taskId}`);
+		}
+	}
 	// Deterministic delivery order (same sort readAllMailboxMessages applies).
 	return picked;
 }

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

@@ -25,7 +25,12 @@ import { randomUUID } from "node:crypto";
 import * as fsp from "node:fs/promises";
 import * as net from "node:net";
 import { withRunLockSync } from "../../state/coordination/locks.ts";
-import { appendMailboxMessageAsync, type MailboxMessage, registerMailboxAppendObserver } from "../../state/coordination/mailbox.ts";
+import {
+	appendMailboxMessageAsync,
+	appendMailboxMessageIdempotentAsync,
+	type MailboxMessage,
+	registerMailboxAppendObserver,
+} from "../../state/coordination/mailbox.ts";
 import { appendEventAsync } from "../../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunManifest, saveRunTasks } from "../../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
@@ -936,6 +941,13 @@ export class CrewBroker {
 		}
 		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.
+		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
@@ -947,7 +959,7 @@ export class CrewBroker {
 			for (let i = 0; i < targets.length; i += CHUNK) {
 				const results = await Promise.allSettled(
 					targets.slice(i, i + CHUNK).map((target) =>
-						appendMailboxMessageAsync(manifest, {
+						appendMailboxMessageIdempotentAsync(manifest, {
 							id: `${messageId}_${target.label}`,
 							direction: "inbox",
 							from: fromField,
@@ -958,9 +970,13 @@ export class CrewBroker {
 							priority: parsed.priority ?? "normal",
 							deliveryMode: "next_turn",
 							replyTo: parsed.replyTo,
+							requestId,
 						}),
 					),
 				);
+				for (const r of results) {
+					if (r.status === "fulfilled" && r.value.deduped) dedupedRecipients++;
+				}
 				const failure = results.find((r) => r.status === "rejected") as PromiseRejectedResult | undefined;
 				if (failure) throw failure.reason;
 			}
@@ -969,6 +985,32 @@ 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.
+		try {
+			await appendEventAsync(manifest.eventsPath, {
+				type: "mailbox.send",
+				runId: manifest.runId,
+				taskId: fromField,
+				message: `Mailbox send ${dedupedRecipients > 0 ? "(resend, deduped) " : ""}to ${targets.length} recipient(s).`,
+				data: {
+					requestId,
+					messageId,
+					recipients: targets.length,
+					deduped: dedupedRecipients,
+					kind: parsed.kind ?? "message",
+					to: isWorker ? (typeof parsed.to === "string" ? parsed.to : "group") : "orchestrator",
+				},
+			});
+		} catch (err) {
+			logInternalError(
+				"crew-broker.msg.mailbox-send-event",
+				err instanceof Error ? err : new Error(String(err)),
+				`runId=${conn.runId}`,
+			);
+		}
 		// Task 5b (spec §15.2 wake): a worker message addressed to the parent
 		// appends a bounded `worker.message` run event so the host-side event
 		// bus (sidebar/widget refresh) and any live orchestrator connection
@@ -986,6 +1028,8 @@ export class CrewBroker {
 						to: "parent",
 						kind: parsed.kind ?? "message",
 						...(parsed.subject !== undefined ? { subject: parsed.subject } : {}),
+						// U5: correlate the wake event with the durable send.
+						requestId,
 					},
 				});
 			} catch (err) {
@@ -998,7 +1042,9 @@ export class CrewBroker {
 		}
 		this.sendResult(conn, id, {
 			messageId,
+			requestId,
 			recipientCount: targets.length,
+			dedupedRecipients,
 			durableStatus: durable ? "ok" : "failed",
 			liveDeliveryStatus: "ok",
 		});

package/src/runtime/broker/protocol/lock-busy.ts

@@ -16,7 +16,7 @@
  * Precedent: protocol/request-parsers.ts (M4/WI-4.1 extraction discipline).
  */
 
-import { withRunLockSync } from "../../../state/coordination/locks.ts";
+import { withRunLock, withRunLockSync } from "../../../state/coordination/locks.ts";
 import type { TeamRunManifest } from "../../../state/types.ts";
 
 /** Default bounded retry schedule for run.lock contention (ms). Five
@@ -24,6 +24,19 @@ import type { TeamRunManifest } from "../../../state/types.ts";
  *  detached runner's state flush — without parking the request. */
 export const DEFAULT_LOCK_BUSY_RETRY_DELAYS_MS: readonly number[] = [50, 100, 200, 400, 800];
 
+/** Merge-site busy-retry schedule (ms) — RELIABILITY FIX 2026-10-10
+ *  (run team_20261010100956 incident: background-runner killed by an
+ *  unhandled rejection when mergeUnitResult's withRunLock lost a run.lock
+ *  contention race against a concurrent writer). Longer than the broker
+ *  default above: a merge under contention sits on the scheduler's critical
+ *  path — the run is mid-flight and the settled unit is held in memory — so
+ *  it is worth ~7.9s of back-off (6 attempts) before the busy error is
+ *  allowed to propagate to the run-level error handler. Each attempt itself
+ *  already waits up to staleMs*2 inside acquireLockWithRetryAsync for
+ *  in-process holders; this schedule covers the LIVE FOREIGN holder case,
+ *  which throws immediately. */
+export const MERGE_LOCK_BUSY_RETRY_DELAYS_MS: readonly number[] = [100, 250, 500, 1000, 2000, 4000];
+
 /** Match the exact identity locks.ts throws for a LIVE holder on the
  *  never-steal path (sync acquireLockWithRetry, its async twin, and the
  *  lockCtx fallthrough): `Run '<basename>' is locked by another operation.`
@@ -74,3 +87,36 @@ export async function withRunLockBusyRetry<T>(
 function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+/** Async twin of withRunLockBusyRetry for the scheduler's merge sites
+ *  (merge-loop.ts mergeUnitResult, budget-enforcement.ts
+ *  terminaliseRunWithDrain): run `fn` under the ASYNC withRunLock with a
+ *  bounded busy-retry, notifying `onRetry` before each back-off sleep so the
+ *  call site can log a lock_retry event.
+ *
+ *  Retry safety mirrors the sync twin: the busy throw is raised by the lock
+ *  ACQUIRE before `fn` runs, and every nested state write inside the merge
+ *  bodies is lockCtx-reentrant (same-context nesting never re-acquires), so a
+ *  retry never re-executes a partially-run body. Any NON-busy error
+ *  propagates unchanged — real faults (ENOSPC, EACCES, corruption) keep their
+ *  current fatal path; only the transient contention identity is retried.
+ *  When the schedule is exhausted the busy error is rethrown for the run-level
+ *  handler to classify (bounded — never an infinite loop). */
+export async function withRunLockBusyRetryAsync<T>(
+	manifest: TeamRunManifest,
+	delaysMs: readonly number[],
+	fn: () => Promise<T>,
+	onRetry?: (attempt: number, delayMs: number, error: Error) => void,
+): Promise<T> {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			return await withRunLock(manifest, fn);
+		} catch (error) {
+			if (!isRunLockBusyError(error)) throw error;
+			const delay = delaysMs[attempt];
+			if (delay === undefined) throw error;
+			onRetry?.(attempt + 1, delay, error as Error);
+			await sleep(delay);
+		}
+	}
+}

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

@@ -61,6 +61,11 @@ export interface MsgSendParams {
 	/** Task 5b (§15.2): short subject echoed into the worker.message wake
 	 * event (bounded like the tool-side MSG_SUBJECT_MAX_CHARS). */
 	subject?: string;
+	/** U5 (2026-10-10): client-supplied idempotency key — a msg.send retried
+	 *  with the SAME requestId is deduped per target mailbox (no duplicate
+	 *  rows; the broker returns the existing message). Charset-bounded like
+	 *  cross-extension-rpc's requestId to keep it a safe log/mailbox token. */
+	requestId?: string;
 }
 
 export function parseMsgSendParams(value: unknown): MsgSendParams | undefined {
@@ -81,7 +86,9 @@ export function parseMsgSendParams(value: unknown): MsgSendParams | undefined {
 	}
 	const replyTo = typeof v.replyTo === "string" ? v.replyTo : undefined;
 	const subject = typeof v.subject === "string" && v.subject.length > 0 && v.subject.length <= 256 ? v.subject : undefined;
-	return { to: to as string | string[] | "all", body: v.body, kind, priority, replyTo, subject };
+	const rawRequestId = v.requestId;
+	const requestId = typeof rawRequestId === "string" && /^[\w:.-]{1,256}$/.test(rawRequestId) ? rawRequestId : undefined;
+	return { to: to as string | string[] | "all", body: v.body, kind, priority, replyTo, subject, requestId };
 }
 
 export interface MsgInboxParams {

package/src/runtime/budget-enforcement.ts

@@ -16,12 +16,12 @@
  * team-runner.ts would create a cycle).
  */
 import { flushPendingAtomicWrites } from "../state/atomic-write.ts";
-import { withRunLock } from "../state/coordination/locks.ts";
 import { appendEventAsync } from "../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunManifestAsync, saveRunTasksAsync, updateRunStatus } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { aggregateUsage, formatTokens } from "../state/usage.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { MERGE_LOCK_BUSY_RETRY_DELAYS_MS, withRunLockBusyRetryAsync } from "./broker/protocol/lock-busy.ts";
 import { saveCrewAgents } from "./crew-agent-records.ts";
 import { cancelNonTerminalTasks, markBlocked } from "./dispatch-batch.ts";
 import { isNonTerminalTaskStatus, mergeTaskUpdatesPreservingTerminal } from "./merge-gate.ts";
@@ -136,25 +136,41 @@ export async function terminaliseRunWithDrain(
 	if (validResults.length > 0) {
 		// Merge under the run lock — same pattern as mergeUnitResult:
 		// flush pending writes, load disk state, merge artifacts + tasks,
-		// save atomically.
-		const mergeResult = await withRunLock(ctx.manifest, async () => {
-			flushPendingAtomicWrites();
-			const disk = loadRunManifestById(ctx.manifest.cwd, ctx.manifest.runId);
-			const diskManifest = disk?.manifest ?? ctx.manifest;
-			const reconciledArtifacts = mergeArtifacts([
-				...diskManifest.artifacts,
-				...validResults.flatMap((item) => item.manifest.artifacts),
-			]);
-			const resultManifest = updateRunStatus(
-				{ ...diskManifest, artifacts: reconciledArtifacts },
-				"running",
-				"Merged in-flight results during failed-task abort.",
-			);
-			const resultTasks = mergeTaskUpdatesPreservingTerminal(disk?.tasks ?? ctx.tasks, validResults);
-			await saveRunManifestAsync(resultManifest);
-			await saveRunTasksAsync(resultManifest, resultTasks);
-			return { resultManifest, resultTasks };
-		});
+		// save atomically. RELIABILITY FIX 2026-10-10: bare withRunLock here had
+		// the same contention-fatal flaw as mergeUnitResult (see merge-loop.ts) —
+		// a busy run.lock on this abort path would surface as an unhandled
+		// rejection downstream. Bounded busy-retry + run.lock_retry event now.
+		const mergeResult = await withRunLockBusyRetryAsync(
+			ctx.manifest,
+			MERGE_LOCK_BUSY_RETRY_DELAYS_MS,
+			async () => {
+				flushPendingAtomicWrites();
+				const disk = loadRunManifestById(ctx.manifest.cwd, ctx.manifest.runId);
+				const diskManifest = disk?.manifest ?? ctx.manifest;
+				const reconciledArtifacts = mergeArtifacts([
+					...diskManifest.artifacts,
+					...validResults.flatMap((item) => item.manifest.artifacts),
+				]);
+				const resultManifest = updateRunStatus(
+					{ ...diskManifest, artifacts: reconciledArtifacts },
+					"running",
+					"Merged in-flight results during failed-task abort.",
+				);
+				const resultTasks = mergeTaskUpdatesPreservingTerminal(disk?.tasks ?? ctx.tasks, validResults);
+				await saveRunManifestAsync(resultManifest);
+				await saveRunTasksAsync(resultManifest, resultTasks);
+				return { resultManifest, resultTasks };
+			},
+			(attempt, delayMs, error) => {
+				// Best-effort observability only — a failed event append must not break the retry.
+				appendEventAsync(ctx.manifest.eventsPath, {
+					type: "run.lock_retry",
+					runId: ctx.manifest.runId,
+					message: `run.lock contention during abort drain merge (attempt ${attempt}); retrying in ${delayMs}ms: ${error.message}`,
+					data: { attempt, delayMs, site: "terminaliseRunWithDrain" },
+				}).catch(() => undefined);
+			},
+		);
 		ctx.manifest = mergeResult.resultManifest;
 		ctx.tasks = mergeResult.resultTasks;
 	}

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

@@ -9,6 +9,8 @@
  */
 
 import { DEFAULT_CHILD_PI } from "../../config/defaults.ts";
+import { getCrewEnv } from "../../config/env-vars.ts";
+import type { ChildPiRunInput } from "./child-pi.ts";
 
 /** Post-exit window during which stdio is guarded against late writes. */
 export const POST_EXIT_STDIO_GUARD_MS = DEFAULT_CHILD_PI.postExitStdioGuardMs;
@@ -48,3 +50,25 @@ export const MAX_TOOL_INPUT_CHARS = DEFAULT_CHILD_PI.maxToolInputChars;
 
 /** Maximum characters for general compactable content (used by TruncationStage). */
 export const MAX_COMPACT_CONTENT_CHARS = DEFAULT_CHILD_PI.maxCompactContentChars;
+
+/**
+ * Effective no-response timeout for a child run: env
+ * PI_TEAMS_CHILD_RESPONSE_TIMEOUT_MS (bounded to [1s, 1h] — FIX Round 14: a
+ * hostile/accidental value like 1 or 999_999_999 must neither disable the
+ * timeout nor cause instant kills) beats ChildPiRunInput.responseTimeoutMs
+ * beats the DEFAULT_CHILD_PI default.
+ *
+ * U14: extracted from the json branch's inline copy so the rpc transport
+ * (child-pi-rpc.ts) resolves the EXACT same budget — the watchdog timing is
+ * part of the bảng KHÔNG ĐỔI contract and must not drift between transports.
+ */
+export function resolveResponseTimeoutMs(input: Pick<ChildPiRunInput, "responseTimeoutMs">): number {
+	const RESPONSE_TIMEOUT_MIN_MS = 1_000;
+	const RESPONSE_TIMEOUT_MAX_MS = 3_600_000;
+	const responseTimeoutEnv = Number.parseInt(getCrewEnv("PI_TEAMS_CHILD_RESPONSE_TIMEOUT_MS") ?? "", 10);
+	const envInRange =
+		Number.isFinite(responseTimeoutEnv) &&
+		responseTimeoutEnv >= RESPONSE_TIMEOUT_MIN_MS &&
+		responseTimeoutEnv <= RESPONSE_TIMEOUT_MAX_MS;
+	return envInRange ? responseTimeoutEnv : (input.responseTimeoutMs ?? RESPONSE_TIMEOUT_MS);
+}

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

@@ -1,7 +1,7 @@
 /**
  * child-pi-kill.ts — Kill/escape path for child Pi worker processes.
  *
- * Extracted from child-pi.ts (H-7 decomposition, step 2). Zero behavior change.
+ * Extracted from child-pi.ts (H-7 decomposition, step 2).
  *
  * Responsibilities:
  *   - appendBoundedTail(): bounded concatenation with truncation marker.
@@ -13,6 +13,15 @@
  *
  * The activeChildrenMap and hardKillTimers Map are kept here (not re-exported)
  * because they are tightly coupled to the kill lifecycle.
+ *
+ * U15 (upgrade-spec 2026-10-09): every child registered via registerActiveChild
+ * is ALSO adopted into the OwnedProcess registry (owned-process.ts) — kills then
+ * route through the escalating group dispose (SIGTERM → poll → SIGKILL → cap →
+ * warn give-up) instead of a one-shot fire-and-forget signal pair, and the
+ * root-exit drain-reconcile reaps backgrounded descendants. The background
+ * zombie scanner and the child-side PI_CREW_PARENT_PID guard are KEPT as the
+ * complementary layers (owner-side catchable exits vs child-side leader-death
+ * backstop — see spec U15 "Complementary" note).
  */
 
 import type { ChildProcess } from "node:child_process";
@@ -21,6 +30,7 @@ import { DEFAULT_CHILD_PI } from "../../config/defaults.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { TailCaptureStage } from "../compaction/compact-stages/tail-capture-stage.ts";
 import { HARD_KILL_MS } from "./child-pi-constants.ts";
+import { adoptOwnedProcess, disposeAllOwnedProcesses, type OwnedProcess } from "./owned-process.ts";
 
 const MAX_CAPTURE_BYTES = DEFAULT_CHILD_PI.maxCaptureBytes;
 
@@ -28,6 +38,12 @@ const MAX_CAPTURE_BYTES = DEFAULT_CHILD_PI.maxCaptureBytes;
 const activeChildProcesses = new Map<number, ChildProcess>();
 const childHardKillTimers = new Map<number, NodeJS.Timeout>();
 
+// U15: adopted OwnedProcess handles by pid. Filled by registerActiveChild;
+// entries survive root exit on purpose (the owned process owns the drain-
+// reconcile of backgrounded descendants) and are pruned by the scanner below
+// once the owner reaches its terminal state.
+const ownedByPid = new Map<number, OwnedProcess>();
+
 // Periodic cleanup of dead child process entries to prevent memory leaks.
 // If a child process never emits exit/close (zombie), the entry would leak.
 setInterval(() => {
@@ -38,14 +54,30 @@ setInterval(() => {
 			activeChildProcesses.delete(pid);
 		}
 	}
+	// U15: prune adopted owners that reached terminal state (group confirmed
+	// gone via dispose or drain-reconcile). Non-terminal owners stay routable.
+	for (const [pid, owner] of ownedByPid) {
+		if (owner.terminated) ownedByPid.delete(pid);
+	}
 }, 60_000).unref();
 
 /** Register a newly-spawned child so it can be tracked + killed on shutdown. */
 export function registerActiveChild(pid: number, child: ChildProcess): void {
 	activeChildProcesses.set(pid, child);
+	// U15: adopt into the owned-process registry so kill paths escalate through
+	// group dispose. Group leadership is resolved inside adoptOwnedProcess
+	// (authoritative /proc check on Linux — the rpc branch child, spawned
+	// without detached, lands on the single-process fallback automatically).
+	ownedByPid.set(pid, adoptOwnedProcess(child, { name: `child-pi:${pid}` }));
 }
 
-/** Remove a child from the active set once it has exited (or before kill). */
+/**
+ * Remove a child from the active set once it has exited (or before kill).
+ *
+ * NOTE (U15): this does NOT drop the adopted OwnedProcess handle — the owner
+ * still owes a drain-reconcile for backgrounded descendants after the root
+ * exit. The owned entry is pruned by the scanner once terminal.
+ */
 export function unregisterActiveChild(pid: number): void {
 	activeChildProcesses.delete(pid);
 }
@@ -94,6 +126,16 @@ function spawnTaskkillSafe(pid: number): void {
 
 export function killProcessPid(pid: number): void {
 	if (!Number.isInteger(pid) || pid <= 0) return;
+	// U15: adopted children escalate through the owned dispose ladder
+	// (SIGTERM group → poll → SIGKILL group → cap → warn give-up) instead of
+	// the one-shot signal pair below. External pid-only callers that never
+	// registered (live-session agents, cancel paths on stale pids) keep the
+	// legacy one-shot behavior unchanged.
+	const owned = ownedByPid.get(pid);
+	if (owned) {
+		void owned.dispose();
+		return;
+	}
 	try {
 		if (process.platform === "win32") {
 			// 3.8: Windows path uses taskkill /T /F (force kill the entire tree).
@@ -168,6 +210,16 @@ export function killProcessTree(pid: number | undefined, child?: ChildProcess):
 		/* diagnostic best-effort */
 	}
 	if (!pid || !Number.isInteger(pid) || pid <= 0) return;
+	// U15: route adopted children through the escalating owned dispose. This
+	// deliberately BYPASSES the `child.exitCode !== null` early-out below: a
+	// dead root can still have live backgrounded descendants in its group, and
+	// dispose() is the component that knows (groupAlive is its source of truth;
+	// a terminal owner settles as a no-op via the PID-recycle guard).
+	const owned = ownedByPid.get(pid);
+	if (owned) {
+		void owned.dispose();
+		return;
+	}
 	if (child && child.exitCode !== null) return;
 	killProcessPid(pid);
 	child?.once("exit", () => clearHardKillTimer(pid));
@@ -176,5 +228,10 @@ export function killProcessTree(pid: number | undefined, child?: ChildProcess):
 export function terminateActiveChildPiProcesses(): number {
 	const entries = [...activeChildProcesses.entries()];
 	for (const [pid, child] of entries) killProcessTree(pid, child);
+	// U15: also reap owners whose active-set entry is already gone (root exited,
+	// backgrounded descendants mid-drain). Fire-and-forget by design — the sync
+	// SIGTERM prefix is delivered immediately; the ladder completes while the
+	// shutdown path drains, and the postmortem registry covers a hard exit.
+	void disposeAllOwnedProcesses();
 	return entries.length;
 }