one-code-extension 0.4.1 → 0.6.0

package/extensions/lib/powershell-parser.ts

@@ -0,0 +1,344 @@
+/**
+ * PowerShell's own parser as a service: one long-lived parse server per
+ * process, run on the PowerShell the tool itself runs, so the gate reads a
+ * line exactly as it will execute (decisions/windows.md "The PowerShell
+ * pre-gate reads PowerShell's own parse"; the tree-sitter grammars it replaces
+ * are measured in findings §41).
+ *
+ * {@link PowerShellParser.parse} never rejects. Anything short of a clean
+ * answer, whether the server could not start, timed out, crashed, runs in
+ * Constrained Language Mode or stopped for good after too many crashes,
+ * resolves to `{ ok: false, reason }`, and the caller treats the line as
+ * unparsed (the classifier decides). A parse with errors is still `ok: true`:
+ * the tree and its `errors` are PowerShell's answer; judging them is the
+ * caller's job.
+ *
+ * Lifecycle. The server starts on the first request and stops after
+ * `idleMs` without one; the next request starts it again. A crash, or a
+ * request that times out (the server is then killed), counts toward
+ * `maxRestarts`; past it the parser stays unavailable for the life of the
+ * process. The child, its pipes and every timer are unref'd, so an idle
+ * server never holds a finished one-shot run open; a caller that awaits a
+ * parse in one holds its own ref (`withKeepAlive`). The server also exits on
+ * its own when this process ends, because its stdin closes.
+ *
+ * Pure: no pi imports. The caller supplies `spawnServer`, which starts the
+ * right executable with the bootstrap after `-Command`, so the BI fork can use
+ * its own launcher.
+ */
+
+import type { ChildProcess } from "node:child_process";
+import { POWERSHELL_PARSE_BOOTSTRAP, POWERSHELL_PARSE_WALKER } from "./powershell-parse-script.ts";
+import { unrefHandle } from "./process-tree.ts";
+
+/** One syntax-tree node, as the walker reports it (powershell-parse-script.ts). */
+export interface PowerShellAstNode {
+	/** The .NET type name: `CommandAst`, `StringConstantExpressionAst`, … */
+	type: string;
+	/** Index of the parent node in `nodes`; -1 for the root. */
+	parent: number;
+	/** Extent as UTF-16 offsets into the command (JS string indices). */
+	start: number;
+	end: number;
+	/** CommandAst: the static command name (null when not static). CommandParameterAst: the parameter. VariableExpressionAst: the variable path. Type nodes: the type's full name. */
+	name?: string | null;
+	/** String and constant nodes: the value PowerShell resolved (quotes and escapes applied). */
+	value?: string | null;
+	/** String nodes: `BareWord`, `SingleQuoted`, `DoubleQuoted`, `SingleQuotedHereString`, `DoubleQuotedHereString`. */
+	kind?: string;
+	/** CommandAst: the invocation operator (`Unknown`, `Ampersand`, `Dot`). Operator nodes: the operator. */
+	operator?: string;
+	/** VariableExpressionAst: `@name` splatting. */
+	splatted?: boolean;
+	/** Redirections: the stream redirected (`Output`, `Error`, `All`, …) and, for a merge, where to. */
+	from?: string;
+	to?: string;
+	/** FileRedirectionAst: `>>`. */
+	append?: boolean;
+	/** Pipelines and pipeline chains: a trailing `&` (PowerShell 7). */
+	background?: boolean;
+	/** Member access: `::`. */
+	static?: boolean;
+	/** CommandAst with a static name that resolves in this PowerShell: the resolved command's type (`Cmdlet`, `Application`, `Function`, …), after an alias. */
+	commandType?: string;
+	/** CommandAst: the name was an alias. */
+	alias?: boolean;
+	/** CommandAst: the resolved cmdlet's name, or an application's full path. */
+	resolvedName?: string;
+	/** CommandAst: the resolved command's module (empty for an application). */
+	module?: string;
+	/**
+	 * CommandAst of a cmdlet: PowerShell's static parameter binding. `value` is
+	 * the bound argument's node index, -1 for a switch given alone, and -2 for a
+	 * value the binder built itself: the arguments a remaining-arguments
+	 * parameter collects (`Write-Output a b`), whose node indices are
+	 * `elements` (-1 for one that matched no argument).
+	 */
+	bindings?: Array<{ parameter: string; value: number; elements?: number[] }>;
+	/** CommandAst of a cmdlet: the arguments or parameters the binder could not bind (an unknown or ambiguous name, a surplus positional, a repeat). */
+	bindingErrors?: string[];
+	/** CommandAst of a cmdlet: the static binder is missing or threw. */
+	bindingUnavailable?: boolean;
+}
+
+export interface PowerShellParse {
+	/** The tree in pre-order, root first. */
+	nodes: PowerShellAstNode[];
+	/** Each parse error's ErrorId. PowerShell runs nothing from a line that has one. */
+	errors: string[];
+}
+
+export type PowerShellParseOutcome = { ok: true; parse: PowerShellParse } | { ok: false; reason: string };
+
+export interface PowerShellParserOptions {
+	/** Start the server: the PowerShell executable with `bootstrap` as the argument after `-Command`, stdio all piped. */
+	spawnServer: (bootstrap: string) => ChildProcess;
+	/** How long the first request waits while the server starts. */
+	startTimeoutMs?: number;
+	/** How long a request waits once the server is ready. */
+	requestTimeoutMs?: number;
+	/** Crashes and timeouts tolerated before the parser stays unavailable. */
+	maxRestarts?: number;
+	/** Stop the server after this long without a request. */
+	idleMs?: number;
+}
+
+export const POWERSHELL_PARSE_START_TIMEOUT_MS = 5_000;
+export const POWERSHELL_PARSE_REQUEST_TIMEOUT_MS = 2_000;
+export const POWERSHELL_PARSE_MAX_RESTARTS = 3;
+export const POWERSHELL_PARSE_IDLE_MS = 10 * 60_000;
+
+interface Pending {
+	resolve: (outcome: PowerShellParseOutcome) => void;
+	timer: ReturnType<typeof setTimeout>;
+}
+
+interface Server {
+	child: ChildProcess;
+	ready: boolean;
+	/** Set once the server is gone or being stopped; its late output and exit are ignored. */
+	stopped: boolean;
+	/** Why it stopped. */
+	reason?: string;
+	buffer: string;
+	pending: Map<number, Pending>;
+}
+
+const encode = (text: string) => Buffer.from(text, "utf8").toString("base64");
+
+export class PowerShellParser {
+	private readonly options: Required<PowerShellParserOptions>;
+	private server: Server | undefined;
+	private nextId = 1;
+	private failures = 0;
+	/** Why the parser is unavailable for good; set past `maxRestarts`, or when the server runs in a restricted language mode. */
+	private disabled: string | undefined;
+	private idleTimer: ReturnType<typeof setTimeout> | undefined;
+
+	constructor(options: PowerShellParserOptions) {
+		this.options = {
+			startTimeoutMs: POWERSHELL_PARSE_START_TIMEOUT_MS,
+			requestTimeoutMs: POWERSHELL_PARSE_REQUEST_TIMEOUT_MS,
+			maxRestarts: POWERSHELL_PARSE_MAX_RESTARTS,
+			idleMs: POWERSHELL_PARSE_IDLE_MS,
+			...options,
+		};
+	}
+
+	/** Why the parser cannot answer at all, or undefined while it can (or can still start). */
+	unavailable(): string | undefined {
+		return this.disabled;
+	}
+
+	/** Parse `command` with PowerShell's own parser. Never rejects. */
+	parse(command: string): Promise<PowerShellParseOutcome> {
+		if (this.disabled) return Promise.resolve({ ok: false, reason: this.disabled });
+		let server: Server;
+		try {
+			server = this.server ?? this.start();
+		} catch (error) {
+			return Promise.resolve({ ok: false, reason: this.fail(`PowerShell could not start: ${message(error)}`) });
+		}
+		// A server can fail while it starts (a spawn error, a restricted language
+		// mode) before this request is registered with it.
+		if (server.stopped) return Promise.resolve({ ok: false, reason: this.disabled ?? server.reason ?? "the PowerShell parser stopped" });
+		this.touch();
+		const id = this.nextId++;
+		return new Promise((resolve) => {
+			const timeoutMs = server.ready ? this.options.requestTimeoutMs : this.options.startTimeoutMs;
+			const timer = setTimeout(() => {
+				server.pending.delete(id);
+				resolve({ ok: false, reason: `the PowerShell parser did not answer within ${timeoutMs} ms` });
+				this.crashed(server, `the PowerShell parser timed out after ${timeoutMs} ms`);
+			}, timeoutMs);
+			unrefHandle(timer);
+			server.pending.set(id, { resolve, timer });
+			server.child.stdin?.write(`${id} ${encode(command)}\n`);
+		});
+	}
+
+	/** Stop the server. The next request starts a new one. */
+	stop(): void {
+		const server = this.server;
+		if (!server) return;
+		this.server = undefined;
+		this.clearIdle();
+		this.settleAll(server, "the PowerShell parser was stopped");
+		server.stopped = true;
+		server.child.stdin?.end();
+		server.child.kill();
+	}
+
+	private start(): Server {
+		const child = this.options.spawnServer(POWERSHELL_PARSE_BOOTSTRAP);
+		const server: Server = { child, ready: false, stopped: false, buffer: "", pending: new Map() };
+		this.server = server;
+		child.stdin?.on("error", () => {});
+		child.stdout?.setEncoding("ascii");
+		child.stdout?.on("data", (chunk: string) => this.receive(server, chunk));
+		// PowerShell's own error output is not part of the protocol; drain it so
+		// the pipe never fills.
+		child.stderr?.on("data", () => {});
+		child.on("error", (error) => this.crashed(server, `PowerShell could not start: ${message(error)}`));
+		child.on("exit", (code, signal) => this.crashed(server, `the PowerShell parser exited (${signal ?? `code ${code}`})`));
+		unrefHandle(child);
+		unrefHandle(child.stdin);
+		unrefHandle(child.stdout);
+		unrefHandle(child.stderr);
+		child.stdin?.write(`${encode(POWERSHELL_PARSE_WALKER)}\n`);
+		return server;
+	}
+
+	private receive(server: Server, chunk: string): void {
+		if (server.stopped) return;
+		server.buffer += chunk;
+		for (let newline = server.buffer.indexOf("\n"); newline >= 0; newline = server.buffer.indexOf("\n")) {
+			const line = server.buffer.slice(0, newline).trim();
+			server.buffer = server.buffer.slice(newline + 1);
+			if (line) this.record(server, line);
+			if (server.stopped) return;
+		}
+	}
+
+	private record(server: Server, line: string): void {
+		let record: Record<string, unknown>;
+		try {
+			record = JSON.parse(Buffer.from(line, "base64").toString("utf8")) as Record<string, unknown>;
+		} catch {
+			this.crashed(server, "the PowerShell parser wrote a line that is not part of its protocol");
+			return;
+		}
+		if (record.id === 0) {
+			if (record.language !== "FullLanguage") {
+				// Constrained Language Mode (or stricter) is a machine policy, so a
+				// restart cannot change it.
+				this.disabled = `PowerShell runs in ${String(record.language)} mode, where the parser is not available`;
+				this.crashed(server, this.disabled);
+				return;
+			}
+			// Failures are not reset here: a line that hangs the walker would
+			// otherwise restart it forever.
+			server.ready = true;
+			return;
+		}
+		const pending = typeof record.id === "number" ? server.pending.get(record.id) : undefined;
+		if (!pending) return;
+		server.pending.delete(record.id as number);
+		clearTimeout(pending.timer);
+		if (typeof record.failure === "string") {
+			pending.resolve({ ok: false, reason: `the PowerShell parser failed: ${record.failure}` });
+			return;
+		}
+		pending.resolve({ ok: true, parse: { nodes: asArray(record.nodes).map(normalizeNode), errors: asArray(record.errors).map(String) } });
+	}
+
+	/** The server is gone or unusable: settle what waits on it and count the failure. */
+	private crashed(server: Server, reason: string): void {
+		if (server.stopped) return;
+		server.stopped = true;
+		server.reason = reason;
+		if (this.server === server) this.server = undefined;
+		this.clearIdle();
+		this.settleAll(server, reason);
+		server.child.stdin?.end();
+		server.child.kill();
+		this.fail(reason);
+	}
+
+	private fail(reason: string): string {
+		this.failures++;
+		if (!this.disabled && this.failures > this.options.maxRestarts) {
+			this.disabled = `the PowerShell parser is off after ${this.failures} failures (last: ${reason})`;
+		}
+		return reason;
+	}
+
+	private settleAll(server: Server, reason: string): void {
+		for (const pending of server.pending.values()) {
+			clearTimeout(pending.timer);
+			pending.resolve({ ok: false, reason });
+		}
+		server.pending.clear();
+	}
+
+	private touch(): void {
+		this.clearIdle();
+		this.idleTimer = setTimeout(() => this.stop(), this.options.idleMs);
+		unrefHandle(this.idleTimer);
+	}
+
+	private clearIdle(): void {
+		if (this.idleTimer) clearTimeout(this.idleTimer);
+		this.idleTimer = undefined;
+	}
+}
+
+/**
+ * A node with its list fields made lists: ConvertTo-Json may write a
+ * one-element list as the element. A binding list that is not one after
+ * that marks the binding unavailable, which the gate refuses.
+ */
+function normalizeNode(value: unknown): PowerShellAstNode {
+	const node = { ...(value as PowerShellAstNode) };
+	if (node.bindingErrors !== undefined) node.bindingErrors = asArray(node.bindingErrors).map(String);
+	if (node.bindings !== undefined) {
+		const bindings = asArray(node.bindings) as Array<{ parameter?: unknown; value?: unknown; elements?: unknown }>;
+		if (bindings.every((b) => b !== null && typeof b === "object" && typeof b.parameter === "string" && typeof b.value === "number")) {
+			node.bindings = bindings.map((b) => ({ parameter: b.parameter as string, value: b.value as number, ...(b.elements === undefined ? {} : { elements: asArray(b.elements).map(Number) }) }));
+		} else {
+			delete node.bindings;
+			node.bindingUnavailable = true;
+		}
+	}
+	return node;
+}
+
+function asArray(value: unknown): unknown[] {
+	if (Array.isArray(value)) return value;
+	// ConvertTo-Json writes a one-element array as that element on some
+	// PowerShell versions, and an empty one as null.
+	return value === undefined || value === null ? [] : [value];
+}
+
+function message(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+const STATE_KEY = Symbol.for("one-code.powershell-parser");
+
+/**
+ * The process-wide parser for one PowerShell executable. It lives on
+ * `globalThis`, not in module state: jiti gives each extension, and each
+ * in-process child session, its own instance of this module (findings §3), and
+ * one server per process is the point.
+ */
+export function sharedPowerShellParser(executable: string, create: () => PowerShellParser): PowerShellParser {
+	const store = globalThis as { [STATE_KEY]?: Map<string, PowerShellParser> };
+	const parsers = (store[STATE_KEY] ??= new Map());
+	let parser = parsers.get(executable);
+	if (!parser) {
+		parser = create();
+		parsers.set(executable, parser);
+	}
+	return parser;
+}

package/extensions/lib/previous-mark.ts

@@ -0,0 +1,101 @@
+/**
+ * Keep the previous request's conversation breakpoint (pure).
+ *
+ * Anthropic finds an earlier cache entry only a limited way back from a
+ * breakpoint, about 20 content blocks, and pi moves the one conversation
+ * breakpoint to each request's tail. A request that adds many blocks since the
+ * last one (a large parallel tool batch), or a long run of `tool_addition`
+ * blocks after the session-facts system message, then cannot reach the entry
+ * the previous request wrote and re-caches the whole conversation (findings
+ * §72: a live pair read 11,707 of 24,837 tokens, and 24,837 with this mark).
+ * Marking the block the previous request marked again lets the server match
+ * that entry directly. It costs nothing: the entry exists, so the mark reads.
+ */
+
+import { appendPoint } from "./ledger/wire.ts";
+import { MAX_CACHE_MARKERS } from "./request-replay.ts";
+
+type Block = Record<string, unknown> & { cache_control?: unknown };
+type Message = { role?: unknown; content?: unknown };
+
+/** Where a request's last conversation breakpoint sat, and the block it marked. */
+export interface MessageMark {
+	message: number;
+	block: number;
+	marker: unknown;
+	/** The marked block itself: pi builds each request afresh but reuses large strings (an image's data), so a structural compare short-circuits on them. */
+	content: Block;
+}
+
+const blocksOf = (message: unknown): Block[] =>
+	Array.isArray((message as Message | null)?.content) ? ((message as Message).content as Block[]) : [];
+
+/** Equal JSON values, ignoring a top-level `cache_control`. */
+function sameBlock(a: Block, b: Block): boolean {
+	const keys = (block: Block) => Object.keys(block).filter((key) => key !== "cache_control");
+	const left = keys(a);
+	return left.length === keys(b).length && left.every((key) => sameValue(a[key], b[key]));
+}
+function sameValue(a: unknown, b: unknown): boolean {
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null || Array.isArray(a) !== Array.isArray(b)) return false;
+	const left = Object.keys(a);
+	return left.length === Object.keys(b).length && left.every((key) => sameValue((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]));
+}
+
+/** The last breakpoint in `messages`, or undefined when none carries one. */
+export function lastMessageMark(messages: unknown): MessageMark | undefined {
+	if (!Array.isArray(messages)) return undefined;
+	for (let message = messages.length - 1; message >= 0; message--) {
+		const blocks = blocksOf(messages[message]);
+		for (let block = blocks.length - 1; block >= 0; block--) {
+			const marker = blocks[block]?.cache_control;
+			if (marker !== undefined) return { message, block, marker, content: blocks[block] };
+		}
+	}
+	return undefined;
+}
+
+function marksIn(value: unknown): number {
+	if (!Array.isArray(value)) return 0;
+	return value.reduce((sum: number, entry) => {
+		const own = (entry as Block | null)?.cache_control !== undefined ? 1 : 0;
+		return sum + own + blocksOf(entry).filter((block) => block?.cache_control !== undefined).length;
+	}, 0);
+}
+
+/**
+ * The payload with `previous` marked again: only when that block is still
+ * there with the same bytes, no later block already took its place as the
+ * tail mark, and a breakpoint slot is free. Otherwise the payload unchanged.
+ */
+export function withPreviousMark<T extends Record<string, unknown>>(payload: T, previous: MessageMark | undefined): T {
+	if (!previous || !Array.isArray(payload.messages)) return payload;
+	const messages = payload.messages as Message[];
+	const blocks = blocksOf(messages[previous.message]);
+	const target = blocks[previous.block];
+	if (!target || target.cache_control !== undefined || !sameBlock(target, previous.content)) return payload;
+	if (marksIn(payload.tools) + marksIn(payload.system) + marksIn(messages) >= MAX_CACHE_MARKERS) return payload;
+	const copy = [...messages];
+	const content = [...blocks];
+	content[previous.block] = { ...target, cache_control: previous.marker };
+	copy[previous.message] = { ...messages[previous.message], content };
+	return { ...payload, messages: copy };
+}
+
+/**
+ * The breakpoint the base request carried, located in `messages` (the request
+ * that extends it, spliced): the last block of the base's last element before
+ * its trailing directives, with the marker this request's own tail mark uses.
+ * Undefined when the request has no tail mark or the base is empty.
+ */
+export function baseMark(messages: unknown, baseList: readonly unknown[], api: string): MessageMark | undefined {
+	if (!Array.isArray(messages)) return undefined;
+	const end = appendPoint(baseList, api);
+	const tail = lastMessageMark(messages);
+	if (end === 0 || !tail || tail.message < end) return undefined;
+	const blocks = blocksOf(messages[end - 1]);
+	const block = blocks.length - 1;
+	if (block < 0) return undefined;
+	return { message: end - 1, block, marker: tail.marker, content: blocks[block] };
+}

package/extensions/lib/process-state.ts

@@ -0,0 +1,48 @@
+/**
+ * Process state: what lives as long as the One Code process and no longer
+ * (lifecycle-grid-hunt plan, part D). Every piece of state an extension holds
+ * is one of three kinds:
+ *
+ * - branch state follows the conversation: a resume, `/reload`, `/fork` and
+ *   `/tree` each read it back from the branch (a `one-code:state` entry,
+ *   lib/ledger/state.ts, or a fold of the branch's own entries);
+ * - process state survives `/reload` and the session swaps of `/clear`,
+ *   `/new`, `/resume` and `/fork`, and ends with the process (a grant the
+ *   user gave "for this session", a notice owed to the next session): this
+ *   module;
+ * - resources (a timer, a child process, a connection) end with the instance
+ *   that opened them, in `session_shutdown`.
+ *
+ * Module scope is none of them: pi re-evaluates every extension module at a
+ * `/reload` and at a `/resume` into another directory (findings §8), so a
+ * module-level value is lost there and kept everywhere else. The store here
+ * is a `globalThis` slot, which no re-evaluation resets.
+ *
+ * Pure: no pi imports.
+ */
+
+const SLOT = Symbol.for("one-code:process-state");
+
+type Store = Map<string, unknown>;
+
+function store(): Store {
+	const slot = globalThis as { [SLOT]?: Store };
+	return (slot[SLOT] ??= new Map());
+}
+
+/**
+ * The process's value for `key`, created by `init` on first use. Keys are
+ * namespaced by their owner (`"permissions:grants"`); the value is shared by
+ * every instance of that owner in the process, so it must be mutated, not
+ * replaced.
+ */
+export function processState<T>(key: string, init: () => T): T {
+	const values = store();
+	if (!values.has(key)) values.set(key, init());
+	return values.get(key) as T;
+}
+
+/** Forget every process value: a test's fresh process. */
+export function resetProcessStateForTest(): void {
+	store().clear();
+}

package/extensions/lib/process-tree.ts

@@ -14,9 +14,22 @@
  * The producer spawns `detached` (own process group; `detachedSpawnOptions`)
  * and stops it with `killProcessTree`, which signals the negative pid — the
  * whole group — falling back to the child alone when the group is already gone.
- * `stopProcessTree` adds the grace period: SIGTERM now, SIGKILL if the leader
- * has not exited by then (a command that ignores SIGTERM still closes late,
- * which is exactly the late callback the shutdown paths guard against).
+ * `stopProcessTree` adds the grace period: SIGTERM now, SIGKILL to the group
+ * when it ends, whether or not the leader is still alive. The leader is often
+ * only the `bash -c` wrapper, which dies on TERM at once while the command it
+ * forked (a dev server in its graceful-shutdown handler) keeps the group and
+ * its port; a leader-only check skipped the SIGKILL exactly then
+ * (LIFECYCLE-BACKGROUND-REVIEW-2026-09-26 M1, measured). A group whose SIGKILL
+ * is still pending when the process exits (pi's quit calls `process.exit`,
+ * and the grace timer is unref'd) is SIGKILLed from a `process.on("exit")`
+ * hook, so nothing One Code stopped outlives it.
+ *
+ * `rememberProcessGroup` owns a background shell's group for the lifetime of
+ * this process, including descendants left by a successfully exited leader.
+ * Session replacement must not kill those intentionally launched daemons.
+ * Each module instance keeps its own groups through process listeners (never
+ * through a session context or cross-extension module state), reaps empty
+ * groups, and sends TERM synchronously on process exit or termination signals.
  *
  * `waitForChildExit` is the counterpart on the waiting side: it settles on
  * `exit` plus a short stdio grace, never on `close` alone — a descendant the
@@ -37,6 +50,16 @@ export const EXIT_STDIO_GRACE_MS = 200;
 /** ...and the most it may keep arriving in total: a straggler writing continuously must not keep re-arming the grace. */
 export const EXIT_STDIO_MAX_MS = 2_000;
 
+/**
+ * Unref a child process, one of its stdio streams or a timer, so it never
+ * holds the event loop open on its own (a finished one-shot run can exit);
+ * a caller awaiting it holds its own ref. Child pipes are sockets at run
+ * time and carry `unref()` even though their stream types do not declare it.
+ */
+export function unrefHandle(handle: unknown): void {
+	(handle as { unref?: () => void } | null | undefined)?.unref?.();
+}
+
 /**
  * `detached` everywhere but Windows, where process groups do not exist — except
  * for a child that must outlive an exiting parent (a fire-and-forget hook),
@@ -95,20 +118,121 @@ export function killProcessTree(child: ChildProcess, signal: NodeJS.Signals = "S
 	}
 }
 
+/** Groups owned by this producer, retained by process listeners across session replacement. */
+const rememberedGroups = new Set<ChildProcess>();
+let groupReaper: NodeJS.Timeout | undefined;
+const terminationSignals = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
+const groupSignalHandlers = new Map<NodeJS.Signals, () => void>();
+
+/**
+ * Whether a remembered tree still needs killing at exit. Windows has no
+ * process groups, so only a live leader is worth a `taskkill /T`; it is judged
+ * by the child's own exit state, because once the leader exits Windows may
+ * hand its pid to an unrelated process that a pid probe would then find. On
+ * POSIX a group id stays reserved while any member lives, and the reaper
+ * forgets an emptied group within a second, far sooner than sequential pid
+ * allocation wraps around to it.
+ */
+export function rememberedGroupAlive(child: ChildProcess): boolean {
+	if (child.pid == null) return false;
+	if (process.platform === "win32") return child.exitCode === null && child.signalCode === null;
+	try {
+		process.kill(-child.pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code !== "ESRCH";
+	}
+}
+
+function releaseGroupListeners(): void {
+	if (groupReaper) clearInterval(groupReaper);
+	groupReaper = undefined;
+	process.removeListener("exit", terminateRememberedGroups);
+	for (const [signal, handler] of groupSignalHandlers) process.removeListener(signal, handler);
+	groupSignalHandlers.clear();
+}
+
+/** Exit handlers cannot await a grace period. Existing explicit stops retain their TERM/KILL escalation below. */
+function terminateRememberedGroups(): void {
+	for (const child of rememberedGroups) {
+		if (rememberedGroupAlive(child)) killProcessTree(child, "SIGTERM");
+	}
+	rememberedGroups.clear();
+	releaseGroupListeners();
+}
+
 /**
- * SIGTERM the tree, then SIGKILL it after `graceMs` unless the leader exited.
- * The timer is unref'd: it must never be what keeps a one-shot process alive.
+ * Remember a detached background tree from spawn until its group becomes empty.
+ * Register before awaiting its leader, so even immediate process exit covers
+ * running work. The unref'd reaper cannot keep a print run alive. No session
+ * shutdown handler touches this set; the process listeners keep this module
+ * instance alive, and reach its set, even after pi evaluates the module again
+ * (a /reload, a /resume into another directory: findings §8).
+ */
+export function rememberProcessGroup(child: ChildProcess): void {
+	if (child.pid == null || rememberedGroups.has(child)) return;
+	rememberedGroups.add(child);
+	if (groupReaper) return;
+	process.on("exit", terminateRememberedGroups);
+	for (const signal of terminationSignals) {
+		const handler = () => {
+			terminateRememberedGroups();
+			// Do not swallow Node's default signal termination when there is no
+			// pi handler. With isolated producers, the last listener re-raises it.
+			if (process.listenerCount(signal) === 0) process.kill(process.pid, signal);
+		};
+		groupSignalHandlers.set(signal, handler);
+		// Run before signal-exit observers: after we remove ourselves they must
+		// still see the original listener count and preserve default termination.
+		process.prependOnceListener(signal, handler);
+	}
+	groupReaper = setInterval(() => {
+		for (const child of rememberedGroups) {
+			if (!rememberedGroupAlive(child)) rememberedGroups.delete(child);
+		}
+		if (rememberedGroups.size === 0) releaseGroupListeners();
+	}, 1_000);
+	groupReaper.unref?.();
+}
+
+/**
+ * Trees sent SIGTERM whose SIGKILL has not run yet. Keyed by the child, not
+ * its pid, so a pid the OS hands to a new child during the grace does not
+ * make that child look already scheduled. Per module instance on purpose
+ * (each extension force-kills its own children); one `exit` listener per
+ * instance, installed on first use.
+ */
+const pendingKills = new Set<ChildProcess>();
+let exitHookInstalled = false;
+
+/** The process is exiting: the grace timers will never fire, so force-kill every tree still pending. */
+function killPendingAtExit(): void {
+	for (const child of pendingKills) killProcessTree(child, "SIGKILL");
+	pendingKills.clear();
+}
+
+/**
+ * SIGTERM the tree, then SIGKILL the whole group after `graceMs`, whatever
+ * the leader's state: a group already gone makes that an ESRCH, and a live
+ * group keeps its id reserved, so the id cannot name anyone else. The timer
+ * is unref'd (it must never be what keeps a one-shot process alive); a
+ * process exit before it fires runs the SIGKILL from the `exit` hook.
  */
 export function stopProcessTree(child: ChildProcess, graceMs: number): void {
 	killProcessTree(child, "SIGTERM");
 	// taskkill /F is already forceful; there is no gentler first signal to grace.
 	if (process.platform === "win32") return;
-	if (child.exitCode !== null || child.signalCode !== null) return;
+	if (child.pid == null || pendingKills.has(child)) return;
+	pendingKills.add(child);
+	if (!exitHookInstalled) {
+		exitHookInstalled = true;
+		process.on("exit", killPendingAtExit);
+	}
 	const timer = setTimeout(() => {
-		if (child.exitCode === null && child.signalCode === null) killProcessTree(child, "SIGKILL");
+		if (!pendingKills.delete(child)) return;
+		killProcessTree(child, "SIGKILL");
 	}, graceMs);
 	timer.unref?.();
-	child.once("exit", () => clearTimeout(timer));
 }
 
 export interface ChildExit {