pi-crew 0.10.2 → 0.10.3

package/src/runtime/output/sidechain-output.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { logInternalError } from "../../utils/internal-error.ts";
 import { redactSecrets } from "../../utils/redaction.ts";
 import { isSafePathId } from "../../utils/safe-paths.ts";
 
@@ -12,15 +13,69 @@ export interface SidechainEntry {
 	cwd: string;
 }
 
+// ── Batched JSONL writer (Task 26, 2026-08-24) ──────────────────────────
+// PERF (2026-08-24): the old writeSidechainEntry did one mkdirSync +
+// appendFileSync + full redaction clone PER STREAMING EVENT (message_update
+// fires per chunk). Batch per path on a 50ms unref'd timer like
+// child-pi-transcript; redaction + serialization still run per event at
+// queue time, and the flush does ONE mkdir + append per path per window.
+interface PendingJsonlBatch {
+	lines: string[];
+	timer: NodeJS.Timeout;
+}
+const pendingJsonlBatches = new Map<string, PendingJsonlBatch>();
+const JSONL_FLUSH_MS = 50;
+
+function queueJsonlLine(filePath: string, line: string): void {
+	const pending = pendingJsonlBatches.get(filePath);
+	if (pending) {
+		pending.lines.push(line);
+		return;
+	}
+	const timer = setTimeout(() => flushJsonlBatch(filePath), JSONL_FLUSH_MS);
+	timer.unref();
+	pendingJsonlBatches.set(filePath, { lines: [line], timer });
+}
+
+function flushJsonlBatch(filePath: string): void {
+	const pending = pendingJsonlBatches.get(filePath);
+	if (!pending) return;
+	pendingJsonlBatches.delete(filePath);
+	clearTimeout(pending.timer);
+	try {
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		fs.appendFileSync(filePath, pending.lines.join(""), "utf-8");
+	} catch (error) {
+		logInternalError("sidechain-output.flush", error as Error, `path=${filePath}`);
+	}
+}
+
 export function writeSidechainEntry(filePath: string, entry: Omit<SidechainEntry, "isSidechain" | "timestamp">): void {
-	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	fs.appendFileSync(
-		filePath,
-		`${JSON.stringify(redactSecrets({ isSidechain: true, timestamp: new Date().toISOString(), ...entry }))}\n`,
-		"utf-8",
-	);
+	queueJsonlLine(filePath, `${JSON.stringify(redactSecrets({ isSidechain: true, timestamp: new Date().toISOString(), ...entry }))}\n`);
 }
 
+/**
+ * Append one pre-serialized JSONL line through the shared batched writer.
+ * Task 26: the live-session transcript append routes through the same
+ * per-path 50ms batching as sidechain output. child-pi-transcript's batched
+ * writer was NOT reused — it takes a ChildPiRunInput and enforces
+ * artifactsRoot containment + a second redaction pass (redactJsonLine over
+ * the already-redacted line), so it is not generic over plain paths.
+ */
+export function appendBatchedJsonlLine(filePath: string, line: string): void {
+	queueJsonlLine(filePath, line);
+}
+
+/** @internal — flush on session teardown / process exit so files are complete. */
+export function flushPendingSidechainWrites(): void {
+	for (const filePath of [...pendingJsonlBatches.keys()]) flushJsonlBatch(filePath);
+}
+
+// The batch timers are unref'd, so a naturally-draining event loop can exit
+// with unflushed telemetry. Same exit-hook pattern as atomic-write.ts and
+// crew-agent-records.ts (sync-only work, safe inside "exit").
+process.on("exit", () => flushPendingSidechainWrites());
+
 export function sidechainOutputPath(stateRoot: string, taskId: string): string {
 	if (!isSafePathId(taskId)) throw new Error(`Invalid taskId: ${taskId}`);
 	return path.join(stateRoot, "agents", taskId, "sidechain.output.jsonl");

package/src/runtime/process/proc-stat.ts

@@ -0,0 +1,46 @@
+/**
+ * proc-stat.ts — THE single `/proc/<pid>/stat` field parser.
+ *
+ * Three consumers previously hand-rolled the same paren-aware split (the
+ * surface spawn's parent starttime capture, the worker-side parent-guard, and
+ * the zombie scanner's ppid/starttime read). A divergence between them is not
+ * cosmetic: the spawn writes `PI_CREW_PARENT_START_TIME` from field 22, and
+ * the worker kills itself when that value stops matching — so both sides MUST
+ * index identically. comm (field 2) may contain spaces AND ')' characters,
+ * hence everything up to the LAST ")" is skipped, never a naive whitespace
+ * split.
+ *
+ * Layout after the comm field: rest[0] = state, rest[1] = ppid, …
+ * rest[STARTTIME_INDEX] = starttime (field 22, clock ticks since boot).
+ */
+
+/** Field 22 (starttime) minus the two consumed by the comm cut = index 19. */
+export const PROC_STAT_STARTTIME_INDEX = 19;
+/** Field 3 (state) → first entry after the comm cut. */
+export const PROC_STAT_STATE_INDEX = 0;
+/** Field 4 (ppid) → second entry after the comm cut. */
+export const PROC_STAT_PPID_INDEX = 1;
+
+/**
+ * Fields of a `/proc/<pid>/stat` line AFTER the comm column (paren-aware).
+ * Returns undefined when the buffer has no closing paren at all.
+ */
+export function fieldsAfterComm(stat: string): string[] | undefined {
+	const lastParen = stat.lastIndexOf(")");
+	if (lastParen === -1) return undefined;
+	return stat
+		.slice(lastParen + 1)
+		.trim()
+		.split(/\s+/);
+}
+
+/**
+ * Raw starttime ticks (field 22) as a string, for byte-exact comparison with
+ * the value the spawner recorded. undefined when absent/unparseable.
+ */
+export function procStartTimeTicks(stat: string): string | undefined {
+	const fields = fieldsAfterComm(stat);
+	if (!fields) return undefined;
+	const raw = fields[PROC_STAT_STARTTIME_INDEX];
+	return raw && Number.isFinite(Number(raw)) ? raw : undefined;
+}

package/src/runtime/process/zombie-scanner.ts

@@ -23,6 +23,7 @@
  */
 
 import * as fs from "node:fs";
+import { fieldsAfterComm, PROC_STAT_PPID_INDEX, PROC_STAT_STARTTIME_INDEX } from "./proc-stat.ts";
 
 export interface ZombieSubagent {
 	pid: number;
@@ -32,6 +33,15 @@ export interface ZombieSubagent {
 	/** Whether the recorded crew parent PID is still alive. */
 	parentAlive: boolean;
 	role: string | undefined;
+	/**
+	 * Mux kind from PI_CREW_SURFACE ("tmux"|"herdr") when the worker booted in
+	 * a surface pane (T12). Surface workers have NO heartbeat (T9 handoff) —
+	 * env markers are the only identity signal, so the scanner never gates a
+	 * surface entry on liveness telemetry.
+	 */
+	surface?: "tmux" | "herdr";
+	/** Pane id from PI_CREW_SURFACE_PANE — doctor closes orphan panes by it. */
+	surfacePaneId?: string;
 	rssKb: number;
 	elapsedSec: number | undefined;
 	cmd: string;
@@ -66,17 +76,12 @@ function readProcStat(pid: number): { ppid: number; elapsedSec: number | undefin
 	try {
 		const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
 		// stat format: pid (comm) state ppid ... starttime ...
-		// comm may contain spaces/parens, so parse from the LAST ')' backwards.
-		const closeParen = stat.lastIndexOf(")");
-		if (closeParen < 0) return undefined;
-		const rest = stat
-			.slice(closeParen + 2)
-			.trim()
-			.split(/\s+/);
-		// rest[0] = state, rest[1] = ppid
-		const ppid = Number.parseInt(rest[1] ?? "", 10);
-		// starttime (clock ticks since boot) is field 22 in the full stat → index 19 in `rest`
-		const starttimeTicksRaw = Number.parseInt(rest[19] ?? "", 10);
+		// Shared paren-aware cut (proc-stat.ts) — MUST index identically with
+		// surface-spawn's PI_CREW_PARENT_START_TIME capture.
+		const rest = fieldsAfterComm(stat);
+		if (!rest) return undefined;
+		const ppid = Number.parseInt(rest[PROC_STAT_PPID_INDEX] ?? "", 10);
+		const starttimeTicksRaw = Number.parseInt(rest[PROC_STAT_STARTTIME_INDEX] ?? "", 10);
 		const starttimeTicks = Number.isFinite(starttimeTicksRaw) ? starttimeTicksRaw : undefined;
 		const elapsedSec = computeElapsedSec(starttimeTicks);
 		return { ppid: Number.isFinite(ppid) ? ppid : 0, elapsedSec };
@@ -184,12 +189,17 @@ export function scanZombieSubagents(): ZombieScanResult {
 
 			const crewParentPid = Number.parseInt(environ.PI_CREW_PARENT_PID ?? "", 10);
 			const stat = readProcStat(pid);
+			// Surface identity (T12): strict allowlist — an unrelated PI_CREW_SURFACE
+			// value must not half-populate the fields doctor relies on for pane close.
+			const surface = environ.PI_CREW_SURFACE === "tmux" || environ.PI_CREW_SURFACE === "herdr" ? environ.PI_CREW_SURFACE : undefined;
 			const entry: ZombieSubagent = {
 				pid,
 				ppid: stat?.ppid ?? 0,
 				crewParentPid: Number.isFinite(crewParentPid) ? crewParentPid : 0,
 				parentAlive: Number.isFinite(crewParentPid) && isPidAlive(crewParentPid),
 				role: environ.PI_CREW_ROLE,
+				surface,
+				surfacePaneId: environ.PI_CREW_SURFACE_PANE || undefined,
 				rssKb: readProcRssKb(pid),
 				elapsedSec: stat?.elapsedSec,
 				cmd: readProcCmdline(pid),
@@ -256,11 +266,9 @@ export function formatZombieReport(scan: ZombieScanResult): string {
 		lines.push(`### Zombies — parent dead (${scan.zombies.length})`);
 		lines.push("These sub-agents are orphaned. Safe to kill after review:");
 		lines.push("");
-		lines.push("  PID       PARENT  RSS       ROLE          CMD");
+		lines.push("  PID       PARENT  RSS       ROLE          SURFACE          CMD");
 		for (const z of scan.zombies) {
-			lines.push(
-				`  ${String(z.pid).padEnd(9)}${String(z.crewParentPid).padEnd(8)}${formatRss(z.rssKb).padEnd(10)}${(z.role ?? "?").padEnd(14)}${z.cmd.slice(0, 60)}`,
-			);
+			lines.push(formatZombieRow(z));
 		}
 		lines.push("");
 	}
@@ -269,11 +277,9 @@ export function formatZombieReport(scan: ZombieScanResult): string {
 		lines.push(`### Live — parent still running (${scan.live.length})`);
 		lines.push("NOT zombies. Do not kill (parent PID is alive and may still reap them).");
 		lines.push("");
-		lines.push("  PID       PARENT  RSS       ROLE          CMD");
+		lines.push("  PID       PARENT  RSS       ROLE          SURFACE          CMD");
 		for (const l of scan.live) {
-			lines.push(
-				`  ${String(l.pid).padEnd(9)}${String(l.crewParentPid).padEnd(8)}${formatRss(l.rssKb).padEnd(10)}${(l.role ?? "?").padEnd(14)}${l.cmd.slice(0, 60)}`,
-			);
+			lines.push(formatZombieRow(l));
 		}
 		lines.push("");
 	}
@@ -288,6 +294,13 @@ export function formatZombieReport(scan: ZombieScanResult): string {
 	return lines.join("\n");
 }
 
+/** One table row — shared by the zombie + live sections so columns stay aligned. */
+function formatZombieRow(z: ZombieSubagent): string {
+	// SURFACE = "kind:paneId" (T12) — the pane doctor closes when orphaned.
+	const surface = z.surface ? `${z.surface}:${z.surfacePaneId ?? "?"}` : "-";
+	return `  ${String(z.pid).padEnd(9)}${String(z.crewParentPid).padEnd(8)}${formatRss(z.rssKb).padEnd(10)}${(z.role ?? "?").padEnd(14)}${surface.padEnd(16)}${z.cmd.slice(0, 44)}`;
+}
+
 function formatRss(kb: number): string {
 	if (kb >= 1024 * 1024) return `${(kb / 1024 / 1024).toFixed(1)}G`;
 	if (kb >= 1024) return `${(kb / 1024).toFixed(0)}M`;

package/src/runtime/spawn-policy.ts

@@ -8,26 +8,26 @@
  *
  * Gate dimensions (each with a distinct machine-readable reason + fail-fast
  * message; evaluated in this order — cheapest/most-global first):
- *   1. nesting-disabled   — `nesting.enabled` is false (DEFAULT; fail-closed)
- *   2. role-denied        — the PARENT task's role is not executor-class
- *                           (read-only roles cannot raise spawn privileges),
- *                           or the requested grandchild role is not one of
- *                           the delegate-tool's allowed roles
- *   3. trust-denied       — untrusted escalation context (manual-only trust
+ *   1. trust-denied       — untrusted escalation context (manual-only trust
  *                           gate; the handler resolves trust, policy enforces)
- *   4. depth-exceeded     — child depth (parent.depth + 1) exceeds the
- *                           resolved maxDepth (default 2). Depth comes from
+ *   2. role-denied        — the REQUESTED grandchild role is not one of the
+ *                           delegate-tool's allowed roles (the parent role is
+ *                           NO LONGER gated — D8: every role may delegate;
+ *                           the spawn-side checkCrewDepth cap is the boundary)
+ *   3. depth-exceeded     — child depth (parent.depth + 1) exceeds the
+ *                           resolved maxDepth (default 4). Depth comes from
  *                           the parent task RECORD, never worker env
  *                           (design §7 rev-2 P0-2)
- *   5. slots-exhausted    — nested-slot budget exhausted ("N/M in flight");
+ *   4. slots-exhausted    — nested-slot budget exhausted ("N/M in flight");
  *                           fail-fast, never queue
- *   6. budget-insufficient— requested budgetTokens exceed the parent task's
+ *   5. budget-insufficient— requested budgetTokens exceed the parent task's
  *                           remaining allocation (tokensGranted - tokensSpent)
- *   7. model-invalid      — requested model is not in the resolved model
+ *   6. model-invalid      — requested model is not in the resolved model
  *                           catalog (the unvalidated provider/model
  *                           pass-through — model-fallback.ts:282, the
  *                           429-cascade root — must not be reachable here)
- *   8. timeout-invalid    — timeoutSec outside 1..MAX (default 900)
+ *   7. timeout-invalid    — timeoutSec outside 1..MAX (default 900)
+ *   8. workspace-conflict — write-capable grandchild narrowing cwd overlap
  */
 
 import { modelRefToString } from "./model/model-fallback.ts";
@@ -48,7 +48,6 @@ export const DEFAULT_DELEGATE_TIMEOUT_SEC = 900;
 export const MAX_DELEGATE_TIMEOUT_SEC = 86_400;
 
 export type SpawnPolicyDenyReason =
-	| "nesting-disabled"
 	| "role-denied"
 	| "trust-denied"
 	| "depth-exceeded"
@@ -59,14 +58,14 @@ export type SpawnPolicyDenyReason =
 	| "workspace-conflict";
 
 export interface DelegateAdmissionInput {
-	/** Resolved `nesting.enabled` config (DEFAULT false — fail-closed, ADR-5 §10). */
-	nestingEnabled: boolean;
-	/** Resolved max depth (nesting.maxDepth default 2; env clamp mirrors PI_CREW_MAX_DEPTH 1..10). */
+	/** Resolved max depth (nesting.maxDepth default 4; env clamp mirrors PI_CREW_MAX_DEPTH 1..10). */
 	maxDepth: number;
 	/** Parent task record fields the policy is allowed to trust. */
 	parentTask: {
 		taskId: string;
-		role: string;
+		/** Role for workspace-capability evaluation (policy no longer gates the
+		 *  parent role — D8 opens delegation to every role). */
+		role?: string;
 		/** Absent on pre-v2 records — treated as depth 1 (a worker). */
 		depth?: number;
 		allocation?: { tokensGranted?: number; tokensSpent?: number };
@@ -122,26 +121,13 @@ function deny(reason: SpawnPolicyDenyReason, message: string): SpawnPolicyDecisi
 }
 
 export function evaluateDelegateAdmission(input: DelegateAdmissionInput): SpawnPolicyDecision {
-	const { nestingEnabled, maxDepth, parentTask, requested } = input;
+	const { maxDepth, parentTask, requested } = input;
 	const parentDepth = parentTask.depth ?? 1; // pre-v2 records: workers are depth 1
 	const childDepth = parentDepth + 1;
 
-	// 1. Flag gate — fail-closed default (ADR-5 §10).
-	if (!nestingEnabled) {
-		return deny(
-			"nesting-disabled",
-			"delegate rejected: governed nesting is disabled (nesting.enabled=false, the fail-closed default; enable it in USER config)",
-		);
-	}
-
-	// 2. Role gate — parent must be executor-class; requested role must be in
-	// the tool's allowed set.
-	if (!isExecutorClassRole(parentTask.role)) {
-		return deny(
-			"role-denied",
-			`delegate rejected: role '${parentTask.role}' is not executor-class (${EXECUTOR_CLASS_ROLES.join("/")}) — read-only roles cannot delegate`,
-		);
-	}
+	// 1. Role gate — the REQUESTED grandchild role must be in the tool's allowed
+	// set (the PARENT role is no longer gated — D8: every role may delegate;
+	// the spawn-side checkCrewDepth cap + slot budget below are the boundary).
 	const requestedRole = requested?.role;
 	if (requestedRole !== undefined && !(DELEGATE_ALLOWED_ROLES as readonly string[]).includes(requestedRole)) {
 		return deny(
@@ -150,12 +136,12 @@ export function evaluateDelegateAdmission(input: DelegateAdmissionInput): SpawnP
 		);
 	}
 
-	// 3. Trust gate — untrusted escalation context never spawns.
+	// 2. Trust gate — untrusted escalation context never spawns.
 	if (input.untrusted) {
 		return deny("trust-denied", "delegate rejected: untrusted escalation context (trust gate is manual-only)");
 	}
 
-	// 4. Depth gate — computed from the parent RECORD (never worker env).
+	// 3. Depth gate — computed from the parent RECORD (never worker env).
 	if (childDepth > maxDepth) {
 		return deny(
 			"depth-exceeded",
@@ -163,7 +149,7 @@ export function evaluateDelegateAdmission(input: DelegateAdmissionInput): SpawnP
 		);
 	}
 
-	// 5. Nested-slot budget — fail-fast, never queue.
+	// 4. Nested-slot budget — fail-fast, never queue.
 	if (input.slots.used >= input.slots.max) {
 		return deny(
 			"slots-exhausted",
@@ -171,7 +157,7 @@ export function evaluateDelegateAdmission(input: DelegateAdmissionInput): SpawnP
 		);
 	}
 
-	// 6. Parent allocation sufficiency — reserve up-front or reject.
+	// 5. Parent allocation sufficiency — reserve up-front or reject.
 	if (requested?.budgetTokens !== undefined) {
 		const granted = parentTask.allocation?.tokensGranted ?? 0;
 		const spent = parentTask.allocation?.tokensSpent ?? 0;
@@ -184,7 +170,7 @@ export function evaluateDelegateAdmission(input: DelegateAdmissionInput): SpawnP
 		}
 	}
 
-	// 7. Model validation against the resolved catalog.
+	// 6. Model validation against the resolved catalog.
 	const normalizedModel = requested?.model !== undefined ? modelRefToString(requested.model) : undefined;
 	if (normalizedModel !== undefined && input.modelCatalog !== undefined) {
 		if (!input.modelCatalog.includes(normalizedModel)) {
@@ -192,7 +178,7 @@ export function evaluateDelegateAdmission(input: DelegateAdmissionInput): SpawnP
 		}
 	}
 
-	// 8. Timeout validation (mandatory default 900).
+	// 7. Timeout validation (mandatory default 900).
 	const timeoutSec = requested?.timeoutSec ?? DEFAULT_DELEGATE_TIMEOUT_SEC;
 	if (!Number.isFinite(timeoutSec) || timeoutSec < 1 || timeoutSec > MAX_DELEGATE_TIMEOUT_SEC) {
 		return deny(
@@ -201,7 +187,7 @@ export function evaluateDelegateAdmission(input: DelegateAdmissionInput): SpawnP
 		);
 	}
 
-	// 9. Workspace interaction (ADR-5 §9): a write-capable grandchild sharing
+	// 8. Workspace interaction (ADR-5 §9): a write-capable grandchild sharing
 	// the parent's cwd with ANOTHER in-flight executor is only admitted when
 	// serialization is established (limits.serializeOnPathOverlap) — otherwise
 	// reject; read-only grandchild roles (explorer/analyst) never conflict.