pi-minimal-dispatch 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,443 @@
+/**
+ * pi-minimal-dispatch — detached lane dispatch with visible state (README.md).
+ * `dispatch`: spawn a wave of detached `timeout … pi --mode json …` lanes, return immediately.
+ * `lanes`: stateless status/kill/collect over the wave's manifest + event streams.
+ * The lane protocol is fixed (`--mode json --no-session -ns`); every variable
+ * knob is configurable (docs/API.md → Configuration).
+ */
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type DispatchConfig, loadConfig } from "./config.ts";
+import {
+	type LaneRecord,
+	type LaneStatus,
+	type Manifest,
+	deriveLane,
+	finalAssistantText,
+	manifestPathFor,
+	parseEvents,
+	pidAlive,
+	psLstart,
+	readManifest,
+	waitForTerminal,
+	writeManifestAtomic,
+} from "./derive.ts";
+import { formatStatusBarSummary, formatWaveStatus } from "./format.ts";
+import { type LaneParams, assertLaneTools, assertSlugs, buildLaneArgs, laneEnv, missingBriefs, resolveExecutable, selectKillTargets } from "./lane.ts";
+
+/** Spawn one lane detached; a failure at any step becomes the record's spawnError, never a throw. */
+function spawnLane(workDir: string, wave: string, lane: LaneParams, cfg: DispatchConfig, timeoutBin: string): LaneRecord {
+	const briefPath = path.resolve(lane.briefPath);
+	const record: LaneRecord = {
+		name: lane.name,
+		briefPath,
+		eventsPath: path.join(workDir, `${wave}-${lane.name}.events.jsonl`),
+		errPath: path.join(workDir, `${wave}-${lane.name}.err`),
+		pid: null,
+		processStart: null,
+		startedAt: new Date().toISOString(),
+		deadlineSec: lane.deadlineSec ?? cfg.deadlineSec,
+		model: lane.model,
+		tools: lane.tools,
+		spawned: false,
+	};
+
+	let outFd = -1;
+	let errFd = -1;
+	try {
+		outFd = fs.openSync(record.eventsPath, "w");
+		errFd = fs.openSync(record.errPath, "w");
+		const args = [
+			timeoutBin,
+			...buildLaneArgs(lane, cfg, record.deadlineSec, Math.ceil(cfg.killGraceMs / 1000)),
+		];
+		const child = spawn(args[0], args.slice(1), {
+			detached: true, // own process group; survives this process's exit
+			stdio: ["ignore", outFd, errFd],
+			env: laneEnv(),
+		});
+		child.unref();
+		child.on("error", (e) => {
+			// Async spawn failure lands after we returned; the cause goes to .err
+			try {
+				fs.appendFileSync(record.errPath, `\n[pi-minimal-dispatch] spawn error: ${e.message}\n`);
+			} catch {}
+		});
+		record.pid = child.pid;
+		const start = psLstart(child.pid!);
+		if (start === "") {
+			// Without a start-time the liveness guard can never match — stop the lane
+			// now rather than record an unmatchable identity.
+			try {
+				process.kill(-child.pid!, "SIGTERM");
+			} catch {}
+			record.spawnError = "could not capture process start-time (ps failed); lane terminated";
+		} else {
+			record.processStart = start;
+			record.spawned = true;
+		}
+	} catch (e: any) {
+		record.spawnError = e.message;
+	} finally {
+		if (outFd !== -1) fs.closeSync(outFd);
+		if (errFd !== -1) fs.closeSync(errFd);
+	}
+	return record;
+}
+
+const dispatchTool = defineTool({
+	name: "dispatch",
+	label: "Dispatch lanes",
+	description:
+		"Spawn detached sub-agent lanes (fresh pi processes) for a wave and return immediately. Each lane runs " +
+		"`timeout -k <graceSec> <deadlineSec> pi --mode json --no-session -ns [flags] @<briefPath>` in its own " +
+		"process group, streaming JSON events to <workDir>/<wave>-<name>.events.jsonl. Lanes survive this " +
+		"session's exit. Write briefs first — one brief file per lane is the lane's entire prompt; " +
+		"lanes run in fresh processes (JSON event mode, no session) with skills unloaded (-ns), " +
+		"a read-only tool default, MCP reach only via a route named in tools (else set mcp: false), " +
+		"and never the dispatch tool itself. Every lane in the call is " +
+		"spawned — the caller bounds the wave. " +
+		"Then poll with the lanes tool; collect artifacts when settled.",
+	parameters: Type.Object({
+		wave: Type.String({ description: "Wave slug (kebab-case, max 64 chars); must not already exist in workDir" }),
+		lanes: Type.Array(
+			Type.Object({
+				name: Type.String({ description: "Lane slug (kebab-case, max 64 chars, unique within the wave)" }),
+				briefPath: Type.String({ description: "Path to the lane's brief file (@file prompt)" }),
+				model: Type.Optional(Type.String({ description: "Pin a model id for this lane; omitted: pi's configured default model — not necessarily the dispatcher session's active model" })),
+				deadlineSec: Type.Optional(Type.Number({ description: "Deadline leash in seconds (config default: 900)", minimum: 1 })),
+				tools: Type.Optional(Type.String({ description: "Tool allowlist for --tools; omitted: 'read,grep,find,ls' — add 'bash' when a lane must run commands (bash can still invoke git). Plain names or mcp__/tool patterns only: +name/-name modifiers, shell quoting, and empty lists are rejected. With mcp enabled, MCP/web tools are reachable only through 'codemode' or 'tool_search' named here ('mcp__server__*' entries declare tools directly only for direct-exposure servers)" })),
+				noExtensions: Type.Optional(Type.Boolean({ description: "Pass -ne (drop extensions incl. MCP)" })),
+				mcp: Type.Optional(Type.Boolean({ description: "Set false to pass --no-mcp (no MCP servers connect). Servers connecting alone grants no reach: with mcp enabled, tools must name 'codemode' or 'tool_search' or dispatch rejects the lane" })),
+			}),
+			{ minItems: 1 },
+		),
+		workDir: Type.Optional(Type.String({ description: "Directory for briefs/events/manifest (config default: .pi/work)" })),
+	}),
+
+	async execute(_id, params) {
+		const cfg = loadConfig();
+		const workDir = path.resolve(params.workDir ?? cfg.workDir);
+		fs.mkdirSync(workDir, { recursive: true });
+		// Slugs are validated before the manifest claim: a post-claim throw would strand the slug.
+		assertSlugs(params.wave, params.lanes.map((l) => l.name));
+
+		// All briefs must exist before anything spawns: report every missing one.
+		const missing = missingBriefs(params.lanes);
+		if (missing.length > 0) {
+			throw new Error(`brief file(s) not found: ${missing.join(", ")} — nothing spawned`);
+		}
+
+		// Tool contracts are validated before the manifest claim: a post-claim throw would strand the slug.
+		assertLaneTools(params.lanes);
+
+		// Claim the wave slug atomically; an existing manifest rejects it.
+		const manifestPath = manifestPathFor(workDir, params.wave);
+		let claimFd: number;
+		try {
+			claimFd = fs.openSync(manifestPath, "wx");
+		} catch (e: any) {
+			if (e.code === "EEXIST") throw new Error(`wave '${params.wave}' already exists (${manifestPath})`);
+			throw e;
+		}
+
+		let timeoutBin: string;
+		try {
+			timeoutBin = resolveExecutable(cfg.timeoutBin);
+			resolveExecutable(cfg.piBin);
+		} catch (e) {
+			fs.closeSync(claimFd);
+			fs.unlinkSync(manifestPath);
+			throw e;
+		}
+
+		const manifest: Manifest = {
+			version: 1,
+			wave: params.wave,
+			workDir,
+			createdAt: new Date().toISOString(),
+			lanes: [],
+		};
+		for (const lane of params.lanes) {
+			manifest.lanes.push(spawnLane(workDir, params.wave, lane, cfg, timeoutBin));
+		}
+
+		try {
+			fs.writeSync(claimFd, JSON.stringify(manifest, null, "\t"));
+			fs.closeSync(claimFd);
+		} catch (e) {
+			// environmental failure after the claim: free the slug and stop already-spawned lanes
+			for (const l of manifest.lanes) {
+				if (l.pid !== null) {
+					try {
+						process.kill(-l.pid, "SIGTERM");
+					} catch {}
+				}
+			}
+			try {
+				fs.closeSync(claimFd);
+			} catch {}
+			fs.unlinkSync(manifestPath);
+			throw e;
+		}
+		trackWave(params.wave, workDir);
+
+		const lines = manifest.lanes.map(
+			(l) =>
+				`  ${l.name}: ${l.spawned ? `pid ${l.pid} (deadline ${l.deadlineSec}s)` : `SPAWN ERROR: ${l.spawnError}`}`,
+		);
+		return {
+			content: [
+				{
+					type: "text",
+					text: `wave '${params.wave}' dispatched — ${manifest.lanes.filter((l) => l.spawned).length}/${manifest.lanes.length} lanes spawned\n${lines.join("\n")}\nmanifest: ${manifestPath}`,
+				},
+			],
+			structuredContent: { wave: params.wave, manifestPath, lanes: manifest.lanes },
+			details: { manifestPath },
+		};
+	},
+});
+
+const lanesTool = defineTool({
+	name: "lanes",
+	label: "Lane status",
+	description:
+		"Observe/control a dispatched wave. action=status (default): per-lane derived state " +
+		"(starting/running/settled/failed + cause spawn|killed|deadline|crashed), turns, run-total usage, " +
+		"stopReason, last-event age, .err tail for crashed lanes. action=wait: hold this call open, " +
+		"re-deriving at the pollMs cadence, until every lane is settled/failed or waitSec (default 300, " +
+		"max 3600) elapses — then return the status table; replaces blind sleep-then-status polling. " +
+		"action=kill: SIGTERM the lane process group " +
+		"(SIGKILL after the configured grace), start-time guarded. action=collect: write each finished lane's final assistant " +
+		"message to <wave>-<name>.md (suspect-flagged on failure/empty/non-clean stopReason); a refusal " +
+		"(running / never spawned) is a successful result with a per-lane reason. Stateless: reads the manifest " +
+		"fresh — works across sessions, including after the dispatcher exited. A collected lane is a path plus " +
+		"`suspect`; `suspect: true` means the artifact is not done — read the file only to judge it, do not paste " +
+		"it back. Discover waves: ls <workDir>/*-manifest.json.",
+	parameters: Type.Object({
+		wave: Type.String({ description: "Wave slug" }),
+		action: Type.Optional(StringEnum(["status", "wait", "kill", "collect"])),
+		waitSec: Type.Optional(Type.Number({ description: "wait action only: max seconds to hold the call open (default 300; 1–3600)", minimum: 1, maximum: 3600 })),
+		workDir: Type.Optional(Type.String({ description: "Directory holding the manifest (config default: .pi/work)" })),
+	}),
+
+	async execute(_id, params, signal) {
+		const cfg = loadConfig();
+		const workDir = path.resolve(params.workDir ?? cfg.workDir);
+		const action = params.action ?? "status";
+		const manifest = readManifest(workDir, params.wave);
+		trackWave(params.wave, workDir);
+
+		if (action === "status") {
+			const now = Date.now();
+			const statuses = manifest.lanes.map((l) => deriveLane(l, now));
+			return {
+				content: [{ type: "text", text: formatWaveStatus(params.wave, statuses) }],
+				structuredContent: { wave: params.wave, lanes: statuses },
+				details: { wave: params.wave },
+			};
+		}
+
+		if (action === "wait") {
+			// A timeout is a normal status result with running lanes, never an error.
+			const statuses = await waitForTerminal(workDir, params.wave, (params.waitSec ?? 300) * 1000, cfg.pollMs, signal);
+			return {
+				content: [{ type: "text", text: formatWaveStatus(params.wave, statuses) }],
+				structuredContent: { wave: params.wave, lanes: statuses },
+				details: { wave: params.wave },
+			};
+		}
+
+		if (action === "kill") {
+			const killed: string[] = [];
+			try {
+				const targets = selectKillTargets(
+					manifest.lanes,
+					(l) => pidAlive(l.pid!, l.processStart), // never signal a reused PID
+					(l) => deriveLane(l, Date.now()).state === "settled",
+				);
+				for (const lane of targets) {
+					try {
+						process.kill(-lane.pid!, "SIGTERM"); // negative = process group (timeout + pi)
+					} catch (e: any) {
+						if (e.code === "ESRCH") continue;
+						throw e;
+					}
+					killed.push(lane.name);
+					lane.killedAt = new Date().toISOString(); // tombstone
+				}
+			} catch (e) {
+				writeManifestAtomic(manifest); // a throw mid-loop must not lose already-stamped tombstones
+				throw e;
+			}
+			if (killed.length > 0) {
+				const deadline = Date.now() + cfg.killGraceMs;
+				while (Date.now() < deadline) {
+					if (signal?.aborted) break;
+					await new Promise((r) => setTimeout(r, 200));
+					const survivors = manifest.lanes.filter(
+						(l) => l.killedAt !== undefined && l.pid !== null && pidAlive(l.pid, l.processStart),
+					);
+					if (survivors.length === 0) break;
+					if (Date.now() + 200 >= deadline) {
+						for (const l of survivors) {
+							try {
+								process.kill(-l.pid!, "SIGKILL");
+							} catch {}
+						}
+					}
+				}
+				writeManifestAtomic(manifest);
+			}
+			const statuses = manifest.lanes.map((l) => deriveLane(l, Date.now()));
+			return {
+				content: [
+					{
+						type: "text",
+						text:
+							`killed: ${killed.length ? killed.join(", ") : "none (nothing eligible)"}\n` +
+							statuses.map((s) => `  ${s.name}: ${s.state}${s.cause ? ` (${s.cause})` : ""}`).join("\n"),
+					},
+				],
+				structuredContent: { wave: params.wave, killed, lanes: statuses },
+				details: { wave: params.wave },
+			};
+		}
+
+		// action === "collect"
+		const results: Array<{ name: string; artifact?: string; suspect?: boolean; reason?: string; stopReason?: string }> = [];
+		for (const lane of manifest.lanes) {
+			const status = deriveLane(lane, Date.now());
+			if (status.cause === "spawn") {
+				results.push({ name: lane.name, reason: "never spawned — refused" });
+				continue;
+			}
+			if (status.state === "running" || status.state === "starting") {
+				results.push({ name: lane.name, reason: "still running — refused" });
+				continue;
+			}
+			const text = finalAssistantText(parseEvents(lane.eventsPath));
+			const suspect = status.state === "failed" || text === "" || status.stopReason !== "stop";
+			const artifact = path.join(workDir, `${params.wave}-${lane.name}.md`);
+			fs.writeFileSync(artifact, text.endsWith("\n") || text === "" ? text : text + "\n");
+			results.push({ name: lane.name, artifact, suspect, stopReason: status.stopReason });
+		}
+		const text = results
+			.map((r) => `  ${r.name}: ${r.artifact ?? r.reason}${r.suspect ? " [SUSPECT]" : ""}${r.stopReason !== undefined ? ` stop:${r.stopReason}` : ""}`)
+			.join("\n");
+		return {
+			content: [{ type: "text", text: `collect wave '${params.wave}':\n${text}` }],
+			structuredContent: { wave: params.wave, results },
+			details: { wave: params.wave },
+		};
+	},
+});
+
+// --- statusbar tracking (in-memory cache; manifest and event files stay authoritative) ---
+
+const STATUS_KEY = "pi-minimal-dispatch";
+
+type UiCtx = { mode: string; ui: { setStatus(key: string, text: string | undefined): void } };
+
+const tracked = new Map<string, string>(); // wave -> workDir
+let pollTimer: ReturnType<typeof setInterval> | null = null;
+let uiCtx: UiCtx | null = null;
+
+function statusBarTick(): void {
+	const ctx = uiCtx;
+	if (ctx === null) return;
+	const all: LaneStatus[] = [];
+	for (const [wave, workDir] of tracked) {
+		if (!fs.existsSync(manifestPathFor(workDir, wave))) {
+			tracked.delete(wave); // the wave was cleaned up
+			continue;
+		}
+		try {
+			const m = readManifest(workDir, wave);
+			all.push(...m.lanes.map((l) => deriveLane(l, Date.now())));
+		} catch {
+			// corrupt manifest/events: skipped this tick — /lanes and the lanes tool surface the error loudly
+		}
+	}
+	const summary = formatStatusBarSummary(all);
+	if (summary === undefined) {
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+		stopPolling();
+	} else {
+		ctx.ui.setStatus(STATUS_KEY, summary);
+	}
+}
+
+function armPolling(): void {
+	if (pollTimer === null && tracked.size > 0 && uiCtx !== null && (uiCtx.mode === "tui" || uiCtx.mode === "rpc")) {
+		pollTimer = setInterval(statusBarTick, loadConfig().pollMs);
+	}
+}
+
+function trackWave(wave: string, workDir: string): void {
+	tracked.set(wave, workDir);
+	armPolling();
+}
+
+function stopPolling(): void {
+	if (pollTimer !== null) {
+		clearInterval(pollTimer);
+		pollTimer = null;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	// A dispatched lane never gets the dispatch tool again — the child marker
+	// keeps this extension out of the lane while the rest of the user's setup loads.
+	if (process.env.PI_MINIMAL_DISPATCH_CHILD === "1") return;
+
+	pi.registerTool(dispatchTool);
+	pi.registerTool(lanesTool);
+
+	pi.on("session_start", (_event, ctx) => {
+		uiCtx = ctx;
+		// session replacement (new/resume/fork) keeps module state: re-arm if waves are still in flight
+		armPolling();
+	});
+
+	pi.on("session_shutdown", () => {
+		stopPolling();
+	});
+
+	pi.registerCommand("lanes", {
+		description: "Show dispatched lane status — /lanes [wave]",
+		getArgumentCompletions: (prefix) => {
+			const hits = [...tracked.keys()].filter((w) => w.startsWith(prefix));
+			return hits.length > 0 ? hits.map((w) => ({ value: w, label: w })) : null;
+		},
+		handler: async (args, ctx) => {
+			const show = (wave: string, workDir: string) =>
+				ctx.ui.notify(formatWaveStatus(wave, readManifest(workDir, wave).lanes.map((l) => deriveLane(l, Date.now()))), "info");
+			try {
+				const wave = args.trim();
+				if (wave === "") {
+					if (tracked.size === 0) {
+						ctx.ui.notify("no waves tracked this session", "info");
+						return;
+					}
+					for (const [w, workDir] of tracked) {
+						try {
+							show(w, workDir);
+						} catch {
+							// a vanished manifest must not hide the remaining waves
+						}
+					}
+					return;
+				}
+				show(wave, tracked.get(wave) ?? path.resolve(loadConfig().workDir));
+			} catch (e: any) {
+				ctx.ui.notify(e.message, "error");
+			}
+		},
+	});
+}

package/src/lane.ts

@@ -0,0 +1,169 @@
+/**
+ * pi-minimal-dispatch lane contract — slug validation, brief validation,
+ * executable resolution, spawn argv construction, and kill-target selection.
+ * Pure Node builtins: importable and testable without the pi host.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { DispatchConfig } from "./config.ts";
+import type { LaneRecord } from "./derive.ts";
+
+export const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/** Tool allowlist used when a lane omits `tools` — read-only by design. */
+export const DEFAULT_LANE_TOOLS = "read,grep,find,ls";
+
+/**
+ * Tools that route a lane to MCP tools whatever the servers' exposure —
+ * `mcp__` entries and the resource tools declare tools only under `direct`
+ * exposure (pi waits for those), which dispatch cannot know in advance.
+ */
+const MCP_REACH_TOOLS = ["codemode", "tool_search"];
+
+/** Lane parameters as they arrive from the dispatch tool. */
+export type LaneParams = {
+	name: string;
+	briefPath: string;
+	model?: string;
+	deadlineSec?: number;
+	tools?: string;
+	noExtensions?: boolean;
+	mcp?: boolean;
+};
+
+/** Validate wave and lane slugs: kebab-case, max 64 chars, unique within the call. */
+export function assertSlugs(wave: string, names: string[]): void {
+	const bad: string[] = [];
+	if (!SLUG.test(wave)) bad.push(`wave '${wave}'`);
+	for (const n of names) if (!SLUG.test(n)) bad.push(`lane '${n}'`);
+	const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+	for (const d of new Set(dupes)) bad.push(`duplicate lane '${d}'`);
+	if (bad.length > 0) throw new Error(`slugs must be kebab-case [a-z0-9-], max 64 chars, unique: ${bad.join(", ")}`);
+}
+
+/** Return every brief path that does not resolve to an existing regular file. */
+export function missingBriefs(lanes: LaneParams[], cwd: string = process.cwd()): string[] {
+	const missing: string[] = [];
+	for (const lane of lanes) {
+		const abs = path.resolve(cwd, lane.briefPath);
+		if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) missing.push(lane.briefPath);
+	}
+	return missing;
+}
+
+/** Resolve an executable on PATH; a directory on PATH is not an executable. */
+export function resolveExecutable(name: string): string {
+	for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+		if (!dir) continue;
+		const p = path.join(dir, name);
+		try {
+			if (!fs.statSync(p).isFile()) continue;
+			fs.accessSync(p, fs.constants.X_OK);
+			return p;
+		} catch {
+			// keep scanning
+		}
+	}
+	throw new Error(`executable '${name}' not found on PATH`);
+}
+
+/** Parse a `tools` string exactly as pi parses `--tools`: split on commas, trim, drop empties. */
+export function toolEntries(lane: LaneParams): string[] {
+	return (lane.tools ?? DEFAULT_LANE_TOOLS)
+		.split(",")
+		.map((s) => s.trim())
+		.filter((e) => e !== "");
+}
+
+/** Whether a `--tools` entry matches a tool name — exact, or a `*` pattern anchored both ends (pi's matcher). */
+function entryMatches(entry: string, name: string): boolean {
+	if (!entry.includes("*")) return entry === name;
+	const source = entry.split("*").map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+	return new RegExp(`^${source}$`).test(name);
+}
+
+/**
+ * Validate every lane's `tools` at the tool boundary. An allowlist names plain
+ * tools or `*` patterns — `+name`/`-name` lists are not allowlists: pi applies
+ * them to its default selection and would silently grant `bash`/`edit`/`write`.
+ * A lane that leaves MCP enabled must name `codemode` or `tool_search`, else
+ * its connected servers stay unreachable dead weight.
+ */
+export function assertLaneTools(lanes: LaneParams[]): void {
+	const problems: string[] = [];
+	for (const lane of lanes) {
+		const entries = toolEntries(lane);
+		const modifiers = entries.filter((e) => e.startsWith("+") || e.startsWith("-"));
+		if (modifiers.length > 0) {
+			problems.push(
+				`lane '${lane.name}': tools must be a plain allowlist, not +name/-name modifiers (${modifiers.join(", ")}) — ` +
+					"modifiers apply to pi's default selection and silently grant bash/edit/write; list every tool instead",
+			);
+			continue;
+		}
+		const quoted = entries.filter((e) => e.includes("'") || e.includes('"'));
+		if (quoted.length > 0) {
+			problems.push(
+				`lane '${lane.name}': tools entries must not carry shell quoting (${quoted.join(", ")}) — ` +
+					"the allowlist is one argv value and pi takes entries verbatim, so a quoted name matches no tool; write read, not 'read'",
+			);
+			continue;
+		}
+		if (entries.length === 0) {
+			problems.push(`lane '${lane.name}': tools allowlist is empty — name at least one tool`);
+			continue;
+		}
+		if (lane.mcp === false || lane.noExtensions === true) continue; // MCP never connects
+		const hasRoute = entries.some((e) => MCP_REACH_TOOLS.some((t) => entryMatches(e, t)));
+		if (!hasRoute) {
+			problems.push(
+				`lane '${lane.name}': MCP left enabled but tools '${lane.tools ?? DEFAULT_LANE_TOOLS}' grants no route to MCP tools — ` +
+					"name 'codemode' or 'tool_search' (an 'mcp__server__*' entry alone reaches only direct-exposure servers; pair it with codemode), " +
+					"or set mcp:false — entries reach pi verbatim, no shell quoting",
+			);
+		}
+	}
+	if (problems.length > 0) throw new Error(problems.join("\n"));
+}
+
+/**
+ * Build the lane argv: `timeout -k <graceSec> <deadlineSec> pi --mode json
+ * --no-session -ns [flags] @<brief>`. The json/no-session/-ns triple is the
+ * fixed lane protocol (lanes never load skills); everything variable is a
+ * parameter or config knob. `-k` escalates a caught SIGTERM to SIGKILL so a
+ * stalled dispose cannot outlive the leash. Omitted `tools` defaults to a
+ * read-only allowlist — a lane must be granted `bash`/`edit`/`write` explicitly.
+ */
+export function buildLaneArgs(lane: LaneParams, cfg: Pick<DispatchConfig, "piBin">, deadlineSec: number, killGraceSec: number): string[] {
+	return [
+		"-k",
+		String(killGraceSec),
+		String(deadlineSec),
+		cfg.piBin,
+		"--mode",
+		"json",
+		"--no-session",
+		"-ns",
+		...(lane.noExtensions ? ["-ne"] : []),
+		"--tools",
+		lane.tools ?? DEFAULT_LANE_TOOLS,
+		...(lane.mcp === false ? ["--no-mcp"] : []),
+		...(lane.model ? ["--model", lane.model] : []),
+		`@${path.resolve(lane.briefPath)}`,
+	];
+}
+
+/**
+ * Child env: marks the process as a dispatched lane so this extension's
+ * factory stays out of it — a lane never gets the `dispatch` tool again.
+ * `-ne` remains the switch that drops all extensions.
+ */
+export function laneEnv(): NodeJS.ProcessEnv {
+	return { ...process.env, PI_MINIMAL_DISPATCH_CHILD: "1" };
+}
+
+/** Lanes eligible for a kill signal: spawned, alive by the caller's check, not settled. */
+export function selectKillTargets(lanes: LaneRecord[], isAlive: (lane: LaneRecord) => boolean, isSettled: (lane: LaneRecord) => boolean): LaneRecord[] {
+	return lanes.filter((lane) => lane.pid !== null && lane.spawned && isAlive(lane) && !isSettled(lane));
+}