harnery 0.46.0 → 0.47.0

package/src/lib/computer/lease.ts

@@ -0,0 +1,299 @@
+/**
+ * Desktop lease for `harn computer` (ADR 0228).
+ *
+ * One JSON file per desktop records which agent may drive it. Callers are
+ * short-lived CLI invocations from WSL distros and native Windows shells that
+ * share the file through `/mnt/<drive>` (drvfs) or the native path, so this
+ * module relies on nothing that breaks across that boundary:
+ *
+ * - No flock and no pid liveness. Owner identity is `LeaseOwner.id`; a lease
+ *   ends when its owner releases it or when it sits idle past `expires_at`.
+ * - The read-modify-write critical section is an atomic `mkdir` of
+ *   `<dir>/lease.lock`. The holder writes `owner.json` ({pid, at, token}) into
+ *   it and keeps it for milliseconds. A lock older than 10 seconds belongs to
+ *   a crashed holder and is broken.
+ * - Lease writes go to a temporary file in the same directory and are renamed
+ *   over the target, so a reader never sees a partial record.
+ *
+ * Generation rule: every acquisition of a free or expired lease increments
+ * `generation`, including an owner re-taking its own lease after it expired.
+ * A refresh of an unexpired lease by the same owner keeps the generation.
+ *
+ * Internal module: not exported from package.json.
+ */
+import { randomUUID } from "node:crypto";
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type {
+  DesktopLease,
+  LeaseAcquireResult,
+  LeaseApi,
+  LeaseOptions,
+  LeaseOwner,
+} from "./types.ts";
+
+/** Idle expiry when `LeaseOptions.idleMs` is omitted. */
+export const DEFAULT_LEASE_IDLE_MS = 120_000;
+const DEFAULT_POLL_MS = 500;
+const LEASE_FILE = "desktop-lease.json";
+const LOCK_DIR = "lease.lock";
+const LOCK_OWNER_FILE = "owner.json";
+/** A critical-section lock older than this belongs to a crashed holder. */
+const LOCK_STALE_MS = 10_000;
+/** Give up on the critical section after this long (stale break happens first). */
+const LOCK_TIMEOUT_MS = 15_000;
+const LOCK_RETRY_MS = 10;
+
+/** Directory holding the lease file for a desktop state dir. */
+export function leaseDir(desktopStateDir: string): string {
+  return join(desktopStateDir, "computer");
+}
+
+function leaseFile(dir: string): string {
+  return join(dir, LEASE_FILE);
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function errCode(error: unknown): string | undefined {
+  return (error as NodeJS.ErrnoException | undefined)?.code;
+}
+
+/** Parse a lease record; anything malformed counts as no lease. */
+function parseLease(text: string): DesktopLease | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== "object") return null;
+  const lease = value as Partial<DesktopLease>;
+  if (
+    lease.schema !== 1 ||
+    typeof lease.owner_id !== "string" ||
+    typeof lease.owner_label !== "string" ||
+    typeof lease.generation !== "number" ||
+    !Number.isFinite(lease.generation) ||
+    typeof lease.acquired_at !== "string" ||
+    typeof lease.refreshed_at !== "string" ||
+    typeof lease.expires_at !== "string" ||
+    Number.isNaN(Date.parse(lease.expires_at))
+  ) {
+    return null;
+  }
+  return lease as DesktopLease;
+}
+
+/** The lease record on disk, expired or not; null when missing or corrupt. */
+function readRaw(dir: string): DesktopLease | null {
+  try {
+    return parseLease(readFileSync(leaseFile(dir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isExpired(lease: DesktopLease, nowMs: number): boolean {
+  return nowMs >= Date.parse(lease.expires_at);
+}
+
+function writeLease(dir: string, lease: DesktopLease): void {
+  const tmp = join(dir, `${LEASE_FILE}.${process.pid}.${randomUUID()}.tmp`);
+  writeFileSync(tmp, `${JSON.stringify(lease, null, 2)}\n`);
+  try {
+    renameSync(tmp, leaseFile(dir));
+  } catch (error) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // best effort
+    }
+    throw error;
+  }
+}
+
+/** Age of a lock dir: owner.json `at`, else the directory mtime. */
+function lockAgeMs(lockDir: string): number | undefined {
+  try {
+    const owner = JSON.parse(readFileSync(join(lockDir, LOCK_OWNER_FILE), "utf8")) as {
+      at?: unknown;
+    };
+    const at = typeof owner.at === "string" ? Date.parse(owner.at) : Number.NaN;
+    if (!Number.isNaN(at)) return Date.now() - at;
+  } catch {
+    // owner.json not written yet or unreadable: fall back to the dir itself
+  }
+  try {
+    return Date.now() - statSync(lockDir).mtimeMs;
+  } catch {
+    return undefined; // lock vanished
+  }
+}
+
+/** Break a stale lock. Rename first so two breakers cannot both win. */
+function breakLock(lockDir: string): void {
+  const grave = `${lockDir}.stale.${process.pid}.${randomUUID()}`;
+  try {
+    renameSync(lockDir, grave);
+  } catch {
+    return; // someone else broke or released it
+  }
+  rmSync(grave, { recursive: true, force: true });
+}
+
+/**
+ * Run `fn` while holding the critical-section lock in `dir` (which must
+ * exist). Synchronous: the section is a few file operations, and release()
+ * is synchronous in the contract.
+ */
+function withLock<T>(dir: string, fn: () => T): T {
+  const lockDir = join(dir, LOCK_DIR);
+  const token = randomUUID();
+  const started = Date.now();
+  for (;;) {
+    try {
+      mkdirSync(lockDir);
+      break;
+    } catch (error) {
+      if (errCode(error) !== "EEXIST") throw error;
+    }
+    const age = lockAgeMs(lockDir);
+    if (age !== undefined && age > LOCK_STALE_MS) {
+      breakLock(lockDir);
+      continue;
+    }
+    if (Date.now() - started > LOCK_TIMEOUT_MS) {
+      throw new Error(`desktop lease: timed out waiting for ${lockDir}`);
+    }
+    sleepSync(LOCK_RETRY_MS);
+  }
+  try {
+    writeFileSync(
+      join(lockDir, LOCK_OWNER_FILE),
+      JSON.stringify({ pid: process.pid, at: new Date().toISOString(), token }),
+    );
+  } catch {
+    // The mkdir already gave us the lock; owner.json only aids stale detection.
+  }
+  try {
+    return fn();
+  } finally {
+    releaseLock(lockDir, token);
+  }
+}
+
+/** Remove the lock only if it is still ours (a slow holder may have been broken). */
+function releaseLock(lockDir: string, token: string): void {
+  try {
+    const owner = JSON.parse(readFileSync(join(lockDir, LOCK_OWNER_FILE), "utf8")) as {
+      token?: unknown;
+    };
+    if (owner.token !== token) return;
+  } catch (error) {
+    if (errCode(error) !== "ENOENT") return; // unreadable owner.json: leave it for stale breaking
+    // owner.json missing: our write failed or the lock is gone; fall through
+  }
+  rmSync(lockDir, { recursive: true, force: true });
+}
+
+type TryResult =
+  | { ok: true; lease: DesktopLease; fresh: boolean }
+  | { ok: false; holder: DesktopLease };
+
+function tryAcquire(owner: LeaseOwner, dir: string, nowMs: number, idleMs: number): TryResult {
+  return withLock(dir, () => {
+    const current = readRaw(dir);
+    const nowIso = new Date(nowMs).toISOString();
+    const expiresIso = new Date(nowMs + idleMs).toISOString();
+    if (current && !isExpired(current, nowMs)) {
+      if (current.owner_id !== owner.id) return { ok: false, holder: current };
+      const refreshed: DesktopLease = { ...current, refreshed_at: nowIso, expires_at: expiresIso };
+      writeLease(dir, refreshed);
+      return { ok: true, lease: refreshed, fresh: false };
+    }
+    const lease: DesktopLease = {
+      schema: 1,
+      owner_id: owner.id,
+      owner_label: owner.label,
+      ...(owner.project !== undefined ? { project: owner.project } : {}),
+      generation: (current?.generation ?? 0) + 1,
+      acquired_at: nowIso,
+      refreshed_at: nowIso,
+      expires_at: expiresIso,
+    };
+    writeLease(dir, lease);
+    return { ok: true, lease, fresh: true };
+  });
+}
+
+export interface DesktopLeaseDeps {
+  /** Async sleep used while waiting for another owner's lease. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+/** Build a lease API; tests inject `sleep` (and `LeaseOptions.now`). */
+export function createDesktopLease(deps: DesktopLeaseDeps = {}): LeaseApi {
+  const sleep =
+    deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+  return {
+    async acquire(owner: LeaseOwner, opts: LeaseOptions): Promise<LeaseAcquireResult> {
+      const now = opts.now ?? Date.now;
+      const idleMs = opts.idleMs ?? DEFAULT_LEASE_IDLE_MS;
+      const waitMs = Math.max(0, opts.waitMs ?? 0);
+      const pollMs = Math.max(1, opts.pollMs ?? DEFAULT_POLL_MS);
+      mkdirSync(opts.dir, { recursive: true });
+      const started = now();
+      // Track slept time too, so a frozen injected clock cannot wait forever.
+      let slept = 0;
+      for (;;) {
+        const result = tryAcquire(owner, opts.dir, now(), idleMs);
+        const waited = Math.max(now() - started, slept);
+        if (result.ok) return result;
+        const remaining = waitMs - waited;
+        if (remaining <= 0) return { ok: false, holder: result.holder, waitedMs: waited };
+        const step = Math.min(pollMs, remaining);
+        await sleep(step);
+        slept += step;
+      }
+    },
+
+    release(owner: LeaseOwner, opts: LeaseOptions): boolean {
+      try {
+        if (!statSync(opts.dir).isDirectory()) return false;
+      } catch {
+        return false;
+      }
+      return withLock(opts.dir, () => {
+        const current = readRaw(opts.dir);
+        if (!current || current.owner_id !== owner.id) return false;
+        const nowMs = (opts.now ?? Date.now)();
+        if (isExpired(current, nowMs)) return false;
+        // Expire the record instead of deleting it, so the next owner's
+        // generation still counts up from this one.
+        const nowIso = new Date(nowMs).toISOString();
+        writeLease(opts.dir, { ...current, refreshed_at: nowIso, expires_at: nowIso });
+        return true;
+      });
+    },
+
+    read(opts: LeaseOptions): DesktopLease | null {
+      const now = opts.now ?? Date.now;
+      const lease = readRaw(opts.dir);
+      return lease && !isExpired(lease, now()) ? lease : null;
+    },
+  };
+}
+
+export const desktopLease: LeaseApi = createDesktopLease();

package/src/lib/computer/types.ts

@@ -0,0 +1,177 @@
+/**
+ * Shared contracts for `harn computer` (ADR 0228).
+ *
+ * The command layer and the desktop lease depend only on these types. Every
+ * driver-specific detail (release URLs, archive layout, CLI arguments, config
+ * files) lives behind `DesktopDriver` in a driver module such as `cua.ts`.
+ *
+ * Internal module: not exported from package.json.
+ */
+
+/** Where the desktop being driven lives, relative to the calling process. */
+export type HostKind =
+  /** A native Windows process driving its own desktop. */
+  | "windows"
+  /** A WSL2 process driving the Windows desktop through interop. */
+  | "wsl"
+  /** Any host without a supported driver build (macOS, Linux desktops). */
+  | "unsupported";
+
+export interface HostInfo {
+  kind: HostKind;
+  /** Human-readable reason when kind is "unsupported". */
+  reason?: string;
+  /**
+   * Directory (in the CALLER's path syntax) that is shared by every caller of
+   * this desktop: on Windows and WSL, `%LOCALAPPDATA%\harnery` expressed as a
+   * Windows path (windows) or its `/mnt/<drive>/...` form (wsl). The lease file
+   * and driver installs live under it.
+   */
+  desktopStateDir?: string;
+}
+
+/** A pinned, checksum-verified build of one driver for one platform. */
+export interface PinnedArtifact {
+  /** Driver version, e.g. "0.38.0". */
+  version: string;
+  /** Archive file name as published. */
+  fileName: string;
+  /** Download URL. */
+  url: string;
+  /** Lowercase hex SHA-256 of the archive. */
+  sha256: string;
+  /** Path of the driver executable inside the archive. */
+  executableEntry: string;
+}
+
+export interface InstallPlan {
+  driver: string;
+  version: string;
+  host: HostKind;
+  artifact: PinnedArtifact;
+  /** Install directory in the caller's path syntax (versioned). */
+  installDir: string;
+  /** Executable path in the caller's path syntax. */
+  executable: string;
+  /** Already installed and the executable's archive hash was verified at install time. */
+  alreadyInstalled: boolean;
+  /** Driver preference file written before first run, caller's path syntax. */
+  preferenceFile: string;
+  /** Preferences merged into that file (e.g. telemetry off). */
+  preferences: Record<string, unknown>;
+}
+
+export interface InstallResult extends InstallPlan {
+  installed: boolean;
+}
+
+export interface DaemonStatus {
+  running: boolean;
+  /** Raw first line(s) from the driver's status output, for display. */
+  detail: string;
+  pid?: number;
+}
+
+export interface DriverCallResult {
+  /** Process exit code of the driver invocation. */
+  exitCode: number;
+  /** Driver stdout with CRLF normalized to LF. */
+  stdout: string;
+  /** Driver stderr with CRLF normalized to LF. */
+  stderr: string;
+  /** Parsed stdout when it is a single JSON value, else undefined. */
+  json?: unknown;
+}
+
+/**
+ * The adapter boundary. One implementation today (`cua.ts`); a second driver
+ * would implement this interface rather than branch inside the command.
+ */
+export interface DesktopDriver {
+  /** Stable id, e.g. "cua". */
+  readonly id: string;
+  /** Pinned version this Harnery build installs. */
+  readonly version: string;
+  /** Resolve the install plan for this host without side effects. */
+  planInstall(host: HostInfo): InstallPlan;
+  /** Download, verify, extract and write preferences. Idempotent. */
+  install(plan: InstallPlan): Promise<InstallResult>;
+  /** Executable path if the pinned version is installed, else undefined. */
+  installedExecutable(host: HostInfo): string | undefined;
+  daemonStatus(host: HostInfo): DaemonStatus;
+  /** Start the daemon unelevated if it is not running. Returns the new status. */
+  startDaemon(host: HostInfo): Promise<DaemonStatus>;
+  stopDaemon(host: HostInfo): DaemonStatus;
+  /** One tool call. `args` is the JSON object passed to the tool. */
+  call(host: HostInfo, tool: string, args: Record<string, unknown>): DriverCallResult;
+  /** Tool catalog lines ("name: description"). */
+  listTools(host: HostInfo): DriverCallResult;
+  /** Full description + input schema of one tool. */
+  describe(host: HostInfo, tool: string): DriverCallResult;
+  /** End-to-end diagnostics (driver's own health report). */
+  health(host: HostInfo): DriverCallResult;
+  /**
+   * Rewrite caller-side paths inside tool args to the driver's path syntax
+   * (e.g. WSL `/home/...` -> `\\wsl.localhost\...`, `/mnt/c/...` -> `C:\...`),
+   * and the reverse for paths in results. Identity on native hosts.
+   */
+  translateArgsPaths(
+    host: HostInfo,
+    tool: string,
+    args: Record<string, unknown>,
+  ): Record<string, unknown>;
+  translateResultPaths(host: HostInfo, stdout: string): string;
+}
+
+/** Who is asking for the desktop. Resolved by the command layer. */
+export interface LeaseOwner {
+  /** Stable id: the agent instance id, or `pid:<pid>@<host>` without one. */
+  id: string;
+  /** Display label, e.g. "agent-Dexter". Also the default driver session. */
+  label: string;
+  /** Project root of the caller, informational. */
+  project?: string;
+}
+
+/** On-disk lease record (one per desktop). */
+export interface DesktopLease {
+  schema: 1;
+  owner_id: string;
+  owner_label: string;
+  project?: string;
+  /** Increments on every fresh acquisition (no lease, or the previous one expired or was released). */
+  generation: number;
+  acquired_at: string;
+  refreshed_at: string;
+  /** ISO time after which the lease is free for anyone. */
+  expires_at: string;
+}
+
+export interface LeaseOptions {
+  /** Directory holding the lease file (HostInfo.desktopStateDir/computer). */
+  dir: string;
+  /** Idle expiry, refreshed on every acquire by the same owner. Default 120s. */
+  idleMs?: number;
+  /** How long to wait for another owner's lease. Default 0 (fail at once). */
+  waitMs?: number;
+  /** Poll interval while waiting. Default 500ms. */
+  pollMs?: number;
+  /** Injectable clock for tests. */
+  now?: () => number;
+}
+
+export type LeaseAcquireResult =
+  | {
+      ok: true;
+      lease: DesktopLease /** true when this call took the lease from nobody/expired. */;
+      fresh: boolean;
+    }
+  | { ok: false; holder: DesktopLease; waitedMs: number };
+
+export interface LeaseApi {
+  acquire(owner: LeaseOwner, opts: LeaseOptions): Promise<LeaseAcquireResult>;
+  /** Release only if held by `owner`. Returns true when a lease was removed. */
+  release(owner: LeaseOwner, opts: LeaseOptions): boolean;
+  /** Current unexpired lease, or null. */
+  read(opts: LeaseOptions): DesktopLease | null;
+}

package/src/lib/docs-metadata-v2.ts

@@ -287,7 +287,13 @@ function validateRelations(
   const allowed = new Set(["depends_on", "supersedes", "superseded_by", "continues", "related"]);
   for (const [key, value] of Object.entries(data.relations)) {
     if (!allowed.has(key)) {
-      add(issues, "error", "unknown_relation", `relations.${key}`, `unknown relation '${key}'`);
+      add(
+        issues,
+        "error",
+        "unknown_relation",
+        `relations.${key}`,
+        `unknown relation '${key}'; use one of: ${[...allowed].join(", ")}`,
+      );
       continue;
     }
     validateStringList(value, `relations.${key}`, issues);
@@ -311,7 +317,7 @@ function validateAccess(
         "error",
         "unknown_access_field",
         `access.${key}`,
-        `unknown access field '${key}'`,
+        `unknown access field '${key}'; use ${[...allowed].join(" or ")}`,
       );
     }
   }
@@ -334,7 +340,13 @@ function validateLifecycle(
   const allowed =
     type === "plan" ? PLAN_STATUSES : type === "issue" ? ISSUE_STATUSES : HANDOFF_STATUSES;
   if (status && !allowed.has(status)) {
-    add(issues, "error", "invalid_status", "status", `status '${status}' is invalid for ${type}`);
+    add(
+      issues,
+      "error",
+      "invalid_status",
+      "status",
+      `status '${status}' is invalid for ${type}; use one of: ${[...allowed].join(", ")}`,
+    );
   }
 
   const changedAt = validateTimestamp(data, "status_changed_at", issues);
@@ -543,8 +555,15 @@ function validateInquiry(
 ): void {
   requireString(data, "title", issues);
   const status = requireString(data, "status", issues);
-  if (status && !new Set(["open", "resolved", "abandoned"]).has(status)) {
-    add(issues, "error", "invalid_status", "status", `inquiry status '${status}' is invalid`);
+  const inquiryStatuses = ["open", "resolved", "abandoned"];
+  if (status && !inquiryStatuses.includes(status)) {
+    add(
+      issues,
+      "error",
+      "invalid_status",
+      "status",
+      `inquiry status '${status}' is invalid; use one of: ${inquiryStatuses.join(", ")}`,
+    );
   }
   const changedAt = validateTimestamp(data, "status_changed_at", issues);
   if (createdAt !== null && changedAt !== null && changedAt < createdAt) {

package/src/lib/exec.ts

@@ -46,6 +46,7 @@ export function exec(cmd: string[], opts: ExecOpts = {}): Promise<ExecResult> {
   const [file, ...args] = cmd;
   return new Promise<ExecResult>((resolveResult) => {
     const proc = spawn(file, args, {
+      windowsHide: true,
       cwd: opts.cwd ?? process.cwd(),
       env: opts.env ?? { ...process.env },
       stdio: ["ignore", "pipe", "pipe"],

package/src/lib/guarded-remove.ts

@@ -92,7 +92,8 @@ export function guardedRemove(
     throw new Error("--root cannot be a filesystem root or home directory");
   assertEntryLimitAuthority();
   if (paths.length === 0 || paths.length > 100) throw new Error("Supply 1-100 explicit targets");
-  const targets = paths.map((path) => checkedPath(path, allowed));
+  // Relative targets name paths under --root, never under the process cwd.
+  const targets = paths.map((path) => checkedPath(path, allowed, false, root));
   const snapshots = new Map<string, string>();
   const removedProtected = new Set<string>();
   const links: RemovalLink[] = [];
@@ -349,7 +350,7 @@ function allowedProtected(
   for (const input of paths) {
     if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
       throw new Error("Use a nonempty explicit --allow-protected path without wildcards");
-    const path = resolve(input);
+    const path = resolve(root, input);
     let cursor = dirname(path);
     while (true) {
       if (lstatSync(cursor).isSymbolicLink())
@@ -435,10 +436,11 @@ function checkedPath(
   input: string,
   allowed: ReadonlySet<string> = new Set(),
   isRoot = false,
+  base?: string,
 ): string {
   if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
     throw new Error("Use a nonempty explicit path without wildcards or unresolved variables");
-  const path = resolve(input);
+  const path = base === undefined ? resolve(input) : resolve(base, input);
   let cursor = path;
   while (true) {
     if (

package/src/lib/headless/index.ts

@@ -26,6 +26,11 @@
  *   PATH" is not "working", and under parallel load the first backend can
  *   flake on a fraction of calls while the second runs clean.
  *
+ * - A claude-code call loads NO MCP servers and no claude.ai connectors by
+ *   default (`claudeMcpLaunch`). Connectors attach about 130 tool schemas to
+ *   every turn of a one-shot call that never uses them; a caller that needs
+ *   one opts in per request with `mcp: "inherit"` or an explicit server map.
+ *
  * Env knobs (read through coordEnv, so the HARNERY_ prefix stays in one
  * place): HARNERY_HEADLESS_BACKEND forces one backend and disables the
  * fallback walk; HARNERY_HEADLESS_MODEL overrides the model passed to
@@ -77,6 +82,55 @@ export interface HeadlessRequest {
   timeoutMs?: number;
   /** Agentic turn budget where the backend supports one (default 4). */
   maxTurns?: number;
+  /** MCP servers the claude-code backend may load (default `"none"`; see
+   * `ClaudeMcpMode`). The codex and cursor backends ignore it. */
+  mcp?: ClaudeMcpMode;
+}
+
+/**
+ * Which MCP servers a spawned `claude` child may load.
+ *
+ * - `"none"` (the default for every spawn Harnery owns): no MCP servers and no
+ *   claude.ai connectors. Measured on a headless child, connectors add tens of
+ *   thousands of tokens of tool schemas to every turn.
+ * - `"inherit"`: whatever Claude Code would load on its own, connectors
+ *   included. The explicit opt-in for a workflow that really uses one.
+ * - `{ mcpServers }`: exactly these servers (the `--mcp-config` JSON shape),
+ *   with claude.ai connectors still off.
+ */
+export type ClaudeMcpMode = "none" | "inherit" | { mcpServers: Record<string, unknown> };
+
+/** The two guards that keep a `claude` child free of MCP servers: strict MCP
+ * config with an empty server map, plus the env switch that stops claude.ai
+ * connectors attaching mid-session (the flag alone does not cover them). */
+export const CLAUDE_NO_MCP_ARGS: readonly string[] = [
+  "--strict-mcp-config",
+  "--mcp-config",
+  '{"mcpServers":{}}',
+];
+export const CLAUDE_NO_CONNECTORS_ENV: Readonly<Record<string, string>> = {
+  ENABLE_CLAUDEAI_MCP_SERVERS: "false",
+};
+
+/** Resolve an MCP mode to the argv and env additions for a `claude` child.
+ * Throws on a malformed server map rather than launching with a guess. */
+export function claudeMcpLaunch(mode: ClaudeMcpMode = "none"): {
+  args: string[];
+  env: Record<string, string>;
+} {
+  if (mode === "inherit") return { args: [], env: {} };
+  if (mode === "none")
+    return { args: [...CLAUDE_NO_MCP_ARGS], env: { ...CLAUDE_NO_CONNECTORS_ENV } };
+  const servers = (mode as { mcpServers?: unknown } | null)?.mcpServers;
+  if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+    throw new Error(
+      'mcp must be "none", "inherit", or { mcpServers: { <name>: <server config> } }',
+    );
+  }
+  return {
+    args: ["--strict-mcp-config", "--mcp-config", JSON.stringify({ mcpServers: servers })],
+    env: { ...CLAUDE_NO_CONNECTORS_ENV },
+  };
 }
 
 export interface HeadlessResult {
@@ -135,6 +189,7 @@ interface StagedCall {
   model?: string;
   timeoutMs: number;
   maxTurns: number;
+  mcp?: ClaudeMcpMode;
 }
 
 /** Write the request's images into a fresh neutral dir and resolve the
@@ -154,16 +209,23 @@ function stageCall(req: HeadlessRequest): StagedCall {
     model: coordEnv("HEADLESS_MODEL") ?? req.model,
     timeoutMs: req.timeoutMs ?? DEFAULT_TIMEOUT_MS,
     maxTurns: req.maxTurns ?? DEFAULT_MAX_TURNS,
+    ...(req.mcp ? { mcp: req.mcp } : {}),
   };
 }
 
 /** Run a harness CLI from the neutral dir with stdin CLOSED (see module
  * comment: an open stdin pipe deadlocks codex). */
-function execHarness(bin: string, args: string[], call: StagedCall) {
+function execHarness(
+  bin: string,
+  args: string[],
+  call: StagedCall,
+  extraEnv: Record<string, string> = {},
+) {
   const pending = execFileAsync(bin, args, {
     cwd: call.dir,
     timeout: call.timeoutMs,
     maxBuffer: MAX_BUFFER,
+    ...(Object.keys(extraEnv).length ? { env: { ...process.env, ...extraEnv } } : {}),
   });
   pending.child.stdin?.end();
   return pending;
@@ -178,7 +240,9 @@ async function runClaudeCode(bin: string, call: StagedCall): Promise<HeadlessRes
   const args = ["-p", call.prompt, "--output-format", "json", "--max-turns", String(call.maxTurns)];
   if (call.imagePaths.length) args.push("--allowedTools", "Read");
   if (call.model) args.push("--model", call.model);
-  const { stdout } = await execHarness(bin, args, call);
+  const mcp = claudeMcpLaunch(call.mcp);
+  args.push(...mcp.args);
+  const { stdout } = await execHarness(bin, args, call, mcp.env);
   const envelope = JSON.parse(stdout) as { is_error?: boolean; result?: unknown };
   if (envelope.is_error) {
     throw new Error(