@phnx-labs/agents-cli 1.22.40 → 1.22.42

package/dist/lib/entitlement.js

@@ -0,0 +1,137 @@
+/**
+ * Plan-tier entitlement — the one place agents-cli reads a user's live billing
+ * tier for plan gates (the `agents accounts` per-harness cap, the `agents
+ * insights` paid split). Fetches `GET /api/v1/billing/subscription?agent=agi-cli`
+ * using the Rush session token from `~/.rush/user.yaml` (same read pattern as
+ * `lib/cloud/rush.ts` / `lib/secrets/drivers/rush.ts` — this module does not
+ * import either, since neither exports its token reader), caches the result on
+ * disk with a TTL, and stays offline-tolerant: a stale cache is honored over a
+ * failed network call rather than silently dropping a paid account to free, and
+ * no session file at all resolves straight to the free tier with no request.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+import { getCacheDir } from './state.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
+const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
+const SUBSCRIPTION_PATH = '/api/v1/billing/subscription?agent=agi-cli';
+/** How long a cached tier is trusted before the next call re-fetches. */
+export const ENTITLEMENT_CACHE_TTL_MS = 15 * 60_000;
+/** Same shape as bootstrap.ts's fetchNpmPackageMetadata — a hung connection
+ * (dead peer, a firewall dropping packets silently) must not block every
+ * `accounts add`/`insights` call indefinitely once the cache goes stale. */
+const FETCH_TIMEOUT_MS = 5000;
+const FREE_TIER = { tierName: 'free', isPaid: false };
+// ─── Injectable seams (tests only — the lib's own real read/write paths) ────
+let userYamlPathOverride = null;
+let cachePathOverride = null;
+let fetchImpl = globalThis.fetch;
+export function setEntitlementUserYamlPathForTest(value) {
+    userYamlPathOverride = value;
+}
+export function setEntitlementCachePathForTest(value) {
+    cachePathOverride = value;
+}
+export function setEntitlementFetchForTest(fn) {
+    fetchImpl = fn;
+}
+function userYamlPath() {
+    return userYamlPathOverride ?? path.join(os.homedir(), '.rush', 'user.yaml');
+}
+export function entitlementCachePath() {
+    return cachePathOverride ?? path.join(getCacheDir(), '.entitlement-cache.json');
+}
+function readRushToken() {
+    const file = userYamlPath();
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const data = yaml.parse(fs.readFileSync(file, 'utf-8'));
+        return data?.session?.access_token || null;
+    }
+    catch {
+        return null;
+    }
+}
+function readCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(entitlementCachePath(), 'utf-8'));
+        if (parsed?.version === 1 && typeof parsed.tierName === 'string' && typeof parsed.fetchedAt === 'number')
+            return parsed;
+    }
+    catch {
+        // missing or corrupt — treat as no cache
+    }
+    return null;
+}
+/** Best-effort write; a failed cache write just means the next call re-fetches. */
+function writeCache(tierName, isPaid) {
+    try {
+        const target = entitlementCachePath();
+        ensureLockTarget(target);
+        withFileLock(target, () => {
+            const entry = { version: 1, tierName, isPaid, fetchedAt: Date.now() };
+            atomicWriteFileSync(target, JSON.stringify(entry, null, 2));
+        });
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Only `tierName: "free"` (or an absent tier name) reads as free — every other
+ * name (`admin`, or a real paid-tier name once agi-cli has a pricing manifest,
+ * see the integration spec §4.4 G3) is treated as paid. Backend tier config for
+ * agi-cli doesn't exist yet, so this deliberately does not lean on
+ * `hasSubscription`/`needsUpgrade` nuance the backend isn't populating meaningfully
+ * for this agent today.
+ */
+function classifySubscription(sub) {
+    const tierName = typeof sub.tierName === 'string' && sub.tierName ? sub.tierName : 'free';
+    return { tierName, isPaid: tierName !== 'free' };
+}
+/**
+ * The live plan tier, cache-first with a TTL.
+ *
+ * - No `~/.rush/user.yaml` at all → free, no network call.
+ * - A fresh cache entry (within {@link ENTITLEMENT_CACHE_TTL_MS}) is returned
+ *   with no network call.
+ * - A stale or missing cache triggers a live fetch; on success the result is
+ *   cached and returned.
+ * - A failed fetch (offline, timeout, non-2xx) falls back to a stale cache if
+ *   one exists — never silently drops a known-paid account to free just
+ *   because the network hiccuped — and only falls back to free when there is
+ *   no cache at all to fall back to.
+ */
+export async function getTier() {
+    const token = readRushToken();
+    if (!token)
+        return { ...FREE_TIER, source: 'no-session' };
+    const cached = readCache();
+    if (cached && Date.now() - cached.fetchedAt < ENTITLEMENT_CACHE_TTL_MS) {
+        return { tierName: cached.tierName, isPaid: cached.isPaid, source: 'cache' };
+    }
+    try {
+        const res = await fetchImpl(`${PROXY_BASE}${SUBSCRIPTION_PATH}`, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            throw new Error(`billing/subscription responded ${res.status}`);
+        const sub = (await res.json());
+        const { tierName, isPaid } = classifySubscription(sub);
+        writeCache(tierName, isPaid);
+        return { tierName, isPaid, source: 'live' };
+    }
+    catch {
+        if (cached)
+            return { tierName: cached.tierName, isPaid: cached.isPaid, source: 'offline' };
+        return { ...FREE_TIER, source: 'offline' };
+    }
+}
+/** Per-harness account cap for a tier: 3 on free, 10 on paid/admin. */
+export function accountCapForTier(tier) {
+    return tier.isPaid ? 10 : 3;
+}

package/dist/lib/exec.js

@@ -19,8 +19,7 @@ import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { resolveActor, actorEnv } from './actor.js';
 import { expandLocalHome } from './project-root.js';
 import { getShimsDir, getHistoryDir, getRuntimeStateDir } from './state.js';
-import { resolveCodexHome } from './codex-home.js';
-import { readCodexConfiguredModel } from './shims.js';
+import { readCodexConfiguredModel } from './installations/shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
 import { writeSessionActorRecord, writeSessionAliasRecord } from './session/actor-sidecar.js';
 import { loadHookSessionIndex, resolveHookSessionId } from './session/hook-sessions.js';
@@ -32,10 +31,12 @@ import { isTmuxInstalled } from './tmux/binary.js';
 import { isTmuxEnabled } from './device-config.js';
 import { machineId } from './machine-id.js';
 import { shellQuote } from './ssh-exec.js';
-import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { codexEditWritableRoots, codexPolicyArgs } from './codex-policy.js';
+import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { applyAddDirs } from './add-dir.js';
 import { applyActiveRulesPresetAtRun } from './rules/run-sync.js';
+import { resolveHarnessAdapter, stripForeignConfigDir } from './harness/index.js';
+import { resolveConfigVersion } from './harness/exec-config-version.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -282,180 +283,25 @@ export function buildExecEnv(options) {
     // Config-dir env vars are agent-specific. When the caller is running inside
     // an agent-managed shell, process.env already carries one; spreading into a
     // different agent's env would leak a config pointer the target CLI doesn't
-    // understand. Strip foreign vars and pin the right one to the versioned home.
-    if (options.agent === 'claude') {
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('claude', cwd);
-        // Use an explicitly pinned version unconditionally; for auto-resolved versions
-        // only inject the path when the version is actually installed on disk.
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('claude', resolvedVersion) ? resolvedVersion : null);
-        // 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.
-        const versionHome = version ? getVersionHomePath('claude', version) : null;
-        const setupToken = versionHome ? 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 (resolveInteractive(options)) {
-            // 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;
-            }
-        }
-        delete result.CODEX_HOME;
-        delete result.COPILOT_HOME;
-        delete result.KIMI_CODE_HOME;
-    }
-    else if (options.agent === 'codex') {
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('codex', cwd);
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('codex', resolvedVersion) ? resolvedVersion : null);
-        if (version) {
-            // 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(getVersionHomePath('codex', version), '.codex');
-            const agentsUserDir = path.dirname(getHistoryDir());
-            result.CODEX_HOME = resolveCodexHome(versionedHome, agentsUserDir, version);
-        }
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.COPILOT_HOME;
-        delete result.KIMI_CODE_HOME;
-    }
-    else if (options.agent === '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.
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('copilot', cwd);
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('copilot', resolvedVersion) ? resolvedVersion : null);
-        if (version) {
-            result.COPILOT_HOME = path.join(getVersionHomePath('copilot', version), '.copilot');
-        }
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.CODEX_HOME;
-        delete result.KIMI_CODE_HOME;
-    }
-    else if (options.agent === 'kimi') {
-        // Kimi honors KIMI_CODE_HOME (relocates ~/.kimi-code, including config,
-        // skills, hooks, sessions). Pin it at the per-version home.
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('kimi', cwd);
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('kimi', resolvedVersion) ? resolvedVersion : null);
-        if (version) {
-            result.KIMI_CODE_HOME = path.join(getVersionHomePath('kimi', version), '.kimi-code');
-        }
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.CODEX_HOME;
-        delete result.COPILOT_HOME;
-    }
-    else if (options.agent === '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).
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('muse', cwd);
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('muse', resolvedVersion) ? resolvedVersion : null);
-        if (version) {
-            const versionHome = getVersionHomePath('muse', version);
-            result.XDG_CONFIG_HOME = path.join(versionHome, '.config');
-            result.XDG_DATA_HOME = path.join(versionHome, '.local', 'share');
-        }
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.CODEX_HOME;
-        delete result.COPILOT_HOME;
-        delete result.KIMI_CODE_HOME;
-    }
-    else if (options.agent === '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.
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('cursor', cwd);
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('cursor', resolvedVersion) ? resolvedVersion : null);
-        if (version) {
-            result.XDG_CONFIG_HOME = path.join(getVersionHomePath('cursor', version), '.config');
-        }
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.CODEX_HOME;
-        delete result.COPILOT_HOME;
-        delete result.KIMI_CODE_HOME;
+    // understand. Each harness adapter pins its own config-dir var to the versioned
+    // home and strips the foreign ones; a harness with no config-dir env (the old
+    // `else`) has no adapter override, so all four are stripped here.
+    const configAdapter = resolveHarnessAdapter(options.agent);
+    if (configAdapter.applyExecConfigEnv) {
+        // Resolve version/versionHome here (this module already imports
+        // installations/versions); the adapters must not import it themselves or they
+        // close a versions -> shims -> harness -> adapter import cycle.
+        const { version, versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.version);
+        configAdapter.applyExecConfigEnv(result, {
+            agent: options.agent,
+            version,
+            versionHome,
+            interactive: resolveInteractive(options),
+            resolveClaudeSetupToken,
+        });
     }
     else {
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.CODEX_HOME;
-        delete result.COPILOT_HOME;
-        delete result.KIMI_CODE_HOME;
+        stripForeignConfigDir(result);
     }
     // Point the agent at its own mailbox so the PreToolUse `mailbox-inject` hook
     // knows which box to drain and inject mid-run. Keyed by the session id — the
@@ -952,18 +798,24 @@ export function buildExecCommand(options) {
         // AGENT_COMMANDS.modeFlags drifted apart. Tests assert they agree.
         throw new Error(`Internal error: ${options.agent} declares '${resolvedMode}' in capabilities.modes but has no entry in AGENT_COMMANDS.modeFlags.${resolvedMode}.`);
     }
-    if (options.agent === 'cursor' && resolvedMode === 'edit' && !interactive) {
-        // A configured headless run is the workspace trust decision. Keep this
-        // narrower than --yolo/-f, which also bypasses permission checks.
-        cmd.push('--trust');
+    // Launch-arg quirks (the harness axis of Move 3): cursor's additive `--trust`
+    // and the codex/kimi mode-flag overrides move to the harness adapter, so the
+    // per-agent name-chain collapses to one dispatch. The generic resume-subcommand
+    // and modeFlags paths stay here — they are not per-harness.
+    const launchAdapter = resolveHarnessAdapter(options.agent);
+    const launchArgsCtx = {
+        resolvedMode,
+        interactive,
+        cwd: options.cwd ?? process.cwd(),
+        addDirs: (options.addDirs ?? []).map(expandLocalHome),
+    };
+    const preModeArgs = launchAdapter.execPreModeArgs?.(launchArgsCtx);
+    if (preModeArgs) {
+        cmd.push(...preModeArgs);
     }
-    if (options.agent === 'codex') {
-        const policyMode = resolvedMode === 'plan' || resolvedMode === 'skip' ? resolvedMode : 'edit';
-        const writableRoots = [
-            ...codexEditWritableRoots(options.cwd ?? process.cwd()),
-            ...(options.addDirs ?? []).map(expandLocalHome),
-        ];
-        cmd.push(...codexPolicyArgs(policyMode, writableRoots));
+    const modeArgsOverride = launchAdapter.execModeArgs?.(launchArgsCtx);
+    if (modeArgsOverride !== undefined) {
+        cmd.push(...modeArgsOverride);
     }
     else if (resumeSpec && 'subcommand' in resumeSpec) {
         if (resolvedMode === 'skip') {
@@ -982,21 +834,6 @@ export function buildExecCommand(options) {
             cmd.push(...modeFlags);
         }
     }
-    else if (options.agent === 'kimi' && !interactive) {
-        // 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. 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 (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.
-    }
     else {
         cmd.push(...modeFlags);
     }
@@ -1228,7 +1065,7 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     // not parse `rawArgs`, so a `-p "task"` passthrough is headless in fact and
     // interactive by this classification, and loses the token. Windows-only in
     // practice (POSIX uses the bash shim, which execs the binary and never reaches
-    // buildExecEnv — `shims.ts:749`, `shims.ts:761-764`).
+    // buildExecEnv — `installations/shims.ts` generateShimScript).
     const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto', env: { AGENT_LAUNCH_ID: launchId } });
     const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     return new Promise((resolve) => {

package/dist/lib/feed/feed.js

@@ -28,6 +28,7 @@ import { stringifyDoc } from '../yaml-io.js';
 import { getFeedDir, getUserAgentsDir } from '../state.js';
 import { isAdmin, isHighConsequenceAllowed, isKnownOperator } from '../operator.js';
 import { projectKeyFromCwd } from '../project-key.js';
+import { atomicWriteJsonSync } from '../fs-atomic.js';
 /**
  * Stable block id for a session. One block per session -- a new question
  * replaces the previous one (the agent can only ask one question at a time).
@@ -56,11 +57,6 @@ function safeReadJson(file) {
         return undefined;
     }
 }
-function atomicWriteJson(file, value) {
-    const tmp = `${file}.${process.pid}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(value, null, 2), 'utf-8');
-    fs.renameSync(tmp, file);
-}
 /** Read one block record. Returns undefined when missing or corrupt. */
 export function readBlock(blockId, root) {
     const parsed = safeReadJson(blockPath(root ?? getFeedDir(), blockId));
@@ -285,9 +281,7 @@ export function publishBlock(block, root) {
     const dir = root ?? getFeedDir();
     fs.mkdirSync(dir, { recursive: true });
     const target = blockPath(dir, block.blockId);
-    const tmp = `${target}.${process.pid}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(block, null, 2), 'utf-8');
-    fs.renameSync(tmp, target);
+    atomicWriteJsonSync(target, block);
 }
 /** Read all block records. Returns them sorted by stable block filename. */
 export function listBlocks(root) {

package/dist/lib/fs-atomic.d.ts

@@ -11,6 +11,13 @@ export declare function ensureLockTarget(filePath: string, initialContent?: stri
  * partial write. On POSIX, rename(2) is atomic.
  */
 export declare function atomicWriteFileSync(filePath: string, content: string, options?: fs.WriteFileOptions): void;
+/**
+ * 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 declare function atomicWriteJsonSync(filePath: string, data: unknown): void;
 /**
  * Acquires an exclusive proper-lockfile lock on filePath, runs fn, then
  * releases the lock. Retries with capped linear back-off until either the lock

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[];