@agntn/harnesses 0.0.1 → 0.1.0

package/README.md

@@ -1,12 +1,14 @@
 # @agntn/harnesses
 
-[![npm version](https://img.shields.io/npm/v/%40agntn%2Fharnesses?style=flat&colorA=130f40&colorB=474787)](https://npmjs.com/package/@agntn/harnesses)
-[![npm downloads](https://img.shields.io/npm/dm/%40agntn%2Fharnesses?style=flat&colorA=130f40&colorB=474787)](https://npm.chart.dev/@agntn/harnesses)
-[![license](https://img.shields.io/github/license/agntn/harnesses?style=flat&colorA=130f40&colorB=474787)](https://github.com/agntn/harnesses/blob/main/LICENSE)
+[![npm version](https://npmx.dev/api/registry/badge/version/@agntn/harnesses)](https://npmx.dev/package/@agntn/harnesses)
+[![npm downloads](https://npmx.dev/api/registry/badge/downloads/@agntn/harnesses)](https://npmx.dev/package/@agntn/harnesses)
+[![license](https://npmx.dev/api/registry/badge/license/@agntn/harnesses)](https://npmx.dev/package/@agntn/harnesses)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/agntn/harnesses)
 
 Metadata toolkit for AI coding harnesses. One registry of paths, formats, and detection rules for every major CLI.
 
+Docs: [harnesses.agntn.dev](https://harnesses.agntn.dev)
+
 ## Install
 
 ```bash
@@ -24,12 +26,12 @@ console.log(claude.hooks); // [{ path: ".claude/hooks/", scope: "project", ... }
 console.log(claude.invocationModes); // advisor and full agent modes, no read-only mode
 
 const codex = getHarness("codex");
-await codex.invoke("Review this patch", { readOnly: true });
+await codex.invoke("Review this patch", { readOnly: true, timeoutMs: 60_000 });
 
 const pi = getHarness("pi");
 const { models } = await pi.listModels({ search: "gpt-5.4" });
 console.log(models); // [{ provider: "openai-codex", id: "gpt-5.4", ... }]
-await pi.invoke("Review this patch", { model: "openai-codex/gpt-5.4" });
+await pi.invoke("Review this patch", { model: "openai-codex/gpt-5.4", readOnly: true });
 
 // Resolve to absolute paths for current platform
 const paths = claude.resolve({ platform: "linux", homeDir: "/home/dev" });
@@ -89,6 +91,24 @@ import type { ClaudeSessionEntry, CodexThread, GeminiConversationRecord } from "
 
 Primary references: [Antigravity prompting](https://antigravity.google/docs/cli/prompting/), [Antigravity changelog](https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md), [Gemini CLI tools](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/tools.md), [Gemini CLI video request](https://github.com/google-gemini/gemini-cli/issues/27194), [OpenCode attachments](https://opencode.ai/v2/docs/attachments/), [Cursor prompting](https://cursor.com/docs/agent/prompting), and [Copilot CLI voice input](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/voice-input).
 
+`invoke()` and `listModels()` accept `timeoutMs` and `signal?: AbortSignal`. Unset or `0` means no deadline. An already aborted signal skips spawning. Otherwise, the first cancellation or deadline starts cleanup: Linux and macOS use a dedicated process group, with `SIGTERM` followed by `SIGKILL` after 500 ms even if the root has exited. Windows uses `taskkill /T /F` immediately, with a 2 s budget for that command. Cleanup failures reject the call.
+
+Stopped results retain captured output and set `exitCode: null`. Caller cancellation sets `aborted: true`, a deadline sets `timedOut: true`, and the first reason wins. Both flags are false on normal completion. Later aborts do nothing, and cancelled model listings return no parsed models. Pi, OMP, and MCP tools forward their host request signal, not a JSON argument supplied by the model.
+
+```ts
+const controller = new AbortController();
+const pending = getHarness("pi").invoke("Review this change", {
+  tools: true,
+  readOnly: true,
+  signal: controller.signal,
+});
+controller.abort();
+const result = await pending;
+console.log(result.aborted);
+```
+
+This is command cleanup, not a sandbox. Descendants that leave the POSIX process group, or outlive an already exited root on Windows, cannot be reliably reached by these mechanisms. Inherited output pipes do not extend the wait after cleanup. Scheduling and OS delays can exceed the stated budgets.
+
 Each agent is a concrete subclass of the abstract `Harness` class. Custom subclasses can be added with `registerHarness`. Every harness exposes config paths, session locations, instruction files, skills dirs, hooks, commands, persistence formats, capabilities (MCP, vision, audio, video, tools, streaming), detection rules, a normalized non-interactive invocation (`harness.invoke(prompt, { model })`) where the CLI has a headless mode, native model listing (`harness.listModels()`) where the CLI supports it, and its MCP server config files (`listMcpServers`/`addMcpServer`/`removeMcpServer` normalize the dialects; writes rewrite JSON and surgically edit TOML with comments preserved). `syncMcpServers` treats `~/.config/agntn/mcp.jsonc` (JSONC, XDG-aware) as the single source of truth and resets every harness's user-scope MCP config to exactly that list; a top-level `"excludes": ["codex"]` array opts individual harnesses out of the sync (their own servers stay, master-listed names are withdrawn), and `~`/`${HOME}` in commands, args, and env values expand to absolute paths at sync time (harnesses spawn MCP servers without a shell). `syncAgentsFiles` links every harness's global instructions file (CLAUDE.md/AGENTS.md/GEMINI.md) to one master file as symlinks, so an edit made through any harness lands in the single physical copy; `~/.config/agntn/agents.jsonc` sets the `source`, `companions`, and `excludes`, diverged regular files are backed up and relinked, and check mode reports without writing. Companion paths are relative to the source directory and are linked at the same relative path beside each harness target.
 
 ```jsonc
@@ -125,7 +145,7 @@ harnesses agents sync --check   # doctor: link global AGENTS.md files to one mas
 harnesses mcp                   # run the MCP server over stdio
 ```
 
-`tools` defaults to `false` in the library and CLI. The MCP, Pi, and OMP tools require agents to choose it explicitly. `false` must use a native CLI flag that removes tools from the model context; it is a lightweight advisor, not an agent constrained only by prompt wording. Set `tools: true` (or CLI `--tools`) whenever the task needs harness tools, including Grok's native X search. Add `readOnly: true` when those tools must stay inside a sandbox enforced by the harness CLI; the agent tools pass it beside `tools: true`, while the library and CLI let it imply tools. Read-only mode is rejected when a harness has no verified native recipe, so it never falls back to broader access. Harnesses whose CLI cannot disable tools reject advisor mode instead of silently running an agent and return an explicit `tools` retry when their full agent mode can handle the request.
+`tools` defaults to `false` in the library and CLI. The MCP, Pi, and OMP tools require agents to choose it explicitly. `false` must use a native CLI flag that removes tools from the model context; it is a lightweight advisor, not an agent constrained only by prompt wording. Set `tools: true` (or CLI `--tools`) whenever the task needs harness tools, including Grok's native X search. Add `readOnly: true` when those tools must stay inside a sandbox enforced by the harness CLI; the agent tools pass it beside `tools: true`, while the library and CLI let it imply tools. Read-only mode is rejected when a harness has no verified native recipe, so it never falls back to broader access. A recipe can also carry the lowest CLI version whose enforcement was verified, and `invoke()` rejects read-only runs on older or unknown versions: Grok runs `--sandbox read-only` from 1.0.13, and Claude Code keeps read-only runs on `Read`, `Glob` and `Grep` with `--strict-mcp-config` from 2.1.175. Harnesses whose CLI cannot disable tools reject advisor mode instead of silently running an agent and return an explicit `tools` retry when their full agent mode can handle the request.
 
 ## How harnesses compares to unagent
 

package/dist/_chunks/agents-sync.d.mts

@@ -40,6 +40,8 @@ interface HarnessInvocation {
   readOnlyArgs?: string[];
   /** Structured agent argument template with read-only tool access. */
   readOnlyJsonArgs?: string[];
+  /** Lowest CLI version whose read-only enforcement was verified; older or unknown versions reject read-only runs. */
+  readOnlyMinVersion?: string;
   /** Arguments appended when a model is selected; every "{model}" is replaced. */
   modelArgs?: string[];
   level: EvidenceLevel;
@@ -77,8 +79,10 @@ interface ListModelsOptions {
   search?: string;
   cwd?: string;
   env?: Record<string, string>;
-  /** Kill the model-listing command after this many milliseconds; unset means no timeout. */
+  /** Milliseconds before cleanup starts. Unset or 0 disables the deadline. */
   timeoutMs?: number;
+  /** Cancel with the same process cleanup as a timeout. */
+  signal?: AbortSignal;
 }
 interface InvokeOptions {
   cwd?: string;
@@ -89,8 +93,10 @@ interface InvokeOptions {
   tools?: boolean;
   /** Require native enforcement of read-only tool access. Implies `tools: true`. */
   readOnly?: boolean;
-  /** Kill the harness after this many milliseconds; unset means no timeout. */
+  /** Milliseconds before cleanup starts. Unset or 0 disables the deadline. */
   timeoutMs?: number;
+  /** Cancel with the same process cleanup as a timeout. */
+  signal?: AbortSignal;
   /** Use the harness's structured (JSON) output mode instead of plain text. */
   structured?: boolean;
 }
@@ -99,9 +105,11 @@ interface InvokeResult {
   args: string[];
   stdout: string;
   stderr: string;
-  /** Process exit code; null when the run hit `timeoutMs` and was killed. */
+  /** Process exit code; null when terminated by a signal, timeout, or cancellation. */
   exitCode: number | null;
   timedOut: boolean;
+  /** True when caller cancellation wins over the deadline or completion. */
+  aborted: boolean;
 }
 /** Result of one native model-listing command. */
 interface ListModelsResult extends InvokeResult {
@@ -214,10 +222,19 @@ declare abstract class Harness {
    * exits instead of waiting forever.
    *
    * @param prompt - Prompt sent to the harness.
-   * @param options - Invocation, environment, and timeout options.
+   * @param options - Invocation, environment, timeout, and cancellation options.
    * @returns {Promise<InvokeResult>} The completed process result.
    */
   invoke(prompt: string, options?: InvokeOptions): Promise<InvokeResult>;
+  /**
+   * Explains why the installed CLI cannot run a read-only recipe that carries a
+   * version floor, or returns null when no floor applies or the installed
+   * version meets it. An unknown version fails closed, like a missing recipe.
+   *
+   * @param options - Requested execution mode.
+   * @returns {string | null} The version incompatibility, or null when the run may proceed.
+   */
+  private readOnlyVersionError;
   /**
    * Expands the native model-listing recipe without spawning anything.
    *
@@ -232,7 +249,7 @@ declare abstract class Harness {
    * Runs the harness's native model-listing command and normalizes its output.
    * stdin is closed for the same reason as {@link invoke}.
    *
-   * @param options - Search, environment, and timeout options.
+   * @param options - Search, environment, timeout, and cancellation options.
    * @returns {Promise<ListModelsResult>} The normalized command and model result.
    */
   listModels(options?: ListModelsOptions): Promise<ListModelsResult>;

package/dist/_chunks/agents-sync.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"agents-sync.d.mts","names":[],"sources":["../../src/types.ts","../../src/harness.ts","../../src/mcp-servers.ts","../../src/agents-sync.ts"],"mappings":"AAEA,cAAa;KAED;KAaA;KACA;UAEK;EACf;EACA;EACA,OAAO;EACP,YAAY;EACZ;;UAGe;EACf;EACA,OAAO;EACP;;UAGe;EACf;EACA;;EAEA;;EAEA;EACA;EACA;;;UAIe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;EACA,OAAO;EACP;;;UAIe;EACf;EACA;EACA;EACA;EACA;EACA;;;UAIe;;EAEf;;EAEA;EACA,OAAO;EACP;;;UAIe;EACf;EACA;EACA;EACA;EACA;EACA;;;UAIe;EACf;EACA;EACA,MAAM;;EAEN;;UAGe;EACf;EACA,MAAM;;EAEN;;EAEA;;EAEA;;EAEA;;EAEA;;UAGe;EACf;EACA;EACA;EACA;;EAEA;EACA;;;UAIe,yBAAyB;;EAExC,QAAQ;;;UAIO;EACf;EACA;EACA;EACA;EACA,MAAM;EACN;EACA,UAAU;;EAEV;;;UAIe,sBAAsB;EACrC;;EAEA;;EAEA;;UAGe;;EAEf;;EAEA;;UAGe;EACf;EACA;EACA,WAAW;;UAGI;EACf,QAAQ;EACR,UAAU;EACV,cAAc;EACd,QAAQ;EACR,UAAU;EACV,OAAO;;KC9IJ,oBAAoB;EACvB;EACA;EACA;EACA;;uBAqHoB;oBACF,IAAI;oBACJ;oBACA;oBACA,QAAQ;oBACR,UAAU;oBACV,aAAa;oBACb,cAAc;oBACd,QAAQ;oBACR,UAAU;oBACV,OAAO;oBACP,cAAc;oBACd,WAAW;;oBAEX,YAAY;;WAErB,cAAc;;WAEd,YAAY;;;;;;WAMZ;EAET;EAYA;EAIA,cAAc;MAKV;;;;;;MAsBA,mBAAmB;;;;;;;;;;EAoBvB,gBACE,gBACA,UAAS;IACN;IAAiB;;;;;;;;EAmBtB,gBAAgB,UAAS;;;;;;;;;;EAwBzB,OAAO,gBAAgB,UAAS,gBAAqB,QAAQ;;;;;;;EAuB7D,yBAAyB;IAAoB;IAAiB;;;;;;;;;EAmBxD,WAAW,UAAS,oBAAyB,QAAQ;;;;;;YAyBjD,wBAAwB,kBAAkB;;;;;;;;;;EAapD,kBAAkB,UAAU,eAC1B,kBAAkB,KAClB,UAAS,iBACR;EAcH,QAAQ,UAAS,iBAAsB;;KAY7B,+BAA+B;;UC9X1B;EACf;EACA,OAAO;EACP,QAAQ;EACR,OAAO;EACP;EACA;EACA,SAAS;;EAET;;;;;;;;;;iBAmRc,eAAe,SAAS,SAAS,UAAS,iBAAsB;;;;;;;;;;;;iBAiLhE,aACd,SAAS,SACT,QAAQ,iBACR,4BACA,UAAS;EACN;EAAc;;;;;;;;;;;iBA0BH,gBACd,SAAS,SACT,cACA,4BACA,UAAS;EACN;EAAc;;;;;;;;;iBA8FH,WAAW;;;;;;;iBAwBX,cAAc,UAAS;;UAKtB;EACf;EACA;;EAEA;;EAEA;EACA,SAAS;IAAQ;IAAc;;;;UAIhB;EACf;EACA;EACA,SAAS;;;;;;;;iBAuEK,qBAAqB,UAAS;EAC5C;EACA,SAAS;;EAET;;;;;;;;;;;iBA2Hc,eACd,oBAAoB,WACpB,UAAS,iBACR;;UC1zBc;;EAEf;;EAEA;;EAEA;;EAEA;;KAGU;;UAGK;WACN;WACA;WACA,QAAQ,QAAQ;;WAEhB;;;UAIM;EACf;EACA;EACA,QAAQ;;EAER;;EAEA,sBAAsB;;;UAIP;EACf;EACA;EACA,SAAS;;;;;;;;iBAkFK,iBAAiB,UAAS,iBAAsB;;;;;;;;;;iBAiMhD,gBACd,oBAAoB,WACpB,iBACA,UAAS,iBACR"}
+{"version":3,"file":"agents-sync.d.mts","names":[],"sources":["../../src/types.ts","../../src/harness.ts","../../src/mcp-servers.ts","../../src/agents-sync.ts"],"mappings":"AAEA,cAAa;KAED;KAaA;KACA;UAEK;EACf;EACA;EACA,OAAO;EACP,YAAY;EACZ;;UAGe;EACf;EACA,OAAO;EACP;;UAGe;EACf;EACA;;EAEA;;EAEA;EACA;EACA;;;UAIe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;EACA,OAAO;EACP;;;UAIe;EACf;EACA;EACA;EACA;EACA;EACA;;;UAIe;;EAEf;;EAEA;EACA,OAAO;EACP;;;UAIe;EACf;EACA;EACA;EACA;EACA;EACA;;;UAIe;EACf;EACA;EACA,MAAM;;EAEN;;EAEA,SAAS;;UAGM;EACf;EACA,MAAM;;EAEN;;EAEA;;EAEA;;EAEA;;EAEA,SAAS;;EAET;;UAGe;EACf;EACA;EACA;EACA;;EAEA;EACA;;EAEA;;;UAIe,yBAAyB;;EAExC,QAAQ;;;UAIO;EACf;EACA;EACA;EACA;EACA,MAAM;EACN;EACA,UAAU;;EAEV;;;UAIe,sBAAsB;EACrC;;EAEA;;EAEA;;UAGe;;EAEf;;EAEA;;UAGe;EACf;EACA;EACA,WAAW;;UAGI;EACf,QAAQ;EACR,UAAU;EACV,cAAc;EACd,QAAQ;EACR,UAAU;EACV,OAAO;;KCnJJ,oBAAoB;EACvB;EACA;EACA;EACA;;uBA2OoB;oBACF,IAAI;oBACJ;oBACA;oBACA,QAAQ;oBACR,UAAU;oBACV,aAAa;oBACb,cAAc;oBACd,QAAQ;oBACR,UAAU;oBACV,OAAO;oBACP,cAAc;oBACd,WAAW;;oBAEX,YAAY;;WAErB,cAAc;;WAEd,YAAY;;;;;;WAMZ;EAET;EAYA;EAIA,cAAc;MAKV;;;;;;MAsBA,mBAAmB;;;;;;;;;;EAoBvB,gBACE,gBACA,UAAS;IACN;IAAiB;;;;;;;;EAmBtB,gBAAgB,UAAS;;;;;;;;;;EAqBzB,OAAO,gBAAgB,UAAS,gBAAqB,QAAQ;;;;;;;;;UA2BrD;;;;;;;EAgBR,yBAAyB;IAAoB;IAAiB;;;;;;;;;EAmBxD,WAAW,UAAS,oBAAyB,QAAQ;;;;;;YAyBjD,wBAAwB,kBAAkB;;;;;;;;;;EAapD,kBAAkB,UAAU,eAC1B,kBAAkB,KAClB,UAAS,iBACR;EAcH,QAAQ,UAAS,iBAAsB;;KAY7B,+BAA+B;;UCxgB1B;EACf;EACA,OAAO;EACP,QAAQ;EACR,OAAO;EACP;EACA;EACA,SAAS;;EAET;;;;;;;;;;iBAmRc,eAAe,SAAS,SAAS,UAAS,iBAAsB;;;;;;;;;;;;iBAiLhE,aACd,SAAS,SACT,QAAQ,iBACR,4BACA,UAAS;EACN;EAAc;;;;;;;;;;;iBA0BH,gBACd,SAAS,SACT,cACA,4BACA,UAAS;EACN;EAAc;;;;;;;;;iBA8FH,WAAW;;;;;;;iBAwBX,cAAc,UAAS;;UAKtB;EACf;EACA;;EAEA;;EAEA;EACA,SAAS;IAAQ;IAAc;;;;UAIhB;EACf;EACA;EACA,SAAS;;;;;;;;iBAuEK,qBAAqB,UAAS;EAC5C;EACA,SAAS;;EAET;;;;;;;;;;;iBA2Hc,eACd,oBAAoB,WACpB,UAAS,iBACR;;UC1zBc;;EAEf;;EAEA;;EAEA;;EAEA;;KAGU;;UAGK;WACN;WACA;WACA,QAAQ,QAAQ;;WAEhB;;;UAIM;EACf;EACA;EACA,QAAQ;;EAER;;EAEA,sBAAsB;;;UAIP;EACf;EACA;EACA,SAAS;;;;;;;;iBA2FK,iBAAiB,UAAS,iBAAsB;;;;;;;;;;iBAiMhD,gBACd,oBAAoB,WACpB,iBACA,UAAS,iBACR"}

package/dist/_chunks/agents-sync.mjs

@@ -1,13 +1,20 @@
+import { addAbortListener } from "node:events";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
-import { execFileSync, spawn } from "node:child_process";
-import { basename, dirname, isAbsolute, join, normalize, resolve, sep } from "node:path";
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { basename, dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
 import os, { homedir } from "node:os";
 import { stripVTControlCharacters } from "node:util";
 import { parse } from "smol-toml";
+const PATH_MARKERS = /^~(?=\/|$)|\$\{HOME\}|\$\{PROJECT_ROOT\}|%([^%]+)%/g;
 function resolvePathTemplate(template, options = {}) {
 	const homeDir = options.homeDir ?? os.homedir();
 	const projectRoot = options.projectRoot ?? process.cwd();
-	return template.replace(/^~(?=\/|$)/, homeDir).replaceAll("${HOME}", homeDir).replaceAll("${PROJECT_ROOT}", projectRoot).replaceAll(/%([^%]+)%/g, (match, name) => process.env[name] ?? match);
+	return template.replaceAll(PATH_MARKERS, (match, name) => {
+		if (match === "${PROJECT_ROOT}") return projectRoot;
+		if (name === void 0) return homeDir;
+		return process.env[name] ?? match;
+	});
 }
 function agntnConfigDir(options = {}) {
 	const base = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME !== "" ? process.env.XDG_CONFIG_HOME : join(options.homeDir ?? os.homedir(), ".config");
@@ -53,13 +60,75 @@ function invocationTemplate(invocation, mode) {
 		case "agentStructured": return invocation.jsonArgs;
 	}
 }
+function invocationRetryHint(invocation, mode, options) {
+	const withoutStructured = requestedInvocationMode({
+		...options,
+		structured: false
+	});
+	if (options.structured === true) {
+		if (invocationTemplate(invocation, withoutStructured)) return "; retry with structured: false";
+		const alternateWithoutStructured = ALTERNATE_INVOCATION_MODE[withoutStructured];
+		if (alternateWithoutStructured !== void 0 && invocationTemplate(invocation, alternateWithoutStructured)) return `; retry with structured: false and tools: ${!options.tools}`;
+	}
+	const alternateMode = ALTERNATE_INVOCATION_MODE[mode];
+	return (alternateMode === void 0 ? void 0 : invocationTemplate(invocation, alternateMode)) ? INVOCATION_RETRY_HINT[mode] ?? "" : "";
+}
+function compareVersions(a, b) {
+	const [aBase = "", aPre] = a.split("-", 2);
+	const [bBase = "", bPre] = b.split("-", 2);
+	const left = aBase.split(".").map(Number);
+	const right = bBase.split(".").map(Number);
+	for (let i = 0; i < Math.max(left.length, right.length); i++) {
+		const diff = (left[i] ?? 0) - (right[i] ?? 0);
+		if (diff !== 0) return diff;
+	}
+	return Number(aPre === void 0) - Number(bPre === void 0);
+}
 function buildInvocationArgs(template, prompt, modelArgs, model) {
-	const args = template.map((arg) => arg.replaceAll("{prompt}", prompt));
-	if (model !== void 0 && modelArgs) args.push(...modelArgs.map((arg) => arg.replaceAll("{model}", model)));
+	const args = template.map((arg) => arg.replaceAll("{prompt}", () => prompt));
+	if (model !== void 0 && modelArgs) args.push(...modelArgs.map((arg) => arg.replaceAll("{model}", () => model)));
 	return args;
 }
+function signalProcessGroup(pid, signal) {
+	try {
+		process.kill(-pid, signal);
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) throw error;
+	}
+}
+async function terminateCommand(pid) {
+	if (process.platform === "win32") {
+		await new Promise((resolve, reject) => {
+			execFile(join(process.env.SystemRoot ?? "C:\\Windows", "System32", "taskkill.exe"), [
+				"/PID",
+				String(pid),
+				"/T",
+				"/F"
+			], {
+				windowsHide: true,
+				timeout: 2e3,
+				killSignal: "SIGKILL"
+			}, (error) => error ? reject(error) : resolve());
+		});
+		return;
+	}
+	signalProcessGroup(pid, "SIGTERM");
+	await setTimeout$1(500);
+	signalProcessGroup(pid, "SIGKILL");
+}
 function executeCommand(command, args, options) {
 	return new Promise((resolve, reject) => {
+		let stdout = "";
+		let stderr = "";
+		let stopped;
+		let settled = false;
+		let timer;
+		let abortListener;
+		if (options.signal?.aborted) {
+			stopped = "abort";
+			finish(null);
+			return;
+		}
 		const child = spawn(command, args, {
 			cwd: options.cwd,
 			env: options.env ? {
@@ -70,36 +139,60 @@ function executeCommand(command, args, options) {
 				"ignore",
 				"pipe",
 				"pipe"
-			]
+			],
+			detached: process.platform !== "win32" && (Boolean(options.timeoutMs) || options.signal !== void 0)
 		});
-		let stdout = "";
-		let stderr = "";
-		let timedOut = false;
-		const timer = options.timeoutMs ? setTimeout(() => {
-			timedOut = true;
-			child.kill("SIGTERM");
-		}, options.timeoutMs) : void 0;
+		if (options.timeoutMs) timer = setTimeout(() => stop("timeout"), options.timeoutMs);
+		if (options.signal) abortListener = addAbortListener(options.signal, () => stop("abort"));
 		child.stdout.on("data", (chunk) => {
 			stdout += chunk.toString("utf8");
 		});
 		child.stderr.on("data", (chunk) => {
 			stderr += chunk.toString("utf8");
 		});
-		child.on("error", (error) => {
-			if (timer) clearTimeout(timer);
-			reject(error);
-		});
+		child.on("error", fail);
 		child.on("close", (code) => {
+			if (stopped === void 0) finish(code);
+		});
+		function cleanup() {
 			if (timer) clearTimeout(timer);
+			abortListener?.[Symbol.dispose]();
+		}
+		function fail(error) {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(error);
+		}
+		function stop(reason) {
+			if (settled || stopped !== void 0) return;
+			stopped = reason;
+			cleanup();
+			if (child.pid === void 0) return;
+			terminateCommand(child.pid).then(() => {
+				child.stdout.destroy();
+				child.stderr.destroy();
+				finish(null);
+			}, (error) => {
+				child.stdout.destroy();
+				child.stderr.destroy();
+				fail(error);
+			});
+		}
+		function finish(code) {
+			if (settled) return;
+			settled = true;
+			cleanup();
 			resolve({
 				command,
 				args: [...args],
 				stdout,
 				stderr,
-				exitCode: timedOut ? null : code,
-				timedOut
+				exitCode: stopped === void 0 ? code : null,
+				timedOut: stopped === "timeout",
+				aborted: stopped === "abort"
 			});
-		});
+		}
 	});
 }
 var Harness = class {
@@ -168,9 +261,7 @@ var Harness = class {
 		if (options.model !== void 0 && !this.invocation.modelArgs) return `Harness ${this.id} does not support model selection`;
 		const mode = requestedInvocationMode(options);
 		if (invocationTemplate(this.invocation, mode)) return null;
-		const alternateMode = ALTERNATE_INVOCATION_MODE[mode];
-		const retry = (alternateMode === void 0 ? void 0 : invocationTemplate(this.invocation, alternateMode)) ? INVOCATION_RETRY_HINT[mode] ?? "" : "";
-		return `Harness ${this.id} has no ${INVOCATION_MODE_DESCRIPTION[mode]} invocation${retry}`;
+		return `${`Harness ${this.id} has no ${INVOCATION_MODE_DESCRIPTION[mode]} invocation`}${invocationRetryHint(this.invocation, mode, options)}`;
 	}
 	invoke(prompt, options = {}) {
 		const invocationOptions = {
@@ -181,8 +272,19 @@ var Harness = class {
 		};
 		const built = this.buildInvocation(prompt, invocationOptions);
 		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);
 	}
+	readOnlyVersionError(options) {
+		const floor = this.invocation?.readOnlyMinVersion;
+		if (floor === void 0 || options.readOnly !== true) return null;
+		const installed = this.version;
+		const error = `Harness ${this.id} requires version ${floor} or newer for read-only runs`;
+		if (installed === null) return `${error}; installed version unknown`;
+		if (compareVersions(installed, floor) < 0) return `${error}; installed ${installed}`;
+		return null;
+	}
 	buildModelListInvocation(search) {
 		if (!this.modelListing) return null;
 		const command = this.binaries[0];
@@ -191,7 +293,7 @@ var Harness = class {
 		if (!template) return null;
 		return {
 			command,
-			args: template.map((arg) => arg.replaceAll("{search}", search ?? ""))
+			args: template.map((arg) => arg.replaceAll("{search}", () => search ?? ""))
 		};
 	}
 	async listModels(options = {}) {
@@ -200,7 +302,7 @@ var Harness = class {
 		const result = await executeCommand(built.command, built.args, options);
 		return {
 			...result,
-			models: !result.timedOut && result.exitCode === 0 ? this.parseModelListingOutput(result.stdout) : []
+			models: !result.timedOut && !result.aborted && result.exitCode === 0 ? this.parseModelListingOutput(result.stdout) : []
 		};
 	}
 	parseModelListingOutput(_stdout) {
@@ -531,9 +633,26 @@ var Claude = class extends Harness {
 			"--tools",
 			""
 		],
+		readOnlyArgs: [
+			"-p",
+			"{prompt}",
+			"--strict-mcp-config",
+			"--tools",
+			"Read,Glob,Grep"
+		],
+		readOnlyJsonArgs: [
+			"-p",
+			"--output-format",
+			"json",
+			"{prompt}",
+			"--strict-mcp-config",
+			"--tools",
+			"Read,Glob,Grep"
+		],
+		readOnlyMinVersion: "2.1.175",
 		modelArgs: ["--model", "{model}"],
 		level: "official",
-		note: "Headless print mode; add --output-format json for structured output."
+		note: "Headless print mode; add --output-format json for structured output. Read-only runs keep the built-in Read, Glob and Grep tools and --strict-mcp-config drops every configured MCP server, 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",
@@ -691,20 +810,27 @@ var Codex = class extends Harness {
 	commands = [];
 	hooks = [];
 	invocation = {
-		args: ["exec", "{prompt}"],
+		args: [
+			"exec",
+			"--skip-git-repo-check",
+			"{prompt}"
+		],
 		jsonArgs: [
 			"exec",
+			"--skip-git-repo-check",
 			"--json",
 			"{prompt}"
 		],
 		readOnlyArgs: [
 			"exec",
+			"--skip-git-repo-check",
 			"--sandbox",
 			"read-only",
 			"{prompt}"
 		],
 		readOnlyJsonArgs: [
 			"exec",
+			"--skip-git-repo-check",
 			"--sandbox",
 			"read-only",
 			"--json",
@@ -1069,7 +1195,7 @@ var Gemini = class extends Harness {
 var GitHubCopilot = class extends Harness {
 	id = "github-copilot";
 	name = "GitHub Copilot";
-	binaries = [];
+	binaries = ["copilot"];
 	capabilities = {
 		mcp: true,
 		vision: true,
@@ -1247,9 +1373,24 @@ var Grok = class extends Harness {
 			"--output-format",
 			"json"
 		],
+		readOnlyArgs: [
+			"-p",
+			"{prompt}",
+			"--sandbox",
+			"read-only"
+		],
+		readOnlyJsonArgs: [
+			"-p",
+			"{prompt}",
+			"--sandbox",
+			"read-only",
+			"--output-format",
+			"json"
+		],
+		readOnlyMinVersion: "1.0.13",
 		modelArgs: ["--model", "{model}"],
 		level: "official",
-		note: "-p is short for --single; add --output-format json for structured output."
+		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."
 	};
 	mcpConfigs = [{
 		path: "~/.grok/config.toml",
@@ -1576,21 +1717,9 @@ var Omp = class extends Harness {
 			"json",
 			"{prompt}"
 		],
-		noToolsArgs: [
-			"-p",
-			"--no-tools",
-			"{prompt}"
-		],
-		noToolsJsonArgs: [
-			"-p",
-			"--no-tools",
-			"--mode",
-			"json",
-			"{prompt}"
-		],
 		modelArgs: ["--model={model}"],
 		level: "official",
-		note: "Add --mode json for structured event output."
+		note: "Add --mode json for structured event output. --no-tools disables only OMP's bundled tools, so it cannot provide an advisor mode without tools."
 	};
 	mcpConfigs = [{
 		path: "~/.omp/agent/mcp.json",
@@ -1883,6 +2012,20 @@ var Pi = class extends Harness {
 			"json",
 			"{prompt}"
 		],
+		readOnlyArgs: [
+			"-p",
+			"--tools",
+			"read,grep,find,ls",
+			"{prompt}"
+		],
+		readOnlyJsonArgs: [
+			"-p",
+			"--tools",
+			"read,grep,find,ls",
+			"--mode",
+			"json",
+			"{prompt}"
+		],
 		modelArgs: ["--model", "{model}"],
 		level: "official",
 		note: "Add --mode json for structured event output."
@@ -2406,7 +2549,7 @@ function canonical(server) {
 	return JSON.stringify(Object.fromEntries(Object.entries(server).sort(([a], [b]) => a.localeCompare(b))));
 }
 function expandHome(value, home) {
-	return value.replace(/^~(?=\/|$)/, home).replaceAll("${HOME}", home);
+	return value.replaceAll(/^~(?=\/|$)|\$\{HOME\}/g, () => home);
 }
 function expandServerHome(server, home) {
 	return compact({
@@ -2544,8 +2687,9 @@ function agentsConfigRecord(raw, configPath) {
 	if (typeof parsed !== "object" || parsed === null) throw new Error(`Agents config at ${configPath} is not an object`);
 	return parsed;
 }
-function agentsSource(value, defaultSource, options) {
-	if (typeof value !== "string") return defaultSource;
+function agentsSource(value, defaultSource, options, configPath) {
+	if (value === void 0) return defaultSource;
+	if (typeof value !== "string" || value.length === 0) throw new Error(`Agents config at ${configPath} has an invalid source: expected a path string`);
 	const expanded = resolvePathTemplate(value, options);
 	return isAbsolute(expanded) ? expanded : join(agntnConfigDir(options), expanded);
 }
@@ -2555,9 +2699,9 @@ function agentsExcludes(value, configPath) {
 	return value;
 }
 function companionPath(value, configPath) {
-	const normalized = normalize(value);
-	if (normalized === "." || normalized === ".." || normalized.startsWith(`..${sep}`) || isAbsolute(normalized)) throw new Error(`Agents config at ${configPath} has an unsafe companion path: ${JSON.stringify(normalized)}`);
-	return normalized.endsWith(sep) ? normalized.slice(0, -sep.length) : normalized;
+	const normalized = posix.normalize(value.replaceAll("\\", "/"));
+	if (normalized === "." || normalized === ".." || normalized.startsWith("../") || posix.isAbsolute(normalized) || win32.parse(value).root !== "") throw new Error(`Agents config at ${configPath} has an unsafe companion path: ${JSON.stringify(normalized)}`);
+	return normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
 }
 function comparablePath(path) {
 	return resolve(path).toLowerCase();
@@ -2581,7 +2725,7 @@ function readAgentsConfig(options = {}) {
 	if (raw === null) return defaults;
 	const record = agentsConfigRecord(raw, configPath);
 	return {
-		source: agentsSource(record.source, defaults.source, options),
+		source: agentsSource(record.source, defaults.source, options, configPath),
 		companions: agentsCompanions(record.companions, configPath),
 		excludes: agentsExcludes(record.excludes, configPath),
 		configPath