@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-subagents/src/runs/shared/codex-exec-adapter.ts

@@ -0,0 +1,129 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseExternalCliJsonlEvent, type ExternalCliParser, type ExternalCliParserProgress, type ExternalCliParserTerminal } from "./external-cli-runner.ts";
+import type { ExternalCliPreflightSpec } from "./external-cli-preflight.ts";
+
+const MAX_FINAL_MESSAGE_BYTES = 1024 * 1024;
+const MAX_EVENT_TYPE_LENGTH = 128;
+
+export const CODEX_EXEC_ADAPTER_ID = "codex-exec" as const;
+export const CODEX_EXEC_WRITER_ADAPTER_ID = "codex-exec-writer" as const;
+export const CODEX_EXEC_ENV_ALLOWLIST = [
+	"PATH",
+	"HOME",
+	"USERPROFILE",
+	"CODEX_HOME",
+	"CODEX_API_KEY",
+	"OPENAI_API_KEY",
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"NO_PROXY",
+	"http_proxy",
+	"https_proxy",
+	"no_proxy",
+	"SSL_CERT_FILE",
+	"SSL_CERT_DIR",
+] as const;
+
+function eventError(event: Record<string, unknown>, fallback: string): string {
+	const error = event.error;
+	if (typeof error === "string" && error.trim()) return error.trim().slice(0, 4_096);
+	if (error && typeof error === "object" && !Array.isArray(error)) {
+		const message = (error as Record<string, unknown>).message;
+		if (typeof message === "string" && message.trim()) return message.trim().slice(0, 4_096);
+	}
+	const message = event.message;
+	return typeof message === "string" && message.trim() ? message.trim().slice(0, 4_096) : fallback;
+}
+
+export function createCodexExecJsonlParser(finalMessagePath: string): ExternalCliParser {
+	let eventCount = 0;
+	let terminal: ExternalCliParserTerminal | undefined;
+	return {
+		parseLine(line): ExternalCliParserProgress {
+			const event = parseExternalCliJsonlEvent(line, "Codex exec", MAX_EVENT_TYPE_LENGTH);
+			if (terminal) throw new Error("Codex exec emitted an event after its terminal state.");
+			eventCount += 1;
+			if (event.type === "turn.completed") terminal = { state: "completed" };
+			else if (event.type === "turn.failed") terminal = { state: "failed", error: eventError(event, "Codex exec reported turn.failed.") };
+			else if (event.type === "error") terminal = { state: "failed", error: eventError(event, "Codex exec reported an error event.") };
+			return { phase: terminal ? terminal.state : "streaming", eventCount };
+		},
+		finish(): ExternalCliParserTerminal | undefined {
+			if (!terminal || terminal.state === "failed") return terminal;
+			let descriptor: number;
+			try { descriptor = fs.openSync(finalMessagePath, "r"); }
+			catch (error) { throw new Error(`Codex exec did not write its final-message artifact: ${error instanceof Error ? error.message : String(error)}`); }
+			try {
+				const stat = fs.fstatSync(descriptor);
+				if (!stat.isFile()) throw new Error("Codex exec final-message artifact is not a file.");
+				if (stat.size > MAX_FINAL_MESSAGE_BYTES) throw new Error("Codex exec final-message artifact exceeded its byte limit.");
+				const content = Buffer.alloc(stat.size);
+				let bytesRead = 0;
+				while (bytesRead < content.length) {
+					const count = fs.readSync(descriptor, content, bytesRead, content.length - bytesRead, bytesRead);
+					if (count === 0) break;
+					bytesRead += count;
+				}
+				const output = content.subarray(0, bytesRead).toString("utf-8").trim();
+				if (!output) throw new Error("Codex exec final-message artifact is empty.");
+				return { state: "completed", output };
+			} finally { fs.closeSync(descriptor); }
+		},
+	};
+}
+
+export function resolveCodexExecLaunch(input: {
+	adapter: typeof CODEX_EXEC_ADAPTER_ID | typeof CODEX_EXEC_WRITER_ADAPTER_ID;
+	command: string;
+	asyncDir: string;
+	stepIndex: number;
+	/** Test-only executable prefix for a fake Codex process. */
+	commandPrefixArgs?: readonly string[];
+}): {
+	command: string;
+	args: string[];
+	finalOutputPath: string;
+	promptFilePath?: undefined;
+	temporaryDirectories?: undefined;
+	environment: { allowlist: readonly string[] };
+	preflight: ExternalCliPreflightSpec;
+	parser: ExternalCliParser;
+} {
+	const writer = input.adapter === CODEX_EXEC_WRITER_ADAPTER_ID;
+	const finalMessagePath = path.join(input.asyncDir, `external-${input.stepIndex}.final-message.txt`);
+	fs.rmSync(finalMessagePath, { force: true });
+	const prefix = [...(input.commandPrefixArgs ?? [])];
+	const args = [
+		...prefix,
+		"exec",
+		"--json",
+		"--color", "never",
+		"--ephemeral",
+		"--ignore-user-config",
+		"--ignore-rules",
+		"--skip-git-repo-check",
+		"-s", writer ? "workspace-write" : "read-only",
+		"-c", 'approval_policy="never"',
+		"--output-last-message", finalMessagePath,
+		"-",
+	];
+	return {
+		command: input.command,
+		args,
+		finalOutputPath: finalMessagePath,
+		environment: { allowlist: CODEX_EXEC_ENV_ALLOWLIST },
+		preflight: {
+			id: input.adapter,
+			versionArgs: [...prefix, "--version"],
+			helpArgs: [...prefix, "exec", "--help"],
+			validate(result) {
+				if (!/^codex-cli \d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(result.version)) throw new Error(`Unsupported Codex version response: ${JSON.stringify(result.version)}.`);
+				for (const required of ["Run Codex non-interactively", "--json", "--output-last-message", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--skip-git-repo-check", "--sandbox", writer ? "workspace-write" : "read-only", "--config"]) {
+					if (!result.help.includes(required)) throw new Error(`Codex exec help does not document required option ${JSON.stringify(required)}.`);
+				}
+			},
+		},
+		parser: createCodexExecJsonlParser(finalMessagePath),
+	};
+}

package/dist/extensions/pi-subagents/src/runs/shared/cursor-agent-adapter.ts

@@ -0,0 +1,114 @@
+import * as path from "node:path";
+import { parseExternalCliJsonlEvent, type ExternalCliParser, type ExternalCliParserProgress, type ExternalCliParserTerminal } from "./external-cli-runner.ts";
+import type { ExternalCliPreflightSpec } from "./external-cli-preflight.ts";
+
+const MAX_EVENT_TYPE_LENGTH = 128;
+const MAX_ERROR_LENGTH = 4_096;
+const MAX_OVERSIZED_TOOL_CALL_BYTES = 1024 * 1024;
+
+export const CURSOR_AGENT_ADAPTER_ID = "cursor-agent" as const;
+export const CURSOR_AGENT_WRITER_ADAPTER_ID = "cursor-agent-writer" as const;
+export const CURSOR_AGENT_ENV_ALLOWLIST = [
+	"PATH",
+	"HOME",
+	"USERPROFILE",
+	"CURSOR_API_KEY",
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"NO_PROXY",
+	"http_proxy",
+	"https_proxy",
+	"no_proxy",
+	"SSL_CERT_FILE",
+	"SSL_CERT_DIR",
+] as const;
+
+function terminalError(event: Record<string, unknown>): string {
+	for (const value of [event.result, event.error, event.message]) {
+		if (typeof value === "string" && value.trim()) return value.trim().slice(0, MAX_ERROR_LENGTH);
+	}
+	const subtype = typeof event.subtype === "string" && event.subtype ? event.subtype : "unknown";
+	return `Cursor Agent reported terminal result ${subtype}.`;
+}
+
+export function createCursorAgentJsonlParser(): ExternalCliParser {
+	let eventCount = 0;
+	let terminal: ExternalCliParserTerminal | undefined;
+	return {
+		parseLine(line): ExternalCliParserProgress {
+			const event = parseExternalCliJsonlEvent(line, "Cursor Agent", MAX_EVENT_TYPE_LENGTH);
+			if (terminal) throw new Error("Cursor Agent emitted an event after its terminal state.");
+			eventCount += 1;
+			if (event.type === "error") terminal = { state: "failed", error: terminalError(event) };
+			else if (event.type === "result") {
+				if (event.subtype === "success" && event.is_error === false && typeof event.result === "string" && event.result.trim()) {
+					terminal = { state: "completed", output: event.result.trim() };
+				} else terminal = { state: "failed", error: terminalError(event) };
+			}
+			return { phase: terminal ? terminal.state : "streaming", eventCount };
+		},
+		skipOversizedLine(prefix, byteLength): ExternalCliParserProgress | undefined {
+			if (terminal || byteLength > MAX_OVERSIZED_TOOL_CALL_BYTES || !/^\s*\{\s*"type"\s*:\s*"tool_call"\s*,/.test(prefix)) return undefined;
+			eventCount += 1;
+			return { phase: "streaming", eventCount };
+		},
+		finish(): ExternalCliParserTerminal | undefined {
+			return terminal;
+		},
+	};
+}
+
+export function resolveCursorAgentLaunch(input: {
+	adapter: typeof CURSOR_AGENT_ADAPTER_ID | typeof CURSOR_AGENT_WRITER_ADAPTER_ID;
+	command: string;
+	cwd: string;
+	asyncDir: string;
+	stepIndex: number;
+	/** Test-only executable prefix for a fake Cursor Agent process. */
+	commandPrefixArgs?: readonly string[];
+}): {
+	command: string;
+	args: string[];
+	finalOutputPath?: undefined;
+	promptFilePath: string;
+	temporaryDirectories: string[];
+	environment: { allowlist: readonly string[] };
+	preflight: ExternalCliPreflightSpec;
+	parser: ExternalCliParser;
+} {
+	const writer = input.adapter === CURSOR_AGENT_WRITER_ADAPTER_ID;
+	const promptDirectory = path.join(input.asyncDir, `external-${input.stepIndex}.cursor-prompt`);
+	const promptFilePath = path.join(promptDirectory, "handoff.txt");
+	const promptRelative = path.relative(input.cwd, promptDirectory);
+	const promptOutsideWorkspace = promptRelative.startsWith("..") || path.isAbsolute(promptRelative);
+	const prefix = [...(input.commandPrefixArgs ?? [])];
+	const args = [
+		...prefix,
+		"-p",
+		"--output-format", "stream-json",
+		...(writer ? [] : ["--mode", "ask"]),
+		"--sandbox", "enabled",
+		"--workspace", input.cwd,
+		...(promptOutsideWorkspace ? ["--add-dir", promptDirectory] : []),
+		`Read the complete handoff from the private file at ${promptFilePath}. Follow it and return only the final answer.`,
+	];
+	return {
+		command: input.command,
+		args,
+		promptFilePath,
+		temporaryDirectories: [promptDirectory],
+		environment: { allowlist: CURSOR_AGENT_ENV_ALLOWLIST },
+		preflight: {
+			id: input.adapter,
+			versionArgs: [...prefix, "--version"],
+			helpArgs: [...prefix, "--help"],
+			validate(result) {
+				if (!/^\d{4}\.\d{2}\.\d{2}-[0-9a-f]+$/.test(result.version)) throw new Error(`Unsupported Cursor Agent version response: ${JSON.stringify(result.version)}.`);
+				for (const required of ["Start the Cursor Agent", "--print", "stream-json", "--sandbox <mode>", "enabled", "--workspace <path-or-name>", "--add-dir <path>", ...(writer ? ["all tools", "including write and shell"] : ["--mode <mode>", "ask:", "read-only"])]) {
+					if (!result.help.includes(required)) throw new Error(`Cursor Agent help does not document required option ${JSON.stringify(required)}.`);
+				}
+			},
+		},
+		parser: createCursorAgentJsonlParser(),
+	};
+}

package/dist/extensions/pi-subagents/src/runs/shared/dynamic-fanout.ts

@@ -46,12 +46,12 @@ const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency
 const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "sessionFiles", "thinkingOverrides"]);
 const DYNAMIC_EXPAND_KEYS = new Set(["from", "item", "key", "maxItems", "onEmpty"]);
 const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
-const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
+const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "machine", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
-	"outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled", "waitToolDefaultTimeoutMs",
-	"structuredOutput", "structuredOutputSchema", "tools", "excludeTools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
-	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions", "requestedCwd",
+	"runner", "outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled", "waitToolDefaultTimeoutMs",
+	"structuredOutput", "structuredOutputSchema", "tools", "excludeTools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "builtinMcpTools", "mutationTools", "capabilityCeiling", "systemPrompt",
+	"systemPromptMode", "thinking", "requestedModel", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "requiredExtensions", "launchResolvedExtensions", "requestedCwd", "machineEnv",
 ]);
 const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);
 
@@ -294,4 +294,4 @@ export async function validateDynamicCollection(schema: JsonSchemaObject | undef
 	if (validation.status === "invalid") {
 		throw new DynamicFanoutError(`Collected output validation failed: ${validation.message}`);
 	}
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/effective-system-prompt.ts

@@ -0,0 +1,33 @@
+import type { AgentConfig } from "../../agents/agents.ts";
+import { buildAgentMemoryInjection } from "../../agents/agent-memory.ts";
+import { appendAgentRefinementOverlay } from "../../agents/agent-refinements.ts";
+import { buildSkillInjection } from "../../agents/skills.ts";
+import { injectOutputPathSystemPrompt } from "./single-output.ts";
+
+export interface EffectiveSystemPromptInput {
+	/** Agent as handed to the child, including runtime-declared overlays such as the Intercom bridge. */
+	agent: AgentConfig;
+	resolvedSkills: Parameters<typeof buildSkillInjection>[0];
+	/** Directory that scopes memory and refinement lookups. */
+	cwd: string;
+	/** Omit when the caller injects the output path through another channel. */
+	outputPath?: string;
+}
+
+function appendSection(prompt: string, section: string): string {
+	return prompt ? `${prompt}\n\n${section}` : section;
+}
+
+/**
+ * Child system prompt in the order preflight and every execution path hash:
+ * base prompt, skills, memory, refinement overlay, output path. Runtime
+ * acceptance prose is appended later and stays outside launch identity.
+ */
+export function buildEffectiveSystemPrompt(input: EffectiveSystemPromptInput): string {
+	let prompt = input.agent.systemPrompt?.trim() ?? "";
+	if (input.resolvedSkills.length > 0) prompt = appendSection(prompt, buildSkillInjection(input.resolvedSkills));
+	const memoryInjection = buildAgentMemoryInjection(input.agent, input.cwd);
+	if (memoryInjection) prompt = appendSection(prompt, memoryInjection);
+	prompt = appendAgentRefinementOverlay(prompt, { cwd: input.cwd, agentName: input.agent.name });
+	return injectOutputPathSystemPrompt(prompt, input.outputPath, input.agent);
+}

package/dist/extensions/pi-subagents/src/runs/shared/external-cli-contract.ts

@@ -2,7 +2,9 @@ import type {
 	ExternalCliReceiptMetadata,
 	ExternalCliCapabilityNarrowing,
 	ExternalCliRunnerStatus,
+	ExternalCliMachineStatus,
 	ExternalProcessStatus,
+	HerdrMachineReference,
 } from "../../shared/types.ts";
 
 const UNSUPPORTED = {
@@ -22,27 +24,43 @@ const PROMPT_FILE_UNSUPPORTED = {
 	resume: "The one-shot prompt-file adapter does not retain a durable external session identity.",
 } as const;
 
-export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS = [] as const;
+export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS = [
+	"codex-exec",
+	"codex-exec-writer",
+	"claude-code",
+	"claude-code-writer",
+	"cursor-agent",
+	"cursor-agent-writer",
+] as const;
 export type CodeOwnedExternalCliAdapterId = typeof CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS[number];
 
 const CODE_OWNED_EXTERNAL_CLI_ADAPTER_ID_SET = new Set<string>(CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS);
-export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL = "(none)";
+export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL = CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS.map((id) => `'${id}'`).join(", ");
 
 export function isCodeOwnedExternalCliAdapterId(value: unknown): value is CodeOwnedExternalCliAdapterId {
 	return typeof value === "string" && CODE_OWNED_EXTERNAL_CLI_ADAPTER_ID_SET.has(value);
 }
 
-const RESERVED_READ_ONLY_ADAPTERS = [] as const;
+const RESERVED_READ_ONLY_ADAPTERS = [
+	{ name: "claude-code", writer: "claude-code-writer", access: "file-write" },
+	{ name: "codex-exec", writer: "codex-exec-writer", access: "workspace-write" },
+	{ name: "cursor-agent", writer: "cursor-agent-writer", access: "workspace-write" },
+] as const;
 
 export function validateCodeOwnedProfileRunner(
-	_agent: {
+	agent: {
 		name: string;
 		localName?: string;
 		aliases?: readonly string[];
 		runner?: { type: string; adapter?: string };
 	},
 ): string | undefined {
-	// With no code-owned adapter profiles bundled, no selection names are reserved.
+	const selectionNames = [agent.name, ...(agent.localName ? [agent.localName] : []), ...(agent.aliases ?? [])];
+	for (const adapter of RESERVED_READ_ONLY_ADAPTERS) {
+		if (selectionNames.includes(adapter.name) && !(agent.runner?.type === "external-cli" && agent.runner.adapter === adapter.name)) {
+			return `Selection name '${adapter.name}' is reserved for the read-only '${adapter.name}' adapter. Use '${adapter.writer}' for explicit ${adapter.access} access.`;
+		}
+	}
 	return undefined;
 }
 
@@ -64,14 +82,29 @@ export function resolveExternalCliRunnerStatus(input: {
 	args?: string[];
 	promptDelivery?: "stdin";
 	capabilities?: ExternalCliCapabilityNarrowing;
+	machine?: HerdrMachineReference;
 }): ExternalCliRunnerStatus {
-	const unsupported = UNSUPPORTED;
+	const codexExec = input.adapter === "codex-exec";
+	const codexExecWriter = input.adapter === "codex-exec-writer";
+	const claudeCode = input.adapter === "claude-code";
+	const claudeCodeWriter = input.adapter === "claude-code-writer";
+	const cursorAgent = input.adapter === "cursor-agent";
+	const cursorAgentWriter = input.adapter === "cursor-agent-writer";
+	const cursor = cursorAgent || cursorAgentWriter;
+	const unsupported = cursor ? PROMPT_FILE_UNSUPPORTED : UNSUPPORTED;
 	return {
 		type: "external-cli",
 		command: input.command,
 		args: input.args ?? [],
-		promptDelivery: input.promptDelivery ?? "stdin",
-		adapter: { id: input.adapter ?? "external-cli", version: 1, executionMode: "one-shot-stdin" },
+		promptDelivery: cursor ? "prompt-file" : input.promptDelivery ?? "stdin",
+		adapter: { id: input.adapter ?? "external-cli", version: 1, executionMode: cursor ? "one-shot-prompt-file" : "one-shot-stdin" },
+		...(codexExec ? { safety: { sandbox: "read-only" as const, approvalPolicy: "never" as const, ephemeral: true as const } } : {}),
+		...(codexExecWriter ? { safety: { access: "workspace-write" as const, sandbox: "workspace-write" as const, approvalPolicy: "never" as const, ephemeral: true as const } } : {}),
+		...(claudeCode ? { safety: { access: "read-only" as const, authentication: "existing-cli-required" as const, permissionMode: "plan" as const, tools: "none" as const, mcp: "empty-strict" as const, settingSources: "user" as const, userSettingsTrust: "required" as const, sessionPersistence: false as const } } : {}),
+		...(claudeCodeWriter ? { safety: { access: "workspace-write" as const, authentication: "existing-cli-required" as const, permissionMode: "acceptEdits" as const, tools: "Read,Write,Edit,Glob,Grep" as const, mcp: "empty-strict" as const, settingSources: "user" as const, userSettingsTrust: "required" as const, sessionPersistence: false as const } } : {}),
+		...(cursorAgent ? { safety: { access: "read-only" as const, authentication: "cursor-api-key-or-existing-login" as const, mode: "ask" as const, sandbox: "enabled" as const, workspaceTrust: "existing-required" as const, sessionReuse: false as const } } : {}),
+		...(cursorAgentWriter ? { safety: { access: "workspace-write" as const, authentication: "cursor-api-key-or-existing-login" as const, mode: "print" as const, sandbox: "enabled" as const, workspaceTrust: "existing-required" as const, sessionReuse: false as const } } : {}),
+		...(input.machine ? { machine: input.machine } : {}),
 		capabilities: {
 			stop: true,
 			steer: false,
@@ -95,6 +128,9 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
 		? input.args
 		: undefined;
 	const promptDelivery = input.promptDelivery === "stdin" ? "stdin" : undefined;
+	const machine = input.machine && typeof input.machine === "object" && !Array.isArray(input.machine)
+		? input.machine as HerdrMachineReference
+		: undefined;
 	const adapterId = input.adapter && typeof input.adapter === "object" && !Array.isArray(input.adapter)
 		? (input.adapter as Record<string, unknown>).id
 		: undefined;
@@ -102,6 +138,7 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
 		return {
 			type: "external-cli",
 			command: input.command,
+			...(machine ? { machine } : {}),
 			args: args ?? [],
 			promptDelivery: "prompt-file",
 			adapter: { id: "grok-build", version: 1, executionMode: "one-shot-prompt-file" },
@@ -111,7 +148,7 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
 		};
 	}
 	const adapter = isCodeOwnedExternalCliAdapterId(adapterId) ? adapterId : undefined;
-	return resolveExternalCliRunnerStatus({ ...(adapter ? { adapter } : {}), command: input.command, ...(args ? { args } : {}), ...(promptDelivery ? { promptDelivery } : {}) });
+	return resolveExternalCliRunnerStatus({ ...(adapter ? { adapter } : {}), command: input.command, ...(args ? { args } : {}), ...(promptDelivery ? { promptDelivery } : {}), ...(machine ? { machine } : {}) });
 }
 
 export function externalCliReceiptMetadata(input: {
@@ -120,9 +157,11 @@ export function externalCliReceiptMetadata(input: {
 	outputReference?: string;
 }): ExternalCliReceiptMetadata {
 	const { runner } = input;
+	const machine: ExternalCliMachineStatus | undefined = input.externalProcess?.machine ?? runner.machine;
 	return {
 		adapter: { ...runner.adapter },
 		capabilities: { ...runner.capabilities },
+		...(machine ? { machine: { ...machine, ...(machine.remoteGit ? { remoteGit: { ...machine.remoteGit } } : {}) } } : {}),
 		...(runner.safety ? { safety: { ...runner.safety } } : {}),
 		...(input.externalProcess ? {
 			outputArtifacts: {
@@ -135,4 +174,4 @@ export function externalCliReceiptMetadata(input: {
 		supervisor: { mode: "unsupported", reason: runner.unsupportedReasons.supervisor },
 		nonResumableReason: runner.nonResumableReason,
 	};
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/external-cli-preflight.ts

@@ -1,9 +1,11 @@
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { resolveNodeExecutable } from "../../shared/node-executable.ts";
 
 const MAX_PROBE_OUTPUT_BYTES = 256 * 1024;
 const MAX_PROBE_TIMEOUT_MS = 5_000;
+const MAX_REMOTE_PROBE_TIMEOUT_MS = 15_000;
 const MAX_CACHE_ENTRIES = 64;
 const MAX_AVAILABILITY_REASON_LENGTH = 256;
 
@@ -16,6 +18,8 @@ export interface ExternalCliPreflightSpec {
 	evidenceArgs?: readonly string[];
 	evidenceLabel?: string;
 	probeTimeoutMs?: number;
+	/** Remote probes include SSH handshakes; values may only narrow the code-owned remote ceiling. */
+	remote?: boolean;
 	validate?: (result: ExternalCliPreflightResult) => void;
 }
 
@@ -37,20 +41,28 @@ export type ExternalCliBinaryAvailability =
 	| { available: true }
 	| { available: false; unavailableReason: string };
 
-function resolveBinary(command: string, env: NodeJS.ProcessEnv): string {
-	if (path.isAbsolute(command) || command.includes(path.sep)) {
+const BATCH_FILE = /\.(cmd|bat)$/i;
+
+function resolveBinary(command: string, env: NodeJS.ProcessEnv, platform: NodeJS.Platform = process.platform): string {
+	const windows = platform === "win32";
+	if (path.isAbsolute(command) || command.includes(path.sep) || (windows && command.includes("/"))) {
 		const resolved = path.resolve(command);
 		fs.accessSync(resolved, fs.constants.X_OK);
 		return resolved;
 	}
-	const extensions = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
-	for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+	// Windows environment names are case-insensitive, and a copied process.env keeps its spelling (often `Path`).
+	const read = (name: string) => windows ? Object.entries(env).find(([key]) => key.toUpperCase() === name)?.[1] : env[name];
+	const pathExt = windows ? (read("PATHEXT") ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean) : [];
+	const named = pathExt.some((extension) => command.toLowerCase().endsWith(extension.toLowerCase()));
+	const extensions = windows ? (named ? ["", ...pathExt] : pathExt) : [""];
+	for (const directory of (read("PATH") ?? "").split(path.delimiter)) {
 		if (!directory) continue;
 		for (const extension of extensions) {
 			const candidate = path.join(directory, `${command}${extension}`);
 			try {
 				fs.accessSync(candidate, fs.constants.X_OK);
-				return fs.realpathSync(candidate);
+				// A batch shim resolves its target from its own directory (%dp0%), so keep the path it was found at.
+				return windows && BATCH_FILE.test(candidate) ? candidate : fs.realpathSync(candidate);
 			} catch {}
 		}
 	}
@@ -68,8 +80,47 @@ export function resolveExternalCliBinaryAvailability(command: string, env: NodeJ
 	}
 }
 
+// npm's cmd-shim output for a `#!/usr/bin/env node` bin, with CRLF normalized; the target path sits between the two parts.
+const NPM_NODE_SHIM_HEAD = '@ECHO off\nGOTO start\n:find_dp0\nSET dp0=%~dp0\nEXIT /b\n:start\nSETLOCAL\nCALL :find_dp0\n\nIF EXIST "%dp0%\\node.exe" (\n  SET "_prog=%dp0%\\node.exe"\n) ELSE (\n  SET "_prog=node"\n  SET PATHEXT=%PATHEXT:;.JS;=;%\n)\n\nendLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%_prog%"  "%dp0%\\';
+const NPM_NODE_SHIM_TAIL = '" %*\n';
+
+export interface ExternalCliSpawn {
+	command: string;
+	args: readonly string[];
+}
+
+/**
+ * Node refuses to spawn `.cmd`/`.bat` files without a shell (CVE-2024-27980), and a shell would expand
+ * `%` and `!` inside operator- and project-controlled arguments. On Windows, an npm Node shim is launched
+ * by running Node on its script directly; every other batch wrapper is rejected.
+ */
+export function resolveExternalCliSpawn(command: string, args: readonly string[], env: NodeJS.ProcessEnv, platform: NodeJS.Platform = process.platform): ExternalCliSpawn {
+	const unchanged = { command, args };
+	if (platform !== "win32") return unchanged;
+	let resolved: string;
+	try {
+		resolved = resolveBinary(command, env, platform);
+	} catch (error) {
+		if (BATCH_FILE.test(command)) throw error;
+		return unchanged;
+	}
+	if (!BATCH_FILE.test(resolved)) return unchanged;
+	const shim = fs.readFileSync(resolved, "utf-8").replace(/\r\n/g, "\n");
+	const target = /\.cmd$/i.test(resolved) && shim.startsWith(NPM_NODE_SHIM_HEAD) && shim.endsWith(NPM_NODE_SHIM_TAIL)
+		? shim.slice(NPM_NODE_SHIM_HEAD.length, shim.length - NPM_NODE_SHIM_TAIL.length)
+		: "";
+	const directory = path.dirname(resolved);
+	const script = path.resolve(directory, target.split("\\").join(path.sep));
+	if (!target || /^\\|["%:/\n]/.test(target) || !fs.statSync(script, { throwIfNoEntry: false })?.isFile()) {
+		throw new Error(`External CLI '${resolved}' is a batch wrapper that cannot run without a shell. On Windows, only npm-generated Node shims and .exe files can launch.`);
+	}
+	const bundledNode = path.join(directory, "node.exe");
+	return { command: fs.existsSync(bundledNode) ? bundledNode : resolveNodeExecutable(), args: [script, ...args] };
+}
+
 function probeWithTimeout(binaryPath: string, args: readonly string[], env: NodeJS.ProcessEnv, label: string, timeoutMs: number, cwd?: string): string {
-	const result = spawnSync(binaryPath, [...args], {
+	const launch = resolveExternalCliSpawn(binaryPath, args, env);
+	const result = spawnSync(launch.command, launch.args, {
 		cwd,
 		env,
 		encoding: "utf-8",
@@ -90,7 +141,7 @@ function narrowPositiveInteger(value: number | undefined, ceiling: number, label
 }
 
 function specKey(spec: ExternalCliPreflightSpec): string {
-	return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs]);
+	return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs, spec.remote === true]);
 }
 
 export function preflightExternalCli(command: string, spec: ExternalCliPreflightSpec, env: NodeJS.ProcessEnv, cwd?: string): ExternalCliPreflightResult {
@@ -99,7 +150,8 @@ export function preflightExternalCli(command: string, spec: ExternalCliPreflight
 	const lookupKey = JSON.stringify([binaryPath, binaryMtimeMs, specKey(spec)]);
 	const cachedKey = lookup.get(lookupKey);
 	const cached = cachedKey ? cache.get(cachedKey) : undefined;
-	const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, MAX_PROBE_TIMEOUT_MS, "probeTimeoutMs");
+	const ceiling = spec.remote === true ? MAX_REMOTE_PROBE_TIMEOUT_MS : MAX_PROBE_TIMEOUT_MS;
+	const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, ceiling, "probeTimeoutMs");
 	const base = cached ?? {
 		binaryPath,
 		binaryMtimeMs,
@@ -135,4 +187,4 @@ export function invalidateExternalCliPreflight(command: string, spec: ExternalCl
 export function clearExternalCliPreflightCacheForTests(): void {
 	cache.clear();
 	lookup.clear();
-}
+}