@phnx-labs/agents-cli 1.22.41 → 1.22.42

package/dist/lib/fs-atomic.js

@@ -55,6 +55,15 @@ export function atomicWriteFileSync(filePath, content, options = 'utf-8') {
         throw err;
     }
 }
+/**
+ * Convenience wrapper around {@link atomicWriteFileSync} for the common case of
+ * writing pretty-printed JSON (RUSH-2840). Same tmp-then-rename mechanics, same
+ * caller responsibility to ensure the parent directory exists first — this adds
+ * only the `JSON.stringify`.
+ */
+export function atomicWriteJsonSync(filePath, data) {
+    atomicWriteFileSync(filePath, JSON.stringify(data, null, 2));
+}
 export function withFileLock(filePath, fn, opts = {}) {
     let release = null;
     let lastError;

package/dist/lib/harness/adapter.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Harness adapter registry — the behavior axis of a supported harness.
+ *
+ * The declarative FLAG table lives in `AGENTS` (lib/agents.ts): what a harness
+ * *is* (cliCommand, configDir, capabilities). A HarnessAdapter carries what a
+ * harness *does* at the execution boundary — the per-harness quirks that four
+ * call sites otherwise each re-express as a `if (agent === 'x') … else if …`
+ * name-chain:
+ *
+ *   - config-dir env pins        → exec.ts buildExecEnv + shims.ts shim script
+ *   - launch-arg quirks          → exec.ts buildExecCommand + runner.ts buildJobCommand
+ *
+ * One adapter per harness is the single source of truth for that harness's
+ * behavior across every consuming site, mirroring the ChannelProvider
+ * (lib/channels/registry.ts), HostProvider (lib/hosts/types.ts), and
+ * AccountProviderAdapter (lib/account-provider-registry.ts) registries this repo
+ * already proves.
+ *
+ * NOT here: transcript parsing and live team-event normalization. Those are
+ * registry-dispatched too — a `Record` table in `session/parse.ts`
+ * (`TRANSCRIPT_PARSERS`) and one in `teams/parsers.ts` (`TEAM_EVENT_NORMALIZERS`)
+ * — but kept beside the parser functions they dispatch (which live in those
+ * files) rather than on this `AgentId` registry, because their id domains differ:
+ * the offline transcript reader keys on `SessionAgentId` (which includes `rush`,
+ * not an `AgentId`), and the live team-event normalizer keys on the teams
+ * `AgentType`. They stay separate functions — offline transcript vs live team
+ * events — deliberately.
+ */
+import type { AgentId, Mode } from '../types.js';
+import type { JobConfig } from '../scheduling/routines.js';
+/**
+ * Context for the exec-time config-env pin (mapping A, exec.ts side). The caller
+ * resolves the interactive/version facts once; the adapter only expresses the
+ * harness-specific env manipulation, operating on the accumulating `result` env
+ * exactly as the old per-agent branch did.
+ */
+export interface ExecConfigEnvCtx {
+    agent: AgentId;
+    /** The version to pin, pre-resolved by the caller (null = unresolved/not installed). */
+    version: string | null;
+    /** That version's home, pre-resolved by the caller (null when version is null). */
+    versionHome: string | null;
+    /** resolveInteractive(options) — computed once by the caller. */
+    interactive: boolean;
+    /**
+     * claude-account-token's resolveClaudeSetupToken, injected. The adapters MUST
+     * stay import-leaf: claude-account-token pulls in the secrets stack, which
+     * transitively imports sqlite.ts (top-level await). Importing it inside an
+     * adapter drags that into shims.ts's module graph (shims imports the harness
+     * barrel), and subprocess-spawning tests that load shims via tsx then fail the
+     * cjs transform. Only claude uses it.
+     */
+    resolveClaudeSetupToken: (versionHome: string) => string | null;
+}
+/** Context for the shim-script config-env block (mapping A, shims.ts side). */
+export interface ShimConfigEnvCtx {
+    /**
+     * The config-dir path relative to `$HOME` (e.g. `.claude`, or the nested
+     * `.gemini/antigravity-cli`), derived by the caller from the AGENTS registry.
+     */
+    configDirName: string;
+}
+/**
+ * Context for the exec-time launch-arg quirks (mapping B, exec.ts side). Mirrors
+ * the locals buildExecCommand already computed at the emission point.
+ */
+export interface ExecLaunchArgsCtx {
+    resolvedMode: Mode;
+    interactive: boolean;
+    cwd: string;
+    /** Extra writable roots (`--add-dir`) requested for this run, home-expanded. */
+    addDirs: string[];
+}
+/**
+ * Context for the routine (daemon-job) launch-arg quirks (mapping B, runner.ts
+ * side). This idiom mutates a pre-baked token array from ROUTINE_AGENT_COMMANDS,
+ * distinct from buildExecCommand's declarative modeFlags — so it is a separate
+ * method on the same adapter, one source of truth per harness across both.
+ */
+export interface RoutineLaunchCtx {
+    /** normalizeMode(config.mode) — the canonicalized mode. */
+    mode: Mode;
+    config: JobConfig;
+    /**
+     * exec.ts resolveHeadlessMode, injected to avoid an import cycle (exec.ts
+     * imports this registry). Kimi calls it for its plan→auto downgrade warning.
+     */
+    resolveHeadlessMode: (agent: AgentId, mode: Mode, interactive: boolean) => void;
+}
+export interface HarnessAdapter {
+    id: AgentId;
+    /**
+     * Apply this harness's config-dir env pins to the live process env for an
+     * `agents run` invocation (exec.ts buildExecEnv). Mutates `result` in place,
+     * exactly as the old per-agent branch did. The caller has already stripped the
+     * shared config-dir keys (CONFIG_DIR_ENV_KEYS), so an adapter only sets its own
+     * vars (plus any harness-specific extra it must delete, e.g. Claude's inherited
+     * OAuth token). Omitted for a harness with no config-dir env (the old `else`).
+     */
+    applyExecConfigEnv?(result: NodeJS.ProcessEnv, ctx: ExecConfigEnvCtx): void;
+    /**
+     * The config-env bash block for this harness's generated shim (shims.ts). The
+     * returned string is spliced verbatim into the shim script. Omitted (⇒ '') for
+     * a harness with no managed config-dir env.
+     */
+    shimConfigEnvBash?(ctx: ShimConfigEnvCtx): string;
+    /**
+     * Launch args appended to this harness's shim `exec` line (shims.ts). Codex
+     * pins `check_for_update_on_startup=false` + its edit-profile policy args here.
+     * Returns '' for a harness with no shim launch args.
+     */
+    shimLaunchArgs?(): string;
+    /**
+     * The shim's `exec` tail for this harness (shims.ts). Codex resolves the repo's
+     * `.agents` dir from `$PWD` at run time and appends `--add-dir`. Omitted ⇒ the
+     * default `exec "$BINARY"<launchArgs> "$@"`.
+     */
+    shimExecTail?(launchArgs: string): string;
+    /**
+     * Additive launch args emitted BEFORE mode-flag resolution in buildExecCommand
+     * (exec.ts). Cursor's `--trust` for a configured headless edit lives here.
+     * Returns undefined when this harness adds nothing.
+     */
+    execPreModeArgs?(ctx: ExecLaunchArgsCtx): string[] | undefined;
+    /**
+     * This harness's mode-flag emission for buildExecCommand (exec.ts), overriding
+     * the generic `template.modeFlags` / resume-subcommand path. Codex returns its
+     * policy args; Kimi returns [] for a headless run (and throws on an invariant
+     * violation). Returns undefined to defer to the generic path.
+     */
+    execModeArgs?(ctx: ExecLaunchArgsCtx): string[] | undefined;
+    /**
+     * This harness's routine (daemon-job) launch-arg quirks for buildJobCommand
+     * (runner.ts). Mutates the ROUTINE_AGENT_COMMANDS token array in place, exactly
+     * as the old per-agent arm did; runner appends model/reasoning flags after.
+     * Omitted for a harness with no routine launch quirks.
+     */
+    routineModeArgs?(cmd: string[], ctx: RoutineLaunchCtx): void;
+}
+/**
+ * The four config-dir env keys a harness pins to its version home. Every
+ * per-harness branch in the old buildExecEnv deleted the ones it does NOT set,
+ * so its own config pointer never leaks into a foreign harness's invocation.
+ * (XDG_CONFIG_HOME / XDG_DATA_HOME — Muse/Cursor — are deliberately absent: the
+ * old code sets them but never strips them, and this preserves that exactly.)
+ */
+export declare const CONFIG_DIR_ENV_KEYS: readonly ["CLAUDE_CONFIG_DIR", "CODEX_HOME", "COPILOT_HOME", "KIMI_CODE_HOME"];
+/**
+ * Strip every config-dir env key except the one(s) this harness sets. `keep=[]`
+ * (the default / no-config-dir harness) deletes all four — the old `else` arm.
+ */
+export declare function stripForeignConfigDir(result: NodeJS.ProcessEnv, keep?: readonly string[]): void;
+export declare function registerHarnessAdapter(adapter: HarnessAdapter): void;
+/**
+ * The behavior adapter for a harness. Every `AgentId` resolves to an adapter —
+ * one with real behavior when registered, else the id-only default (the old
+ * `else` arm). Callers therefore never name-check a harness.
+ */
+export declare function resolveHarnessAdapter(id: AgentId): HarnessAdapter;
+export declare function listHarnessAdapters(): AgentId[];

package/dist/lib/harness/adapter.js

@@ -0,0 +1,47 @@
+/**
+ * The four config-dir env keys a harness pins to its version home. Every
+ * per-harness branch in the old buildExecEnv deleted the ones it does NOT set,
+ * so its own config pointer never leaks into a foreign harness's invocation.
+ * (XDG_CONFIG_HOME / XDG_DATA_HOME — Muse/Cursor — are deliberately absent: the
+ * old code sets them but never strips them, and this preserves that exactly.)
+ */
+export const CONFIG_DIR_ENV_KEYS = [
+    'CLAUDE_CONFIG_DIR',
+    'CODEX_HOME',
+    'COPILOT_HOME',
+    'KIMI_CODE_HOME',
+];
+/**
+ * Strip every config-dir env key except the one(s) this harness sets. `keep=[]`
+ * (the default / no-config-dir harness) deletes all four — the old `else` arm.
+ */
+export function stripForeignConfigDir(result, keep = []) {
+    for (const key of CONFIG_DIR_ENV_KEYS) {
+        if (!keep.includes(key))
+            delete result[key];
+    }
+}
+const REGISTRY = new Map();
+/**
+ * The no-behavior adapter — a harness with no managed config-dir env and no
+ * launch-arg quirks. buildExecEnv strips all four config-dir keys for it (the old
+ * `else` arm) by falling back to {@link stripForeignConfigDir} when an adapter
+ * omits `applyExecConfigEnv`.
+ */
+function defaultAdapter(id) {
+    return { id };
+}
+export function registerHarnessAdapter(adapter) {
+    REGISTRY.set(adapter.id, adapter);
+}
+/**
+ * The behavior adapter for a harness. Every `AgentId` resolves to an adapter —
+ * one with real behavior when registered, else the id-only default (the old
+ * `else` arm). Callers therefore never name-check a harness.
+ */
+export function resolveHarnessAdapter(id) {
+    return REGISTRY.get(id) ?? defaultAdapter(id);
+}
+export function listHarnessAdapters() {
+    return [...REGISTRY.keys()].sort();
+}

package/dist/lib/harness/adapters/claude.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessAdapter } from '../adapter.js';
+export declare const claudeAdapter: HarnessAdapter;

package/dist/lib/harness/adapters/claude.js

@@ -0,0 +1,110 @@
+import * as path from 'path';
+import { stripForeignConfigDir } from '../adapter.js';
+export const claudeAdapter = {
+    id: 'claude',
+    applyExecConfigEnv(result, ctx) {
+        const { versionHome } = ctx;
+        // The per-account `claude setup-token` only resolves when there is a version
+        // home to key it to; version===null (claude unresolved / not installed) yields
+        // null, exactly as the routines path treats it (`runner.ts:1017-1021`). The
+        // token decision below runs even then, so an ambient inherited value is stripped
+        // on the routines/provisioned path regardless of whether a version resolved.
+        // resolveClaudeSetupToken is injected (see ExecConfigEnvCtx) to keep this
+        // adapter import-leaf — importing claude-account-token here would drag the
+        // secrets/sqlite graph into shims.ts.
+        const setupToken = versionHome ? ctx.resolveClaudeSetupToken(versionHome) : null;
+        if (versionHome) {
+            result.CLAUDE_CONFIG_DIR = path.join(versionHome, '.claude');
+            // A managed pin lives in a per-version dir; Claude Code's own background
+            // auto-updater would rewrite that pinned binary in place (and has left it
+            // half-swapped and broken). Disable it so a pin stays a pin. Honor an
+            // explicit user value — from process.env (already in result) or from
+            // options.env (spread over result below).
+            if (result.DISABLE_AUTOUPDATER === undefined) {
+                result.DISABLE_AUTOUPDATER = '1';
+            }
+        }
+        // The `auth` bundle's setup-token exists so a run with NO human present
+        // authenticates without the Touch-ID-gated login item — usage probes,
+        // routines, dispatched runs (claude-account-token.ts). An interactive run
+        // has a human at the TTY, and their own per-version login is the credential
+        // they established and expect; overriding it made `/status` report
+        // `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal machine and took every
+        // hand-driven session off that login. macOS cannot cheaply confirm a home's
+        // login first (probing the Keychain raises an authorization sheet per
+        // installed version on the `agents run` hot path — agents.ts
+        // `isClaudeCredentialFileBlank`), so interactive simply defers to Claude
+        // Code, which prompts a present human to log in if the login is missing.
+        if (ctx.interactive) {
+            // Drop an INHERITED copy of OUR OWN setup-token: an interactive launch from
+            // inside a headless agent's shell inherits that agent's injected value via
+            // sanitizeProcessEnv(process.env) and would keep authenticating as it.
+            // Matched by VALUE, so a token the user exported deliberately is a different
+            // string and is left alone (#2383). This is NARROWER than the non-interactive
+            // path below, which overwrites-or-deletes unconditionally and never inspects
+            // the inherited value — a DIFFERENT account's inherited setup-token passing
+            // through this equality check is the adjacent hole RUSH-2360 leaves as
+            // follow-up (it does not silently run on a *shared, rotating* token, which is
+            // what caused the RUSH-1822 logout storm).
+            if (setupToken && result.CLAUDE_CODE_OAUTH_TOKEN === setupToken) {
+                delete result.CLAUDE_CODE_OAUTH_TOKEN;
+            }
+        }
+        else {
+            // Non-interactive (routines, dispatched, provisioned box): mirror the routines
+            // path (`runner.ts:1017-1021`) UNCONDITIONALLY. Inject the per-account
+            // setup-token when one resolves — it replaces any ambient shared value
+            // inherited from the launcher. When NONE resolves, STRIP the ambient
+            // CLAUDE_CODE_OAUTH_TOKEN so a run on a provisioned box can never silently
+            // authenticate as the shared, rotating token an earlier version of this path
+            // let through — the RUSH-1822 fleet-wide-logout hazard, tracked by RUSH-2360.
+            // A missing login then fails loud (401) against this home's own credential
+            // instead of quietly borrowing another's. options.env still wins below for an
+            // explicit caller override.
+            if (setupToken) {
+                result.CLAUDE_CODE_OAUTH_TOKEN = setupToken;
+            }
+            else {
+                delete result.CLAUDE_CODE_OAUTH_TOKEN;
+            }
+        }
+        stripForeignConfigDir(result, ['CLAUDE_CONFIG_DIR']);
+    },
+    shimConfigEnvBash(ctx) {
+        return `
+# Claude stores OAuth credentials in the macOS keychain. Scope them to the
+# selected version's config directory so switching versions also switches the
+# live Claude account.
+export CLAUDE_CONFIG_DIR="$VERSION_DIR/home/${ctx.configDirName}"
+# Managed installs are pinned in a per-version dir; Claude Code's background
+# auto-updater would rewrite the pinned binary in place. Disable it so a pin
+# stays a pin. An explicit user value always wins.
+export DISABLE_AUTOUPDATER="\${DISABLE_AUTOUPDATER:-1}"
+# On Linux sandboxes (no keychain), fall back to a per-version token file.
+# The env var always wins if already set; no-op on macOS.
+if [ "\$(uname -s)" = "Linux" ] && [ -z "\${CLAUDE_CODE_OAUTH_TOKEN:-}" ] && [ -f "\$CLAUDE_CONFIG_DIR/.oauth_token" ]; then
+  CLAUDE_CODE_OAUTH_TOKEN=\$(cat "\$CLAUDE_CONFIG_DIR/.oauth_token")
+  export CLAUDE_CODE_OAUTH_TOKEN
+fi
+`;
+    },
+    routineModeArgs(cmd, ctx) {
+        const mode = ctx.mode;
+        if (mode === 'edit') {
+            const planIndex = cmd.indexOf('plan');
+            if (planIndex !== -1)
+                cmd[planIndex] = 'acceptEdits';
+        }
+        else if (mode === 'auto') {
+            const planIndex = cmd.indexOf('plan');
+            if (planIndex !== -1)
+                cmd[planIndex] = 'auto';
+        }
+        else if (mode === 'skip') {
+            // Replace --permission-mode plan with --dangerously-skip-permissions
+            const pmIndex = cmd.indexOf('--permission-mode');
+            if (pmIndex !== -1)
+                cmd.splice(pmIndex, 2, '--dangerously-skip-permissions');
+        }
+    },
+};

package/dist/lib/harness/adapters/codex.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessAdapter } from '../adapter.js';
+export declare const codexAdapter: HarnessAdapter;

package/dist/lib/harness/adapters/codex.js

@@ -0,0 +1,83 @@
+import * as os from 'os';
+import * as path from 'path';
+import { getHistoryDir } from '../../state.js';
+import { resolveCodexHome, codexHomeShimBash } from '../../codex-home.js';
+import { codexEditWritableRoots, codexPolicyArgs } from '../../codex-policy.js';
+import { stripForeignConfigDir } from '../adapter.js';
+/**
+ * Shim-script single-quoting — identical to the local `shellQuote` in shims.ts
+ * (always wraps in single quotes), NOT ssh-exec's variant (which leaves
+ * shell-safe strings unquoted). The generated shim's codex launch args must stay
+ * byte-for-byte what shims.ts produced, so the quoting moves with the logic.
+ */
+function shimShellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export const codexAdapter = {
+    id: 'codex',
+    applyExecConfigEnv(result, ctx) {
+        if (ctx.version && ctx.versionHome) {
+            // On macOS the deep versioned home overflows the Unix-socket SUN_LEN
+            // limit for codex's app-server control socket; resolve to a short,
+            // SUN_LEN-safe home (migrating once if needed). See codex-home.ts.
+            const versionedHome = path.join(ctx.versionHome, '.codex');
+            const agentsUserDir = path.dirname(getHistoryDir());
+            result.CODEX_HOME = resolveCodexHome(versionedHome, agentsUserDir, ctx.version);
+        }
+        stripForeignConfigDir(result, ['CODEX_HOME']);
+    },
+    shimConfigEnvBash(ctx) {
+        return codexHomeShimBash(`$VERSION_DIR/home/${ctx.configDirName}`, `$AGENTS_USER_DIR/.codex-homes/$VERSION`);
+    },
+    shimLaunchArgs() {
+        return ` ${[
+            '-c',
+            'check_for_update_on_startup=false',
+            ...codexPolicyArgs('edit'),
+        ].map(shimShellQuote).join(' ')}`;
+    },
+    shimExecTail(launchArgs) {
+        // Codex is special: its `workspace-write` sandbox hardcodes any `.agents/`
+        // (and `.codex/`) directory read-only, but agents-cli keeps every worktree at
+        // `<repo>/.agents/worktrees/<slug>`, so an in-repo build under a static shim
+        // would hit `EROFS`. The shim resolves the repo's `.agents` from `$PWD` at RUN
+        // time — worktree-aware, mirroring repoAgentsDirForCwd — and passes it via
+        // Codex's own `--add-dir`. `--add-dir` is added only when the resolved
+        // `.agents` exists.
+        return `_repo_agents=""
+case "$PWD" in
+  */.agents/worktrees/*) _repo_agents="\${PWD%%/.agents/worktrees/*}/.agents" ;;
+  *)
+    _d="$PWD"
+    # Stop before $HOME so a dotfiles repo at $HOME is not treated as the project
+    # root (mirrors repoRootForCwd's home exclusion in project-key.ts).
+    while [ -n "$_d" ] && [ "$_d" != "/" ] && [ "$_d" != "$HOME" ]; do
+      if [ -e "$_d/.git" ]; then _repo_agents="$_d/.agents"; break; fi
+      _d=$(dirname "$_d")
+    done
+    ;;
+esac
+if [ -n "$_repo_agents" ] && [ -d "$_repo_agents" ]; then
+  exec "$BINARY"${launchArgs} --add-dir "$_repo_agents" "$@"
+fi
+exec "$BINARY"${launchArgs} "$@"`;
+    },
+    execModeArgs(ctx) {
+        const policyMode = ctx.resolvedMode === 'plan' || ctx.resolvedMode === 'skip' ? ctx.resolvedMode : 'edit';
+        const writableRoots = [
+            ...codexEditWritableRoots(ctx.cwd),
+            ...ctx.addDirs,
+        ];
+        return codexPolicyArgs(policyMode, writableRoots);
+    },
+    routineModeArgs(cmd, ctx) {
+        const policyMode = ctx.mode === 'plan' || ctx.mode === 'skip' ? ctx.mode : 'edit';
+        const routineRoots = (ctx.config.allow?.dirs ?? []).map((dir) => {
+            if (dir.startsWith('-')) {
+                throw new Error(`allow.dirs entries must not start with '-': ${JSON.stringify(dir)}`);
+            }
+            return dir.replace(/^~/, os.homedir());
+        });
+        cmd.push(...codexPolicyArgs(policyMode, [...codexEditWritableRoots(), ...routineRoots]));
+    },
+};

package/dist/lib/harness/adapters/copilot.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessAdapter } from '../adapter.js';
+export declare const copilotAdapter: HarnessAdapter;

package/dist/lib/harness/adapters/copilot.js

@@ -0,0 +1,23 @@
+import * as path from 'path';
+import { stripForeignConfigDir } from '../adapter.js';
+export const copilotAdapter = {
+    id: 'copilot',
+    // Copilot honors COPILOT_HOME (relocates ~/.copilot, including settings,
+    // mcp-config.json, sessions, logs). Pin it at the per-version home so
+    // version switches isolate MCP servers, auth, and session history.
+    applyExecConfigEnv(result, ctx) {
+        if (ctx.versionHome) {
+            result.COPILOT_HOME = path.join(ctx.versionHome, '.copilot');
+        }
+        stripForeignConfigDir(result, ['COPILOT_HOME']);
+    },
+    shimConfigEnvBash(ctx) {
+        return `
+# GitHub Copilot CLI honors COPILOT_HOME to relocate its config and state
+# (settings.json, mcp-config.json, session-state/, logs/, plugins/). Point
+# it at the versioned home so MCP servers, custom agents, and session
+# history are isolated per copilot version.
+export COPILOT_HOME="$VERSION_DIR/home/${ctx.configDirName}"
+`;
+    },
+};

package/dist/lib/harness/adapters/cursor.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessAdapter } from '../adapter.js';
+export declare const cursorAdapter: HarnessAdapter;

package/dist/lib/harness/adapters/cursor.js

@@ -0,0 +1,38 @@
+import * as path from 'path';
+import { stripForeignConfigDir } from '../adapter.js';
+export const cursorAdapter = {
+    id: 'cursor',
+    // Cursor has no config-dir env var (only CURSOR_API_KEY / CURSOR_API_ENDPOINT).
+    // Its OAuth token — the login gate — lives at $XDG_CONFIG_HOME/cursor/auth.json
+    // (verified empirically: relocating XDG_CONFIG_HOME relocates the login;
+    // ~/.cursor/cli-config.json holds only account metadata, not the token). Pin
+    // XDG_CONFIG_HOME into the version home so each installed Cursor account
+    // authenticates from its own token, isolated per run — no global ~/.cursor
+    // symlink swap, so concurrent runs on different accounts never clobber one
+    // another. cli-config.json (HOME-relative) has no override and stays on the
+    // shared home; only the token is per-account, which is what gates the login.
+    applyExecConfigEnv(result, ctx) {
+        if (ctx.versionHome) {
+            result.XDG_CONFIG_HOME = path.join(ctx.versionHome, '.config');
+        }
+        stripForeignConfigDir(result);
+    },
+    execPreModeArgs(ctx) {
+        // A configured headless run is the workspace trust decision. Keep this
+        // narrower than --yolo/-f, which also bypasses permission checks.
+        return ctx.resolvedMode === 'edit' && !ctx.interactive ? ['--trust'] : undefined;
+    },
+    routineModeArgs(cmd, ctx) {
+        if (ctx.mode === 'plan') {
+            cmd.push('--plan');
+        }
+        else if (ctx.mode === 'skip') {
+            cmd.push('-f');
+        }
+        else {
+            // The configured cwd is the user's workspace trust decision. --trust is
+            // narrower than --yolo/-f because it does not bypass tool permissions.
+            cmd.push('--trust');
+        }
+    },
+};

package/dist/lib/harness/adapters/droid.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessAdapter } from '../adapter.js';
+export declare const droidAdapter: HarnessAdapter;

package/dist/lib/harness/adapters/droid.js

@@ -0,0 +1,17 @@
+// Droid has no config-dir env pin (exec strips the foreign keys via the registry
+// fallback) and no shim config env. Its only harness quirk is routine autonomy.
+export const droidAdapter = {
+    id: 'droid',
+    // droid exec defaults to read-only (plan). Escalate autonomy per mode.
+    routineModeArgs(cmd, ctx) {
+        if (ctx.mode === 'edit') {
+            cmd.push('--auto', 'low');
+        }
+        else if (ctx.mode === 'auto') {
+            cmd.push('--auto', 'high');
+        }
+        else if (ctx.mode === 'skip') {
+            cmd.push('--skip-permissions-unsafe');
+        }
+    },
+};

package/dist/lib/harness/adapters/grok.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessAdapter } from '../adapter.js';
+export declare const grokAdapter: HarnessAdapter;

package/dist/lib/harness/adapters/grok.js

@@ -0,0 +1,14 @@
+// Grok has no exec-time config-dir env pin (buildExecEnv's `else` strips the
+// foreign keys — the registry fallback preserves that). It DOES relocate its
+// whole config tree via GROK_HOME in the generated shim.
+export const grokAdapter = {
+    id: 'grok',
+    shimConfigEnvBash() {
+        return `
+# Grok Build uses GROK_HOME to isolate its entire configuration tree
+# (skills, hooks, plugins, agents, memory, sessions, config.toml, MCP, etc.).
+# This gives agents-cli full versioned isolation + resource sync for grok.
+export GROK_HOME="$VERSION_DIR/home/.grok"
+`;
+    },
+};

package/dist/lib/harness/adapters/kimi.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessAdapter } from '../adapter.js';
+export declare const kimiAdapter: HarnessAdapter;

package/dist/lib/harness/adapters/kimi.js

@@ -0,0 +1,49 @@
+import * as path from 'path';
+import { stripForeignConfigDir } from '../adapter.js';
+export const kimiAdapter = {
+    id: 'kimi',
+    // Kimi honors KIMI_CODE_HOME (relocates ~/.kimi-code, including config,
+    // skills, hooks, sessions). Pin it at the per-version home.
+    applyExecConfigEnv(result, ctx) {
+        if (ctx.versionHome) {
+            result.KIMI_CODE_HOME = path.join(ctx.versionHome, '.kimi-code');
+        }
+        stripForeignConfigDir(result, ['KIMI_CODE_HOME']);
+    },
+    shimConfigEnvBash(ctx) {
+        return `
+# Kimi Code CLI honors KIMI_CODE_HOME to relocate ~/.kimi-code (config.toml,
+# mcp.json, sessions, skills, hooks). Point it at the versioned home.
+export KIMI_CODE_HOME="$VERSION_DIR/home/${ctx.configDirName}"
+`;
+    },
+    execModeArgs(ctx) {
+        // kimi's headless prompt mode (`-p`/`--prompt`) is self-contained and REFUSES
+        // to be combined with any startup-mode flag: `--plan`, `--auto`, and `--yolo`
+        // all abort with "Cannot combine --prompt with --X" (verified against the live
+        // kimi CLI). The write-capable modes (edit/auto/skip) all collapse to kimi's
+        // default `-p` behavior, which already auto-approves tool calls, so we emit no
+        // mode flag. An interactive kimi run defers to the generic modeFlags path.
+        if (ctx.interactive)
+            return undefined;
+        // Plan can't reach here headless — resolveHeadlessMode already downgraded it to
+        // auto (kimi's headlessPlan:false); this asserts that invariant so a plan-mode
+        // run can never silently mutate the workspace.
+        if (ctx.resolvedMode === 'plan') {
+            throw new Error(`Internal error: kimi reached headless command build with resolved mode 'plan'; ` +
+                `resolveHeadlessMode should have downgraded it to auto (capabilities.headlessPlan is false).`);
+        }
+        // edit/auto/skip: emit no mode flag — `kimi -p` auto-runs.
+        return [];
+    },
+    routineModeArgs(_cmd, ctx) {
+        // kimi daemon jobs always run headless via `--prompt`, which cannot be
+        // combined with any startup-mode flag (--plan/--auto/--yolo all abort with
+        // "Cannot combine --prompt with --X"). edit/auto/skip reduce to kimi's default
+        // headless auto-run, so emit no flag. plan has no headless read-only
+        // equivalent, so resolveHeadlessMode downgrades a plan request to auto with a
+        // stderr warning (kimi's headlessPlan is false) — routines run headless, so
+        // interactive is always false here. The returned mode carries no flag either.
+        ctx.resolveHeadlessMode('kimi', ctx.mode, false);
+    },
+};

package/dist/lib/harness/adapters/muse.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessAdapter } from '../adapter.js';
+export declare const museAdapter: HarnessAdapter;

package/dist/lib/harness/adapters/muse.js

@@ -0,0 +1,44 @@
+import * as path from 'path';
+import { stripForeignConfigDir } from '../adapter.js';
+export const museAdapter = {
+    id: 'muse',
+    // Muse has no MUSE_CONFIG_DIR. Config is XDG-based:
+    //   $XDG_CONFIG_HOME/muse  (settings, skills, hooks, auth)
+    //   $XDG_DATA_HOME/muse    (sessions, plugins)
+    // Pin both into the version home so multi-version isolation matches
+    // Claude's CLAUDE_CONFIG_DIR / Codex's CODEX_HOME, and so Muse never
+    // resolves through the adopt-time ~/.config/muse symlink (SymlinkOrReparse).
+    applyExecConfigEnv(result, ctx) {
+        if (ctx.versionHome) {
+            result.XDG_CONFIG_HOME = path.join(ctx.versionHome, '.config');
+            result.XDG_DATA_HOME = path.join(ctx.versionHome, '.local', 'share');
+        }
+        stripForeignConfigDir(result);
+    },
+    shimConfigEnvBash() {
+        return `
+# Muse Code has no MUSE_CONFIG_DIR. It resolves config via XDG:
+#   $XDG_CONFIG_HOME/muse  (settings, skills, hooks, auth)
+#   $XDG_DATA_HOME/muse    (sessions, plugins)
+# Pin XDG into the version home so managed runs never walk the adopt-time
+# ~/.config/muse -> version-home symlink — Muse refuses agent-definition
+# sources that are SymlinkOrReparse (exit 1). Same idea as CLAUDE_CONFIG_DIR.
+export XDG_CONFIG_HOME="$VERSION_DIR/home/.config"
+export XDG_DATA_HOME="$VERSION_DIR/home/.local/share"
+`;
+    },
+    // muse exec: plan ≈ no non-shell writes; auto skips approval prompts but
+    // keeps the OS sandbox; skip is --yolo (no approval, no sandbox, trust).
+    routineModeArgs(cmd, ctx) {
+        if (ctx.mode === 'plan') {
+            cmd.push('--disable-write');
+        }
+        else if (ctx.mode === 'auto') {
+            cmd.push('--disable-approval');
+        }
+        else if (ctx.mode === 'skip') {
+            cmd.push('--yolo');
+        }
+        // edit: default on-request approval + sandbox
+    },
+};

package/dist/lib/harness/adapters/opencode.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessAdapter } from '../adapter.js';
+export declare const opencodeAdapter: HarnessAdapter;