@selesai/code 0.13.39 → 0.14.0

package/dist/extensions/pi-subagents/test/unit/codex-exec-adapter.test.ts

@@ -0,0 +1,157 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, it } from "node:test";
+import { discoverAgents, discoverAgentsAll, resolveAgentName } from "../../src/agents/agents.ts";
+import { CODEX_EXEC_ADAPTER_ID, CODEX_EXEC_WRITER_ADAPTER_ID, createCodexExecJsonlParser, resolveCodexExecLaunch } from "../../src/runs/shared/codex-exec-adapter.ts";
+import { externalCliReceiptMetadata, resolveExternalCliRunnerStatus } from "../../src/runs/shared/external-cli-contract.ts";
+import { clearExternalCliPreflightCacheForTests } from "../../src/runs/shared/external-cli-preflight.ts";
+import { runExternalCli } from "../../src/runs/shared/external-cli-runner.ts";
+import { buildWorkflowReceipt, readWorkflowReceipt, writeWorkflowReceipt } from "../../src/workflows/workflow-receipt.ts";
+
+const tempDirs: string[] = [];
+function tempDir(): string {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-codex-exec-"));
+	tempDirs.push(dir);
+	return dir;
+}
+afterEach(() => {
+	clearExternalCliPreflightCacheForTests();
+	for (const dir of tempDirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function fakeCodexScript(dir: string): string {
+	const scriptPath = path.join(dir, "fake-codex.cjs");
+	fs.writeFileSync(scriptPath, String.raw`
++const fs = require("node:fs");
++const args = process.argv.slice(2);
++if (args[0] === "--version") { console.log("codex-cli 0.147.0"); process.exit(0); }
++if (args[0] === "exec" && args[1] === "--help") {
++  console.log("Run Codex non-interactively --json --output-last-message --ephemeral --ignore-user-config --ignore-rules --skip-git-repo-check --sandbox read-only workspace-write --config");
++  process.exit(0);
++}
++let prompt = "";
++process.stdin.on("data", chunk => prompt += chunk);
++process.stdin.on("end", () => {
++  const outputIndex = args.indexOf("--output-last-message");
++  const outputPath = args[outputIndex + 1];
++  if (prompt.includes("malformed")) return process.stdout.write("{bad json}\n");
++  if (prompt.includes("oversized")) return process.stdout.write(JSON.stringify({type:"item.completed", value:"x".repeat(300000)}) + "\n");
++  if (prompt.includes("missing-terminal")) return process.stdout.write(JSON.stringify({type:"turn.started"}) + "\n");
++  if (prompt.includes("failed")) return process.stdout.write(JSON.stringify({type:"turn.failed", error:{message:"fake failure"}}) + "\n");
++  if (!prompt.includes("missing-artifact")) fs.writeFileSync(outputPath, "trusted final message");
++  process.stdout.write(JSON.stringify({type:"thread.started", thread_id:"fake"}) + "\n" + JSON.stringify({type:"turn.completed", usage:{input_tokens:1}}) + "\n");
++});
++`.replace(/^\+/gm, ""), "utf-8");
+	return scriptPath;
+}
+
+async function runFake(dir: string, stepIndex: number, prompt: string, adapter: typeof CODEX_EXEC_ADAPTER_ID | typeof CODEX_EXEC_WRITER_ADAPTER_ID = CODEX_EXEC_ADAPTER_ID) {
+	const scriptPath = fakeCodexScript(dir);
+	const launch = resolveCodexExecLaunch({ adapter, command: process.execPath, commandPrefixArgs: [scriptPath], asyncDir: dir, stepIndex });
+	const result = await runExternalCli({ ...launch, cwd: dir, prompt, asyncDir: dir, stepIndex });
+	return { launch, result };
+}
+
+describe("Codex exec adapter", () => {
+	it("owns safe argv, stdin delivery, preflight, terminal proof, and final-message output", async () => {
+		const dir = tempDir();
+		const { launch, result } = await runFake(dir, 0, "review $HOME; echo nope");
+		assert.deepEqual(launch.args.slice(1), [
+			"exec", "--json", "--color", "never", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--skip-git-repo-check", "-s", "read-only",
+			"-c", 'approval_policy="never"', "--output-last-message", launch.finalOutputPath, "-",
+		]);
+		assert.equal(launch.args.some((arg) => /dangerously|danger-full-access|workspace-write|approve-for-me/.test(arg)), false);
+		assert.equal(result.exitCode, 0);
+		assert.equal(result.output, "trusted final message");
+		assert.equal(result.parserTerminal?.state, "completed");
+		assert.equal(result.preflight?.version, "codex-cli 0.147.0");
+		assert.equal(result.externalProcess.finalOutputPath, launch.finalOutputPath);
+		assert.equal(fs.readFileSync(launch.finalOutputPath, "utf-8"), "trusted final message");
+	});
+
+	it("owns explicit workspace-write argv without bypass or extra writable roots", async () => {
+		const dir = tempDir();
+		const { launch, result } = await runFake(dir, 8, "write the requested file", CODEX_EXEC_WRITER_ADAPTER_ID);
+		assert.deepEqual(launch.args.slice(1), [
+			"exec", "--json", "--color", "never", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--skip-git-repo-check", "-s", "workspace-write",
+			"-c", 'approval_policy="never"', "--output-last-message", launch.finalOutputPath, "-",
+		]);
+		assert.equal(launch.args.some((arg) => /danger-full-access|dangerously|approve-for-me|--add-dir/.test(arg)), false);
+		assert.equal(result.exitCode, 0);
+		assert.equal(result.output, "trusted final message");
+	});
+
+	it("fails closed on malformed, oversized, failed, missing terminal, and missing final artifacts", async () => {
+		const dir = tempDir();
+		for (const [index, prompt, pattern] of [
+			[1, "malformed", /malformed JSONL/],
+			[2, "oversized", /line exceeded/],
+			[3, "failed", /fake failure/],
+			[4, "missing-terminal", /did not produce a terminal state/],
+			[5, "missing-artifact", /did not write its final-message artifact/],
+		] as const) {
+			const { result } = await runFake(dir, index, prompt);
+			assert.equal(result.exitCode, 1, prompt);
+			assert.match(result.error ?? "", pattern, prompt);
+		}
+	});
+
+	it("rejects unsupported version and incomplete help during launch preflight", () => {
+		const dir = tempDir();
+		const launch = resolveCodexExecLaunch({ adapter: CODEX_EXEC_ADAPTER_ID, command: "codex", asyncDir: dir, stepIndex: 6 });
+		const evidence = { binaryPath: "/tmp/codex", binaryMtimeMs: 1, version: "codex-cli 0.147.0", help: "Run Codex non-interactively --json --output-last-message --ephemeral --ignore-user-config --ignore-rules --skip-git-repo-check --sandbox read-only --config", cacheHit: false };
+		assert.throws(() => launch.preflight.validate?.({ ...evidence, version: "Codex unknown" }), /Unsupported Codex version response/);
+		assert.throws(() => launch.preflight.validate?.({ ...evidence, help: "Run Codex non-interactively --json" }), /does not document required option/);
+	});
+
+	it("removes a stale final-message artifact before launch", () => {
+		const dir = tempDir();
+		const finalPath = path.join(dir, "external-7.final-message.txt");
+		fs.writeFileSync(finalPath, "stale output");
+		const launch = resolveCodexExecLaunch({ adapter: CODEX_EXEC_ADAPTER_ID, command: "codex", asyncDir: dir, stepIndex: 7 });
+		assert.equal(launch.finalOutputPath, finalPath);
+		assert.equal(fs.existsSync(finalPath), false);
+	});
+
+	it("rejects duplicate terminal events and oversized final-message artifacts", () => {
+		const dir = tempDir();
+		const finalPath = path.join(dir, "final.txt");
+		const duplicate = createCodexExecJsonlParser(finalPath);
+		duplicate.parseLine('{"type":"turn.completed"}');
+		assert.throws(() => duplicate.parseLine('{"type":"turn.completed"}'), /after its terminal state/);
+		fs.writeFileSync(finalPath, "x".repeat(1024 * 1024 + 1));
+		assert.throws(() => duplicate.finish(), /artifact exceeded/);
+	});
+
+	it("publishes compact Codex safety and final-message receipt metadata", () => {
+		const runner = resolveExternalCliRunnerStatus({ adapter: "codex-exec", command: "codex" });
+		const metadata = externalCliReceiptMetadata({
+			runner,
+			externalProcess: { startedAt: 1, stdoutPath: "/tmp/stdout", stderrPath: "/tmp/stderr", finalOutputPath: "/tmp/final" },
+		});
+		const receipt = buildWorkflowReceipt({
+			workflowRunId: "codex-workflow",
+			state: "complete",
+			children: [{ key: "codex", ok: true, output: "done", resumability: { state: "not-resumable", reason: metadata.nonResumableReason }, continuation: { runIds: [] }, externalAdapter: metadata, results: [], artifactPaths: [] }],
+		});
+		assert.equal(receipt.entries.codex?.externalAdapter?.adapter.id, "codex-exec");
+		assert.deepEqual(receipt.entries.codex?.externalAdapter?.safety, { sandbox: "read-only", approvalPolicy: "never", ephemeral: true });
+		assert.equal(receipt.entries.codex?.externalAdapter?.outputArtifacts?.finalOutputPath, "/tmp/final");
+		assert.doesNotMatch(JSON.stringify(receipt), /trusted final message|turn\.completed|rawOutput/);
+		const writer = externalCliReceiptMetadata({ runner: resolveExternalCliRunnerStatus({ adapter: "codex-exec-writer", command: "codex" }) });
+		assert.deepEqual(writer.safety, { access: "workspace-write", sandbox: "workspace-write", approvalPolicy: "never", ephemeral: true });
+		const writerRoot = tempDir();
+		const writerDir = path.join(writerRoot, "writer");
+		fs.mkdirSync(writerDir);
+		const writerReceipt = buildWorkflowReceipt({
+			workflowRunId: "writer",
+			state: "complete",
+			children: [{ key: "codex", ok: true, output: "done", resumability: { state: "not-resumable", reason: writer.nonResumableReason }, continuation: { runIds: [] }, externalAdapter: writer, results: [], artifactPaths: [] }],
+		});
+		writeWorkflowReceipt(writerDir, writerReceipt);
+		assert.deepEqual(readWorkflowReceipt(writerRoot, "writer").entries.codex?.externalAdapter?.safety, writer.safety);
+	});
+
+});

package/dist/extensions/pi-subagents/test/unit/command-action.test.ts

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { createBashToolDefinition, type ExtensionContext } from "@selesai/code";
+import { commandAction } from "../../src/runs/foreground/command-action.ts";
+import { createChildCommandRuntime } from "../../src/runs/shared/child-commands.ts";
+import { supervisorChannelDir } from "../../src/runs/shared/child-tool-plan.ts";
+import type { SubagentState } from "../../src/shared/types.ts";
+
+const ctx = { sessionManager: { getSessionId: () => "session-1", getSessionFile: () => undefined } } as ExtensionContext;
+function liveState(runId: string): SubagentState {
+	const state = { currentSessionId: "session-1", foregroundControls: new Map(), foregroundRuns: new Map() } as SubagentState;
+	state.currentSessionId = "session-1";
+	state.foregroundControls.set(runId, {
+		runId, sessionId: "session-1", mode: "parallel", startedAt: Date.now(), updatedAt: Date.now(),
+		activeChildren: new Map([0, 1].map((index) => [index, { index, agent: "worker", startedAt: Date.now(), updatedAt: Date.now() }])),
+	});
+	return state;
+}
+
+describe("supervisor command actions", () => {
+	for (const kind of ["foreground", "async"] as const) {
+		it(`targets one command in a ${kind} child`, async () => {
+			const runId = `command-action-${randomUUID()}`;
+			const channel = supervisorChannelDir(runId, "worker", 1);
+			const commands = createChildCommandRuntime(channel);
+			const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-command-action-"));
+			const state = liveState(runId);
+			const target = kind === "foreground" ? { kind, id: runId } : { kind, id: runId, location: { resolvedId: runId, asyncDir: dir, resultPath: null } };
+			if (kind === "async") fs.writeFileSync(path.join(dir, "status.json"), JSON.stringify({ runId, sessionId: "session-1", state: "running", steps: [{ agent: "worker", status: "running" }, { agent: "worker", status: "running" }] }));
+			try {
+				await commands.wrap(createBashToolDefinition(dir)).execute("selected-command", { command: "sleep 10", yieldTimeMs: 0 }, undefined, undefined, ctx);
+				await assert.rejects(commandAction({ state, target, operation: "cancel", toolCallId: "selected-command" }), /explicit child index/);
+				await assert.rejects(commandAction({ state, target, operation: "cancel", index: 1 }), /exact toolCallId/);
+				const result = await commandAction({ state, target, operation: "status", index: 1, toolCallId: "selected-command" });
+				assert.equal(result.details.commands?.[0].state, "yielded");
+				state.currentSessionId = "different-session";
+				await assert.rejects(commandAction({ state, target, operation: "cancel", index: 1, toolCallId: "selected-command" }), /not owned by this session/);
+				state.currentSessionId = "session-1";
+				await commandAction({ state, target, operation: "cancel", index: 1, toolCallId: "selected-command" });
+				await commands.shutdown();
+				const terminal = await commandAction({ state, target, operation: "status", index: 1 });
+				assert.equal(terminal.details.commands?.[0].state, "cancelled");
+			} finally { await commands.shutdown(); fs.rmSync(channel, { recursive: true, force: true }); fs.rmSync(dir, { recursive: true, force: true }); }
+		});
+	}
+});

package/dist/extensions/pi-subagents/test/unit/compaction-resume.test.ts

@@ -7,7 +7,7 @@ import { describe, it } from "node:test";
 const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 describe("async compaction resume", () => {
-	it("continues an interactive parent after compaction while async work is active", () => {
+	it("only re-drives manual compaction while async work is active", () => {
 		const script = String.raw`
 			import os from "node:os";
 			import path from "node:path";
@@ -23,7 +23,7 @@ describe("async compaction resume", () => {
 				registerTool() {}, registerCommand() {}, registerShortcut() {}, registerMessageRenderer() {},
 				sendMessage(message, options) { sent.push({ message, options }); }, getSessionName() { return undefined; },
 			}, { get(target, prop) { return prop in target ? target[prop] : () => undefined; } });
-			const ctx = { cwd: process.cwd(), hasUI: true, ui: { setWidget(key, value) { widgets.push([key, value]); }, requestRender() { renders++; }, onTerminalInput() { return () => {}; }, getEditorText() { return ""; }, notify() {}, theme: { fg(_name, text) { return text; }, bg(_name, text) { return text; }, bold(text) { return text; } } }, sessionManager: { getSessionId() { return "compact-session"; }, getSessionFile() { return null; }, getEntries() { return []; } }, modelRegistry: { getAvailable() { return []; } } };
+			const ctx = { cwd: process.cwd(), isIdle() { return false; }, hasUI: true, ui: { setWidget(key, value) { widgets.push([key, value]); }, requestRender() { renders++; }, onTerminalInput() { return () => {}; }, getEditorText() { return ""; }, notify() {}, theme: { fg(_name, text) { return text; }, bg(_name, text) { return text; }, bold(text) { return text; } } }, sessionManager: { getSessionId() { return "compact-session"; }, getSessionFile() { return null; }, getEntries() { return []; } }, modelRegistry: { getAvailable() { return []; } } };
 			registerSubagentExtension(pi);
 			for (const handler of handlers.get("session_start")) await handler({}, ctx);
 			sent.length = 0;
@@ -42,25 +42,36 @@ describe("async compaction resume", () => {
 			for (const handler of handlers.get("agent_start")) await handler();
 			const restored = widgets.filter(([_, value]) => value !== undefined).map(([key]) => key).sort();
 			if (JSON.stringify(restored) !== JSON.stringify(["subagent-async", "subagent-fleet-status"])) throw new Error(JSON.stringify(widgets));
+			if (sent.some((entry) => entry.message?.customType === "subagent-compaction-resume")) throw new Error("resumed after threshold compaction");
+
+			sent.length = 0;
+			widgets.length = 0;
+			for (const handler of handlers.get("session_before_compact")) await handler({ reason: "manual", signal: new AbortController().signal });
+			if (widgets.length !== 0) throw new Error("manual compaction changed widget state");
+			for (const handler of handlers.get("session_compact")) await handler({ reason: "manual" });
 			if (sent.length !== 1 || sent[0].options?.triggerTurn !== true || sent[0].message?.customType !== "subagent-compaction-resume") throw new Error(JSON.stringify(sent));
 
 			sent.length = 0;
 			events.emit("subagent:async-complete", { id: "running-2", sessionId: "compact-session", agent: "worker", success: true, summary: "done" });
-			for (const handler of handlers.get("session_before_compact")) await handler({ reason: "threshold", signal: new AbortController().signal });
-			for (const handler of handlers.get("session_compact")) await handler({ reason: "threshold" });
+			for (const handler of handlers.get("session_before_compact")) await handler({ reason: "manual", signal: new AbortController().signal });
+			for (const handler of handlers.get("session_compact")) await handler({ reason: "manual" });
 			for (const handler of handlers.get("agent_settled")) await handler();
 			if (sent.some((entry) => entry.message?.customType === "subagent-compaction-resume")) throw new Error("resumed without active work");
 
 			events.emit("subagent:async-started", { id: "running-3", pid: 3, sessionId: "compact-session", mode: "single", agent: "worker", asyncDir: path.join(os.tmpdir(), "pi-compaction-test-running-3") });
+			sent.length = 0;
 			widgets.length = 0;
 			for (const handler of handlers.get("session_before_compact")) await handler({ reason: "overflow", signal: new AbortController().signal });
 			widgets.length = 0;
-			for (const handler of handlers.get("agent_settled")) await handler();
-			if (!widgets.some(([_, value]) => value !== undefined)) throw new Error("widgets did not recover after compaction failure");
+			for (const handler of handlers.get("session_compact")) await handler({ reason: "overflow" });
+			if (sent.some((entry) => entry.message?.customType === "subagent-compaction-resume")) throw new Error("resumed after overflow compaction");
+			for (const handler of handlers.get("agent_start")) await handler();
 
 			widgets.length = 0;
-			for (const handler of handlers.get("session_before_compact")) await handler({ reason: "manual", signal: new AbortController().signal });
-			if (widgets.length !== 0) throw new Error("manual compaction changed widget state");
+			for (const handler of handlers.get("session_before_compact")) await handler({ reason: "overflow", signal: new AbortController().signal });
+			widgets.length = 0;
+			for (const handler of handlers.get("agent_settled")) await handler();
+			if (!widgets.some(([_, value]) => value !== undefined)) throw new Error("widgets did not recover after compaction failure");
 			for (const handler of handlers.get("session_shutdown")) await handler();
 		`;
 		const env = { ...process.env };
@@ -74,19 +85,22 @@ describe("async compaction resume", () => {
 			import registerSubagentExtension from "./index.ts";
 			const handlers = new Map();
 			const events = { listeners: new Map(), on(name, handler) { this.listeners.set(name, handler); return () => this.listeners.delete(name); }, emit(name, payload) { this.listeners.get(name)?.(payload); } };
+			const sent = [];
 			const pi = new Proxy({
 				events,
 				on(name, handler) { handlers.set(name, [...(handlers.get(name) ?? []), handler]); },
 				registerTool() {}, registerCommand() {}, registerShortcut() {}, registerMessageRenderer() {},
-				sendMessage() {}, getSessionName() { return undefined; },
+				sendMessage(message, options) { sent.push({ message, options }); }, getSessionName() { return undefined; },
 			}, { get(target, prop) { return prop in target ? target[prop] : () => undefined; } });
 			let stale = false;
-			const ctx = { cwd: process.cwd(), get hasUI() { if (stale) throw new Error("This extension ctx is stale after session replacement or reload."); return true; }, ui: { setWidget() {}, requestRender() {}, onTerminalInput() { return () => {}; }, getEditorText() { return ""; }, notify() {}, theme: { fg(_name, text) { return text; }, bg(_name, text) { return text; }, bold(text) { return text; } } }, sessionManager: { getSessionId() { return "stale-context-session"; }, getSessionFile() { return null; }, getEntries() { return []; } }, modelRegistry: { getAvailable() { return []; } } };
+			const ctx = { cwd: process.cwd(), isIdle() { return false; }, get hasUI() { if (stale) throw new Error("This extension ctx is stale after session replacement or reload."); return true; }, ui: { setWidget() {}, requestRender() {}, onTerminalInput() { return () => {}; }, getEditorText() { return ""; }, notify() {}, theme: { fg(_name, text) { return text; }, bg(_name, text) { return text; }, bold(text) { return text; } } }, sessionManager: { getSessionId() { return "stale-context-session"; }, getSessionFile() { return null; }, getEntries() { return []; } }, modelRegistry: { getAvailable() { return []; } } };
 			registerSubagentExtension(pi);
 			for (const handler of handlers.get("session_start")) await handler({}, ctx);
+			sent.length = 0;
 			events.emit("subagent:async-started", { id: "running", sessionId: "stale-context-session", mode: "single", agent: "worker", asyncDir: "/tmp/pi-stale-context-running" });
 			stale = true;
-			for (const handler of handlers.get("session_compact")) await handler({ reason: "threshold" });
+			for (const handler of handlers.get("session_compact")) await handler({ reason: "manual" });
+			if (sent.some((entry) => entry.message?.customType === "subagent-compaction-resume")) throw new Error("resumed with stale UI context");
 			for (const handler of handlers.get("session_before_compact")) await handler({ reason: "threshold", signal: new AbortController().signal });
 			for (const handler of handlers.get("session_shutdown")) await handler();
 		`;

package/dist/extensions/pi-subagents/test/unit/completion-replay.test.ts

@@ -37,6 +37,8 @@ describe("completion replay", () => {
 		try {
 			const now = Date.now();
 			recordWaitCompletion(makeState(), "run-a", {
+				runId: "run-a",
+				sessionId: "session-a",
 				agent: "worker",
 				mode: "single",
 				state: "complete",
@@ -302,4 +304,4 @@ describe("completion replay", () => {
 			fs.rmSync(root, { recursive: true, force: true });
 		}
 	});
-});
+});

package/dist/extensions/pi-subagents/test/unit/control-channel.test.ts

@@ -4,6 +4,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { describe, it } from "node:test";
 import {
+	closeStopInbox,
 	closeSteerInbox,
 	consumeInterruptRequest,
 	consumeSteerRequests,
@@ -68,6 +69,23 @@ describe("control channel: request file", () => {
 		}
 	});
 
+	it("removes a stop request if the inbox closes while it is being written", () => {
+		const asyncDir = tmpAsyncDir("pi-control-stop-closing-");
+		try {
+			assert.throws(() => requestAsyncStop(asyncDir, { source: "test" }, {
+				now: () => 1234,
+				write(requestPath, request) {
+					fs.mkdirSync(path.dirname(requestPath), { recursive: true });
+					fs.writeFileSync(requestPath, JSON.stringify(request), "utf-8");
+					closeStopInbox(asyncDir);
+				},
+			}), /Retry stop after runner shutdown is observed/);
+			assert.deepEqual(fs.readdirSync(stopRequestsDir(asyncDir)), []);
+		} finally {
+			cleanup(asyncDir);
+		}
+	});
+
 	it("keeps concurrent stop requests instead of replacing the first one", () => {
 		const asyncDir = tmpAsyncDir("pi-control-stop-queue-");
 		try {

package/dist/extensions/pi-subagents/test/unit/control-notices.test.ts

@@ -77,6 +77,12 @@ describe("subagent control notice delivery", () => {
 		assert.deepEqual(recorder.sent[0]?.options, { triggerTurn: false });
 	});
 
+	it("sends nothing for a deferred supervisor-request status event", () => {
+		const recorder = makeRecorder();
+		handleSubagentControlNotice({ pi: recorder.pi, state: makeState(), visibleControlNotices: new Set(), details: { source: "async", event: needsAttentionEvent({ reason: "supervisor_request" }), noticeDeferred: true } });
+		assert.deepEqual(recorder.sent, []);
+	});
+
 	it("does not queue a foreground notice that Pi could flush after completion", () => {
 		const state = makeState();
 		state.foregroundControls.set("run-1", {
@@ -107,4 +113,4 @@ describe("subagent control notice delivery", () => {
 
 		assert.deepEqual(visible, []);
 	});
-});
+});

package/dist/extensions/pi-subagents/test/unit/cursor-agent-adapter.test.ts

@@ -0,0 +1,220 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, it } from "node:test";
+import { discoverAgents, discoverAgentsAll, resolveAgentName } from "../../src/agents/agents.ts";
+import { CURSOR_AGENT_ADAPTER_ID, CURSOR_AGENT_ENV_ALLOWLIST, CURSOR_AGENT_WRITER_ADAPTER_ID, createCursorAgentJsonlParser, resolveCursorAgentLaunch } from "../../src/runs/shared/cursor-agent-adapter.ts";
+import { externalCliReceiptMetadata, normalizeExternalCliRunnerStatus, resolveExternalCliRunnerStatus } from "../../src/runs/shared/external-cli-contract.ts";
+import { clearExternalCliPreflightCacheForTests } from "../../src/runs/shared/external-cli-preflight.ts";
+import { runExternalCli } from "../../src/runs/shared/external-cli-runner.ts";
+import { buildWorkflowReceipt, readWorkflowReceipt, writeWorkflowReceipt } from "../../src/workflows/workflow-receipt.ts";
+
+const tempDirs: string[] = [];
+function tempDir(): string {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-cursor-agent-"));
+	tempDirs.push(dir);
+	return dir;
+}
+afterEach(() => {
+	clearExternalCliPreflightCacheForTests();
+	for (const dir of tempDirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function fakeCursorScript(dir: string): string {
+	const scriptPath = path.join(dir, "fake-cursor-agent.cjs");
+	fs.writeFileSync(scriptPath, String.raw`
++const fs = require("node:fs");
++const args = process.argv.slice(2);
++if (args[0] === "--version") { console.log("2026.08.11-e8db854"); process.exit(0); }
++if (args[0] === "--help") {
++  console.log("Start the Cursor Agent --print Has access to all tools, including write and shell --output-format text | json | stream-json --mode <mode> ask: Q&A read-only --sandbox <mode> enabled --workspace <path-or-name> --add-dir <path>");
++  process.exit(0);
++}
++let stdin = "";
++process.stdin.on("data", chunk => stdin += chunk);
++process.stdin.on("end", () => {
++  if (stdin) { console.error("unexpected stdin prompt"); process.exit(2); }
++  const shortPrompt = args.at(-1) || "";
++  const match = /^Read the complete handoff from the private file at (.+)\. Follow it and return only the final answer\.$/.exec(shortPrompt);
++  if (!match) { console.error("unsafe argv prompt"); process.exit(2); }
++  const prompt = fs.readFileSync(match[1], "utf-8");
++  if (prompt.includes("hang")) return setInterval(() => {}, 1000);
++  if (prompt.includes("malformed")) return process.stdout.write("{bad json}\n");
++  if (prompt.includes("missing-terminal")) return process.stdout.write(JSON.stringify({type:"assistant",message:{content:[{type:"text",text:"partial"}]}}) + "\n");
++  if (prompt.includes("oversized-tool-call") && !prompt.includes("post-terminal-oversized-tool-call")) process.stdout.write(JSON.stringify({type:"tool_call",subtype:"completed",tool_call:{name:"write",args:"x".repeat(300 * 1024)}}) + "\n");
++  if (prompt.includes("post-terminal-oversized-tool-call")) return process.stdout.write(JSON.stringify({type:"result",subtype:"success",is_error:false,result:"trusted final result"}) + "\n" + JSON.stringify({type:"tool_call",subtype:"completed",tool_call:{name:"write",args:"x".repeat(300 * 1024)}}) + "\n");
++  if (prompt.includes("error-event")) return process.stdout.write(JSON.stringify({type:"error",message:"fake auth failure"}) + "\n");
++  if (prompt.includes("failed-result")) return process.stdout.write(JSON.stringify({type:"result",subtype:"error_during_execution",is_error:true,result:"fake failure"}) + "\n");
++  if (prompt.includes("missing-text")) return process.stdout.write(JSON.stringify({type:"result",subtype:"success",is_error:false,result:""}) + "\n");
++  process.stdout.write(JSON.stringify({type:"system",subtype:"init",permissionMode:"default"}) + "\n");
++  process.stdout.write(JSON.stringify({type:"future_event",value:true}) + "\n");
++  process.stdout.write(JSON.stringify({type:"assistant",message:{role:"assistant",content:[{type:"text",text:"untrusted partial"}]}}) + "\n");
++  process.stdout.write(JSON.stringify({type:"result",subtype:"success",is_error:false,result:"trusted final result"}) + "\n");
++});
++`.replace(/^\+/gm, ""), "utf-8");
+	return scriptPath;
+}
+
+async function runFake(workspace: string, stateDir: string, stepIndex: number, prompt: string, adapter: typeof CURSOR_AGENT_ADAPTER_ID | typeof CURSOR_AGENT_WRITER_ADAPTER_ID = CURSOR_AGENT_ADAPTER_ID, registerStop?: (stop: (() => void) | undefined) => void) {
+	const scriptPath = fakeCursorScript(stateDir);
+	const launch = resolveCursorAgentLaunch({ adapter, command: process.execPath, commandPrefixArgs: [scriptPath], cwd: workspace, asyncDir: stateDir, stepIndex });
+	const result = await runExternalCli({ ...launch, cwd: workspace, prompt, asyncDir: stateDir, stepIndex, registerStop });
+	return { launch, result };
+}
+
+describe("Cursor Agent adapter", () => {
+	it("owns read-only argv, private prompt-file delivery, and terminal proof", async () => {
+		const workspace = tempDir();
+		const stateDir = tempDir();
+		const secretPrompt = "review PRIVATE_HANDOFF_TEXT; echo nope";
+		const { launch, result } = await runFake(workspace, stateDir, 0, secretPrompt);
+		assert.deepEqual(launch.args.slice(1, -1), [
+			"-p", "--output-format", "stream-json", "--mode", "ask", "--sandbox", "enabled",
+			"--workspace", workspace, "--add-dir", path.dirname(launch.promptFilePath),
+		]);
+		assert.match(launch.args.at(-1) ?? "", /handoff\.txt/);
+		assert.equal(launch.args.some((arg) => arg.includes("PRIVATE_HANDOFF_TEXT")), false);
+		assert.equal(launch.args.some((arg) => /--force|--yolo|--auto-review|--approve-mcps|--plugin-dir|--resume|--continue|--worktree|--trust/.test(arg)), false);
+		assert.equal((CURSOR_AGENT_ENV_ALLOWLIST as readonly string[]).includes("CURSOR_API_ENDPOINT"), false);
+		assert.equal(result.exitCode, 0);
+		assert.equal(result.output, "trusted final result");
+		assert.equal(result.parserTerminal?.state, "completed");
+		assert.equal(result.preflight?.version, "2026.08.11-e8db854");
+		assert.equal(fs.existsSync(launch.promptFilePath), false);
+		assert.equal(fs.existsSync(launch.temporaryDirectories[0]!), false);
+	});
+
+	it("owns explicit writer argv without bypass, session reuse, or user roots", async () => {
+		const workspace = tempDir();
+		const stateDir = tempDir();
+		const { launch, result } = await runFake(workspace, stateDir, 1, "write the requested file", CURSOR_AGENT_WRITER_ADAPTER_ID);
+		assert.deepEqual(launch.args.slice(1, -1), [
+			"-p", "--output-format", "stream-json", "--sandbox", "enabled",
+			"--workspace", workspace, "--add-dir", path.dirname(launch.promptFilePath),
+		]);
+		assert.equal(launch.args.includes("--mode"), false);
+		assert.equal(launch.args.some((arg) => /--force|--yolo|--auto-review|--approve-mcps|--plugin-dir|--resume|--continue|--worktree|--trust/.test(arg)), false);
+		assert.equal(result.exitCode, 0);
+		assert.equal(result.output, "trusted final result");
+		assert.equal(fs.existsSync(launch.temporaryDirectories[0]!), false);
+	});
+
+	it("skips a bounded oversized non-terminal tool call before terminal proof", async () => {
+		const workspace = tempDir();
+		const stateDir = tempDir();
+		const { result } = await runFake(workspace, stateDir, 2, "oversized-tool-call", CURSOR_AGENT_WRITER_ADAPTER_ID);
+		assert.equal(result.exitCode, 0);
+		assert.equal(result.output, "trusted final result");
+		assert.deepEqual(result.parserTerminal, { state: "completed", output: "trusted final result" });
+	});
+
+	it("fails closed on an oversized tool call after terminal proof", async () => {
+		const workspace = tempDir();
+		const stateDir = tempDir();
+		const { result } = await runFake(workspace, stateDir, 3, "post-terminal-oversized-tool-call", CURSOR_AGENT_WRITER_ADAPTER_ID);
+		assert.equal(result.exitCode, 1);
+		assert.match(result.error ?? "", /line exceeded/);
+		assert.equal(result.parserTerminal, undefined);
+	});
+
+	it("adds no extra root when the prompt directory is inside the workspace", () => {
+		const workspace = tempDir();
+		const launch = resolveCursorAgentLaunch({ adapter: CURSOR_AGENT_ADAPTER_ID, command: "cursor-agent", cwd: workspace, asyncDir: workspace, stepIndex: 2 });
+		assert.equal(launch.args.includes("--add-dir"), false);
+	});
+
+	it("fails closed on malformed, error, failed result, missing terminal, missing text, and post-terminal output", async () => {
+		const workspace = tempDir();
+		const stateDir = tempDir();
+		for (const [index, prompt, pattern] of [
+			[3, "malformed", /malformed JSONL/],
+			[4, "error-event", /fake auth failure/],
+			[5, "failed-result", /fake failure/],
+			[6, "missing-terminal", /did not produce a terminal state/],
+			[7, "missing-text", /terminal result success/],
+		] as const) {
+			const { launch, result } = await runFake(workspace, stateDir, index, prompt);
+			assert.equal(result.exitCode, 1, prompt);
+			assert.match(result.error ?? "", pattern, prompt);
+			assert.equal(fs.existsSync(launch.temporaryDirectories[0]!), false, prompt);
+		}
+		const parser = createCursorAgentJsonlParser();
+		parser.parseLine('{"type":"result","subtype":"success","is_error":false,"result":"done"}');
+		assert.throws(() => parser.parseLine('{"type":"assistant"}'), /after its terminal state/);
+	});
+
+	it("rejects unsupported versions and incomplete help", () => {
+		const workspace = tempDir();
+		const stateDir = tempDir();
+		const launch = resolveCursorAgentLaunch({ adapter: CURSOR_AGENT_ADAPTER_ID, command: "cursor-agent", cwd: workspace, asyncDir: stateDir, stepIndex: 8 });
+		const help = "Start the Cursor Agent --print stream-json --mode <mode> ask: Q&A read-only --sandbox <mode> enabled --workspace <path-or-name> --add-dir <path>";
+		const evidence = { binaryPath: "/tmp/cursor-agent", binaryMtimeMs: 1, version: "2026.08.11-e8db854", help, cacheHit: false };
+		assert.doesNotThrow(() => launch.preflight.validate?.(evidence));
+		assert.throws(() => launch.preflight.validate?.({ ...evidence, version: "Cursor unknown" }), /Unsupported Cursor Agent version response/);
+		assert.throws(() => launch.preflight.validate?.({ ...evidence, help: "Start the Cursor Agent --print" }), /does not document required option/);
+	});
+
+	it("stops and reaps the fake process while deleting the private prompt directory", async () => {
+		const workspace = tempDir();
+		const stateDir = tempDir();
+		let stop: (() => void) | undefined;
+		const running = runFake(workspace, stateDir, 9, "hang", CURSOR_AGENT_ADAPTER_ID, (next) => { stop = next; });
+		for (let attempt = 0; attempt < 100 && !stop; attempt++) await new Promise((resolve) => setTimeout(resolve, 10));
+		assert.ok(stop, "stop callback was not registered");
+		stop();
+		const { launch, result } = await running;
+		assert.equal(result.stopped, true);
+		assert.equal(result.exitCode, 1);
+		assert.equal(fs.existsSync(launch.temporaryDirectories[0]!), false);
+	});
+
+	it("refuses to overwrite a stale prompt path and preserves the existing directory", async () => {
+		const workspace = tempDir();
+		const stateDir = tempDir();
+		const scriptPath = fakeCursorScript(stateDir);
+		const launch = resolveCursorAgentLaunch({ adapter: CURSOR_AGENT_ADAPTER_ID, command: process.execPath, commandPrefixArgs: [scriptPath], cwd: workspace, asyncDir: stateDir, stepIndex: 10 });
+		fs.mkdirSync(path.dirname(launch.promptFilePath), { mode: 0o700 });
+		fs.writeFileSync(launch.promptFilePath, "stale", { mode: 0o600 });
+		const result = await runExternalCli({ ...launch, cwd: workspace, prompt: "new secret", asyncDir: stateDir, stepIndex: 10 });
+		assert.equal(result.exitCode, 1);
+		assert.match(result.error ?? "", /EEXIST/);
+		assert.equal(fs.readFileSync(launch.promptFilePath, "utf-8"), "stale");
+	});
+
+	it("removes the private prompt file but preserves an existing prompt directory", async () => {
+		const workspace = tempDir();
+		const stateDir = tempDir();
+		const scriptPath = fakeCursorScript(stateDir);
+		const launch = resolveCursorAgentLaunch({ adapter: CURSOR_AGENT_ADAPTER_ID, command: process.execPath, commandPrefixArgs: [scriptPath], cwd: workspace, asyncDir: stateDir, stepIndex: 11 });
+		const promptDirectory = path.dirname(launch.promptFilePath);
+		fs.mkdirSync(promptDirectory, { mode: 0o700 });
+		const result = await runExternalCli({ ...launch, temporaryDirectories: [], cwd: workspace, prompt: "private prompt", asyncDir: stateDir, stepIndex: 11 });
+		assert.equal(result.exitCode, 0);
+		assert.equal(fs.existsSync(launch.promptFilePath), false);
+		assert.deepEqual(fs.readdirSync(promptDirectory), []);
+	});
+
+	it("publishes strict read and writer metadata and loads legacy Grok status", () => {
+		const read = externalCliReceiptMetadata({ runner: resolveExternalCliRunnerStatus({ adapter: "cursor-agent", command: "cursor-agent" }) });
+		const writer = externalCliReceiptMetadata({ runner: resolveExternalCliRunnerStatus({ adapter: "cursor-agent-writer", command: "cursor-agent" }) });
+		assert.deepEqual(read.safety, { access: "read-only", authentication: "cursor-api-key-or-existing-login", mode: "ask", sandbox: "enabled", workspaceTrust: "existing-required", sessionReuse: false });
+		assert.deepEqual(writer.safety, { access: "workspace-write", authentication: "cursor-api-key-or-existing-login", mode: "print", sandbox: "enabled", workspaceTrust: "existing-required", sessionReuse: false });
+		const receipt = buildWorkflowReceipt({
+			workflowRunId: "cursor-workflow",
+			state: "complete",
+			children: [{ key: "cursor", ok: true, output: "done", resumability: { state: "not-resumable", reason: writer.nonResumableReason }, continuation: { runIds: [] }, externalAdapter: writer, results: [], artifactPaths: [] }],
+		});
+		const root = tempDir();
+		const runDir = path.join(root, receipt.workflowRunId);
+		fs.mkdirSync(runDir);
+		writeWorkflowReceipt(runDir, receipt);
+		assert.deepEqual(readWorkflowReceipt(root, receipt.workflowRunId).entries.cursor?.externalAdapter?.safety, writer.safety);
+
+		const legacy = normalizeExternalCliRunnerStatus({ type: "external-cli", command: "grok", args: [], promptDelivery: "prompt-file", adapter: { id: "grok-build", version: 1, executionMode: "one-shot-prompt-file" } });
+		assert.equal(legacy?.adapter.id, "grok-build");
+		assert.equal(legacy?.promptDelivery, "prompt-file");
+		assert.equal(legacy?.capabilities.stop, true);
+	});
+
+});