@phnx-labs/agents-cli 1.22.31 → 1.22.33

package/dist/lib/installations/strategies.js

@@ -0,0 +1,293 @@
+import * as crypto from 'crypto';
+import { promisify } from 'util';
+import { exec, execFile } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, findInPath, isSelfUpdatingAgent } from '../agents.js';
+import { VERSION_RE } from '../agent-spec/primitives.js';
+import { importInstallScriptBinary } from '../import.js';
+import { getBinaryPath, getLatestNpmVersion, getOldestNpmVersion, getLiveVersion, getVersionHomePath, invalidateLiveVersionCache, isGlobalBinaryAgent, } from '../versions.js';
+import { installationDir } from './store.js';
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+/** npm install timeout, matching the install path's own installer budget. */
+const INSTALL_TIMEOUT_MS = 120_000;
+function runId() {
+    return `${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+}
+function moveDir(from, to) {
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    try {
+        fs.renameSync(from, to);
+    }
+    catch (err) {
+        // Windows refuses a rename while any file in the tree is open, and a
+        // cross-device staging dir cannot be renamed at all. Copy+remove is the same
+        // observable move; it is slower, so it is the fallback, not the default.
+        const code = err.code;
+        if (code !== 'EPERM' && code !== 'EACCES' && code !== 'EXDEV')
+            throw err;
+        fs.cpSync(from, to, { recursive: true });
+        fs.rmSync(from, { recursive: true, force: true });
+    }
+}
+/**
+ * Entries a swap replaces: everything npm owns inside a version dir. The lockfile
+ * is included deliberately — leaving the previous release's `package-lock.json`
+ * beside the new `node_modules` would make the directory describe a release it no
+ * longer contains, and the next repair reinstall would resolve from that stale lock.
+ * Entries absent on either side are skipped, so a dir without a lockfile is fine.
+ */
+const NPM_LIVE_ENTRIES = ['node_modules', 'package.json', 'package-lock.json'];
+/**
+ * npm-packaged harnesses (claude, codex, kimi, opencode, …). The only fully
+ * transactional class: a pinned release can be fetched into a sibling directory,
+ * probed there, and swapped in, with the displaced tree kept until the swap is
+ * proven — so a failed update leaves the previous release running.
+ */
+const npmPackageStrategy = {
+    id: 'npm-package',
+    transactional: true,
+    sharedBinary: false,
+    async resolveTarget(ctx) {
+        if (ctx.requested === 'latest' || ctx.requested === 'oldest') {
+            const resolved = ctx.requested === 'latest'
+                ? await getLatestNpmVersion(ctx.agent)
+                : await getOldestNpmVersion(ctx.agent);
+            if (!resolved) {
+                throw new Error(`Could not resolve the ${ctx.requested} published version for ${AGENTS[ctx.agent].name} from npm.`);
+            }
+            return resolved;
+        }
+        return ctx.requested;
+    },
+    async stage(ctx, target) {
+        const pkg = AGENTS[ctx.agent].npmPackage;
+        const dir = installationDir(ctx.agent, ctx.installation.label);
+        const stagingDir = path.join(dir, `.staging-${runId()}`);
+        fs.mkdirSync(stagingDir, { recursive: true });
+        fs.writeFileSync(path.join(stagingDir, 'package.json'), JSON.stringify({ name: `agents-${ctx.agent}-${target}`, version: '1.0.0', private: true }, null, 2));
+        const winShell = process.platform === 'win32';
+        ctx.onProgress?.(`Staging ${pkg}@${target}...`);
+        // `--ignore-scripts` for the dependency tree; the first-party package's own
+        // postinstall is re-run below, exactly as the install path does — several
+        // harnesses ship their native binary via that script and are unlaunchable
+        // without it.
+        await execFileAsync('npm', ['install', `${pkg}@${target}`, '--ignore-scripts'], {
+            cwd: stagingDir,
+            shell: winShell,
+            timeout: INSTALL_TIMEOUT_MS,
+        });
+        const pkgRoot = path.join(stagingDir, 'node_modules', pkg);
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf-8'));
+            const postinstall = manifest?.scripts?.postinstall;
+            if (typeof postinstall === 'string' && postinstall.trim()) {
+                ctx.onProgress?.(`Running ${AGENTS[ctx.agent].name} postinstall...`);
+                await execFileAsync(postinstall, [], { cwd: pkgRoot, shell: true, timeout: INSTALL_TIMEOUT_MS });
+            }
+        }
+        catch {
+            /* non-fatal: the launch probe in update.ts is the real gate */
+        }
+        return {
+            release: target,
+            binary: path.join(stagingDir, 'node_modules', '.bin', AGENTS[ctx.agent].cliCommand),
+            home: getVersionHomePath(ctx.agent, ctx.installation.label),
+            stagingDir,
+        };
+    },
+    async commit(ctx, staged) {
+        const dir = installationDir(ctx.agent, ctx.installation.label);
+        const rollbackDir = path.join(dir, `.rollback-${runId()}`);
+        const displaced = [];
+        // Move the live tree aside first, then move the staged tree in. Doing it in
+        // this order means the failure window contains no half-merged tree: either
+        // the old entries are all aside (undo restores them) or the new ones are all
+        // in place.
+        for (const entry of NPM_LIVE_ENTRIES) {
+            const live = path.join(dir, entry);
+            if (!fs.existsSync(live))
+                continue;
+            moveDir(live, path.join(rollbackDir, entry));
+            displaced.push(entry);
+        }
+        for (const entry of NPM_LIVE_ENTRIES) {
+            const from = path.join(staged.stagingDir, entry);
+            if (fs.existsSync(from))
+                moveDir(from, path.join(dir, entry));
+        }
+        return {
+            undo: () => {
+                for (const entry of NPM_LIVE_ENTRIES) {
+                    fs.rmSync(path.join(dir, entry), { recursive: true, force: true });
+                }
+                for (const entry of displaced) {
+                    moveDir(path.join(rollbackDir, entry), path.join(dir, entry));
+                }
+                fs.rmSync(rollbackDir, { recursive: true, force: true });
+            },
+            finalize: () => fs.rmSync(rollbackDir, { recursive: true, force: true }),
+        };
+    },
+};
+/**
+ * Harnesses that are ONE global self-updating binary (droid, muse, warp): every
+ * installation of the agent points at the same file, so there is nothing
+ * per-installation to stage or swap, and updating one necessarily updates all.
+ * The honest model is therefore: run the official installer, probe the live
+ * binary, and record the new release on every installation that shares it.
+ */
+const globalBinaryStrategy = {
+    id: 'global-binary',
+    transactional: false,
+    sharedBinary: true,
+    async resolveTarget(ctx) {
+        // The installer for these carries no version token, so a requested release
+        // cannot be honoured. Fail loud rather than install something else and
+        // report it as the pin the user asked for.
+        if (ctx.requested !== 'latest') {
+            throw new Error(`${AGENTS[ctx.agent].name} is a single self-updating binary with no pinnable releases — `
+                + `it can only be updated to the current one. Re-run: agents update ${ctx.agent}@${ctx.installation.label} --to latest`);
+        }
+        // Resolved after the installer runs — `latest` here is whatever it fetches.
+        return 'latest';
+    },
+    async stage(ctx) {
+        const script = AGENTS[ctx.agent].installScript;
+        ctx.onProgress?.(`Updating ${AGENTS[ctx.agent].name} via official installer...`);
+        await execAsync(script, { timeout: INSTALL_TIMEOUT_MS });
+        invalidateLiveVersionCache(ctx.agent);
+        const live = await getLiveVersion(ctx.agent);
+        if (!live) {
+            throw new Error(`${AGENTS[ctx.agent].name} installer finished but its version could not be determined.`);
+        }
+        return {
+            release: live,
+            binary: getBinaryPath(ctx.agent, ctx.installation.label),
+            home: getVersionHomePath(ctx.agent, ctx.installation.label),
+            stagingDir: null,
+        };
+    },
+    async commit() {
+        // The installer already replaced the shared binary; there is no per-install
+        // swap to perform and no previous copy to restore.
+        return { undo: () => { }, finalize: () => { } };
+    },
+};
+/**
+ * Harnesses installed by an official script that keeps a per-installation copy
+ * or symlink farm (grok, cursor, antigravity, hermes, kiro, goose, …). The
+ * vendor artifact lands in a global location the installer owns, so the fetch
+ * itself is not reversible; what IS per-installation — the version dir's binary
+ * link farm — is staged and swapped so a failed re-import cannot strand the
+ * installation without a launch target.
+ */
+const installScriptStrategy = {
+    id: 'install-script',
+    transactional: false,
+    sharedBinary: false,
+    async resolveTarget(ctx) {
+        const script = AGENTS[ctx.agent].installScript;
+        if (!script.includes('VERSION') && ctx.requested !== 'latest') {
+            throw new Error(`${AGENTS[ctx.agent].name}'s installer takes no version, so it can only be updated to the current release. `
+                + `Re-run: agents update ${ctx.agent}@${ctx.installation.label} --to latest`);
+        }
+        return ctx.requested;
+    },
+    async stage(ctx, target) {
+        const config = AGENTS[ctx.agent];
+        const script = config.installScript.replaceAll('VERSION', target === 'latest' ? 'latest' : target);
+        ctx.onProgress?.(`Updating ${config.name} via official installer...`);
+        await execAsync(script, { timeout: INSTALL_TIMEOUT_MS });
+        invalidateLiveVersionCache(ctx.agent);
+        // findInPath skips our own shims dir, so this is the genuine vendor binary
+        // and never our dispatcher (which would produce a self-execing link farm).
+        const installed = findInPath(config.cliCommand);
+        if (!installed) {
+            throw new Error(`${config.name} installer finished but ${config.cliCommand} is not on PATH — the install did not complete.`);
+        }
+        // On Windows there is no `.cmd` wrapper beside an imported install-script
+        // binary, so the staged launch probe cannot run and reports healthy. The
+        // gate is therefore weaker here than on POSIX; the unconditional undo in
+        // update.ts is what keeps a bad swap recoverable.
+        const release = target === 'latest'
+            ? (await getLiveVersion(ctx.agent)) ?? target
+            : target;
+        const dir = installationDir(ctx.agent, ctx.installation.label);
+        const stagingDir = path.join(dir, `.staging-${runId()}`);
+        fs.mkdirSync(stagingDir, { recursive: true });
+        const imported = importInstallScriptBinary({ agentId: ctx.agent, npmPackage: config.npmPackage, cliCommand: config.cliCommand }, ctx.installation.label, installed, stagingDir);
+        if (!imported.success) {
+            // Swallowing this reported the launch probe's generic "binary not found"
+            // instead of the real reason the import failed.
+            throw new Error(`${config.name} ${release} was installed but could not be linked into the version directory: ${imported.error ?? 'unknown error'}`);
+        }
+        return {
+            release,
+            binary: path.join(stagingDir, 'node_modules', '.bin', config.cliCommand),
+            home: getVersionHomePath(ctx.agent, ctx.installation.label),
+            stagingDir,
+        };
+    },
+    commit: npmPackageStrategy.commit,
+};
+/**
+ * Pick the update strategy for an agent from the registry's declared shape.
+ *
+ * The ordering mirrors `installVersion`: an npm package wins whenever one is
+ * declared (kimi declares both a package and a script, and its package is what
+ * `agents add` installs), then a single shared global binary, then a per-install
+ * script. Anything else is an integration boundary we do not handle — it throws
+ * rather than silently no-opping and reporting success.
+ */
+export function selectUpdateStrategy(agent) {
+    const config = AGENTS[agent];
+    if (config.npmPackage)
+        return npmPackageStrategy;
+    if (config.installScript && isGlobalBinaryAgent(agent))
+        return globalBinaryStrategy;
+    if (config.installScript) {
+        if (!usesVersionDirLinkFarm(agent)) {
+            // The install path resolves this harness's binary somewhere the version
+            // dir's link farm does not describe (grok keeps a real per-release copy
+            // under its version home). Staging and swapping the link farm would leave
+            // the launch target untouched, so the update would record a release that
+            // is not actually installed. Refuse instead of reporting a false success.
+            throw new Error(`${config.name} keeps its binary outside the managed version directory, so agents-cli cannot yet update an `
+                + `installation in place. Install the current release as a new installation: agents add ${agent}@latest`);
+        }
+        return installScriptStrategy;
+    }
+    throw new Error(`${config.name} is not installed by agents-cli (it declares no npm package and no installer), so there is nothing to update. `
+        + `Update it with its own tooling.`);
+}
+/**
+ * Does this harness's launch target live in the version dir's own
+ * `node_modules/.bin` link farm — the thing an installation can stage and swap?
+ *
+ * Probed through `getBinaryPath`, the single resolver the shims and `agents run`
+ * use, rather than tested against an agent id, so a harness that resolves its
+ * binary elsewhere is recognised without being enumerated here.
+ */
+function usesVersionDirLinkFarm(agent) {
+    const probe = '0.0.0-probe';
+    const expected = path.join(installationDir(agent, probe), 'node_modules', '.bin', AGENTS[agent].cliCommand);
+    return getBinaryPath(agent, probe) === expected;
+}
+/**
+ * Whether a concrete release can be requested for this agent at all. False for
+ * every self-updating harness — their installers carry no version token.
+ */
+export function supportsPinnedUpdate(agent) {
+    const config = AGENTS[agent];
+    if (config.npmPackage)
+        return true;
+    return !isSelfUpdatingAgent(agent);
+}
+/** Guard a user-supplied release token before it reaches a path or a package spec. */
+export function assertValidRelease(requested) {
+    if (!VERSION_RE.test(requested)) {
+        throw new Error(`Invalid release: ${JSON.stringify(requested)}`);
+    }
+}

package/dist/lib/installations/types.d.ts

@@ -0,0 +1,78 @@
+import type { AgentId } from '../types.js';
+/**
+ * Schema version of the on-disk installation record. Bump only for a change a
+ * previous CLI could not read; {@link INSTALLATION_SCHEMA} is asserted on read
+ * so a newer record fails loud instead of being silently misinterpreted.
+ */
+export declare const INSTALLATION_SCHEMA = 1;
+/** File name of the record, written at the root of a version dir. */
+export declare const INSTALLATION_RECORD_FILE = "installation.json";
+/**
+ * One entry in an installation's release history — appended on every successful
+ * update so `agents update --json` can report where a frozen installation came
+ * from without consulting the vendor.
+ */
+export interface InstallationRelease {
+    /** The vendor release that was live for this span. */
+    releaseVersion: string;
+    /** ISO-8601 timestamp at which this release became live. */
+    at: string;
+}
+/**
+ * A frozen agent installation.
+ *
+ * The load-bearing idea: an installation's IDENTITY ({@link id}, {@link label})
+ * is stable for the life of the install, while the vendor release it carries
+ * ({@link releaseVersion}) moves only on an explicit `agents update`. Every
+ * persisted reference — the global default, an isolated default, a project pin,
+ * a routine's agent spec — names the {@link label}, so a release change never
+ * invalidates a reference.
+ *
+ * Before this record existed the version-dir NAME was the only identity, which
+ * made those two concepts the same string: updating a release necessarily
+ * renamed the directory and broke every reference pointing at it, and two
+ * installations of the same release could not coexist at all. Splitting them is
+ * what makes both possible.
+ */
+export interface Installation {
+    schema: number;
+    /** Opaque, stable, never reused. Survives every update. */
+    id: string;
+    agent: AgentId;
+    /**
+     * The addressable name of this installation — the version-dir basename, and
+     * the token users type in `agents update <agent>@<label>`. Frozen at creation.
+     */
+    label: string;
+    /** The vendor release currently installed on disk. Moves on update. */
+    releaseVersion: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Newest last. Always non-empty: creation seeds it with the first release. */
+    history: InstallationRelease[];
+}
+/**
+ * How an installation's release is replaced. Selected from the agent registry's
+ * capabilities, never from an agent id — see `selectUpdateStrategy`.
+ */
+export type UpdateStrategyId = 
+/** Agent ships an npm package: a pinnable release staged into the version dir. */
+'npm-package'
+/** One global self-updating binary shared by every installation of the agent. */
+ | 'global-binary'
+/** An official install script with no pinnable version, re-imported per install. */
+ | 'install-script';
+/** Outcome of a single `agents update` run against one installation. */
+export interface UpdateOutcome {
+    installation: Installation;
+    strategy: UpdateStrategyId;
+    fromRelease: string;
+    toRelease: string;
+    /** True when the resolved target already matched the installed release. */
+    unchanged: boolean;
+    /**
+     * Installations other than the target whose recorded release also moved,
+     * because the strategy replaced a binary they share (global-binary only).
+     */
+    alsoUpdated: Installation[];
+}

package/dist/lib/installations/types.js

@@ -0,0 +1,8 @@
+/**
+ * Schema version of the on-disk installation record. Bump only for a change a
+ * previous CLI could not read; {@link INSTALLATION_SCHEMA} is asserted on read
+ * so a newer record fails loud instead of being silently misinterpreted.
+ */
+export const INSTALLATION_SCHEMA = 1;
+/** File name of the record, written at the root of a version dir. */
+export const INSTALLATION_RECORD_FILE = 'installation.json';

package/dist/lib/installations/update.d.ts

@@ -0,0 +1,40 @@
+import { type UpdateStrategy } from './strategies.js';
+import type { Installation, UpdateOutcome } from './types.js';
+export interface UpdateInstallationOptions {
+    /** `latest` (default), `oldest`, or a concrete release. */
+    to?: string;
+    onProgress?: (message: string) => void;
+    /**
+     * Replace the registry-selected strategy. The seam exists so the transaction
+     * below can be exercised against a real filesystem without a vendor fetch, and
+     * so a track that installs a harness differently (per-installation Cursor
+     * isolation) can reuse this orchestration instead of re-implementing it.
+     * Omitted in every normal call — `selectUpdateStrategy` is the default.
+     */
+    strategy?: UpdateStrategy;
+}
+/**
+ * Move one frozen installation to a new vendor release, preserving its identity.
+ *
+ * The transaction is stage → verify → commit → record, with rollback on any
+ * failure after the swap:
+ *
+ *   1. **stage**   — fetch the target release somewhere that is not yet live.
+ *   2. **verify**  — launch the STAGED binary. This is the gate that makes the
+ *                    update safe: a release that cannot start is discarded while
+ *                    the working one is still in place, so the failure mode is
+ *                    "nothing changed", not "the agent no longer runs".
+ *   3. **commit**  — swap it in, keeping the displaced release until step 4.
+ *   4. **record**  — re-verify in place, then write the new release into the
+ *                    installation record and drop the rollback material.
+ *
+ * The installation's `id` and `label` are never touched, so the global default,
+ * an isolated default, a project pin, a routine's `version:`, and a profile's
+ * `host.version` all keep resolving to this installation across the update —
+ * that reference preservation is the whole point of freezing the label.
+ *
+ * Strategies whose vendor artifact is global (a self-updating binary) report
+ * `transactional: false`; for those, step 3 is a no-op and a failed verify is
+ * surfaced as a failed update rather than pretended to be reversible.
+ */
+export declare function updateInstallation(installation: Installation, options?: UpdateInstallationOptions): Promise<UpdateOutcome>;

package/dist/lib/installations/update.js

@@ -0,0 +1,131 @@
+import * as fs from 'fs';
+import { AGENTS, isAgentHardDeprecated, hardDeprecationError } from '../agents.js';
+import { emit } from '../events.js';
+import { getBinaryPath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, verifyBinaryLaunches, } from '../versions.js';
+import { assertValidRelease, selectUpdateStrategy, } from './strategies.js';
+import { listInstallations, recordRelease } from './store.js';
+/**
+ * Move one frozen installation to a new vendor release, preserving its identity.
+ *
+ * The transaction is stage → verify → commit → record, with rollback on any
+ * failure after the swap:
+ *
+ *   1. **stage**   — fetch the target release somewhere that is not yet live.
+ *   2. **verify**  — launch the STAGED binary. This is the gate that makes the
+ *                    update safe: a release that cannot start is discarded while
+ *                    the working one is still in place, so the failure mode is
+ *                    "nothing changed", not "the agent no longer runs".
+ *   3. **commit**  — swap it in, keeping the displaced release until step 4.
+ *   4. **record**  — re-verify in place, then write the new release into the
+ *                    installation record and drop the rollback material.
+ *
+ * The installation's `id` and `label` are never touched, so the global default,
+ * an isolated default, a project pin, a routine's `version:`, and a profile's
+ * `host.version` all keep resolving to this installation across the update —
+ * that reference preservation is the whole point of freezing the label.
+ *
+ * Strategies whose vendor artifact is global (a self-updating binary) report
+ * `transactional: false`; for those, step 3 is a no-op and a failed verify is
+ * surfaced as a failed update rather than pretended to be reversible.
+ */
+export async function updateInstallation(installation, options = {}) {
+    const agent = installation.agent;
+    if (isAgentHardDeprecated(agent))
+        throw new Error(hardDeprecationError(agent));
+    const requested = options.to ?? 'latest';
+    assertValidRelease(requested);
+    const strategy = options.strategy ?? selectUpdateStrategy(agent);
+    const ctx = { agent, installation, requested, onProgress: options.onProgress };
+    const target = await strategy.resolveTarget(ctx);
+    if (target === installation.releaseVersion) {
+        options.onProgress?.(`${AGENTS[agent].name}@${installation.label} is already on release ${target}; nothing to update.`);
+        return {
+            installation,
+            strategy: strategy.id,
+            fromRelease: installation.releaseVersion,
+            toRelease: target,
+            unchanged: true,
+            alsoUpdated: [],
+        };
+    }
+    let staged = null;
+    try {
+        staged = await strategy.stage(ctx, target);
+        const stagedHealth = await verifyBinaryLaunches(staged.binary, staged.home);
+        if (!stagedHealth.ok) {
+            throw new Error(`${AGENTS[agent].name} release ${staged.release} was fetched but its binary failed to launch`
+                + `${stagedHealth.detail ? ` (${stagedHealth.detail})` : ''}. `
+                + `${installation.label} is unchanged and still on ${installation.releaseVersion}.`);
+        }
+        // The installer may have reported a release the installation already has
+        // (a self-updating binary that was already current). Recording it would
+        // claim a change that did not happen and append a bogus history entry.
+        if (staged.release === installation.releaseVersion) {
+            options.onProgress?.(`${AGENTS[agent].name}@${installation.label} is already on release ${staged.release}; nothing to update.`);
+            // Deliberately NOT committed: there is no new release to make live, and
+            // for a strategy that swaps the version dir a commit here would displace
+            // a working tree, discard its rollback material, and skip the live probe —
+            // all while reporting that nothing changed. The `finally` clears staging.
+            return {
+                installation,
+                strategy: strategy.id,
+                fromRelease: installation.releaseVersion,
+                toRelease: staged.release,
+                unchanged: true,
+                alsoUpdated: [],
+            };
+        }
+        const handles = await strategy.commit(ctx, staged);
+        try {
+            // Probe what will actually execute — `getBinaryPath` is the same resolver
+            // the shims and `agents run` use — not the staging copy probed above.
+            const liveBinary = getBinaryPath(agent, installation.label);
+            const liveHealth = await verifyBinaryLaunches(liveBinary, staged.home);
+            if (!liveHealth.ok) {
+                throw new Error(`${AGENTS[agent].name} release ${staged.release} failed to launch after being installed`
+                    + `${liveHealth.detail ? ` (${liveHealth.detail})` : ''}.`);
+            }
+        }
+        catch (err) {
+            // Undo unconditionally. `transactional` describes whether the VENDOR
+            // artifact can be put back, not whether this directory can — gating the
+            // undo on it left an installer-driven harness with the broken tree live
+            // AND the previous one orphaned in rollback material nothing deletes.
+            // A strategy with nothing to restore returns a no-op undo.
+            handles.undo();
+            throw new Error(strategy.transactional
+                ? `${err.message} Rolled back to ${installation.releaseVersion}.`
+                : `${err.message} The version directory was restored, but ${AGENTS[agent].name}'s installer `
+                    + `had already replaced the binary it manages globally — repair it with: agents add ${agent}@latest`);
+        }
+        handles.finalize();
+        const updated = recordRelease(installation, staged.release);
+        // Several installations of a global-binary harness point at the same file,
+        // so the one we just replaced is live for all of them. Recording the release
+        // only on the target would leave the others claiming a release that is no
+        // longer on disk.
+        const alsoUpdated = strategy.sharedBinary
+            ? listInstallations(agent)
+                .filter((other) => other.label !== installation.label && other.releaseVersion !== staged.release)
+                .map((other) => recordRelease(other, staged.release))
+            : [];
+        invalidateInstalledVersionsCache(agent);
+        invalidateLiveVersionCache(agent);
+        // A release really was installed, so this is the right event; `installation`
+        // says WHICH frozen install received it, since the label no longer equals
+        // the release.
+        emit('version.install', { agent, version: staged.release, installation: installation.label });
+        return {
+            installation: updated,
+            strategy: strategy.id,
+            fromRelease: installation.releaseVersion,
+            toRelease: staged.release,
+            unchanged: false,
+            alsoUpdated,
+        };
+    }
+    finally {
+        if (staged?.stagingDir)
+            fs.rmSync(staged.stagingDir, { recursive: true, force: true });
+    }
+}

package/dist/lib/migrate.d.ts

@@ -117,6 +117,33 @@ export declare function migrateExtrasExtrasToAgentsExtras(historyDir?: string):
  * Params default to the real routines dir; injectable for tests.
  */
 export declare function migrateRoutineDeviceToDevices(routinesDir?: string): void;
+/**
+ * Fold the legacy host-placement `remoteCwd` field into the canonical portable
+ * `cwd` (RUSH-2290). Host dispatch used to read `remoteCwd` while a local run
+ * inferred its cwd from `repo` — two path semantics for one concept. The runner
+ * now resolves every placement from `cwd`, so this idempotently rewrites the
+ * field:
+ *
+ * - `remoteCwd` present, no `cwd`  → rename to `cwd`.
+ * - both present and equal          → drop the duplicate `remoteCwd`.
+ * - both present and DIFFERENT       → conflict: leave BOTH fields untouched so
+ *   the migration never silently chooses one; `validateJob`/`doctor` then flag the
+ *   pair and the routine stays paused rather than running against a guessed path.
+ *
+ * Idempotent: a file with only `cwd` (already migrated) is skipped.
+ */
+export declare function migrateRoutineRemoteCwdToCwd(routinesDir?: string): void;
+/**
+ * Pause every currently-active routine whose execution context no longer
+ * resolves ready (RUSH-2290). An agent/workflow routine with no project/cwd, a
+ * missing directory, or a non-portable path used to fire and fail every tick —
+ * the mass auth_failed / untrusted-home storm this ticket exists to stop. After
+ * the fold, such a routine is deactivated on THIS device (only), preventing it
+ * from being scheduled until `agents routines doctor --all --fix` (or a repair +
+ * `resume`) makes it ready. Never materializes a device manifest that does not
+ * yet exist, and never touches command routines (they run in the target home).
+ */
+export declare function pauseUnreadyEnabledRoutines(): void;
 /**
  * Fold the legacy watchdog enable sentinel into the watchdog routine.
  *