@selesai/code 0.13.13 → 0.13.14

package/dist/extensions/pi-subagents/test/integration/slash-live-state.test.ts

@@ -0,0 +1,166 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+interface SlashLiveStateModule {
+	applySlashUpdate?: typeof import("../../src/slash/slash-live-state.ts").applySlashUpdate;
+	buildSlashInitialResult?: typeof import("../../src/slash/slash-live-state.ts").buildSlashInitialResult;
+	clearSlashSnapshots?: typeof import("../../src/slash/slash-live-state.ts").clearSlashSnapshots;
+	finalizeSlashResult?: typeof import("../../src/slash/slash-live-state.ts").finalizeSlashResult;
+	getSlashRenderableSnapshot?: typeof import("../../src/slash/slash-live-state.ts").getSlashRenderableSnapshot;
+	restoreSlashFinalSnapshots?: typeof import("../../src/slash/slash-live-state.ts").restoreSlashFinalSnapshots;
+}
+
+let applySlashUpdate: SlashLiveStateModule["applySlashUpdate"];
+let buildSlashInitialResult: SlashLiveStateModule["buildSlashInitialResult"];
+let clearSlashSnapshots: SlashLiveStateModule["clearSlashSnapshots"];
+let finalizeSlashResult: SlashLiveStateModule["finalizeSlashResult"];
+let getSlashRenderableSnapshot: SlashLiveStateModule["getSlashRenderableSnapshot"];
+let restoreSlashFinalSnapshots: SlashLiveStateModule["restoreSlashFinalSnapshots"];
+let available = true;
+try {
+	({
+		applySlashUpdate,
+		buildSlashInitialResult,
+		clearSlashSnapshots,
+		finalizeSlashResult,
+		getSlashRenderableSnapshot,
+		restoreSlashFinalSnapshots,
+	} = await import("../../src/slash/slash-live-state.ts") as SlashLiveStateModule);
+} catch {
+	available = false;
+}
+
+describe("slash live state", { skip: !available ? "slash-live-state.ts not importable" : undefined }, () => {
+	it("streams progress updates into the visible slash snapshot", () => {
+		clearSlashSnapshots!();
+		const details = buildSlashInitialResult!("req-1", {
+			agent: "scout",
+			task: "scan codebase",
+		});
+
+		applySlashUpdate!("req-1", {
+			requestId: "req-1",
+			currentTool: "find",
+			toolCount: 2,
+			progress: [{
+				agent: "scout",
+				status: "running",
+				task: "scan codebase",
+				currentTool: "find",
+				currentToolArgs: '{"pattern":"**/*.ts"}',
+				recentTools: [{ tool: "ls", args: '{"path":"."}', endMs: 10 }],
+				recentOutput: ["src/index.ts", "src/render.ts"],
+				toolCount: 2,
+				tokens: 120,
+				durationMs: 400,
+			}],
+		});
+
+		const snapshot = getSlashRenderableSnapshot!(details);
+		const progress = snapshot.result.details.results[0]?.progress;
+		assert.equal(progress?.currentTool, "find");
+		assert.deepEqual(progress?.recentOutput, ["src/index.ts", "src/render.ts"]);
+		assert.equal(snapshot.version > 0, true);
+	});
+
+	it("marks async initial slash snapshots as background", () => {
+		clearSlashSnapshots!();
+		const details = buildSlashInitialResult!("req-bg", {
+			workflowScript: "return runs.run(\"run\", { agent: \"scout\", task: \"inspect\" })",
+			async: true,
+		});
+
+		assert.equal(details.result.details.mode, "single");
+		assert.equal(details.result.details.background, true);
+		assert.equal(details.result.details.asyncId, undefined);
+	});
+
+	it("does not assign a parallel child update to another chain placeholder", () => {
+		clearSlashSnapshots!();
+		const details = buildSlashInitialResult!("req-parallel", {
+			chain: [{ parallel: [{ agent: "scout", task: "map" }, { agent: "context-builder", task: "analyze" }] }],
+		});
+
+		applySlashUpdate!("req-parallel", {
+			requestId: "req-parallel",
+			progress: [{
+				index: 1,
+				agent: "context-builder",
+				status: "running",
+				task: "analyze",
+				currentTool: "find",
+				recentTools: [],
+				recentOutput: [],
+				toolCount: 38,
+				tokens: 1_000,
+				durationMs: 1_000,
+			}],
+		});
+
+		const results = getSlashRenderableSnapshot!(details).result.details.results;
+		assert.equal(results[0]?.progress?.currentTool, undefined);
+		assert.equal(results[1]?.progress?.currentTool, "find");
+	});
+
+	it("creates stable placeholders for a 40-step worker/reviewer chain", () => {
+		clearSlashSnapshots!();
+		const chain = Array.from({ length: 40 }, (_, index) => ({
+			agent: index % 2 === 0 ? "worker" : "reviewer",
+			...(index === 0 ? { task: "Start long chain" } : {}),
+		}));
+
+		const details = buildSlashInitialResult!("req-long-chain", { chain });
+
+		assert.equal(details.result.details.mode, "chain");
+		assert.equal(details.result.details.results.length, 40);
+		assert.equal(details.result.details.progress?.length, 40);
+		assert.equal(details.result.details.chainAgents?.length, 40);
+		assert.equal(details.result.details.totalSteps, 40);
+		assert.equal(details.result.details.currentStepIndex, 0);
+		assert.equal(details.result.details.results[0]?.progress?.status, "running");
+		assert.equal(details.result.details.results[39]?.agent, "reviewer");
+		assert.equal(details.result.details.results[39]?.progress?.index, 39);
+	});
+
+	it("prefers finalized snapshots and restores them from persisted custom messages", () => {
+		clearSlashSnapshots!();
+		const details = buildSlashInitialResult!("req-2", {
+			agent: "scout",
+			task: "scan codebase",
+		});
+
+		const finalDetails = finalizeSlashResult!({
+			requestId: "req-2",
+			result: {
+				content: [{ type: "text", text: "Done." }],
+				details: {
+					mode: "single",
+					results: [{
+						agent: "scout",
+						task: "scan codebase",
+						exitCode: 0,
+						messages: [],
+						usage: { input: 1, output: 2, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 1 },
+					}],
+				},
+			},
+			isError: false,
+		});
+
+		const liveFinal = getSlashRenderableSnapshot!(details);
+		assert.equal((liveFinal.result.content[0] as { text: string }).text, "Done.");
+
+		clearSlashSnapshots!();
+		restoreSlashFinalSnapshots!([
+			{
+				type: "custom_message",
+				customType: "subagent-slash-result",
+				display: true,
+				details: finalDetails,
+			},
+		]);
+
+		const restored = getSlashRenderableSnapshot!(details);
+		assert.equal((restored.result.content[0] as { text: string }).text, "Done.");
+	});
+});

package/dist/extensions/pi-subagents/test/integration/template-resolution.test.ts

@@ -0,0 +1,344 @@
+/**
+ * Tests for chain template resolution and variable substitution.
+ *
+ * These test the pure logic of how {task}, {previous}, and {chain_dir}
+ * variables get resolved in chain steps. Uses dynamic import since
+ * settings.ts transitively depends on pi packages.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createTempDir, removeTempDir, tryImport } from "../support/helpers.ts";
+
+// Top-level await
+const settings = await tryImport<any>("./src/shared/settings.ts");
+const skills = await tryImport<any>("./src/agents/skills.ts");
+const available = !!(settings && skills);
+
+const resolveChainTemplates = settings?.resolveChainTemplates;
+const buildChainInstructions = settings?.buildChainInstructions;
+const resolveStepBehavior = settings?.resolveStepBehavior;
+const resolveParallelBehaviors = settings?.resolveParallelBehaviors;
+const suppressProgressForReadOnlyTask = settings?.suppressProgressForReadOnlyTask;
+const taskDisallowsFileUpdates = settings?.taskDisallowsFileUpdates;
+const isParallelStep = settings?.isParallelStep;
+const createChainDir = settings?.createChainDir;
+const normalizeSkillInput = skills?.normalizeSkillInput;
+
+describe("resolveChainTemplates", { skip: !available ? "pi packages not available" : undefined }, () => {
+	it("uses step task for first step", () => {
+		const chain = [
+			{ agent: "a", task: "Analyze {task}" },
+			{ agent: "b" },
+		];
+		const templates = resolveChainTemplates(chain);
+		assert.equal(templates[0], "Analyze {task}");
+	});
+
+	it("defaults to {previous} for subsequent steps without task", () => {
+		const chain = [
+			{ agent: "a", task: "Start" },
+			{ agent: "b" },
+			{ agent: "c" },
+		];
+		const templates = resolveChainTemplates(chain);
+		assert.equal(templates[1], "{previous}");
+		assert.equal(templates[2], "{previous}");
+	});
+
+	it("preserves explicit task on later steps", () => {
+		const chain = [
+			{ agent: "a", task: "Start" },
+			{ agent: "b", task: "Custom task for B" },
+		];
+		const templates = resolveChainTemplates(chain);
+		assert.equal(templates[1], "Custom task for B");
+	});
+
+	it("handles parallel steps", () => {
+		const chain = [
+			{
+				parallel: [
+					{ agent: "a", task: "Review auth" },
+					{ agent: "b", task: "Review data" },
+				],
+			},
+		];
+		const templates = resolveChainTemplates(chain);
+		assert.ok(Array.isArray(templates[0]), "parallel step templates should be an array");
+		const parallelTemplates = templates[0] as string[];
+		assert.equal(parallelTemplates[0], "Review auth");
+		assert.equal(parallelTemplates[1], "Review data");
+	});
+
+	it("mixed sequential + parallel", () => {
+		const chain = [
+			{ agent: "scout", task: "Scan" },
+			{
+				parallel: [
+					{ agent: "rev-a", task: "Deep review A" },
+					{ agent: "rev-b" },
+				],
+			},
+			{ agent: "writer" },
+		];
+		const templates = resolveChainTemplates(chain);
+		assert.equal(templates[0], "Scan");
+		assert.ok(Array.isArray(templates[1]));
+		assert.equal(templates[2], "{previous}");
+	});
+});
+
+describe("isParallelStep", { skip: !available ? "pi packages not available" : undefined }, () => {
+	it("returns true for parallel steps", () => {
+		assert.ok(isParallelStep({ parallel: [{ agent: "a", task: "t" }] }));
+	});
+
+	it("returns false for sequential steps", () => {
+		assert.ok(!isParallelStep({ agent: "a", task: "t" }));
+	});
+});
+
+describe("normalizeSkillInput", { skip: !available ? "pi packages not available" : undefined }, () => {
+	it("returns undefined for undefined input", () => {
+		assert.equal(normalizeSkillInput(undefined), undefined);
+	});
+
+	it("returns undefined for true (use default)", () => {
+		assert.equal(normalizeSkillInput(true), undefined);
+	});
+
+	it("returns false for false (disable)", () => {
+		assert.equal(normalizeSkillInput(false), false);
+	});
+
+	it("splits comma-separated string", () => {
+		assert.deepEqual(normalizeSkillInput("web-search,pdf"), ["web-search", "pdf"]);
+	});
+
+	it("passes through array", () => {
+		assert.deepEqual(normalizeSkillInput(["a", "b"]), ["a", "b"]);
+	});
+
+	it("deduplicates", () => {
+		assert.deepEqual(normalizeSkillInput(["a", "b", "a"]), ["a", "b"]);
+	});
+
+	it("trims whitespace", () => {
+		assert.deepEqual(normalizeSkillInput(" a , b "), ["a", "b"]);
+	});
+
+	it("filters empty strings", () => {
+		assert.deepEqual(normalizeSkillInput(",a,,b,"), ["a", "b"]);
+	});
+});
+
+describe("resolveStepBehavior", { skip: !available ? "pi packages not available" : undefined }, () => {
+	it("returns agent defaults when no overrides", () => {
+		// Uses agentConfig.output, .defaultReads, .defaultProgress
+		const config = { name: "test", output: "report.md", defaultProgress: true, defaultReads: ["input.md"] };
+		const behavior = resolveStepBehavior(config, {});
+		assert.equal(behavior.output, "report.md");
+		assert.equal(behavior.progress, true);
+		assert.deepEqual(behavior.reads, ["input.md"]);
+	});
+
+	it("step overrides take precedence", () => {
+		const config = { name: "test", output: "report.md" };
+		const behavior = resolveStepBehavior(config, { output: "custom.md" });
+		assert.equal(behavior.output, "custom.md");
+	});
+
+	it("uses agent outputMode defaults unless a step overrides them", () => {
+		const inlineBehavior = resolveStepBehavior({ name: "test", output: "report.md" }, {});
+		assert.equal(inlineBehavior.outputMode, "inline");
+		assert.equal(resolveStepBehavior({ name: "test", output: "report.md", outputMode: "file-only" }, {}).outputMode, "file-only");
+
+		const stepOverrideBehavior = resolveStepBehavior({ name: "test", output: "report.md", outputMode: "file-only" }, { outputMode: "inline" });
+		assert.equal(stepOverrideBehavior.outputMode, "inline");
+	});
+
+	it("false disables output", () => {
+		const config = { name: "test", output: "report.md" };
+		const behavior = resolveStepBehavior(config, { output: false });
+		assert.equal(behavior.output, false);
+	});
+
+	it("string false disables output defensively", () => {
+		const config = { name: "test", output: "report.md" };
+		const behavior = resolveStepBehavior(config, { output: "false" });
+		assert.equal(behavior.output, false);
+	});
+
+	it("ignores boolean and string true output overrides", () => {
+		const config = { name: "test", output: "report.md" };
+		assert.equal(resolveStepBehavior(config, { output: true }).output, "report.md");
+		assert.equal(resolveStepBehavior(config, { output: "true" }).output, "report.md");
+		assert.equal(resolveStepBehavior({ name: "test" }, { output: true }).output, false);
+		assert.equal(resolveStepBehavior({ name: "test" }, { output: "true" }).output, false);
+	});
+
+	it("defaults to false when agent has no config", () => {
+		const config = { name: "test" };
+		const behavior = resolveStepBehavior(config, {});
+		assert.equal(behavior.output, false);
+		assert.equal(behavior.reads, false);
+		assert.equal(behavior.progress, false);
+	});
+});
+
+describe("resolveParallelBehaviors", { skip: !available ? "pi packages not available" : undefined }, () => {
+	it("uses agent outputMode defaults unless a parallel task overrides them", () => {
+		const [defaultBehavior] = resolveParallelBehaviors(
+			[{ agent: "reviewer", task: "Review" }],
+			[{ name: "reviewer", output: "report.md", outputMode: "file-only" }],
+			0,
+		);
+		assert.equal(defaultBehavior?.outputMode, "file-only");
+
+		const [overrideBehavior] = resolveParallelBehaviors(
+			[{ agent: "reviewer", task: "Review", outputMode: "inline" }],
+			[{ name: "reviewer", output: "report.md", outputMode: "file-only" }],
+			0,
+		);
+		assert.equal(overrideBehavior?.outputMode, "inline");
+	});
+
+	it("string false agent default disables output in chain parallel tasks", () => {
+		const behaviors = resolveParallelBehaviors(
+			[{ agent: "reviewer", task: "Review" }],
+			[{ name: "reviewer", output: "false" }],
+			0,
+		);
+
+		assert.equal(behaviors[0]?.output, false);
+	});
+
+	it("requires truthful context or explicit fallback for missing parallel agents", () => {
+		assert.throws(() => resolveParallelBehaviors([{ agent: "missing", task: "Review" }], [], 0), /requires unknown-agent diagnostic context/);
+		assert.throws(() => resolveParallelBehaviors(
+			[{ agent: "missing", task: "Review" }], [], 0, undefined,
+			{ cwd: process.cwd(), scope: "both" },
+		), /Unknown agent: missing[\s\S]*Effective cwd:[\s\S]*Consulted agent-definition directories/);
+	});
+});
+
+describe("read-only progress suppression", { skip: !available ? "pi packages not available" : undefined }, () => {
+	it("suppresses progress for review-only or no-edit tasks", () => {
+		const behavior = { reads: undefined, output: false, outputMode: "inline", progress: true, skills: undefined };
+
+		assert.equal(taskDisallowsFileUpdates("Review-only. Do not edit files."), true);
+		assert.equal(taskDisallowsFileUpdates("Implement read-only mode for config files."), false);
+		assert.equal(taskDisallowsFileUpdates("This task is not read-only; edit files."), false);
+		assert.equal(suppressProgressForReadOnlyTask(behavior, "Review-only. Do not edit files.").progress, false);
+		assert.equal(suppressProgressForReadOnlyTask(behavior, "{task}", "Review-only. Do not edit files.").progress, false);
+		assert.equal(suppressProgressForReadOnlyTask(behavior, "Implement the approved fix.").progress, true);
+	});
+});
+
+describe("buildChainInstructions", { skip: !available ? "pi packages not available" : undefined }, () => {
+	it("includes existing reads and omits missing reads", () => {
+		const behavior = { reads: ["context.md", "missing.md"], output: false, outputMode: "inline", progress: false, skills: undefined };
+		const dir = createTempDir("chain-test-");
+		try {
+			fs.writeFileSync(path.join(dir, "context.md"), "context");
+			const { prefix } = buildChainInstructions(behavior, dir, false);
+			assert.ok(prefix.includes("[Read from:"), `should have Read instruction: ${prefix}`);
+			assert.ok(prefix.includes("context.md"), "should reference the existing file");
+			assert.doesNotMatch(prefix, /missing\.md/);
+		} finally {
+			removeTempDir(dir);
+		}
+	});
+
+	it("omits the read prefix when all configured reads are missing", () => {
+		const behavior = { reads: ["missing.md"], output: false, outputMode: "inline", progress: false, skills: undefined };
+		const dir = createTempDir("chain-test-");
+		try {
+			assert.doesNotMatch(buildChainInstructions(behavior, dir, false).prefix, /\[Read from:/);
+		} finally {
+			removeTempDir(dir);
+		}
+	});
+
+	it("adds [Write to:] prefix for output", () => {
+		const behavior = { reads: undefined, output: "output.md", outputMode: "inline", progress: false, skills: undefined };
+		const dir = createTempDir("chain-test-");
+		try {
+			const { prefix } = buildChainInstructions(behavior, dir, false);
+			assert.ok(prefix.includes("[Write to:"), `should have Write instruction: ${prefix}`);
+			assert.ok(prefix.includes("output.md"), "should reference the file");
+		} finally {
+			removeTempDir(dir);
+		}
+	});
+
+	it("adds progress instructions in suffix for first progress step", () => {
+		const behavior = { reads: undefined, output: false, outputMode: "inline", progress: true, skills: undefined };
+		const dir = createTempDir("chain-test-");
+		try {
+			const { suffix } = buildChainInstructions(behavior, dir, true);
+			assert.ok(
+				suffix.includes("progress.md"),
+				`should reference progress.md: ${suffix}`,
+			);
+			assert.ok(
+				suffix.includes("Create") || suffix.includes("maintain"),
+				`should say create/maintain for first progress step: ${suffix}`,
+			);
+		} finally {
+			removeTempDir(dir);
+		}
+	});
+
+	it("includes previous output in suffix when not in template", () => {
+		const behavior = { reads: undefined, output: false, outputMode: "inline", progress: false, skills: undefined };
+		const dir = createTempDir("chain-test-");
+		try {
+			const { suffix } = buildChainInstructions(behavior, dir, false, "Previous step output here");
+			assert.ok(
+				suffix.includes("Previous step output here"),
+				"should include previous output",
+			);
+		} finally {
+			removeTempDir(dir);
+		}
+	});
+
+	it("returns empty prefix/suffix when no behavior configured", () => {
+		const behavior = { reads: undefined, output: false, outputMode: "inline", progress: false, skills: undefined };
+		const dir = createTempDir("chain-test-");
+		try {
+			const { prefix, suffix } = buildChainInstructions(behavior, dir, false);
+			assert.equal(prefix, "");
+			assert.equal(suffix, "");
+		} finally {
+			removeTempDir(dir);
+		}
+	});
+});
+
+describe("createChainDir", { skip: !available ? "pi packages not available" : undefined }, () => {
+	it("creates directory with runId", () => {
+		const dir = createChainDir("test-run-123");
+		try {
+			assert.ok(fs.existsSync(dir));
+			assert.ok(dir.includes("test-run-123"));
+		} finally {
+			removeTempDir(dir);
+		}
+	});
+
+	it("uses custom base when provided", () => {
+		const base = createTempDir("chain-base-");
+		try {
+			const dir = createChainDir("run-abc", base);
+			assert.ok(fs.existsSync(dir));
+			assert.ok(dir.startsWith(base) || dir === base);
+		} finally {
+			removeTempDir(base);
+		}
+	});
+});

package/dist/extensions/pi-subagents/test/integration/top-level-async.test.ts

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { tryImport } from "../support/helpers.ts";
+
+interface TopLevelAsyncModule {
+	applyForceTopLevelAsyncOverride<T extends { async?: boolean; clarify?: boolean; foregroundOnly?: boolean }>(
+		params: T,
+		depth: number,
+		forceTopLevelAsync: boolean,
+	): T;
+}
+
+const mod = await tryImport<TopLevelAsyncModule>("./src/runs/background/top-level-async.ts");
+const available = !!mod;
+
+describe("force top-level async helper", { skip: !available ? "pi packages not available" : undefined }, () => {
+	it("forces top-level calls async and disables clarify", () => {
+		const params = { async: false, clarify: true, agent: "worker" };
+		const next = mod!.applyForceTopLevelAsyncOverride(params, 0, true);
+		assert.notEqual(next, params);
+		assert.equal(next.async, true);
+		assert.equal(next.clarify, false);
+		assert.equal(next.agent, "worker");
+	});
+
+	it("keeps bridge-owned foreground calls attached", () => {
+		const params = { async: false, clarify: false, foregroundOnly: true };
+		const next = mod!.applyForceTopLevelAsyncOverride(params, 0, true);
+		assert.equal(next, params);
+	});
+
+	it("leaves nested calls unchanged", () => {
+		const params = { async: false, clarify: true };
+		const next = mod!.applyForceTopLevelAsyncOverride(params, 1, true);
+		assert.equal(next, params);
+	});
+
+	it("leaves top-level calls unchanged when the feature is off", () => {
+		const params = { async: false, clarify: true };
+		const next = mod!.applyForceTopLevelAsyncOverride(params, 0, false);
+		assert.equal(next, params);
+	});
+});

package/dist/extensions/pi-subagents/test/support/cursor-smoke-inputs.ts

@@ -0,0 +1,51 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface CursorSmokeInputs {
+	workspace: string;
+	stateRoot: string;
+	canaryPath: string;
+	promptDirectory: string;
+}
+
+function existingDirectory(value: string | undefined, name: string): string {
+	if (!value?.trim()) throw new Error(`${name} is required.`);
+	try {
+		const resolved = fs.realpathSync(path.resolve(value));
+		if (!fs.statSync(resolved).isDirectory()) throw new Error(`${name} must point to an existing directory.`);
+		return resolved;
+	} catch (error) {
+		if (error instanceof Error && error.message === `${name} must point to an existing directory.`) throw error;
+		throw new Error(`${name} must point to an existing directory.`, { cause: error });
+	}
+}
+
+function pathWithin(parent: string, child: string): boolean {
+	const relative = path.relative(parent, child);
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function cursorSmokeInputs(env: NodeJS.ProcessEnv): CursorSmokeInputs {
+	if (env.SELESAI_SUBAGENTS_CURSOR_SMOKE_DISPOSABLE !== "1") {
+		throw new Error("SELESAI_SUBAGENTS_CURSOR_SMOKE_DISPOSABLE=1 is required to attest that the operator-managed workspace is disposable.");
+	}
+	const workspace = existingDirectory(env.SELESAI_SUBAGENTS_CURSOR_SMOKE_WORKSPACE, "SELESAI_SUBAGENTS_CURSOR_SMOKE_WORKSPACE");
+	const stateRoot = existingDirectory(env.SELESAI_SUBAGENTS_CURSOR_SMOKE_STATE_ROOT, "SELESAI_SUBAGENTS_CURSOR_SMOKE_STATE_ROOT");
+	if (pathWithin(workspace, stateRoot) || pathWithin(stateRoot, workspace)) {
+		throw new Error("Cursor smoke workspace and state root must be separate directories so the production --add-dir launch shape is exercised.");
+	}
+	const canaryPath = path.join(workspace, "pi-subagents-cursor-write-canary.txt");
+	const promptDirectory = path.join(stateRoot, "external-0.cursor-prompt");
+	if (fs.existsSync(canaryPath)) throw new Error(`Cursor smoke canary path must not exist before launch: ${canaryPath}`);
+	let promptDirectoryStatus: fs.Stats;
+	try { promptDirectoryStatus = fs.lstatSync(promptDirectory); }
+	catch (error) { throw new Error(`Cursor smoke prompt directory must be an existing operator-trusted directory: ${promptDirectory}`, { cause: error }); }
+	if (promptDirectoryStatus.isSymbolicLink() || !promptDirectoryStatus.isDirectory()) {
+		throw new Error(`Cursor smoke prompt directory must be an existing directory, not a symlink: ${promptDirectory}`);
+	}
+	if (process.getuid && promptDirectoryStatus.uid !== process.getuid()) {
+		throw new Error(`Cursor smoke prompt directory must be owned by the current operator: ${promptDirectory}`);
+	}
+	if (fs.readdirSync(promptDirectory).length > 0) throw new Error(`Cursor smoke prompt directory must be empty before launch: ${promptDirectory}`);
+	return { workspace, stateRoot, canaryPath, promptDirectory };
+}