@phnx-labs/agents-cli 1.22.41 → 1.22.42

package/dist/lib/devices/doctor-findings.js

@@ -41,13 +41,13 @@ import chalk from 'chalk';
 import { AGENTS, ALL_AGENT_IDS, supportsAccountInspection } from '../agents.js';
 import { blocksLocalScripts } from '../platform/winpath.js';
 import { loginHint } from '../signin-badge.js';
-import { CONFIG_ENV_ISOLATED_AGENTS } from '../shims.js';
+import { CONFIG_ENV_ISOLATED_AGENTS } from '../installations/shims.js';
 import { padToWidth, stringWidth } from '../session/width.js';
 import { windowsSshEnrollmentProblem } from './windows-ssh-enrollment.js';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 /** Agents with NO per-version credential isolation: their login is shared across
  *  every installed version, so a "log into THIS version" remediation would be a
- *  lie. Derived from `CONFIG_ENV_ISOLATED_AGENTS` in `lib/shims.ts` — the shim
+ *  lie. Derived from `CONFIG_ENV_ISOLATED_AGENTS` in `lib/installations/shims.ts` — the shim
  *  generator is what actually exports the per-version isolation env var, so it is
  *  the source of truth. Do not hand-maintain a second copy: an agent gaining
  *  isolation there must not leave a stale "login is shared" hint here. */
@@ -193,7 +193,7 @@ export function remediationFor(finding) {
             }
             // Isolated per-version home: the login must RUN INSIDE that home. A bare
             // `<cli> login` afterwards would NOT — the native shim resolves to the
-            // project/default version (`lib/shims.ts:471-474`), so it would log into
+            // project/default version (`lib/installations/shims.ts:471-474`), so it would log into
             // whichever version is default, not the one that is logged out.
             switch (loginShape(agent)) {
                 case 'subcommand':

package/dist/lib/devices/fleet-inventory.js

@@ -10,7 +10,7 @@
  */
 import { getAvailableResources, getVersionHomePath, isVersionIsolated, listInstalledVersions } from '../installations/versions.js';
 import { supports } from '../capabilities.js';
-import { checkVersionHookWiring } from '../hooks.js';
+import { checkVersionHookWiring } from '../hooks/install.js';
 import { getUserAgentsDir, getSystemAgentsDir, readMeta } from '../state.js';
 import { listNativeAccounts } from '../account-registry.js';
 import { readRepoState } from '../git.js';

package/dist/lib/devices/harness-inventory.js

@@ -16,7 +16,7 @@
 import chalk from 'chalk';
 import { ALL_AGENT_IDS, accountDisplayLabel, getAccountInfo, } from '../agents.js';
 import { deriveUsageStatusFromSnapshot, getUsageInfoByIdentity, getUsageLookupKey, } from '../accounting/usage.js';
-import { getVersionHomePath, listInstalledVersions } from '../installations/versions.js';
+import { getVersionHomePath, listInstalledVersions } from '../installations/store.js';
 import { readMeta } from '../state.js';
 import { listNativeAccounts } from '../account-registry.js';
 /**

package/dist/lib/devices/registry.js

@@ -16,9 +16,9 @@
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
-import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
 import { getDevicesRegistryPath, getDevicesIgnoredPath } from '../state.js';
+import { atomicWriteJsonSync } from '../fs-atomic.js';
 /** A device's effective role, defaulting to `worker` when unset. */
 export function deviceRole(d) {
     return d.role ?? 'worker';
@@ -94,24 +94,6 @@ export function platformFromOs(os) {
 export function shellForPlatform(platform) {
     return platform === 'windows' ? 'powershell' : 'posix';
 }
-/**
- * Atomic JSON write: write to a unique sibling tmp file then rename over the
- * target. rename(2) is atomic on POSIX, so a crashed write leaves the old file
- * untouched instead of producing a half-written registry that loadDevices()
- * would reject.
- */
-async function atomicWriteJson(p, data) {
-    await fs.mkdir(path.dirname(p), { recursive: true });
-    const tmp = `${p}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`;
-    await fs.writeFile(tmp, JSON.stringify(data, null, 2));
-    try {
-        await fs.rename(tmp, p);
-    }
-    catch (err) {
-        await fs.unlink(tmp).catch(() => { });
-        throw err;
-    }
-}
 /**
  * Run `fn` while holding an exclusive cross-process lock on the registry file.
  * proper-lockfile requires the target to exist, so we touch it first. Stale
@@ -187,7 +169,7 @@ export function loadDevicesSync() {
     }
 }
 async function saveDevices(reg) {
-    await atomicWriteJson(registryPath(), reg);
+    atomicWriteJsonSync(registryPath(), reg);
 }
 /** Get a single device profile, or null if it is not registered. */
 export async function getDevice(name) {
@@ -309,7 +291,7 @@ export async function addIgnored(name) {
     return withRegistryLock(p, async () => {
         const set = await loadIgnored();
         set.add(name);
-        await atomicWriteJson(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
+        atomicWriteJsonSync(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
         return set;
     });
 }
@@ -321,7 +303,7 @@ export async function removeIgnored(name) {
         const set = await loadIgnored();
         if (!set.delete(name))
             return false;
-        await atomicWriteJson(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
+        atomicWriteJsonSync(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
         return true;
     });
 }

package/dist/lib/doctor-diff.d.ts

@@ -21,7 +21,7 @@
  */
 import type { AgentId } from './types.js';
 import type { DiscoveredPlugin } from './types.js';
-import { type HookWiringReport } from './hooks.js';
+import { type HookWiringReport } from './hooks/install.js';
 import { type ResourceInventory } from './resource-inventory.js';
 export type DoctorKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'promptcuts';
 export type DiffStatus = 'ok' | 'diff' | 'missing' | 'extra';

package/dist/lib/doctor-diff.js

@@ -33,7 +33,7 @@ import { shouldInstallCommandAsSkill, commandSkillMatches, commandSkillName } fr
 import { gooseCommandMatches, gooseCommandsDir } from './goose-commands.js';
 import { supports } from './capabilities.js';
 import { listSkillsInVersionHome, getVersionSkillsDir } from './plugins/skills.js';
-import { listHookEntriesFromDir } from './hooks.js';
+import { listHookEntriesFromDir } from './hooks/install.js';
 import { getResourceInventory } from './resource-inventory.js';
 const RULES_DOC_FILENAME = 'README.md';
 const ALL_KINDS = [

package/dist/lib/drift.js

@@ -4,7 +4,7 @@ import { loadManifest, isStale } from './staleness/index.js';
 import { diffVersionResources } from './doctor-diff.js';
 import { diffVersionCommands, iterCommandsCapableVersions } from './commands.js';
 import { diffVersionSkills, iterSkillsCapableVersions } from './plugins/skills.js';
-import { iterHooksCapableVersions, listUnmanagedHooksInVersionHome, checkVersionHookWiring } from './hooks.js';
+import { iterHooksCapableVersions, listUnmanagedHooksInVersionHome, checkVersionHookWiring } from './hooks/install.js';
 import { commitsBehindUpstream } from './git.js';
 import { getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos } from './state.js';
 // Lines naming exactly what's out of sync for a version, plugins prioritized:

package/dist/lib/entitlement.d.ts

@@ -0,0 +1,31 @@
+/** How long a cached tier is trusted before the next call re-fetches. */
+export declare const ENTITLEMENT_CACHE_TTL_MS: number;
+export type EntitlementSource = 'live' | 'cache' | 'offline' | 'no-session';
+export interface EntitlementTier {
+    /** The raw tier name from the backend ('free', 'admin', or a paid tier name). */
+    tierName: string;
+    /** true for 'admin' or any tier name other than 'free'. */
+    isPaid: boolean;
+    /** Where this value came from — mainly for diagnostics/tests. */
+    source: EntitlementSource;
+}
+export declare function setEntitlementUserYamlPathForTest(value: string | null): void;
+export declare function setEntitlementCachePathForTest(value: string | null): void;
+export declare function setEntitlementFetchForTest(fn: typeof globalThis.fetch): void;
+export declare function entitlementCachePath(): string;
+/**
+ * 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 declare function getTier(): Promise<EntitlementTier>;
+/** Per-harness account cap for a tier: 3 on free, 10 on paid/admin. */
+export declare function accountCapForTier(tier: Pick<EntitlementTier, 'isPaid'>): number;

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