pi-cohort 6.0.0 → 6.1.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [6.1.0] - 2026-09-12
+
+External execution backends currently require a non-Windows host. Native execution remains supported on Windows.
+
+### Added
+
+- `pi-cohort/execution-backend` registrations may include a validated, package-anchored reload descriptor (`protocolVersion`, `packageJsonUrl`, `publicSubpath`, and `factoryExport`). Detached coordinators reconstruct those public named factories in registration order without serializing live backend objects or environment state.
+- Background child attempts now use the same external execution backend contract as foreground attempts while leaving the detached runner as the durable coordinator. Native selection bypasses backend reload, exact child working directories are preserved, successful delivered surfaces close, and failed or interrupted surfaces remain available for inspection.
+
+### Changed
+
+- `release.sh <level>` now promotes the `## [Unreleased]` CHANGELOG section to the versioned heading and commits it with `package.json` in the single `Release X.Y.Z` commit; a missing or empty section fails the run. New CONFIG field `CHANGELOG_HEADING`.
+- Release skill: a user instruction naming the level is the approval - no proposal step or re-confirmation; bundled follow-ups (ticket close, preset sync) run after `verify`.
+- AGENTS.md rewritten to always-on essentials plus routing; shared core bumped to v3 (north-star communication regimes, authorization rule, docs-as-current-contract, third-party API lookup). Discovery implementation notes moved to `doc/agents-and-chains.md`.
+- Added `.pi/gauntlet-overrides.md` (`tracker: github`, release path, write-gate carve-out for user-named writes).
+- The `@earendil-works/pi-coding-agent` peer dependency now requires Pi >=0.85.0 for interactive execution reporting and control.
+- Background selection fails loudly when an explicitly selected backend cannot reload. `auto` also reports registration/reload failures instead of silently changing configured policy; after successful reload, ordinary unavailable detection still falls back to native.
+
+## [6.0.1] - 2026-09-07
+
+### Fixed
+
+- `getFinalOutput` no longer truncates a multi-block assistant reply to its last text block; it now joins all non-empty text blocks with `\n`. Previously a `BLOCKED:` line in an earlier block was dropped, so the `BLOCKED:` classifier misread a blocked reply as successful (or a completed reply whose trailing block happened to start with `BLOCKED:` as failed).
+
 ## [6.0.0] - 2026-09-07
 
 ### Removed

package/README.md

@@ -39,6 +39,42 @@ pi install npm:pi-cohort
 
 That is the only required step.
 
+## Execution backend extension API
+
+External execution backends are currently unsupported on Windows, for both foreground and background runs. Native execution remains supported.
+
+`pi-cohort/execution-backend` requires Pi >=0.85.0 and is the public API for Pi extensions that add child execution surfaces. Pi's TypeScript-aware runtime loads the API; bare Node is not a supported execution path. Consumers outside Pi must supply a TypeScript-aware loader such as [jiti](https://github.com/unjs/jiti).
+
+An adapter registers its backend in extension load order. To make that backend available to background runs, registration also supplies an optional reload descriptor:
+
+```ts
+import {
+  EXECUTION_BACKEND_PROTOCOL_VERSION,
+  registerExecutionBackend,
+  type ExecutionBackendFactory,
+} from "pi-cohort/execution-backend";
+import { createBackend } from "./adapter.ts";
+
+export const createExampleBackend: ExecutionBackendFactory = createBackend;
+
+// src/execution-backend.ts, exported as "./execution-backend".
+// Pi invokes the default extension; the coordinator invokes only the factory.
+export default async function () {
+  registerExecutionBackend(await createExampleBackend(), {
+    reload: {
+      protocolVersion: EXECUTION_BACKEND_PROTOCOL_VERSION,
+      packageJsonUrl: new URL("../package.json", import.meta.url).href,
+      publicSubpath: "./execution-backend",
+      factoryExport: "createExampleBackend",
+    },
+  });
+}
+```
+
+The descriptor has exactly four fields. `packageJsonUrl` must be an absolute `file:` URL for the adapter package's real `package.json`. `publicSubpath` must be `"."` or an explicit non-pattern `"./..."` entry in that package's `exports`. `factoryExport` names a public, zero-argument export from that subpath; it may return the backend or a promise of it. The reconstructed backend must have the same `name` and protocol version as the original registration.
+
+Cohort serializes only backend names and validated reload descriptors into its detached coordinator - never live backend objects or an environment capsule. The coordinator reloads registrations in their original order before selecting a backend, and every child launch receives its exact resolved `cwd`. Selecting `native` bypasses reload entirely. An explicit backend selection reports that backend's reload failure; `auto` reports any registered reload failure rather than silently changing policy. Once reload succeeds, normal auto-detection still falls back to native when no registered backend is available. Backends registered without `reload` remain usable in the foreground but cannot be reconstructed for a background run.
+
 ## Mental model
 
 Pi is the parent session. A subagent is a focused child Pi session with its own job. When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. Foreground runs stream in the conversation; background runs keep working and can be checked later.

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "pi-cohort",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "Delegate Pi work to focused child agents: code review, scouting, implementation, parallel audits, saved chains, and background jobs.",
   "author": "Jacek Juraszek",
   "license": "MIT",
   "type": "module",
+  "exports": {
+    "./execution-backend": "./src/execution-backend/index.ts",
+    "./execution-backend-testkit": "./src/execution-backend/testkit.ts"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jjuraszek/pi-cohort.git"
@@ -59,7 +63,7 @@
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=0.85.0",
     "@earendil-works/pi-tui": "*"
   },
   "peerDependenciesMeta": {
@@ -81,9 +85,9 @@
     "typebox": "^1.3.11"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.74.0",
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "@earendil-works/pi-tui": "^0.74.0"
+    "@earendil-works/pi-agent-core": "^0.85.0",
+    "@earendil-works/pi-ai": "^0.85.0",
+    "@earendil-works/pi-coding-agent": "^0.85.0",
+    "@earendil-works/pi-tui": "^0.85.0"
   }
 }

package/src/agents/agents.ts

@@ -18,6 +18,13 @@ export { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./
 export type AgentScope = "user" | "project" | "both";
 
 export type AgentSource = "builtin" | "user" | "project";
+
+class InvalidExecutionBackendSettingError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "InvalidExecutionBackendSettingError";
+	}
+}
 type SystemPromptMode = "append" | "replace";
 export type AgentDefaultContext = "fresh" | "fork";
 
@@ -110,6 +117,7 @@ export interface AgentConfig {
 interface SubagentSettings {
 	overrides: Record<string, BuiltinAgentOverrideConfig>;
 	disableBuiltins?: boolean;
+	executionBackend?: string;
 }
 
 const EMPTY_SUBAGENT_SETTINGS: SubagentSettings = { overrides: {} };
@@ -453,16 +461,29 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
 		}
 	}
 
+	let executionBackend: string | undefined;
+	if ("executionBackend" in subagentsObject) {
+		const value = subagentsObject.executionBackend;
+		if (typeof value !== "string") {
+			throw new InvalidExecutionBackendSettingError(`Subagent settings in '${filePath}' have invalid 'executionBackend'; expected a string.`);
+		}
+		const trimmed = value.trim();
+		if (trimmed === "") {
+			throw new InvalidExecutionBackendSettingError(`Subagent settings in '${filePath}' have invalid 'executionBackend'; must not be blank.`);
+		}
+		executionBackend = trimmed;
+	}
+
 	const parsed: Record<string, BuiltinAgentOverrideConfig> = {};
 	const agentOverrides = subagentsObject.agentOverrides;
 	if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides)) {
-		return { overrides: parsed, disableBuiltins };
+		return { overrides: parsed, disableBuiltins, executionBackend };
 	}
 	for (const [name, value] of Object.entries(agentOverrides)) {
 		const override = parseBuiltinOverrideEntry(name, value, filePath);
 		if (override) parsed[name] = override;
 	}
-	return { overrides: parsed, disableBuiltins };
+	return { overrides: parsed, disableBuiltins, executionBackend };
 }
 
 // Merge project .pi/settings.json across every enumerated level, farthest-first
@@ -476,12 +497,17 @@ function readMergedProjectSubagentSettings(cwd: string): SubagentSettings {
 
 	const overrides: Record<string, BuiltinAgentOverrideConfig> = {};
 	let disableBuiltins: boolean | undefined;
+	let executionBackend: string | undefined;
 	for (const level of levels) {
 		const settingsPath = path.join(level, ".pi", "settings.json");
 		let levelSettings: SubagentSettings;
 		try {
 			levelSettings = readSubagentSettings(settingsPath);
 		} catch (error) {
+			// Invalid backend policy must not silently fall back to native execution.
+			if (error instanceof InvalidExecutionBackendSettingError) {
+				throw error;
+			}
 			const message = error instanceof Error ? error.message : String(error);
 			console.warn(`Skipping malformed subagent settings at '${settingsPath}': ${message}`);
 			continue;
@@ -492,8 +518,16 @@ function readMergedProjectSubagentSettings(cwd: string): SubagentSettings {
 		if (levelSettings.disableBuiltins !== undefined) {
 			disableBuiltins = levelSettings.disableBuiltins;
 		}
+		if (levelSettings.executionBackend !== undefined) {
+			executionBackend = levelSettings.executionBackend;
+		}
 	}
-	return { overrides, disableBuiltins };
+	return { overrides, disableBuiltins, executionBackend };
+}
+
+export function readProjectExecutionBackend(cwd: string): string | undefined {
+	const merged = readMergedProjectSubagentSettings(cwd);
+	return merged.executionBackend;
 }
 
 function composeOverrideTools(

package/src/execution-backend/child-host-controller.ts

@@ -0,0 +1,167 @@
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ChildHostFrameDecoder, encodeChildHostMessage, type ChildHostMessage } from "./child-host-protocol.ts";
+import { PI_COHORT_CHILD_HOST_CONFIG } from "./child-host-runtime.ts";
+import { ensureJitiCliPath } from "../runs/shared/jiti-cli.ts";
+import type { ExecutionBackend, ExecutionBackendLease } from "./types.ts";
+
+export interface ChildHostAttempt { readonly attemptId: string; readonly command: string; readonly args: readonly string[]; readonly cwd: string; readonly environment: Readonly<Record<string, string>>; }
+export interface ChildHostExit { readonly status: number | null; readonly signal: string | null; }
+export interface ChildHostController { readonly lease: ExecutionBackendLease; readonly ready: Promise<void>; startAttempt(attempt: ChildHostAttempt): Promise<ChildHostExit>; shutdown(): Promise<void>; releaseObserver(): Promise<void>; }
+export interface ChildHostControllerOptions { readonly backend: ExecutionBackend; readonly runId: string; readonly childId: string; readonly cwd: string; readonly title?: string; readonly signal: AbortSignal; }
+export interface ChildHostControllerDependencies { readonly fs?: typeof fs; readonly ensureJiti?: () => string | undefined; readonly childHostCommand?: () => { command: string; args: readonly string[] }; readonly platform?: NodeJS.Platform; readonly createServer?: typeof net.createServer; }
+
+const HOST_ENVIRONMENT_KEYS = ["PATH", "HOME", "TMPDIR", "SystemRoot"] as const;
+function childHostCommand(ensureJiti: () => string | undefined): { command: string; args: readonly string[] } {
+	const jiti = ensureJiti();
+	if (!jiti) throw new Error("upstream jiti for TypeScript execution could not be found; ensure package dependencies are installed");
+	return { command: process.execPath, args: [jiti, path.resolve(path.dirname(fileURLToPath(import.meta.url)), "child-host-runtime.ts")] };
+}
+function disconnected(phase: string): Error { return new Error(`child host disconnected ${phase}`); }
+function aborted(): Error { return new Error("child host launch aborted"); }
+
+export async function createChildHostController(options: ChildHostControllerOptions, dependencies: ChildHostControllerDependencies = {}): Promise<ChildHostController> {
+	const platform = dependencies.platform ?? process.platform;
+	if (platform === "win32") throw new Error("external terminal mux child host is unsupported on win32");
+	if (options.signal.aborted) throw aborted();
+	const fileSystem = dependencies.fs ?? fs;
+	let directory: string | undefined;
+	let socketPath: string | undefined;
+	let configPath: string | undefined;
+	let server: net.Server | undefined;
+	let socket: net.Socket | undefined;
+	let closed = false;
+	let abortListener: (() => void) | undefined;
+	const cleanup = () => {
+		if (abortListener) options.signal.removeEventListener("abort", abortListener);
+		abortListener = undefined;
+		try { socket?.destroy(); } catch {}
+		try { server?.close(); } catch {}
+		if (socketPath) try { fileSystem.unlinkSync(socketPath); } catch {}
+		if (configPath) try { fileSystem.unlinkSync(configPath); } catch {}
+		if (directory) try { fileSystem.rmdirSync(directory); } catch {}
+	};
+	try {
+		directory = fileSystem.mkdtempSync(path.join(os.tmpdir(), "pi-cohort-host-"));
+		socketPath = path.join(directory, "host.sock");
+		configPath = path.join(directory, "host.json");
+		if (Buffer.byteLength(socketPath) >= 100) throw new Error("child host socket path exceeds platform limit");
+		fileSystem.chmodSync(directory, 0o700);
+		let descriptor: number | undefined;
+		try {
+			descriptor = fileSystem.openSync(configPath, "wx", 0o600);
+			fileSystem.writeFileSync(descriptor, JSON.stringify({ protocolVersion: 1, socketPath, runId: options.runId, childId: options.childId }));
+		} finally { if (descriptor !== undefined) fileSystem.closeSync(descriptor); }
+
+		let lease: ExecutionBackendLease | undefined;
+		let ready = false;
+		let releasePromise: Promise<void> | undefined;
+		let active: { readonly attemptId: string; started: boolean; resolve: (exit: ChildHostExit) => void; reject: (error: Error) => void } | undefined;
+		let pendingShutdown: { resolve: () => void; reject: (error: Error) => void } | undefined;
+		let resolveReady: (() => void) | undefined;
+		let rejectReady: ((error: Error) => void) | undefined;
+		const readyPromise = new Promise<void>((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+		void readyPromise.catch(() => {});
+		let disconnectCause: Error | undefined;
+		const attemptedIds = new Set<string>();
+		const fail = (cause: Error) => {
+			if (closed) return;
+			closed = true;
+			rejectReady?.(cause); rejectReady = undefined;
+			if (active) { active.reject(cause); active = undefined; }
+			if (pendingShutdown) { pendingShutdown.reject(cause); pendingShutdown = undefined; }
+			cleanup();
+		};
+		server = (dependencies.createServer ?? net.createServer)(connection => {
+			if (socket || closed) { connection.destroy(); return; }
+			socket = connection;
+			const decoder = new ChildHostFrameDecoder();
+			connection.on("data", data => {
+				let messages: ChildHostMessage[];
+				try { messages = decoder.push(data); } catch { connection.destroy(); return; }
+				for (const message of messages) {
+					if (message.runId !== options.runId || message.childId !== options.childId) { connection.destroy(); return; }
+					if (!ready) {
+						if (message.kind !== "host_ready") { connection.destroy(); return; }
+						ready = true; resolveReady?.(); resolveReady = undefined; rejectReady = undefined; continue;
+					}
+					if (message.kind === "attempt_started" && active?.attemptId === message.attemptId && !active.started) { active.started = true; continue; }
+					if (message.kind === "attempt_spawn_error" && active?.attemptId === message.attemptId) {
+						const pending = active; active = undefined; pending.reject(new Error("child host attempt spawn error")); continue;
+					}
+					if (message.kind === "attempt_exited" && active?.attemptId === message.attemptId && active.started) {
+						const pending = active; active = undefined; pending.resolve({ status: message.status, signal: message.signal }); continue;
+					}
+					if (message.kind === "shutdown_ack" && pendingShutdown && !active) {
+						const pending = pendingShutdown; pendingShutdown = undefined; closed = true; connection.end(); cleanup(); pending.resolve(); continue;
+					}
+					connection.destroy(); return;
+				}
+			});
+			connection.once("close", () => {
+				if (!closed) {
+					const cause = disconnected(!ready ? "before ready" : active ? "during attempt" : pendingShutdown ? "before shutdown acknowledgement" : "after ready");
+					disconnectCause = cause;
+					fail(cause);
+				}
+			});
+		});
+		server.once("error", cause => fail(cause instanceof Error ? cause : new Error("child host server error")));
+		abortListener = () => fail(aborted());
+		options.signal.addEventListener("abort", abortListener, { once: true });
+		await new Promise<void>((resolve, reject) => server!.listen(socketPath!, () => resolve()).once("error", reject));
+		fileSystem.chmodSync(socketPath, 0o600);
+		if (options.signal.aborted) throw aborted();
+		const host = dependencies.childHostCommand?.() ?? childHostCommand(dependencies.ensureJiti ?? ensureJitiCliPath);
+		const environment: Record<string, string> = { [PI_COHORT_CHILD_HOST_CONFIG]: configPath };
+		for (const key of HOST_ENVIRONMENT_KEYS) if (process.env[key]) environment[key] = process.env[key]!;
+		lease = await options.backend.launch({
+			command: host.command,
+			args: host.args,
+			cwd: options.cwd,
+			environment,
+			runId: options.runId,
+			childId: options.childId,
+			signal: options.signal,
+			...(options.title === undefined ? {} : { awareness: { title: options.title } }),
+		});
+		return {
+			get lease() { return lease!; },
+			ready: readyPromise,
+			startAttempt(attempt) {
+				if (closed || !socket || !ready) return Promise.reject(disconnectCause ?? disconnected("before ready"));
+				if (pendingShutdown) return Promise.reject(new Error("child host is shutting down"));
+				if (active) return Promise.reject(new Error("child host is busy"));
+				if (!attempt.attemptId) return Promise.reject(new Error("attemptId is required"));
+				if (attemptedIds.has(attempt.attemptId)) return Promise.reject(new Error("child host attemptId has already been used"));
+				attemptedIds.add(attempt.attemptId);
+				return new Promise<ChildHostExit>((resolve, reject) => {
+					active = { attemptId: attempt.attemptId, started: false, resolve, reject };
+					socket!.write(encodeChildHostMessage({ protocolVersion: 1, kind: "start_attempt", runId: options.runId, childId: options.childId, ...attempt }), error => { if (error && active?.attemptId === attempt.attemptId) fail(disconnected("during attempt")); });
+				});
+			},
+			shutdown() {
+				if (closed) return disconnectCause ? Promise.reject(disconnectCause) : Promise.resolve();
+				if (!socket || !ready) return Promise.reject(disconnectCause ?? disconnected("before ready"));
+				if (active || pendingShutdown) return Promise.reject(new Error("child host is busy"));
+				return new Promise<void>((resolve, reject) => {
+					pendingShutdown = { resolve, reject };
+					socket!.write(encodeChildHostMessage({ protocolVersion: 1, kind: "shutdown_host", runId: options.runId, childId: options.childId }), error => { if (error) fail(disconnected("before shutdown acknowledgement")); });
+				});
+			},
+			releaseObserver() {
+				return (releasePromise ??= lease!.release().catch(error => {
+					releasePromise = undefined;
+					throw error;
+				}));
+			},
+		};
+	} catch (cause) {
+		closed = true;
+		cleanup();
+		throw cause;
+	}
+}

package/src/execution-backend/child-host-protocol.ts

@@ -0,0 +1,101 @@
+export const CHILD_HOST_PROTOCOL_VERSION = 1;
+export const CHILD_HOST_MAX_FRAME_BYTES = 64 * 1024;
+
+export interface ChildHostConfig {
+	readonly protocolVersion: typeof CHILD_HOST_PROTOCOL_VERSION;
+	readonly socketPath: string;
+	readonly runId: string;
+	readonly childId: string;
+}
+
+type Correlation = { readonly protocolVersion: 1; readonly runId: string; readonly childId: string };
+export type ChildHostMessage =
+	| (Correlation & { readonly kind: "host_ready" })
+	| (Correlation & { readonly kind: "start_attempt"; readonly attemptId: string; readonly command: string; readonly args: readonly string[]; readonly cwd: string; readonly environment: Readonly<Record<string, string>> })
+	| (Correlation & { readonly kind: "attempt_started"; readonly attemptId: string })
+	| (Correlation & { readonly kind: "attempt_spawn_error"; readonly attemptId: string })
+	| (Correlation & { readonly kind: "attempt_exited"; readonly attemptId: string; readonly status: number | null; readonly signal: string | null })
+	| (Correlation & { readonly kind: "shutdown_host" })
+	| (Correlation & { readonly kind: "shutdown_ack" });
+
+function record(value: unknown, label: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${label} must be an object`);
+	return value as Record<string, unknown>;
+}
+function text(value: unknown, label: string): string {
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${label} must be a non-empty string`);
+	return value;
+}
+function exact(input: Record<string, unknown>, fields: readonly string[]): void {
+	if (Object.keys(input).length !== fields.length || fields.some(field => !Object.hasOwn(input, field))) throw new Error("invalid child host message fields");
+}
+function correlation(input: Record<string, unknown>): Correlation {
+	return { protocolVersion: CHILD_HOST_PROTOCOL_VERSION, runId: text(input.runId, "runId"), childId: text(input.childId, "childId") };
+}
+
+export function validateChildHostConfig(value: unknown): ChildHostConfig {
+	const input = record(value, "child host config");
+	exact(input, ["protocolVersion", "socketPath", "runId", "childId"]);
+	if (input.protocolVersion !== CHILD_HOST_PROTOCOL_VERSION) throw new Error("incompatible child host protocol");
+	return { ...correlation(input), socketPath: text(input.socketPath, "socketPath") };
+}
+
+export function validateChildHostMessage(value: unknown): ChildHostMessage {
+	const input = record(value, "child host message");
+	if (input.protocolVersion !== CHILD_HOST_PROTOCOL_VERSION) throw new Error("incompatible child host protocol");
+	const base = correlation(input);
+	switch (input.kind) {
+		case "host_ready": exact(input, ["protocolVersion", "kind", "runId", "childId"]); return { ...base, kind: "host_ready" };
+		case "shutdown_host": exact(input, ["protocolVersion", "kind", "runId", "childId"]); return { ...base, kind: "shutdown_host" };
+		case "shutdown_ack": exact(input, ["protocolVersion", "kind", "runId", "childId"]); return { ...base, kind: "shutdown_ack" };
+		case "attempt_started": exact(input, ["protocolVersion", "kind", "runId", "childId", "attemptId"]); return { ...base, kind: "attempt_started", attemptId: text(input.attemptId, "attemptId") };
+		case "attempt_spawn_error": exact(input, ["protocolVersion", "kind", "runId", "childId", "attemptId"]); return { ...base, kind: "attempt_spawn_error", attemptId: text(input.attemptId, "attemptId") };
+		case "attempt_exited": {
+			exact(input, ["protocolVersion", "kind", "runId", "childId", "attemptId", "status", "signal"]);
+			if (input.status !== null && (!Number.isSafeInteger(input.status) || input.status < 0)) throw new Error("status must be a non-negative integer or null");
+			if (input.signal !== null && typeof input.signal !== "string") throw new Error("signal must be a string or null");
+			return { ...base, kind: "attempt_exited", attemptId: text(input.attemptId, "attemptId"), status: input.status, signal: input.signal };
+		}
+		case "start_attempt": {
+			exact(input, ["protocolVersion", "kind", "runId", "childId", "attemptId", "command", "args", "cwd", "environment"]);
+			if (!Array.isArray(input.args) || input.args.some(arg => typeof arg !== "string")) throw new Error("args must be strings");
+			const environment = record(input.environment, "environment");
+			if (Object.values(environment).some(entry => typeof entry !== "string")) throw new Error("environment values must be strings");
+			return { ...base, kind: "start_attempt", attemptId: text(input.attemptId, "attemptId"), command: text(input.command, "command"), args: input.args, cwd: text(input.cwd, "cwd"), environment: environment as Record<string, string> };
+		}
+		default: throw new Error("invalid child host message kind");
+	}
+}
+
+/** Incremental, bounded JSONL decoder. It intentionally never retains parsed frames. */
+export class ChildHostFrameDecoder {
+	#buffer = Buffer.alloc(0);
+	push(chunk: Buffer | string): ChildHostMessage[] {
+		this.#buffer = Buffer.concat([this.#buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+		const messages: ChildHostMessage[] = [];
+		for (;;) {
+			const newline = this.#buffer.indexOf(0x0a);
+			if (newline < 0) {
+				if (this.#buffer.length > CHILD_HOST_MAX_FRAME_BYTES) throw new Error("child host frame buffer exceeds maximum size");
+				return messages;
+			}
+			if (newline === 0 || newline > CHILD_HOST_MAX_FRAME_BYTES) throw new Error("invalid child host frame");
+			const frame = this.#buffer.subarray(0, newline);
+			this.#buffer = this.#buffer.subarray(newline + 1);
+			try { messages.push(validateChildHostMessage(JSON.parse(frame.toString("utf8")))); }
+			catch { throw new Error("invalid child host frame"); }
+		}
+	}
+	get remainder(): string { return this.#buffer.toString("utf8"); }
+}
+
+export function decodeChildHostFrames(chunk: string, maxBytes = CHILD_HOST_MAX_FRAME_BYTES): { messages: ChildHostMessage[]; remainder: string } {
+	if (maxBytes !== CHILD_HOST_MAX_FRAME_BYTES) {
+		if (Buffer.byteLength(chunk) > maxBytes) throw new Error("child host frame buffer exceeds maximum size");
+		for (const frame of chunk.split("\n").slice(0, -1)) if (!frame || Buffer.byteLength(frame) > maxBytes) throw new Error("invalid child host frame");
+	}
+	const decoder = new ChildHostFrameDecoder();
+	const messages = decoder.push(chunk);
+	return { messages, remainder: decoder.remainder };
+}
+export function encodeChildHostMessage(message: ChildHostMessage): string { return `${JSON.stringify(message)}\n`; }

package/src/execution-backend/child-host-runtime.ts

@@ -0,0 +1,61 @@
+import * as fs from "node:fs";
+import * as net from "node:net";
+import { spawn, type ChildProcess } from "node:child_process";
+import { ChildHostFrameDecoder, type ChildHostConfig, type ChildHostMessage, encodeChildHostMessage, validateChildHostConfig } from "./child-host-protocol.ts";
+
+export const PI_COHORT_CHILD_HOST_CONFIG = "PI_COHORT_CHILD_HOST_CONFIG";
+
+export function loadChildHostConfig(configPath = process.env[PI_COHORT_CHILD_HOST_CONFIG]): ChildHostConfig {
+	if (!configPath) throw new Error(`${PI_COHORT_CHILD_HOST_CONFIG} is required`);
+	let descriptor: number | undefined;
+	try {
+		try { descriptor = fs.openSync(configPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)); }
+		catch (cause) { if ((cause as NodeJS.ErrnoException).code === "ELOOP") throw new Error("child host config must be a regular non-symlink file"); throw cause; }
+		const details = fs.fstatSync(descriptor);
+		if (!details.isFile() || (details.mode & 0o077) !== 0) throw new Error("child host config must be an owner-only regular file");
+		return validateChildHostConfig(JSON.parse(fs.readFileSync(descriptor, "utf8")));
+	} finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
+}
+
+export function runChildHost(config = loadChildHostConfig()): void {
+	const correlation = { protocolVersion: 1 as const, runId: config.runId, childId: config.childId };
+	const socket = net.createConnection(config.socketPath);
+	let active: { attemptId: string; process: ChildProcess } | undefined;
+	let stopping = false;
+	const send = (message: ChildHostMessage) => { if (!socket.destroyed) socket.write(encodeChildHostMessage(message)); };
+	const terminateActive = () => { if (active && !active.process.killed) active.process.kill(); };
+	socket.on("connect", () => send({ ...correlation, kind: "host_ready" }));
+	socket.on("data", data => {
+		let messages: ChildHostMessage[];
+		try { messages = decoder.push(data); } catch { socket.destroy(); return; }
+		for (const message of messages) {
+			if (message.runId !== config.runId || message.childId !== config.childId) { socket.destroy(); return; }
+			if (message.kind === "shutdown_host") {
+				if (active || stopping) { socket.destroy(); return; }
+				stopping = true; send({ ...correlation, kind: "shutdown_ack" }); socket.end(); return;
+			}
+			if (message.kind !== "start_attempt" || active || stopping) { socket.destroy(); return; }
+			let child: ChildProcess;
+			try { child = spawn(message.command, [...message.args], { cwd: message.cwd, env: message.environment, shell: false, stdio: "inherit", windowsHide: true }); }
+			catch { send({ ...correlation, kind: "attempt_spawn_error", attemptId: message.attemptId }); continue; }
+			active = { attemptId: message.attemptId, process: child };
+			send({ ...correlation, kind: "attempt_started", attemptId: message.attemptId });
+			let settled = false;
+			child.once("error", () => {
+				if (settled) return; settled = true;
+				if (active?.attemptId === message.attemptId) active = undefined;
+				send({ ...correlation, kind: "attempt_spawn_error", attemptId: message.attemptId });
+			});
+			child.once("exit", (status, signal) => {
+				if (settled) return; settled = true;
+				if (active?.attemptId === message.attemptId) active = undefined;
+				send({ ...correlation, kind: "attempt_exited", attemptId: message.attemptId, status, signal });
+			});
+		}
+	});
+	const decoder = new ChildHostFrameDecoder();
+	socket.once("close", () => { terminateActive(); });
+	socket.on("error", () => { process.exitCode = 1; });
+}
+
+if (process.argv.some(argument => argument.endsWith("child-host-runtime.ts"))) runChildHost();

package/src/execution-backend/configured-selection.ts

@@ -0,0 +1,19 @@
+import { selectExecutionBackend } from "./selection.ts";
+import { readProjectExecutionBackend } from "../agents/agents.ts";
+import type { ExtensionConfig } from "../shared/types.ts";
+import type { ExecutionBackendPreparation, ExecutionBackendSelectionResult } from "./selection.ts";
+
+export interface ConfiguredSelectionInput {
+	readonly cwd: string;
+	readonly userConfig: ExtensionConfig;
+	/** @internal Detached coordinator registration loader. */
+	readonly preparation?: ExecutionBackendPreparation;
+}
+
+export async function selectConfiguredExecutionBackend(
+	input: ConfiguredSelectionInput,
+): Promise<ExecutionBackendSelectionResult> {
+	const projectPreference = readProjectExecutionBackend(input.cwd);
+	const preference = projectPreference ?? input.userConfig.executionBackend ?? "auto";
+	return selectExecutionBackend(preference, input.preparation);
+}