@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,195 +1,44 @@
-/**
- * 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';
 import type { ConfiguredDeviceRole } from '../device-config.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;
-    /**
-     * The role marked on THIS machine (worker | personal | desktop | undefined),
-     * resolved once by the caller from selfConfiguredDeviceRole(). A headed device
-     * (`personal` or `desktop` — see isHeadedDeviceRole) holds a real per-version
-     * login and the credential decision MUST defer to it for EVERY run — interactive
-     * OR headless — never the worker-only setup-token (RUSH-2395). Injected as a
-     * plain value (not imported) to keep the adapter import-leaf. Absent/undefined
-     * is treated as non-headed (worker-equivalent).
-     */
     deviceRole?: ConfiguredDeviceRole;
-    /**
-     * 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 token array baked from AGENT_COMMANDS
- * (bakeRoutineArgv), 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 bakeRoutineArgv 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;
 }
-/**
- * Config-dir env keys a harness pins to its slot / version home. Every
- * per-harness branch in buildExecEnv deletes the ones it does NOT set, so a
- * slot never inherits another account's dir (PHNX-3940 T5). GROK_HOME,
- * OPENCODE_CONFIG_DIR, and the XDG pair were previously omitted, which let a
- * parent agent's pin leak into a sibling slot.
- */
 export declare const CONFIG_DIR_ENV_KEYS: readonly ["CLAUDE_CONFIG_DIR", "CODEX_HOME", "COPILOT_HOME", "KIMI_CODE_HOME", "GROK_HOME", "OPENCODE_CONFIG_DIR", "XDG_CONFIG_HOME", "XDG_DATA_HOME"];
-/**
- * Strip every config-dir env key except the one(s) this harness sets. `keep=[]`
- * (the default / no-config-dir harness) deletes all of them — the old `else` arm.
- */
 export declare function stripForeignConfigDir(result: NodeJS.ProcessEnv, keep?: readonly string[]): void;
-/**
- * Bash for a harness's config-dir pin that yields to an account-slot launch.
- *
- * A shim (bare or `<agent>@<version>` alias) pins the harness's config-dir env
- * at the version home. An account-slot launch (PHNX-3940 T5) has already chosen
- * the HOME-shaped slot: `agents run` pins the same env at the slot in
- * buildExecEnv and stamps the slot in AGENTS_EXEC_HOME. The shim used to
- * re-export the version home unconditionally, so a run picked as one account
- * read and wrote another account's home (claude on yosemite-m1, 2026-09-10;
- * the same override for every harness below). The pin now yields to the slot
- * — the way the cursor alias's HOME swap yields to a spawner-chosen HOME — and
- * consumes the marker so the launched harness never inherits it into a nested
- * launch; a bare `<agent>@<version>` from a terminal still gets the version home.
- *
- * `pins` are `{ env, rel }` with `rel` the HOME-relative config path (the slot
- * and the version home are both HOME-shaped); `versionHome` is the bash
- * expression for the version home (`$VERSION_DIR/home` in the shared block, the
- * absolute versions path in a direct alias).
- */
 export declare function slotAwareConfigEnvBash(pins: ReadonlyArray<{
     env: string;
     rel: string;
 }>, versionHome: string): string;
 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

@@ -1,10 +1,3 @@
-/**
- * Config-dir env keys a harness pins to its slot / version home. Every
- * per-harness branch in buildExecEnv deletes the ones it does NOT set, so a
- * slot never inherits another account's dir (PHNX-3940 T5). GROK_HOME,
- * OPENCODE_CONFIG_DIR, and the XDG pair were previously omitted, which let a
- * parent agent's pin leak into a sibling slot.
- */
 export const CONFIG_DIR_ENV_KEYS = [
     'CLAUDE_CONFIG_DIR',
     'CODEX_HOME',
@@ -15,35 +8,12 @@ export const CONFIG_DIR_ENV_KEYS = [
     'XDG_CONFIG_HOME',
     'XDG_DATA_HOME',
 ];
-/**
- * Strip every config-dir env key except the one(s) this harness sets. `keep=[]`
- * (the default / no-config-dir harness) deletes all of them — the old `else` arm.
- */
 export function stripForeignConfigDir(result, keep = []) {
     for (const key of CONFIG_DIR_ENV_KEYS) {
         if (!keep.includes(key))
             delete result[key];
     }
 }
-/**
- * Bash for a harness's config-dir pin that yields to an account-slot launch.
- *
- * A shim (bare or `<agent>@<version>` alias) pins the harness's config-dir env
- * at the version home. An account-slot launch (PHNX-3940 T5) has already chosen
- * the HOME-shaped slot: `agents run` pins the same env at the slot in
- * buildExecEnv and stamps the slot in AGENTS_EXEC_HOME. The shim used to
- * re-export the version home unconditionally, so a run picked as one account
- * read and wrote another account's home (claude on yosemite-m1, 2026-09-10;
- * the same override for every harness below). The pin now yields to the slot
- * — the way the cursor alias's HOME swap yields to a spawner-chosen HOME — and
- * consumes the marker so the launched harness never inherits it into a nested
- * launch; a bare `<agent>@<version>` from a terminal still gets the version home.
- *
- * `pins` are `{ env, rel }` with `rel` the HOME-relative config path (the slot
- * and the version home are both HOME-shaped); `versionHome` is the bash
- * expression for the version home (`$VERSION_DIR/home` in the shared block, the
- * absolute versions path in a direct alias).
- */
 export function slotAwareConfigEnvBash(pins, versionHome) {
     const slot = pins.map((p) => `  export ${p.env}="$AGENTS_EXEC_HOME/${p.rel}"`).join('\n');
     const version = pins.map((p) => `  export ${p.env}="${versionHome}/${p.rel}"`).join('\n');
@@ -55,23 +25,12 @@ ${version}
 fi`;
 }
 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);
 }

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

@@ -26,14 +26,6 @@ export declare function claudeWorkerLoginTrapPreflight(args: {
     agent: AgentId;
     interactive: boolean;
     deviceRole?: ConfiguredDeviceRole;
-    /**
-     * Will a Claude credential actually reach the child at spawn? The caller ORs
-     * the resolved worker setup-token with an explicit `--env
-     * CLAUDE_CODE_OAUTH_TOKEN=…` override — `buildExecEnv` merges `options.env`
-     * LAST and unconditionally, so that override wins even the worker branch's
-     * strip and authenticates the run. Gating on the setup-token alone would
-     * falsely refuse that sanctioned escape hatch (forwarded across `--device`).
-     */
     hasWorkerCredential: boolean;
     machine?: string;
 }): string | null;

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

@@ -5,83 +5,20 @@ 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). It is a WORKER
-        // credential. Exactly one kind of run defers to the per-version login
-        // instead: ANY run on a `personal`/`desktop` (headed) device — the user's
-        // own interactive box (zion), marked `config.role: personal`. That box
-        // holds a real per-version login and is the single origin of it, so every
-        // run there — interactive TUI OR a headless one-shot like `agents run
-        // claude "fix the bug"` — MUST use that login, not the setup-token. Keying
-        // the credential on DEVICE ROLE, not run mode, is RUSH-2395's fix: gating on
-        // `ctx.interactive` alone sent a headless run on the laptop onto the
-        // setup-token and hijacked the login.
-        //
-        // A WORKER device carries no such login regardless of interactive/headless:
-        // an interactive run there is a remotely dispatched TUI (`agents run claude
-        // --interactive --device <worker>`), not a human sitting at that box's own
-        // Keychain-trusted session — the same worker credential headless runs use is
-        // the only credential that exists to authenticate it. Treating `interactive`
-        // as "defer to native login" regardless of device role left a keychain-less
-        // worker with NO injected token and a per-version `.credentials.json` that
-        // was never written, so the run landed on Claude Code's login screen instead
-        // of authenticating (PHNX-3502).
-        //
-        // 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 the headed-device path
-        // defers to Claude Code, which reads its own ACL-trusted login item without a
-        // prompt and asks a present human to log in only if the login is missing.
         const headedDevice = isHeadedDeviceRole(ctx.deviceRole);
         if (headedDevice) {
-            // Drop an INHERITED copy of OUR OWN setup-token: a launch from inside a
-            // headless agent's shell inherits that agent's injected value via
-            // sanitizeProcessEnv(process.env) and would keep authenticating as it,
-            // overriding the login this branch is protecting. Matched by VALUE, so a
-            // token the user exported deliberately is a different string and is left
-            // alone (#2383). This is NARROWER than the worker 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 {
-            // Any run on a NON-personal device (worker, dispatched, provisioned box) —
-            // interactive OR headless: mirror the routines path (`runner.ts`)
-            // 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;
             }
@@ -111,11 +48,6 @@ if [ "\$(uname -s)" = "Linux" ] && [ -z "\${CLAUDE_CODE_OAUTH_TOKEN:-}" ] && [ -
 fi
 `;
     },
-    // NOTE: the worker branch above strips the token and returns; a MISSING worker
-    // credential is caught before spawn by claudeWorkerLoginTrapPreflight (below),
-    // which fails loud for an interactive run instead of letting Claude Code fall
-    // through to its "Select login method" screen. A headless run keeps the
-    // strip-and-401 behavior.
     routineModeArgs(cmd, ctx) {
         const mode = ctx.mode;
         if (mode === 'edit') {
@@ -129,7 +61,6 @@ fi
                 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');
@@ -159,27 +90,10 @@ fi
 export function claudeWorkerLoginTrapPreflight(args) {
     if (args.agent !== 'claude')
         return null;
-    // A headless run with no token fails loud with a 401 already; only an
-    // interactive run falls through to Claude Code's login screen.
     if (!args.interactive)
         return null;
-    // Gate ONLY an EXPLICIT `role: worker` box — not a headed box, and NOT an
-    // UNMARKED one. The owner rule guarantees a real worker holds no native login
-    // (it authenticates from the synced setup-token), so no token there genuinely
-    // means the login screen with nothing behind it. A headed box authenticates
-    // from its own native login (its login prompt is the correct first-run flow).
-    // An UNMARKED box is deliberately spared: it never receives a synced setup-token
-    // (auth-sync pushes only to `role=worker` peers), so it is typically an ordinary
-    // machine authenticating from a native login the operator just never marked —
-    // gating it would false-refuse every such laptop, a far larger surface than the
-    // marked-worker case this closes. `--device auto` lands on an explicit worker
-    // once any worker is marked in the fleet (filterAutoPool), which is the primary
-    // trap; a directly-named `--device <unmarked-box>` is left as it was on main
-    // (unprotected — a bootstrap-window residual, not a regression).
     if (args.deviceRole !== 'worker')
         return null;
-    // A credential will reach the child (worker setup-token, or an explicit
-    // --env CLAUDE_CODE_OAUTH_TOKEN override) — proceed.
     if (args.hasWorkerCredential)
         return null;
     const where = args.machine ? `worker '${args.machine}'` : 'this worker';
@@ -194,9 +108,6 @@ export function claudeWorkerLoginTrapPreflight(args) {
         `  • If that account has no token yet, mint it on a HEADED box (e.g. your laptop):`,
         `        agents accounts login claude#<name>`,
         ``,
-        // NB: keep this text clear of RATE_LIMIT_PATTERNS (exec.ts) — this string is
-        // returned as spawn stderr, which runWithFallback scans; a stray "rate limit"
-        // / "quota" phrase here would spuriously trigger an account-rotation fallback.
         `See which accounts are LIVE (signed in, with headroom) with:  agents accounts list`,
     ].join('\n');
 }

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

@@ -4,12 +4,6 @@ import { getHistoryDir } from '../../state.js';
 import { codexHomeShimBash, codexShortKey, resolveCodexHome } 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, `'\\''`)}'`;
 }
@@ -17,11 +11,6 @@ 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.
-            // ctx.versionHome is the account slot on a `codex#<account>` launch, so
-            // the short home is keyed by that origin, never by the version alone.
             const originHome = path.join(ctx.versionHome, '.codex');
             const historyDir = getHistoryDir();
             const agentsUserDir = path.dirname(historyDir);
@@ -40,13 +29,6 @@ export const codexAdapter = {
         ].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" ;;

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

@@ -2,9 +2,6 @@ import * as path from 'path';
 import { stripForeignConfigDir, slotAwareConfigEnvBash } 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');

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

@@ -1,11 +1,6 @@
 import { stripForeignConfigDir } from '../adapter.js';
 export const cursorAdapter = {
     id: 'cursor',
-    // Cursor defaults to one machine-global OS-keychain login on macOS, which
-    // ignores XDG_CONFIG_HOME. Select the file credential store; Cursor writes
-    // that store to HOME-relative ~/.cursor/auth.json, and buildExecEnv already
-    // swaps HOME to the selected version home. Existing keychain credentials
-    // remain untouched.
     applyExecConfigEnv(result, ctx) {
         if (ctx.versionHome) {
             result.AGENTS_REAL_HOME ||= result.HOME;
@@ -15,17 +10,8 @@ export const cursorAdapter = {
         stripForeignConfigDir(result);
     },
     execPreModeArgs(ctx) {
-        // A configured headless run is the workspace trust decision, in plan mode
-        // too: an untrusted cwd otherwise stops on Cursor's trust prompt with no one
-        // to answer it. Keep this narrower than --yolo/-f, which skip already passes
-        // and which also bypasses permission checks.
         return ctx.resolvedMode !== 'skip' && !ctx.interactive ? ['--trust'] : undefined;
     },
-    // Headless read-only runs use ask mode, not --plan. In plan mode Cursor
-    // delivers its answer through the createPlan tool, which `-p` text output
-    // never prints, so the run exits 0 with an empty stdout. Ask mode is equally
-    // read-only (it refuses file writes) and prints its answer. Interactive plan
-    // keeps --plan, where the TUI renders the plan.
     execModeArgs(ctx) {
         return ctx.resolvedMode === 'plan' && !ctx.interactive ? ['--mode', 'ask'] : undefined;
     },
@@ -37,8 +23,6 @@ export const cursorAdapter = {
             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.js

@@ -1,8 +1,5 @@
-// 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');

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

@@ -2,8 +2,6 @@ import * as path from 'path';
 import { stripForeignConfigDir, slotAwareConfigEnvBash } 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');
@@ -20,32 +18,15 @@ ${slotAwareConfigEnvBash([{ env: 'KIMI_CODE_HOME', rel: 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.js

@@ -2,12 +2,6 @@ import * as path from 'path';
 import { stripForeignConfigDir, slotAwareConfigEnvBash } 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');
@@ -28,8 +22,6 @@ export const museAdapter = {
 ${slotAwareConfigEnvBash([{ env: 'XDG_CONFIG_HOME', rel: '.config' }, { env: 'XDG_DATA_HOME', rel: '.local/share' }], '$VERSION_DIR/home')}
 `;
     },
-    // 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');
@@ -40,6 +32,5 @@ ${slotAwareConfigEnvBash([{ env: 'XDG_CONFIG_HOME', rel: '.config' }, { env: 'XD
         else if (ctx.mode === 'skip') {
             cmd.push('--yolo');
         }
-        // edit: default on-request approval + sandbox
     },
 };

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

@@ -1,7 +1,5 @@
 import * as path from 'path';
 import { stripForeignConfigDir, slotAwareConfigEnvBash } from '../adapter.js';
-// OpenCode reads plugins/agents/commands from OPENCODE_CONFIG_DIR and auth from
-// $XDG_DATA_HOME/opencode (HARNESS_AUTH.slotEnv). Pin both at the slot / version
 // home so two accounts in one install never share a credential (PHNX-3940 T5).
 export const opencodeAdapter = {
     id: 'opencode',

package/dist/lib/harness/exec-config-version.d.ts

@@ -1,8 +1,6 @@
 import type { AgentId } from '../types.js';
 interface ResolvedConfigVersion {
-    /** The version to pin, or null when unresolved / not installed. */
     version: string | null;
-    /** The version home for that version, or null. */
     versionHome: string | null;
 }
 export declare function resolveConfigVersion(agent: AgentId, cwd: string, optionsVersion?: string): ResolvedConfigVersion;

package/dist/lib/harness/exec-config-version.js

@@ -1,16 +1,3 @@
-/**
- * Shared version resolution for the exec-time config-dir env pin. Every
- * config-dir harness branch in the old buildExecEnv computed this identically:
- * an explicit `--version` is used unconditionally; an auto-resolved version is
- * only pinned when it is actually installed on disk.
- *
- * The caller (buildExecEnv) invokes this and passes the result into the adapter
- * via ExecConfigEnvCtx — the adapters MUST NOT import installations/versions
- * themselves, because that module imports shims.ts and shims.ts imports the
- * harness barrel, which would close an import cycle (versions → shims → harness →
- * adapter → versions). That cycle forced esbuild/tsx to emit CJS for part of the
- * graph and broke sqlite.ts's top-level await in subprocess-spawning tests.
- */
 import { getVersionHomePath, isVersionInstalled, resolveVersion } from '../installations/versions.js';
 export function resolveConfigVersion(agent, cwd, optionsVersion) {
     const resolvedVersion = optionsVersion ?? resolveVersion(agent, cwd);

package/dist/lib/harness/index.js

@@ -1,13 +1,3 @@
-/**
- * Harness adapter barrel — importing this registers every built-in adapter, the
- * same pattern as lib/channels/providers/index.ts. Consumers import
- * `resolveHarnessAdapter` from here (not from ./adapter.js directly) so the
- * registration side-effect has run before the first resolve.
- *
- * A harness with no config-env / launch quirks needs no adapter file: every
- * `AgentId` still resolves (to the id-only default), so call sites never
- * name-check a harness.
- */
 import { registerHarnessAdapter } from './adapter.js';
 import { claudeAdapter } from './adapters/claude.js';
 import { codexAdapter } from './adapters/codex.js';