pi-crew 0.9.64 → 0.9.65

package/src/runtime/README.md

@@ -7,7 +7,7 @@ clusters are extracted into subdirectories; the remaining files stay at the root
 
 | Subdir | Phase | Cluster | Key files |
 |--------|-------|---------|-----------|
-| [`child-pi/`](./child-pi/) | B-1 | child Pi worker spawn/lifecycle/steering/transcript | `child-pi.ts`, `child-pi-spawn.ts`, `child-pi-kill.ts`, `child-pi-constants.ts`, `child-pi-steering.ts`, `child-pi-streams.ts`, `child-pi-transcript.ts`, `child-pi-pool.ts` |
+| [`child-pi/`](./child-pi/) | B-1 | child Pi worker spawn/lifecycle/steering/transcript | `child-pi.ts`, `child-pi-spawn.ts`, `child-pi-kill.ts`, `child-pi-constants.ts`, `child-pi-steering.ts`, `child-pi-streams.ts`, `child-pi-transcript.ts` |
 | [`broker/`](./broker/) | B-2 | crew broker server/client/auth (child-pi ↔ parent IPC) | `crew-broker.ts`, `crew-broker-client.ts`, `crew-broker-child.ts`, `crew-broker-tokens.ts`, `broker-issuer.ts` |
 | [`task-runner/`](./task-runner/) | (pre-existing) | per-task execution (pre-execution, child-executor) | `child-executor.ts`, `pre-execution.ts`, ... |
 | [`live-session/`](./live-session/) | 3 | live agent control/manager, session runtime, IRC, health, extension bridge | `live-session-runtime.ts`, `live-agent-manager.ts`, `live-agent-control.ts`, `live-control-realtime.ts`, `live-irc.ts`, `live-session-health.ts`, `live-extension-bridge.ts`, `intercom-bridge.ts` |

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

@@ -357,22 +357,6 @@ export class CrewBroker {
 		this.resolvedSocketPath = null;
 	}
 
-	/**
-	 * Non-throwing enqueue entry point for the post-append mailbox observer
-	 * (Phase 1) or any other in-process producer. Phase 0 accepts `notifyMessage`
-	 * as a no-op shape so the lifecycle controller can install a single
-	 * observer regardless of broker state.
-	 *
-	 * Fanout goes ONLY to authenticated connections matching the recipient.
-	 * Phase 0 keeps this as a typed no-op (`not-implemented` would be
-	 * inappropriate here — the caller is in-process and shouldn't be
-	 * punished for testing the broker skeleton).
-	 */
-	notifyMessage(_message: unknown): void {
-		// Phase 0: no fanout. Phase 1 replaces this with the single
-		// post-durable mailbox observer fanout.
-	}
-
 	// ------------------------------------------------------------------------
 	// Connection lifecycle
 	// ------------------------------------------------------------------------

package/src/runtime/effectiveness.ts

@@ -26,6 +26,24 @@ export function taskHasObservableWorkerActivity(task: TeamTaskState): boolean {
 	);
 }
 
+/**
+ * True when the task completed but its result artifact is an EMPTY file
+ * (0 bytes). Closes the F4 monitoring gap (real-test-2026-08-10 finding):
+ * a child worker absorbed by a rate-limit (429) or a model-not-found
+ * failure still emits transcript/usage events, so
+ * {@link taskHasObservableWorkerActivity} reports "activity" — but the
+ * actual result content is empty. A completed task with an empty result
+ * has done no real work and must not count toward run effectiveness.
+ *
+ * Deliberately only flags `sizeBytes === 0` (a written-but-empty file).
+ * A missing resultArtifact stays non-flagging (some tasks legitimately
+ * produce no result file), and an undefined sizeBytes stays non-flagging
+ * (legacy tasks — do not false-positive on absent metadata).
+ */
+export function taskHasEmptyResult(task: TeamTaskState): boolean {
+	return Boolean(task.resultArtifact && task.resultArtifact.sizeBytes === 0);
+}
+
 export function resolveEffectivenessGuardMode(
 	runtimeConfig: CrewRuntimeConfig | undefined,
 	manifest?: TeamRunManifest,
@@ -43,7 +61,11 @@ export function evaluateRunEffectiveness(input: {
 	runtimeConfig?: CrewRuntimeConfig;
 }): RunEffectivenessSummary {
 	const completedTasks = input.tasks.filter((task) => task.status === "completed");
-	const noObservedWorkTasks = completedTasks.filter((task) => !taskHasObservableWorkerActivity(task));
+	// F4: a completed task with an EMPTY result artifact (0 bytes) is
+	// treated exactly like no-observed-work — the worker may have spun up
+	// and streamed transcript events, but it produced no real output
+	// (e.g. a 429 rate-limit absorbed by the fallback chain).
+	const noObservedWorkTasks = completedTasks.filter((task) => !taskHasObservableWorkerActivity(task) || taskHasEmptyResult(task));
 	const needsAttentionTasks = input.tasks.filter((task) => task.agentProgress?.activityState === "needs_attention");
 	const workerExecution: WorkerExecutionState = input.executeWorkers ? "enabled" : "disabled/scaffold";
 	const guardMode = resolveEffectivenessGuardMode(input.runtimeConfig, input.manifest);

package/src/runtime/merge-gate.ts

@@ -0,0 +1,202 @@
+/**
+ * Monotonic merge gate for parallel task updates.
+ *
+ * Extracted from team-runner.ts (2026-08-10, improvement-plan Tier 2
+ * "team-runner split" — self-contained portion). The merge gate protects
+ * terminal task states from being regressed by stale parallel worker
+ * snapshots: every terminal->non-terminal transition is rejected, plus a
+ * small set of bespoke policies (P2 completed integrity, P3
+ * waiting->running stale-snapshot regression) that are stricter than the
+ * lifecycle table on the parallel-merge path.
+ *
+ * Exhaustively tested in test/unit/team-runner-should-merge-table.test.ts.
+ */
+import { TEAM_TASK_STATUSES, TEAM_TERMINAL_TASK_STATUSES, type TeamTaskStatus } from "../state/contracts.ts";
+import type { TeamTaskState } from "../state/types.ts";
+import { refreshTaskGraphQueues } from "./scheduling/task-graph-scheduler.ts";
+
+export function isNonTerminalTaskStatus(status: TeamTaskState["status"]): boolean {
+	return status === "queued" || status === "running" || status === "waiting";
+}
+
+export function safeFinishedAt(task: TeamTaskState): number {
+	if (!task.finishedAt) return -Infinity;
+	const ms = new Date(task.finishedAt).getTime();
+	return Number.isNaN(ms) ? Infinity : ms;
+}
+
+/**
+ * Returns true when the current task has a malformed finishedAt (NaN/Infinity)
+ * and the updated task has a valid finite finishedAt. Malformed finishedAt
+ * should be replaced rather than persisting corruption.
+ */
+export function isMalformedFinishedAtReplacement(currentTime: number, updatedTime: number): boolean {
+	return !Number.isFinite(currentTime) && Number.isFinite(updatedTime);
+}
+
+/**
+ * RT-16: status-level gate for shouldMergeTaskUpdate. Returns the stable
+ * "from->to" key used by REJECTED_STATUS_MERGE_TRANSITIONS.
+ */
+export function statusMergeKey(from: TeamTaskStatus, to: TeamTaskStatus): string {
+	return `${from}->${to}`;
+}
+
+/**
+ * RT-16 — derived merge-gate transition table.
+ *
+ * The set of old->new status pairs that shouldMergeTaskUpdate must REJECT based
+ * solely on the status transition (before any field-level comparison). It
+ * replaces the former 13 hand-written status guards that hand-duplicated the
+ * lifecycle table. Built once from the single source-of-truth table
+ * (TEAM_TASK_STATUSES + TEAM_TERMINAL_TASK_STATUSES — the terminal half of
+ * TEAM_TASK_STATUS_TRANSITIONS) plus two merge-specific policies that are
+ * STRICTER than the lifecycle table on the parallel-merge path:
+ *
+ *  P1 Terminal preservation — every terminal->non-terminal pair is rejected.
+ *    The lifecycle table permits retries (e.g. completed->queued), but a stale
+ *    worker snapshot must never resurrect a settled task.
+ *  P2 Completed integrity — five terminal->terminal flips that touch the
+ *    "completed" success terminal are rejected: completed->failed,
+ *    completed->needs_attention, failed->completed, cancelled->completed,
+ *    needs_attention->completed. (completed may still move to
+ *    cancelled/skipped; that is intentionally allowed, so these are NOT simply
+ *    "every illegal terminal->terminal flip".)
+ *  P3 waiting->running regression — the single stale-snapshot case.
+ *
+ * The decision for every old->new pair is byte-for-byte identical to the former
+ * 7 status guards (verified exhaustively in
+ * test/unit/team-runner-should-merge-table.test.ts).
+ */
+export const REJECTED_STATUS_MERGE_TRANSITIONS: ReadonlySet<string> = (() => {
+	const rejected = new Set<string>();
+	// P1 — terminal preservation: reject every terminal->non-terminal pair.
+	for (const from of TEAM_TASK_STATUSES) {
+		if (!TEAM_TERMINAL_TASK_STATUSES.has(from)) continue;
+		for (const to of TEAM_TASK_STATUSES) {
+			if (!TEAM_TERMINAL_TASK_STATUSES.has(to)) rejected.add(statusMergeKey(from, to));
+		}
+	}
+	// P3 — waiting->running stale-snapshot regression.
+	rejected.add(statusMergeKey("waiting", "running"));
+	// P2 — completed integrity flips (bespoke terminal->terminal policy).
+	const completedIntegrityFlips: ReadonlyArray<[TeamTaskStatus, TeamTaskStatus]> = [
+		["completed", "failed"],
+		["completed", "needs_attention"],
+		["failed", "completed"],
+		["cancelled", "completed"],
+		["needs_attention", "completed"],
+	];
+	for (const [from, to] of completedIntegrityFlips) rejected.add(statusMergeKey(from, to));
+	return rejected;
+})();
+
+export function shouldMergeTaskUpdate(current: TeamTaskState, updated: TeamTaskState): boolean {
+	// RT-16: status-level gate — reject stale/dangerous transitions via the
+	// derived transition table (REJECTED_STATUS_MERGE_TRANSITIONS) instead of
+	// hand-written guards. Parallel workers receive the same input snapshot; a
+	// later result may still carry stale copies. The table encodes three
+	// merge-specific policies stricter than the lifecycle table: terminal
+	// preservation (no terminal->non-terminal resurrection), completed integrity
+	// (no flipping the "completed" success terminal to/from failed or
+	// needs_attention), and the waiting->running stale-snapshot regression.
+	if (REJECTED_STATUS_MERGE_TRANSITIONS.has(statusMergeKey(current.status, updated.status))) return false;
+	// Guard: when current is "running" but has resultArtifact (another worker already
+	// completed it), a stale updated with status="running" and no resultArtifact
+	// must not overwrite the actual completed state.
+	if (current.status === updated.status && updated.status === "running" && current.resultArtifact && !updated.resultArtifact)
+		return false;
+	// Guard: when current is "completed" and has resultArtifact but updated is also
+	// "completed" without resultArtifact, block the stale update from overwriting
+	// a task that successfully produced output.
+	if (current.status === updated.status && current.status === "completed" && current.resultArtifact && !updated.resultArtifact)
+		return false;
+	// Prevent a stale completed task from overwriting a fresher one.
+	// Restructure to handle undefined current.finishedAt as a special case:
+	// - undefined current + valid updated: allow the update
+	// - valid current + undefined updated: block the update (don't lose completion time)
+	// - both undefined: finishedAt guard does not apply, fall through to heartbeat check
+	// - both valid: compare timestamps as before
+	if (current.finishedAt !== undefined && updated.finishedAt !== undefined) {
+		const currentTime = safeFinishedAt(current);
+		const updatedTime = safeFinishedAt(updated);
+		// Malformed finishedAt (NaN) is treated as Infinity — invalid state should be
+		// replaced rather than persisting corruption. Log warning for visibility.
+		if (!Number.isFinite(currentTime)) {
+			console.warn(`[merge-gate] Task ${current.id} has malformed finishedAt: ${current.finishedAt}`);
+		}
+		if (isMalformedFinishedAtReplacement(currentTime, updatedTime)) {
+			return true;
+		}
+		if (updatedTime < currentTime) return false;
+	}
+	// Block if updated is trying to establish a terminal status without a finishedAt
+	// timestamp. Heartbeat-only updates (status='running', no finishedAt) are
+	// allowed if heartbeat has changed (checked separately in hasMeaningfulUpdate).
+	if (!updated.finishedAt && !isNonTerminalTaskStatus(updated.status)) return false;
+	// Explicitly enumerate all fields that constitute a meaningful update so that
+	// adding a new important field requires updating this list (rather than silently
+	// losing data if a field is forgotten in the boolean OR chain below).
+	const hasMeaningfulUpdate =
+		updated.status !== current.status ||
+		updated.finishedAt !== current.finishedAt ||
+		updated.startedAt !== current.startedAt ||
+		Boolean(updated.resultArtifact) !== Boolean(current.resultArtifact) ||
+		(Boolean(updated.resultArtifact) && updated.resultArtifact !== current.resultArtifact) ||
+		Boolean(updated.error) ||
+		Boolean(updated.modelAttempts?.length) ||
+		Boolean(updated.usage) ||
+		Boolean(updated.attempts?.length) ||
+		updated.heartbeat?.lastSeenAt !== current.heartbeat?.lastSeenAt ||
+		updated.jsonEvents !== current.jsonEvents ||
+		updated.agentProgress?.lastActivityAt !== current.agentProgress?.lastActivityAt;
+	return hasMeaningfulUpdate;
+}
+/** Exposed for the exhaustive status-merge table test (RT-16). */
+export const __test__shouldMergeTaskUpdate = shouldMergeTaskUpdate;
+
+// H4 fix: rename to descriptive name. Kept __test__ as alias for backward
+// compat test imports.
+// FIX (perf P10): replace O(N×M) .find() + .map() inside nested loops with a
+// single-pass Map-based merge. Build an index of `merged` once, then for each
+// incoming updated task do O(1) lookup; the final pass reassembles `merged`
+// preserving original order. For a 20-task run × 5-batch merger with
+// ~10 updates per result, this reduces from O(50×20) = 1000 ops to O(120).
+// Behavior is unchanged: skipped updates (shouldMergeTaskUpdate=false) still
+// leave the existing task in place.
+export function mergeTaskUpdatesPreservingTerminal(base: TeamTaskState[], results: Array<{ tasks: TeamTaskState[] }>): TeamTaskState[] {
+	// Index current merged state by id for O(1) lookup during the merge pass.
+	const indexById = new Map<string, TeamTaskState>();
+	for (const task of base) indexById.set(task.id, task);
+
+	let skipped = 0;
+	for (const result of results) {
+		for (const updated of result.tasks) {
+			const current = indexById.get(updated.id);
+			if (!current) continue;
+			if (!shouldMergeTaskUpdate(current, updated)) {
+				// Log skipped merges for visibility into rejected parallel updates.
+				// In distributed systems with parallel workers, rejected merges may
+				// indicate bugs (wrong status, timestamp corruption) if they accumulate.
+				console.debug("[merge-gate] Skipping stale merge for task", updated.id, {
+					currentStatus: current.status,
+					updatedStatus: updated.status,
+					currentFinishedAt: current.finishedAt,
+					updatedFinishedAt: updated.finishedAt,
+				});
+				skipped += 1;
+				continue;
+			}
+			indexById.set(updated.id, updated);
+		}
+	}
+	// Reassemble in original `base` order so downstream snapshots stay stable.
+	const merged = base.map((task) => indexById.get(task.id) ?? task);
+	// `skipped` is intentional visibility — currently no caller reads it but
+	// we'd rather leave the count available for future instrumentation than
+	// remove the cumulative silent-rejection signal it provides.
+	void skipped;
+	return refreshTaskGraphQueues(merged);
+}
+/** @deprecated Use mergeTaskUpdatesPreservingTerminal. Kept for backward test import compat. */
+export const __test__mergeTaskUpdates = mergeTaskUpdatesPreservingTerminal;

package/src/runtime/model/model-fallback.ts

@@ -365,6 +365,17 @@ const RETRYABLE_MODEL_FAILURE_PATTERNS = [
 	/safety/i,
 	/is[_ ]?overloaded/i,
 	/\b408\b/,
+	//
+	// EPIPE / broken-pipe. In the child-pi worker path this typically means
+	// the child `pi` process exited (crash or early exit) while the parent
+	// was still writing to its stdin — spawning a fresh child on the next
+	// model in the fallback chain usually recovers. In the network path it
+	// is a transient pipe close. Both are retryable on a different model.
+	// See docs/failure-mode-inventory.md EPIPE gap; NON_RETRYABLE patterns
+	// (auth/billing) are checked first, so an auth error mentioning EPIPE
+	// stays non-retryable.
+	/epipe/i,
+	/broken pipe/i,
 ];
 
 // These patterns indicate auth/key/billing issues that will never succeed on retry.

package/src/runtime/model/provider-extensions.ts

@@ -22,7 +22,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { userPiRoot } from "../../utils/paths.ts";
+import { packageRoot, userPiRoot } from "../../utils/paths.ts";
 
 export interface DiscoveredProviderExtension {
 	/** Package specifier as written in settings.json packages (e.g. "npm:pi-commandcode-provider"). */
@@ -95,12 +95,17 @@ function resolvePackageEntry(pkgDir: string): string | undefined {
 
 /**
  * Discover provider extension entry points from Pi's installed package registry.
- * Reads `~/.pi/agent/settings.json` → `packages` (npm: specs only — local
- * relative paths are the pi-crew extension itself and other local work, which
- * children already handle) and resolves each against `~/.pi/agent/npm/node_modules/`.
+ * Reads `~/.pi/agent/settings.json` → `packages` and resolves each spec:
+ *   - `npm:<name>`      → `~/.pi/agent/npm/node_modules/<name>/`
+ *   - local path spec   → resolved relative to the settings.json dir (the way
+ *     `pi install <local-path>` records them), e.g. "../../src/foo"
+ *   - git:/file: specs   → skipped (not resolvable on disk)
  *
- * Non-npm specs (local paths, git URLs) are skipped: they are not part of the
- * npm registry dir and resolving them is outside this module's scope.
+ * Both npm: and local-path specs are SANCTIONED channels — the user wrote them
+ * into settings.json (directly or via `pi install`), so they are trusted at the
+ * same level. This is distinct from project-sourced AGENT extensions
+ * (`.crew/agents/*.md` `extensions:` frontmatter), which are repo-adjacent
+ * untrusted data and stay gated by SEC-1 in discover-agents.ts.
  */
 export function discoverProviderExtensions(settingsPath?: string): DiscoveredProviderExtension[] {
 	const root = userPiRoot();
@@ -125,13 +130,27 @@ export function discoverProviderExtensions(settingsPath?: string): DiscoveredPro
 	const npmBase = path.join(baseDir, "npm", "node_modules");
 	for (const spec of settings.packages ?? []) {
 		if (typeof spec !== "string") continue;
-		// Only npm: specs resolve into the npm registry dir. Skip local path
-		// packages (e.g. "../../source/my_pi/pi-crew") and git specs.
-		if (!spec.startsWith("npm:")) continue;
-		const pkgName = spec.slice(4);
-		// Scoped packages: "@scope/name" → "@scope/name"; plain: "name".
-		const pkgDir = path.join(npmBase, pkgName);
+		let pkgDir: string;
+		if (spec.startsWith("npm:")) {
+			// Scoped packages: "@scope/name" → "@scope/name"; plain: "name".
+			pkgDir = path.join(npmBase, spec.slice(4));
+		} else if (spec.startsWith("./") || spec.startsWith("../") || path.isAbsolute(spec)) {
+			// Local path spec — resolve relative to the settings.json dir, matching
+			// how `pi install <local-path>` records it. Same trust level as npm:
+			// (user wrote it into settings.json). Not to be confused with project
+			// AGENT extensions (.crew/agents/* frontmatter) — those stay SEC-1 gated.
+			pkgDir = path.resolve(baseDir, spec);
+		} else {
+			// git:/file:/http: specs etc. — not resolvable on disk, skip.
+			continue;
+		}
 		if (!fs.existsSync(pkgDir)) continue;
+		// Skip self: pi-crew's own package is a settings package (the orchestrator
+		// extension the parent loads), but a child WORKER must not re-load it — it
+		// would register the team tool / observability / MCP wiring intended for
+		// the orchestrator process, not a worker. Provider + adapter extensions
+		// (pi-other-provider, pi-mcp-adapter, pi-rlm, ...) stay.
+		if (path.resolve(pkgDir) === path.resolve(packageRoot())) continue;
 		const entryPath = resolvePackageEntry(pkgDir);
 		if (entryPath) out.push({ spec, entryPath });
 	}

package/src/runtime/output/progress-tracker.ts

@@ -1,5 +1,4 @@
 import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
-import { crewEventBus } from "../../observability/event-bus.ts";
 
 export interface AgentProgress {
 	toolCalls: number;
@@ -25,7 +24,7 @@ export class ProgressTracker {
 			subscribe: (listener: (event: AgentSessionEvent) => void) => () => void;
 		},
 		agentId: string,
-		runId: string,
+		_runId: string,
 	): AgentProgress {
 		if (this.sessions.has(agentId)) {
 			return this.sessions.get(agentId)!.progress;
@@ -42,26 +41,19 @@ export class ProgressTracker {
 		};
 
 		const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
-			this.handleEvent(event, progress, agentId, runId);
+			this.handleEvent(event, progress);
 		});
 
 		this.sessions.set(agentId, { unsubscribe, progress });
 		return progress;
 	}
 
-	private handleEvent(event: AgentSessionEvent, progress: AgentProgress, agentId: string, runId: string): void {
+	private handleEvent(event: AgentSessionEvent, progress: AgentProgress): void {
 		switch (event.type) {
 			case "tool_execution_start":
 				progress.toolCalls++;
 				progress.currentTool = event.toolName;
 				progress.toolStartTime = Date.now();
-				crewEventBus.emit({
-					type: "agent:progress",
-					runId,
-					agentId,
-					payload: { ...progress },
-					timestamp: Date.now(),
-				});
 				break;
 
 			case "tool_execution_end":
@@ -69,21 +61,7 @@ export class ProgressTracker {
 				progress.toolStartTime = null;
 				if (event.isError) {
 					progress.errors.push(String(event.result ?? "Unknown error"));
-					crewEventBus.emit({
-						type: "agent:error",
-						runId,
-						agentId,
-						payload: String(event.result ?? "Unknown error"),
-						timestamp: Date.now(),
-					});
 				}
-				crewEventBus.emit({
-					type: "agent:progress",
-					runId,
-					agentId,
-					payload: { ...progress },
-					timestamp: Date.now(),
-				});
 				break;
 
 			case "turn_start":
@@ -92,13 +70,6 @@ export class ProgressTracker {
 
 			case "agent_end":
 				progress.status = "completed";
-				crewEventBus.emit({
-					type: "agent:complete",
-					runId,
-					agentId,
-					payload: { ...progress },
-					timestamp: Date.now(),
-				});
 				break;
 
 			case "agent_start":
@@ -120,5 +91,4 @@ export class ProgressTracker {
 	}
 }
 
-// Export singleton instance
 export const globalProgressTracker = new ProgressTracker();

package/src/runtime/scratchpad/engine.ts

@@ -17,7 +17,7 @@
  *     grace, truncateWithMarker, the childClosed race guard — is ported 1:1.
  */
 
-import { type ChildProcess, spawn } from "node:child_process";
+import { type ChildProcess, spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { closeSync, constants as fsConstants, fstatSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
@@ -198,6 +198,15 @@ export class EngineManager {
 				...(this.options.env ?? {}),
 				[NONCE_ENV]: this.nonce,
 			},
+			// Run the guest as its own session leader so descendants
+			// (cell-spawned subprocesses) share its process group. teardown
+			// then uses `process.kill(-pid, ...)` (POSIX) or `taskkill /T`
+			// (Windows) to clean up the whole tree — closing the
+			// "cell-subprocess orphan on session_shutdown" gap declared in
+			// docs/failure-mode-inventory.md (D.4 narrowed).
+			// stdio pipes are still owned by the parent; `detached` only
+			// affects process-group / kill-on-parent-exit semantics.
+			detached: true,
 			// fd 3 carries protocol traffic so stdout/stderr stay pure user output.
 			stdio: ["pipe", "pipe", "pipe", "pipe"],
 		});
@@ -303,7 +312,36 @@ export class EngineManager {
 		this.engineState = "shutdown";
 		liveEngines.delete(this);
 		this.failAllPending(new Error("Engine has been shut down"));
-		this.child?.kill("SIGKILL");
+		// Kill the whole process group / job tree so cell-spawned
+		// subprocesses (grandchildren of the host) do not orphan when the
+		// session shuts down. Best-effort: fall back to a single-pid kill
+		// if the group/tree kill fails (already dead, EPERM, etc.).
+		const child = this.child;
+		const pid = child?.pid;
+		if (pid !== undefined && pid > 0) {
+			try {
+				if (process.platform === "win32") {
+					// taskkill /T /F kills the entire process tree rooted at pid.
+					spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore" });
+				} else {
+					// Negative pid = signal the entire process group.
+					// Requires the guest to be its own session leader (detached:true above).
+					process.kill(-pid, "SIGKILL");
+				}
+			} catch {
+				try {
+					child?.kill("SIGKILL");
+				} catch {
+					/* already gone — nothing to clean up */
+				}
+			}
+		} else if (child) {
+			try {
+				child.kill("SIGKILL");
+			} catch {
+				/* already gone */
+			}
+		}
 		this.child = undefined;
 		this.protocolReader?.close();
 		this.protocolReader = undefined;

package/src/runtime/scratchpad/snapshot-hmac.ts

@@ -0,0 +1,161 @@
+/**
+ * Snapshot HMAC helper — opt-in integrity for scratchpad snapshots.
+ *
+ * Closes the E.2 gap declared in docs/improvement-plan-2026-08-09.md and
+ * docs/runtime/scratchpad/README.md:120 ("v8.deserialize of restore content
+ * is unauthenticated (no HMAC)"). The threat model — a same-uid attacker
+ * plants a crafted V8 blob at the snapshot path to run deserialize gadgets
+ * in the guest — does not cross the existing same-uid boundary, but HMAC
+ * hardening is required before snapshots ever land in a shared/networked
+ * store.
+ *
+ * Migration window (see docs/decisions/2026-08-10-scratchpad-snapshot-hmac.md):
+ *
+ *   Phase 1 (this module): HMAC sign-on-write + verify-on-read are OPT-IN
+ *     via PI_CREW_SNAPSHOT_HMAC_KEY. When the key is unset, behaviour is
+ *     unchanged (snapshots remain unsigned). When the key is set, writes
+ *     attach a signature and reads verify it; an unsigned/failed snapshot
+ *     is ACCEPTED with a warning so existing snapshots remain readable.
+ *   Phase 2 (after one release): unsigned snapshots are REJECTED when the
+ *     key is set (configurable via PI_CREW_SNAPSHOT_HMAC_STRICT=1).
+ *   Phase 3 (after snapshots move to a shared store): the key becomes
+ *     required and unsigned snapshots are always rejected.
+ *
+ * Wire-up into the actual write/read paths is intentionally deferred to a
+ * follow-up that audits the snapshot envelope format (V8 base64 vs raw
+ * bytes) and the writeArtifact redaction interaction. See ADR for the plan.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Env var holding the HMAC secret. When unset, HMAC is disabled (Phase 0
+ * behaviour — snapshots unsigned). When set, sign-on-write and
+ * verify-on-read are enabled.
+ */
+export const SNAPSHOT_HMAC_KEY_ENV = "PI_CREW_SNAPSHOT_HMAC_KEY";
+
+/**
+ * Opt-in strict mode (Phase 2): when the key is set AND this is "1",
+ * unsigned or signature-mismatched snapshots are REJECTED on read instead
+ * of accepted with a warning.
+ */
+export const SNAPSHOT_HMAC_STRICT_ENV = "PI_CREW_SNAPSHOT_HMAC_STRICT";
+
+/**
+ * Header prefix for an inline signature. When snapshots are signed, the
+ * signature is prepended to the blob as `PI_CREW_SIG=<hex>\n` so a single
+ * read yields both the signature and the payload. (Sidecar files would
+ * require writeArtifact coordination that the envelope format does not
+ * currently support.)
+ */
+export const SNAPSHOT_SIG_PREFIX = "PI_CREW_SIG=";
+
+export function getSnapshotHmacKey(env: NodeJS.ProcessEnv = process.env): Buffer | undefined {
+	const raw = env[SNAPSHOT_HMAC_KEY_ENV];
+	if (!raw) return undefined;
+	// Accept hex-encoded keys directly; otherwise encode the string as utf8.
+	// A key shorter than 32 bytes is rejected to prevent trivial brute-force.
+	const buf = /^[0-9a-fA-F]+$/.test(raw) && raw.length % 2 === 0 ? Buffer.from(raw, "hex") : Buffer.from(raw, "utf8");
+	if (buf.length < 32) {
+		throw new Error(
+			`${SNAPSHOT_HMAC_KEY_ENV} must be at least 32 bytes (got ${buf.length}); use a longer key or generate one with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`,
+		);
+	}
+	return buf;
+}
+
+export function isSnapshotHmacStrict(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env[SNAPSHOT_HMAC_STRICT_ENV] === "1" || env[SNAPSHOT_HMAC_STRICT_ENV] === "true";
+}
+
+/**
+ * Compute the HMAC-SHA256 signature of `content` under `key`. Returns a
+ * lowercase hex string.
+ */
+export function signSnapshot(content: Buffer | string, key: Buffer): string {
+	return createHmac("sha256", key).update(content).digest("hex");
+}
+
+/**
+ * Constant-time signature comparison. Both signatures must be lowercase
+ * hex of the same length; anything else returns false without throwing.
+ */
+export function snapshotSignatureMatches(content: Buffer | string, signature: string, key: Buffer): boolean {
+	const expected = signSnapshot(content, key);
+	const a = Buffer.from(expected);
+	const b = Buffer.from(signature);
+	if (a.length !== b.length) return false;
+	return timingSafeEqual(a, b);
+}
+
+/**
+ * Outcome of {@link verifySnapshotPayload}. Callers decide how to react
+ * based on the strict-mode flag.
+ */
+export type SnapshotVerifyOutcome =
+	| { kind: "unsigned"; strict: boolean }
+	| { kind: "verified" }
+	| { kind: "mismatch"; strict: boolean }
+	| { kind: "hmac-disabled" };
+
+/**
+ * Verify a snapshot payload that may or may not carry an inline signature.
+ *
+ * @param payload The raw bytes read from disk (possibly including the
+ *   `PI_CREW_SIG=<hex>\n` prefix).
+ * @param key The HMAC key, or `undefined` when HMAC is disabled.
+ * @param strict When true, unsigned/mismatched payloads are reported as
+ *   rejectable. When false (the Phase 1 default), the caller is expected
+ *   to accept the payload with a warning.
+ */
+export function verifySnapshotPayload(payload: Buffer, key: Buffer | undefined, strict: boolean): SnapshotVerifyOutcome {
+	if (!key) return { kind: "hmac-disabled" };
+	const prefixStr = SNAPSHOT_SIG_PREFIX;
+	if (payload.length < prefixStr.length + 1 || payload.subarray(0, prefixStr.length).toString("utf8") !== prefixStr) {
+		return { kind: "unsigned", strict };
+	}
+	const newlineIdx = payload.indexOf(0x0a, prefixStr.length);
+	if (newlineIdx < 0) return { kind: "unsigned", strict };
+	const sigHex = payload.subarray(prefixStr.length, newlineIdx).toString("utf8");
+	const body = payload.subarray(newlineIdx + 1);
+	return snapshotSignatureMatches(body, sigHex, key) ? { kind: "verified" } : { kind: "mismatch", strict };
+}
+
+/**
+ * Strip the inline signature prefix and return the bare payload. Returns
+ * the original buffer when no prefix is present. Used by read paths that
+ * have already called {@link verifySnapshotPayload} and decided to accept.
+ */
+export function stripSnapshotSignature(payload: Buffer): Buffer {
+	if (payload.length < SNAPSHOT_SIG_PREFIX.length) return payload;
+	if (payload.subarray(0, SNAPSHOT_SIG_PREFIX.length).toString("utf8") !== SNAPSHOT_SIG_PREFIX) return payload;
+	const newlineIdx = payload.indexOf(0x0a, SNAPSHOT_SIG_PREFIX.length);
+	if (newlineIdx < 0) return payload;
+	return payload.subarray(newlineIdx + 1);
+}
+
+/**
+ * Attach an inline signature to a payload. Returns a new buffer shaped as
+ * `PI_CREW_SIG=<hex>\n<payload>`. Used by write paths that have HMAC
+ * enabled.
+ */
+export function attachSnapshotSignature(payload: Buffer, key: Buffer): Buffer {
+	const sig = signSnapshot(payload, key);
+	return Buffer.concat([Buffer.from(`${SNAPSHOT_SIG_PREFIX}${sig}\n`, "utf8"), payload]);
+}
+
+/**
+ * Should the caller reject the snapshot based on the verify outcome?
+ * Centralises the strict-vs-migration decision so callers stay simple.
+ */
+export function shouldRejectSnapshot(outcome: SnapshotVerifyOutcome): boolean {
+	switch (outcome.kind) {
+		case "hmac-disabled":
+			return false;
+		case "verified":
+			return false;
+		case "unsigned":
+		case "mismatch":
+			return outcome.strict;
+	}
+}