@agntn/harnesses 0.2.1 → 0.3.0

package/dist/_chunks/prompt-sync.mjs

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { addAbortListener } from "node:events";
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { basename, dirname, extname, isAbsolute, join, posix, relative, resolve, win32 } from "node:path";
@@ -8,13 +8,13 @@ import os, { homedir } from "node:os";
 import { stripVTControlCharacters } from "node:util";
 import { parse } from "smol-toml";
 import { randomUUID } from "node:crypto";
-import { parse as parse$1 } from "yaml";
-const PATH_MARKERS = /^~(?=\/|$)|\$\{HOME\}|\$\{PROJECT_ROOT\}|%([^%]+)%/g;
+const PATH_MARKERS = /^~(?=\/|$)|\$\{HOME\}|\$\{PROJECT_ROOT\}|\$\{TMPDIR\}|%([^%]+)%/g;
 function resolvePathTemplate(template, options = {}) {
 	const homeDir = options.homeDir ?? os.homedir();
 	const projectRoot = options.projectRoot ?? process.cwd();
 	return template.replaceAll(PATH_MARKERS, (match, name) => {
 		if (match === "${PROJECT_ROOT}") return projectRoot;
+		if (match === "${TMPDIR}") return options.tempDir ?? os.tmpdir();
 		if (name === void 0) return homeDir;
 		return process.env[name] ?? match;
 	});
@@ -27,6 +27,11 @@ function agntnDataDir(options = {}) {
 	const base = process.env.XDG_DATA_HOME && process.env.XDG_DATA_HOME !== "" ? process.env.XDG_DATA_HOME : join(options.homeDir ?? os.homedir(), ".local", "share");
 	return join(base, "agntn");
 }
+function moveRoot(path, root, value) {
+	if (path === root) return value;
+	const rest = path.slice(root.length);
+	return path.startsWith(root) && (rest.startsWith("/") || rest.startsWith("\\")) ? value + rest : path;
+}
 const SUPPORTED_PLATFORMS = {
 	linux: true,
 	darwin: true,
@@ -57,6 +62,17 @@ function requestedInvocationMode(options) {
 	if (options.tools === true) return options.structured === true ? "agentStructured" : "agent";
 	return options.structured === true ? "advisorStructured" : "advisor";
 }
+function accessConflictError(id, invocation, options) {
+	if (options.readOnly !== true || options.tools !== false) return null;
+	const retries = [];
+	if (invocationTemplate(invocation, requestedInvocationMode(options))) retries.push("tools: true to keep its read-only tools");
+	if (invocationTemplate(invocation, requestedInvocationMode({
+		...options,
+		readOnly: false
+	}))) retries.push("readOnly: false to use its advisor without tools");
+	const error = `Harness ${id} cannot run readOnly with tools: false, since read-only access still uses tools`;
+	return retries.length === 0 ? error : `${error}; retry with ${retries.join(", or with ")}`;
+}
 function invocationTemplate(invocation, mode) {
 	switch (mode) {
 		case "advisor": return invocation.noToolsArgs;
@@ -123,11 +139,29 @@ async function terminateCommand(pid) {
 	await setTimeout$1(500);
 	signalProcessGroup(pid, "SIGKILL");
 }
+function spawnError(command, cwd, error) {
+	if (!(error instanceof Error && "code" in error)) return error;
+	if (error.code !== "ENOENT" && error.code !== "ENOTDIR") return error;
+	let message;
+	if (cwd !== void 0 && !isDirectory(cwd)) message = existsSync(cwd) ? `Working directory is not a directory: ${cwd}` : `Working directory not found: ${cwd}`;
+	else if (error.code === "ENOENT") message = `Command not found: ${command}. Install it or add it to PATH`;
+	else return error;
+	return Object.assign(new Error(message, { cause: error }), { code: error.code });
+}
+function isDirectory(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
 function executeCommand(command, args, options) {
 	return new Promise((resolve, reject) => {
 		let stdout = "";
 		let stderr = "";
 		let stopped;
+		let lastOutputAt = performance.now();
+		let idleMs;
 		let settled = false;
 		let timer;
 		let abortListener;
@@ -136,28 +170,38 @@ function executeCommand(command, args, options) {
 			finish(null);
 			return;
 		}
-		const child = spawn(command, args, {
-			cwd: options.cwd,
-			env: options.env ? {
-				...process.env,
-				...options.env
-			} : process.env,
-			stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			],
-			detached: process.platform !== "win32" && (Boolean(options.timeoutMs) || options.signal !== void 0)
-		});
+		let child;
+		try {
+			child = spawn(command, args, {
+				cwd: options.cwd,
+				env: options.env ? {
+					...process.env,
+					...options.env
+				} : process.env,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				detached: process.platform !== "win32" && (Boolean(options.timeoutMs) || options.signal !== void 0)
+			});
+		} catch (error) {
+			fail(spawnError(command, options.cwd, error));
+			return;
+		}
 		if (options.timeoutMs) timer = setTimeout(() => stop("timeout"), options.timeoutMs);
 		if (options.signal) abortListener = addAbortListener(options.signal, () => stop("abort"));
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
 		child.stdout.on("data", (chunk) => {
-			stdout += chunk.toString("utf8");
+			stdout += chunk;
+			lastOutputAt = performance.now();
 		});
 		child.stderr.on("data", (chunk) => {
-			stderr += chunk.toString("utf8");
+			stderr += chunk;
+			lastOutputAt = performance.now();
 		});
-		child.on("error", fail);
+		child.on("error", (error) => fail(spawnError(command, options.cwd, error)));
 		child.on("close", (code) => {
 			if (stopped === void 0) finish(code);
 		});
@@ -174,6 +218,7 @@ function executeCommand(command, args, options) {
 		function stop(reason) {
 			if (settled || stopped !== void 0) return;
 			stopped = reason;
+			idleMs = Math.round(performance.now() - lastOutputAt);
 			cleanup();
 			if (child.pid === void 0) return;
 			terminateCommand(child.pid).then(() => {
@@ -197,7 +242,8 @@ function executeCommand(command, args, options) {
 				stderr,
 				exitCode: stopped === void 0 ? code : null,
 				timedOut: stopped === "timeout",
-				aborted: stopped === "abort"
+				aborted: stopped === "abort",
+				...idleMs === void 0 ? {} : { idleMs }
 			});
 		}
 	});
@@ -205,6 +251,8 @@ function executeCommand(command, args, options) {
 var Harness = class {
 	promptTemplates = [];
 	promptTemplateSyncTarget = null;
+	temp = [];
+	envOverrides = [];
 	modelListing = null;
 	mcpConfigs = [];
 	agentsFile = null;
@@ -258,6 +306,7 @@ var Harness = class {
 		const command = this.invocation.binary ?? this.binaries[0];
 		if (!command) return null;
 		if (options.model !== void 0 && !this.invocation.modelArgs) return null;
+		if (accessConflictError(this.id, this.invocation, options) !== null) return null;
 		const template = invocationTemplate(this.invocation, requestedInvocationMode(options));
 		if (!template) return null;
 		return {
@@ -268,6 +317,8 @@ var Harness = class {
 	invocationError(options = {}) {
 		if (!this.invocation) return `Harness ${this.id} has no non-interactive invocation`;
 		if (options.model !== void 0 && !this.invocation.modelArgs) return `Harness ${this.id} does not support model selection`;
+		const conflict = accessConflictError(this.id, this.invocation, options);
+		if (conflict !== null) return conflict;
 		const mode = requestedInvocationMode(options);
 		if (invocationTemplate(this.invocation, mode)) return null;
 		return `${`Harness ${this.id} has no ${INVOCATION_MODE_DESCRIPTION[mode]} invocation`}${invocationRetryHint(this.invocation, mode, options)}`;
@@ -283,7 +334,15 @@ var Harness = class {
 		if (!built) return Promise.reject(new Error(this.invocationError(invocationOptions) ?? "Invalid invocation"));
 		const versionError = this.readOnlyVersionError(invocationOptions);
 		if (versionError) return Promise.reject(new Error(versionError));
-		return executeCommand(built.command, built.args, options);
+		const streamArgs = options.structured ? void 0 : this.invocation?.streamArgs;
+		if (!streamArgs) return executeCommand(built.command, built.args, options);
+		return executeCommand(built.command, [...built.args, ...streamArgs], options).then((result) => ({
+			...result,
+			stdout: this.foldStreamOutput(result.stdout, !result.timedOut && !result.aborted)
+		}));
+	}
+	foldStreamOutput(_stdout, _complete) {
+		throw new Error(`Harness ${this.id} does not implement stream output folding`);
 	}
 	readOnlyVersionError(options) {
 		const floor = this.invocation?.readOnlyMinVersion;
@@ -298,22 +357,33 @@ var Harness = class {
 		if (!this.modelListing) return null;
 		const command = this.binaries[0];
 		if (!command) return null;
-		const template = search === void 0 ? this.modelListing.args : this.modelListing.searchArgs;
-		if (!template) return null;
 		return {
 			command,
-			args: template.map((arg) => arg.replaceAll("{search}", () => search ?? ""))
+			args: (search === void 0 ? this.modelListing.args : this.modelListing.searchArgs ?? this.modelListing.args).map((arg) => arg.replaceAll("{search}", () => search ?? ""))
 		};
 	}
 	async listModels(options = {}) {
 		const built = this.buildModelListInvocation(options.search);
-		if (!built) throw new Error(this.modelListing ? `Harness ${this.id} does not support filtering its model listing` : `Harness ${this.id} does not support model listing`);
+		if (!built) throw new Error(`Harness ${this.id} does not support model listing`);
 		const result = await executeCommand(built.command, built.args, options);
+		if (result.timedOut || result.aborted || result.exitCode !== 0) return {
+			...result,
+			models: []
+		};
+		const models = this.parseModelListingOutput(result.stdout);
+		if (options.search === void 0 || this.modelListing?.searchArgs) return {
+			...result,
+			models
+		};
+		const search = options.search.toLowerCase();
 		return {
 			...result,
-			models: !result.timedOut && !result.aborted && result.exitCode === 0 ? this.parseModelListingOutput(result.stdout) : []
+			models: models.filter((model) => model.id.toLowerCase().includes(search))
 		};
 	}
+	modelSelector(model) {
+		return `${model.provider}/${model.id}`;
+	}
 	parseModelListingOutput(_stdout) {
 		throw new Error(`Harness ${this.id} does not implement model-list output parsing`);
 	}
@@ -335,10 +405,33 @@ var Harness = class {
 			commands: this.resolveCandidates(this.commands, options),
 			promptTemplates: this.resolveCandidates(this.promptTemplates, options),
 			promptTemplateSyncTarget: this.promptTemplateSyncTarget === null ? null : this.resolveCandidates([this.promptTemplateSyncTarget], options)[0] ?? null,
-			hooks: this.resolveCandidates(this.hooks, options)
+			hooks: this.resolveCandidates(this.hooks, options),
+			temp: this.resolveTemp(options)
 		};
 	}
+	resolveTemp(options) {
+		const temp = this.resolveCandidates(this.temp, options);
+		const override = this.resolveCandidates(this.envOverrides, options).find((entry) => entry.relocates.includes("temp"));
+		const value = override ? process.env[override.variable] : void 0;
+		if (!override || !value) return temp;
+		return temp.map((entry) => ({
+			...entry,
+			path: moveRoot(entry.path, override.path, value)
+		}));
+	}
 };
+function parseAntigravityModels(stdout) {
+	const lines = stripVTControlCharacters(stdout).split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+	if (lines.length === 0) throw new Error("Unexpected empty Antigravity model-list output");
+	return lines.map((line) => {
+		const match = /^(\S+)\t.+$/.exec(line);
+		if (!match?.[1]) throw new Error(`Unexpected Antigravity model-list row: ${JSON.stringify(line)}`);
+		return {
+			provider: "google",
+			id: match[1]
+		};
+	});
+}
 var Antigravity = class extends Harness {
 	id = "antigravity";
 	name = "Google Antigravity CLI";
@@ -482,6 +575,11 @@ var Antigravity = class extends Harness {
 		level: "official",
 		note: "Non-interactive print mode."
 	};
+	modelListing = {
+		args: ["models"],
+		level: "official",
+		note: "Prints one id and display name per row, with no default marked and no filter; verified with 1.2.5."
+	};
 	mcpConfigs = [{
 		path: "~/.gemini/config/mcp_config.json",
 		scope: "user",
@@ -495,7 +593,60 @@ var Antigravity = class extends Harness {
 		envVars: [],
 		projectMarkers: [".antigravitycli"]
 	};
+	parseModelListingOutput(stdout) {
+		return parseAntigravityModels(stdout);
+	}
+	modelSelector(model) {
+		return model.id;
+	}
+};
+function parseStreamLine(line) {
+	try {
+		const parsed = JSON.parse(line);
+		return typeof parsed === "object" && parsed !== null && "type" in parsed && typeof parsed.type === "string" ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+function startsTextBlock(event) {
+	return event.type === "stream_event" && event.event?.type === "content_block_start" && event.event.content_block?.type === "text";
+}
+function textDelta(event) {
+	if (event.type !== "stream_event" || event.event?.type !== "content_block_delta") return void 0;
+	const delta = event.event.delta;
+	return delta?.type === "text_delta" && typeof delta.text === "string" ? delta.text : void 0;
+}
+var ClaudeStreamFold = class {
+	blocks = [];
+	other = [];
+	result;
+	add(line) {
+		if (line.trim().length === 0) return;
+		const event = parseStreamLine(line);
+		if (!event) {
+			this.other.push(line);
+			return;
+		}
+		if (event.type === "result" && typeof event.result === "string") this.result = event.result;
+		if (startsTextBlock(event)) this.blocks.push("");
+		const text = textDelta(event);
+		if (text !== void 0) this.blocks.push((this.blocks.pop() ?? "") + text);
+	}
+	text(complete) {
+		const prefix = this.other.map((line) => `${line}\n`).join("");
+		if (complete && this.result !== void 0) return `${prefix}${this.result}\n`;
+		const text = this.blocks.filter((block) => block.length > 0).join("\n\n");
+		return text.length > 0 ? `${prefix}${text}\n` : prefix;
+	}
 };
+function foldClaudeStream(stdout, complete) {
+	const lines = stdout.split("\n");
+	const tail = lines.at(-1);
+	if (!complete && tail?.startsWith("{") && parseStreamLine(tail) === void 0) lines.pop();
+	const fold = new ClaudeStreamFold();
+	for (const line of lines) fold.add(line);
+	return fold.text(complete);
+}
 var Claude = class extends Harness {
 	id = "claude";
 	name = "Anthropic Claude Code";
@@ -671,8 +822,14 @@ var Claude = class extends Harness {
 		],
 		readOnlyMinVersion: "2.1.175",
 		modelArgs: ["--model", "{model}"],
+		streamArgs: [
+			"--output-format",
+			"stream-json",
+			"--verbose",
+			"--include-partial-messages"
+		],
 		level: "official",
-		note: "Headless print mode; add --output-format json for structured output. --tools only covers the built-in set, so every mode without the full agent adds --strict-mcp-config to drop configured MCP servers too; without it an advisor still sees every user and project MCP tool, checked on 2.1.280. Read-only runs keep the built-in Read, Glob and Grep tools, so no write tool exists whatever permission mode the settings carry; verified on 2.1.175 and 2.1.268. --permission-mode plan does not qualify: its shell commands run through the auto mode classifier, which let a file write through."
+		note: "Headless print mode; add --output-format json for structured output. Plain text runs stream events instead and fold them back, since text mode prints nothing until the answer is complete and a timeout would lose all of it; --include-partial-messages streams a single long answer too, checked on 2.1.280. --tools only covers the built-in set, so every mode without the full agent adds --strict-mcp-config to drop configured MCP servers too; without it an advisor still sees every user and project MCP tool, checked on 2.1.280. Read-only runs keep the built-in Read, Glob and Grep tools, so no write tool exists whatever permission mode the settings carry; verified on 2.1.175 and 2.1.268. --permission-mode plan does not qualify: its shell commands run through the auto mode classifier, which let a file write through."
 	};
 	mcpConfigs = [{
 		path: "~/.claude.json",
@@ -689,6 +846,63 @@ var Claude = class extends Harness {
 		key: ["mcpServers"],
 		dialect: "standard"
 	}];
+	temp = [
+		{
+			path: "${TMPDIR}/claude-<uid>/",
+			scope: "data",
+			level: "official",
+			platforms: ["linux"],
+			note: "Session scratchpads sit under <dash-encoded-cwd>/<session-id>/scratchpad."
+		},
+		{
+			path: "/tmp/claude-<uid>/",
+			scope: "data",
+			level: "official",
+			platforms: ["darwin"]
+		},
+		{
+			path: "${TMPDIR}/claude/",
+			scope: "data",
+			level: "official",
+			platforms: ["win32"]
+		}
+	];
+	envOverrides = [
+		{
+			variable: "CLAUDE_CONFIG_DIR",
+			path: "~/.claude",
+			scope: "user",
+			level: "official",
+			relocates: [
+				"config",
+				"sessions",
+				"instructions",
+				"skills",
+				"commands",
+				"promptTemplates",
+				"hooks"
+			],
+			note: "Read from the shell or the env block of user or managed settings, not project settings."
+		},
+		{
+			variable: "CLAUDE_CODE_TMPDIR",
+			path: "${TMPDIR}",
+			scope: "data",
+			level: "official",
+			platforms: ["linux", "win32"],
+			relocates: ["temp"],
+			note: "Read from the shell or the env block of user or managed settings, not project settings."
+		},
+		{
+			variable: "CLAUDE_CODE_TMPDIR",
+			path: "/tmp",
+			scope: "data",
+			level: "official",
+			platforms: ["darwin"],
+			relocates: ["temp"],
+			note: "Read from the shell or the env block of user or managed settings, not project settings."
+		}
+	];
 	agentsFile = "~/.claude/CLAUDE.md";
 	detection = {
 		envVars: [
@@ -704,6 +918,9 @@ var Claude = class extends Harness {
 			"CLAUDE.md"
 		]
 	};
+	foldStreamOutput(stdout, complete) {
+		return foldClaudeStream(stdout, complete);
+	}
 };
 var Codex = class extends Harness {
 	id = "codex";
@@ -831,7 +1048,7 @@ var Codex = class extends Harness {
 		path: "~/.codex/prompts/",
 		scope: "user",
 		level: "official",
-		note: "Deprecated Markdown prompts invoked as /prompts:name. Top-level files only; use skills for shared prompts. Base directory follows CODEX_HOME."
+		note: "Deprecated Markdown prompts invoked as /prompts:name. Top-level files only; use skills for shared prompts."
 	}];
 	promptTemplates = this.commands;
 	promptTemplateSyncTarget = {
@@ -887,6 +1104,20 @@ var Codex = class extends Harness {
 		key: ["mcp_servers"],
 		dialect: "standard"
 	}];
+	envOverrides = [{
+		variable: "CODEX_HOME",
+		path: "~/.codex",
+		scope: "user",
+		level: "official",
+		relocates: [
+			"config",
+			"sessions",
+			"instructions",
+			"skills",
+			"commands",
+			"promptTemplates"
+		]
+	}];
 	agentsFile = "~/.codex/AGENTS.md";
 	detection = {
 		envVars: [],
@@ -1311,6 +1542,20 @@ var GitHubCopilot = class extends Harness {
 		]
 	};
 };
+function parseGrokModels(stdout) {
+	const lines = stripVTControlCharacters(stdout).split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+	const start = lines.indexOf("Available models:");
+	if (start === -1) throw new Error(`Unexpected Grok model-list output: ${JSON.stringify(stdout)}`);
+	return lines.slice(start + 1).map((line) => {
+		const match = /^([*-])\s+(\S+)(?:\s+\(default\))?$/.exec(line);
+		if (!match?.[2]) throw new Error(`Unexpected Grok model-list row: ${JSON.stringify(line)}`);
+		return {
+			provider: "xai",
+			id: match[2],
+			...match[1] === "*" ? { default: true } : {}
+		};
+	});
+}
 var Grok = class extends Harness {
 	id = "grok";
 	name = "xAI Grok CLI";
@@ -1443,6 +1688,11 @@ var Grok = class extends Harness {
 		level: "official",
 		note: "-p is short for --single; add --output-format json for structured output. --sandbox read-only is kernel-enforced (Landlock, Seatbelt) regardless of the inherited permission mode and still allows writes to ~/.grok and temp dirs; verified on Linux with 1.0.13 and 1.0.25."
 	};
+	modelListing = {
+		args: ["models"],
+		level: "official",
+		note: "Prints bare ids with the default marked; verified with 1.0.41."
+	};
 	mcpConfigs = [{
 		path: "~/.grok/config.toml",
 		scope: "user",
@@ -1467,6 +1717,9 @@ var Grok = class extends Harness {
 		],
 		projectMarkers: [".grok"]
 	};
+	parseModelListingOutput(stdout) {
+		return parseGrokModels(stdout);
+	}
 };
 function packageVersion(commandPath) {
 	try {
@@ -1730,7 +1983,7 @@ var Omp = class extends Harness {
 			path: "~/.omp/agent/config.yml",
 			scope: "user",
 			level: "official",
-			note: "Agent dir overridable with PI_CODING_AGENT_DIR; profiles use ~/.omp/profiles/<name>/agent."
+			note: "Profiles use ~/.omp/profiles/<name>/agent."
 		},
 		{
 			path: "~/.omp/agent/settings.json",
@@ -1912,6 +2165,21 @@ var Omp = class extends Harness {
 		key: ["mcpServers"],
 		dialect: "standard"
 	}];
+	envOverrides = [{
+		variable: "PI_CODING_AGENT_DIR",
+		path: "~/.omp/agent",
+		scope: "user",
+		level: "official",
+		relocates: [
+			"config",
+			"sessions",
+			"instructions",
+			"skills",
+			"commands",
+			"promptTemplates"
+		],
+		note: "Ignored under a named profile (OMP_PROFILE). On Linux, after omp config init-xdg, data, state and cache live under $XDG_*_HOME/omp instead."
+	}];
 	agentsFile = "~/.omp/agent/AGENTS.md";
 	detection = {
 		envVars: ["OMP_PROFILE", "PI_CODING_AGENT_DIR"],
@@ -2136,8 +2404,7 @@ var Pi = class extends Harness {
 	config = [{
 		path: "~/.pi/agent/settings.json",
 		scope: "user",
-		level: "official",
-		note: "Config dir overridable with PI_CODING_AGENT_DIR."
+		level: "official"
 	}, {
 		path: ".pi/settings.json",
 		scope: "project",
@@ -2147,7 +2414,7 @@ var Pi = class extends Harness {
 		path: "~/.pi/agent/sessions/<dash-encoded-cwd>/<timestamp>_<session-id>.jsonl",
 		scope: "data",
 		level: "official",
-		note: "Per-project session transcripts in JSONL format; session ids are UUIDv7. Overridable with PI_CODING_AGENT_SESSION_DIR or --session-dir."
+		note: "Per-project session transcripts in JSONL format; session ids are UUIDv7. Overridable with --session-dir."
 	}];
 	persistence = [{
 		format: "JSON",
@@ -2257,6 +2524,28 @@ var Pi = class extends Harness {
 		level: "official",
 		note: "Lists models with configured provider authentication; accepts an optional fuzzy search."
 	};
+	envOverrides = [{
+		variable: "PI_CODING_AGENT_DIR",
+		path: "~/.pi/agent",
+		scope: "user",
+		level: "official",
+		relocates: [
+			"config",
+			"sessions",
+			"instructions",
+			"skills",
+			"commands",
+			"promptTemplates"
+		],
+		note: "A leading ~ in the value is expanded."
+	}, {
+		variable: "PI_CODING_AGENT_SESSION_DIR",
+		path: "~/.pi/agent/sessions",
+		scope: "data",
+		level: "official",
+		relocates: ["sessions"],
+		note: "Takes precedence over PI_CODING_AGENT_DIR for sessions; --session-dir beats both."
+	}];
 	agentsFile = "~/.pi/agent/AGENTS.md";
 	detection = {
 		envVars: [
@@ -3235,6 +3524,14 @@ function moveFile(from, to) {
 		renameSync(from, to);
 	} catch (error) {
 		if (error.code !== "EXDEV") throw error;
+		if (lstatSync(from).isDirectory()) {
+			cpSync(from, to, {
+				recursive: true,
+				verbatimSymlinks: true
+			});
+			rmSync(from, { recursive: true });
+			return;
+		}
 		copyFileSync(from, to);
 		unlinkSync(from);
 	}
@@ -3344,16 +3641,12 @@ const GENERATED_MARKER = "# Generated by @agntn/harnesses from ";
 const PORTABLE_PROMPT_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
 const GEMINI_ACTION = {
 	missing: "generated",
-	"correct-link": "adopted",
-	"wrong-link": "adopted",
 	"owned-file": "replaced",
 	"unmanaged-file": "adopted",
 	unsupported: "skipped"
 };
 const GEMINI_BACKUP = {
 	missing: false,
-	"correct-link": true,
-	"wrong-link": true,
 	"owned-file": true,
 	"unmanaged-file": true,
 	unsupported: false
@@ -3391,7 +3684,11 @@ function generatedSource(content) {
 		return null;
 	}
 }
-function inspectDestination(path, source) {
+function linkTarget(path) {
+	const target = readlinkSync(path);
+	return isAbsolute(target) ? target : resolve(dirname(path), target);
+}
+function inspectDestination(path) {
 	let stats;
 	try {
 		stats = lstatSync(path);
@@ -3399,11 +3696,7 @@ function inspectDestination(path, source) {
 		if (error.code === "ENOENT") return { kind: "missing" };
 		throw error;
 	}
-	if (stats.isSymbolicLink()) {
-		if (source === void 0) return { kind: "unmanaged-file" };
-		const target = readlinkSync(path);
-		return (isAbsolute(target) ? target : resolve(dirname(path), target)) === source ? { kind: "correct-link" } : { kind: "wrong-link" };
-	}
+	if (stats.isSymbolicLink()) return { kind: "unmanaged-file" };
 	if (!stats.isFile()) return { kind: "unsupported" };
 	const content = readFileSync(path, "utf8");
 	if (generatedSource(content) !== null) return {
@@ -3415,10 +3708,10 @@ function inspectDestination(path, source) {
 function tempPath(path, kind) {
 	return join(dirname(path), `.${basename(path)}-${randomUUID()}.${kind}.tmp`);
 }
-function linkTemplate(path, source) {
+function linkDirectory(path, source) {
 	mkdirSync(dirname(path), { recursive: true });
 	const temp = tempPath(path, "prompt-link");
-	symlinkSync(source, temp);
+	symlinkSync(source, temp, "junction");
 	renameSync(temp, path);
 }
 function writeTemplate(path, content) {
@@ -3432,8 +3725,7 @@ function backupDestination(id, path, options) {
 	mkdirSync(backupDir, { recursive: true });
 	const backup = join(backupDir, `${basename(path)}-${Date.now()}-${randomUUID()}`);
 	if (lstatSync(path).isSymbolicLink()) {
-		const target = readlinkSync(path);
-		symlinkSync(isAbsolute(target) ? target : resolve(dirname(path), target), backup);
+		symlinkSync(linkTarget(path), backup);
 		unlinkSync(path);
 		return backup;
 	}
@@ -3443,44 +3735,68 @@ function backupDestination(id, path, options) {
 function checkDetail() {
 	return "check mode: not applied";
 }
-function syncMarkdownTemplate(id, targetDir, template, check, options) {
-	const path = join(targetDir, `${template.name}.md`);
-	const state = inspectDestination(path, template.path);
-	if (state.kind === "correct-link") return {
-		name: template.name,
-		source: template.path,
-		path,
-		action: "unchanged"
-	};
-	if (state.kind === "unsupported") return {
-		name: template.name,
-		source: template.path,
-		path,
-		action: "skipped",
-		detail: "destination exists and is not a file or symlink"
+function isInsideDirectory(path, directory) {
+	const remainder = relative(directory, path);
+	return remainder !== "" && !remainder.startsWith("..") && !isAbsolute(remainder);
+}
+function isLegacyTemplateLink(path, sourceDir) {
+	return lstatSync(path).isSymbolicLink() && isInsideDirectory(linkTarget(path), sourceDir);
+}
+const DIRECTORY_ACTION = {
+	missing: "linked",
+	"correct-link": "unchanged",
+	"wrong-link": "relinked",
+	"legacy-links": "relinked",
+	"local-files": "adopted",
+	"not-directory": "skipped"
+};
+function inspectDirectory(targetDir, sourceDir) {
+	let stats;
+	try {
+		stats = lstatSync(targetDir);
+	} catch (error) {
+		if (error.code === "ENOENT") return { kind: "missing" };
+		throw error;
+	}
+	if (stats.isSymbolicLink()) return { kind: linkTarget(targetDir) === sourceDir ? "correct-link" : "wrong-link" };
+	if (!stats.isDirectory()) return { kind: "not-directory" };
+	const entries = readdirSync(targetDir).map((entry) => join(targetDir, entry));
+	return entries.every((entry) => isLegacyTemplateLink(entry, sourceDir)) ? {
+		kind: "legacy-links",
+		entries
+	} : { kind: "local-files" };
+}
+function clearDirectory(id, targetDir, state, options) {
+	if (state.kind === "wrong-link" || state.kind === "local-files") return backupDestination(id, targetDir, options);
+	if (state.kind === "legacy-links") {
+		for (const entry of state.entries) unlinkSync(entry);
+		rmdirSync(targetDir);
+	}
+}
+function syncMarkdownDirectory(id, targetDir, sourceDir, check, options) {
+	const state = inspectDirectory(targetDir, sourceDir);
+	const action = DIRECTORY_ACTION[state.kind];
+	if (state.kind === "correct-link") return { action };
+	if (state.kind === "not-directory") return {
+		action,
+		detail: "destination exists and is not a directory or symlink"
 	};
-	const action = state.kind === "missing" ? "linked" : state.kind === "wrong-link" ? "relinked" : "adopted";
 	if (check) return {
-		name: template.name,
-		source: template.path,
-		path,
 		action,
 		detail: checkDetail()
 	};
-	let detail;
-	if (state.kind === "wrong-link") unlinkSync(path);
-	if (state.kind === "owned-file" || state.kind === "unmanaged-file") detail = backupDestination(id, path, options);
-	linkTemplate(path, template.path);
+	const detail = clearDirectory(id, targetDir, state, options);
+	linkDirectory(targetDir, sourceDir);
 	return {
-		name: template.name,
-		source: template.path,
-		path,
 		action,
 		detail
 	};
 }
+function parseYaml(raw) {
+	return createRequire(import.meta.url)("yaml").parse(raw);
+}
 function frontmatterDescription(raw, path) {
-	const frontmatter = parse$1(raw);
+	const frontmatter = parseYaml(raw);
 	if (frontmatter === null) return void 0;
 	if (typeof frontmatter !== "object" || Array.isArray(frontmatter)) throw new TypeError(`Prompt template frontmatter is not an object: ${path}`);
 	const description = frontmatter.description;
@@ -3541,23 +3857,6 @@ function syncGeminiTemplate(id, targetDir, template, check, options) {
 		detail
 	};
 }
-function isInsideDirectory(path, directory) {
-	const remainder = relative(directory, path);
-	return remainder !== "" && !remainder.startsWith("..") && !isAbsolute(remainder);
-}
-function staleMarkdownSource(path, sourceDir) {
-	if (inspectDestination(path).kind !== "unmanaged-file") return null;
-	let stats;
-	try {
-		stats = lstatSync(path);
-	} catch {
-		return null;
-	}
-	if (!stats.isSymbolicLink()) return null;
-	const target = readlinkSync(path);
-	const resolved = isAbsolute(target) ? target : resolve(dirname(path), target);
-	return isInsideDirectory(resolved, sourceDir) ? resolved : null;
-}
 function staleGeminiSource(path, sourceDir) {
 	let content;
 	try {
@@ -3569,28 +3868,40 @@ function staleGeminiSource(path, sourceDir) {
 	if (source === null) return null;
 	return isInsideDirectory(source, sourceDir) ? source : null;
 }
-function pruneTarget(targetDir, format, sourceDir, activeSources, check) {
+function pruneGeminiTarget(id, targetDir, sourceDir, activeNames, check, options) {
 	let entries;
 	try {
-		entries = readdirSync(targetDir, { withFileTypes: true });
+		entries = readdirSync(targetDir);
 	} catch (error) {
 		if (error.code === "ENOENT") return [];
 		throw error;
 	}
-	const extension = format === "markdown" ? ".md" : ".toml";
-	const staleSource = format === "markdown" ? staleMarkdownSource : staleGeminiSource;
-	return entries.filter((entry) => entry.name.toLowerCase().endsWith(extension)).flatMap((entry) => {
-		const path = join(targetDir, entry.name);
-		const source = staleSource(path, sourceDir);
-		if (source === null || activeSources.has(source)) return [];
-		if (!check) unlinkSync(path);
-		return [{
-			name: basename(entry.name, extension),
-			source,
+	return entries.filter((entry) => !activeNames.has(entry)).map((entry) => {
+		const path = join(targetDir, entry);
+		const name = basename(entry, extname(entry));
+		const source = staleGeminiSource(path, sourceDir);
+		if (check) return {
+			name,
+			...source === null ? {} : { source },
 			path,
 			action: "removed",
-			...check ? { detail: checkDetail() } : {}
-		}];
+			detail: checkDetail()
+		};
+		if (source !== null) {
+			unlinkSync(path);
+			return {
+				name,
+				source,
+				path,
+				action: "removed"
+			};
+		}
+		return {
+			name,
+			path,
+			action: "removed",
+			detail: backupDestination(id, path, options)
+		};
 	});
 }
 function syncTarget(harness, templates, sourceDir, check, options) {
@@ -3606,11 +3917,17 @@ function syncTarget(harness, templates, sourceDir, check, options) {
 		detail: "prompt template destination is unavailable on this platform",
 		templates: []
 	};
-	const targetDir = resolved.path;
-	const syncTemplate = resolved.format === "markdown" ? syncMarkdownTemplate : syncGeminiTemplate;
-	const results = templates.map((template) => syncTemplate(harness.id, targetDir, template, check, options));
-	const activeSources = new Set(templates.map((template) => template.path));
-	results.push(...pruneTarget(targetDir, resolved.format, sourceDir, activeSources, check));
+	const targetDir = resolve(resolved.path);
+	if (resolved.format === "markdown") return {
+		id: harness.id,
+		path: targetDir,
+		format: resolved.format,
+		...syncMarkdownDirectory(harness.id, targetDir, sourceDir, check, options),
+		templates: []
+	};
+	const results = templates.map((template) => syncGeminiTemplate(harness.id, targetDir, template, check, options));
+	const activeNames = new Set(templates.map((template) => `${template.name}.toml`));
+	results.push(...pruneGeminiTarget(harness.id, targetDir, sourceDir, activeNames, check, options));
 	return {
 		id: harness.id,
 		path: targetDir,