@phnx-labs/agents-cli 1.22.78 → 1.22.79

package/dist/lib/installations/update-runtime.js

@@ -0,0 +1,321 @@
+/**
+ * The automatic-update pass (PHNX-3940): decide which installations may be
+ * moved to their harness's latest release with no operator in the loop, then
+ * (optionally) move them.
+ *
+ * Split into a PLAN (`planAutoUpdates` — the `--check` dry-run and the
+ * daemon's own decision step both read it; it reads through
+ * {@link listInstallationSnapshots}, which NEVER mutates disk, so a preview is
+ * genuinely a preview) and a RUN (`runAutoUpdatePass`, which migrates a
+ * legacy installation for real, under its own lock, and regenerates its
+ * already-owned shim/versioned-alias, before driving eligible plan entries
+ * through the existing `updateInstallation` transaction). Both share one
+ * eligibility computation so a dry-run can never report "would update" for
+ * something the real run would skip, or vice versa.
+ *
+ * Eligibility is deliberately narrow:
+ *   - Only the `npm-package` strategy is transactional AND isolated per
+ *     installation (stage into a sibling dir, launch-probe it, swap, keep the
+ *     displaced tree until the swap is proven) — the shape every existing
+ *     safety property in `update.ts` depends on. A global-binary or
+ *     install-script harness has no reversible per-installation swap to offer,
+ *     so it is reported honestly as manual/vendor-managed rather than silently
+ *     skipped or, worse, "updated" via an irreversible reinstall with no
+ *     operator watching.
+ *   - The operator switch (`updates.auto` / `updates.<agent>.auto`,
+ *     `update-policy.ts`) and the per-installation policy
+ *     (`Installation.updatePolicy`) must both allow it.
+ *   - The installation must not look ACTIVE right now (see
+ *     {@link isInstallationLikelyActive}) — a real OS process-table scan, not
+ *     just this box's session registry, so a harness launched by a bare
+ *     generated shim with no session bookkeeping still defers correctly.
+ *
+ * The latest release for a harness is resolved ONCE per pass (not once per
+ * installation) — `resolveSharedTargets` below — so a fleet with a dozen
+ * pinned-to-latest Claude installations issues one npm registry read, not a
+ * dozen.
+ */
+import * as fs from 'fs';
+import { AGENTS, isAgentHardDeprecated } from '../agents.js';
+import { MANAGED_AGENT_IDS } from '../agent-spec/agents.js';
+import { withFileLockAsync } from '../fs-atomic.js';
+import { ensureInstallationLocked, installationDir, listInstallationLabels, readInstallation, } from './store.js';
+import { refreshOwnedLaunchers, hasLiveLaunchLease } from './shims.js';
+import { installationLooksActive, realProcessSnapshot } from './active-check.js';
+import { selectUpdateStrategy } from './strategies.js';
+import { updateInstallation } from './update.js';
+import { effectiveUpdatePolicy, isAutoUpdateEnabledForAgent } from './update-policy.js';
+import { installationLockTarget, INSTALLATION_LOCK_OPTIONS } from './installation-lock.js';
+import { withGuardedUpdateCancellation } from './update-cancellation.js';
+import { INSTALLATION_SCHEMA } from './types.js';
+/** The only strategy shape the automatic pass will ever touch — see the module docblock. */
+function autoUpdateStrategyFor(agent) {
+    let strategy;
+    try {
+        strategy = selectUpdateStrategy(agent);
+    }
+    catch {
+        return null;
+    }
+    return strategy.id === 'npm-package' && strategy.transactional ? strategy : null;
+}
+/**
+ * Build the record a real migration (`ensureInstallation`, `store.ts`) would
+ * mint for a legacy version dir that has no `installation.json` yet — the
+ * same fields (schema, label-as-release, history seeded from the directory's
+ * own mtime) — but never persisted, and never carrying the real
+ * `mintInstallationId()` format, so nothing downstream can mistake it for an
+ * id that survived a lock-protected migration. Returns null when the
+ * directory itself is gone mid-scan, tolerated the same way
+ * `listInstallations` tolerates that.
+ */
+function ephemeralInstallationSnapshot(agent, label) {
+    const dir = installationDir(agent, label);
+    let createdAt;
+    try {
+        createdAt = fs.statSync(dir).mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+    return {
+        schema: INSTALLATION_SCHEMA,
+        id: `preview:${agent}:${label}`,
+        agent,
+        label,
+        releaseVersion: label,
+        createdAt,
+        updatedAt: createdAt,
+        history: [{ releaseVersion: label, at: createdAt }],
+    };
+}
+/**
+ * Read-only enumeration of installations — the ONLY listing {@link planAutoUpdates}
+ * may use. `listInstallations` (`store.ts`) migrates a legacy version dir's
+ * `installation.json` into existence via `ensureInstallation` as a side
+ * effect of merely being READ, which made `agents update --check` (a
+ * "preview") write to disk. A legacy dir with no persisted record yet gets an
+ * {@link ephemeralInstallationSnapshot} instead — real fields, but never
+ * written and never a real id. The real run migrates it for real, under this
+ * installation's own lock, immediately before acting on it — see
+ * {@link runAutoUpdatePass}.
+ */
+export function listInstallationSnapshots(agent) {
+    const out = [];
+    for (const label of listInstallationLabels(agent)) {
+        let record;
+        try {
+            record = readInstallation(agent, label);
+        }
+        catch {
+            continue; // corrupted record — not an installation this pass can act on
+        }
+        const snapshot = record ?? ephemeralInstallationSnapshot(agent, label);
+        if (snapshot)
+            out.push(snapshot);
+    }
+    return out;
+}
+/**
+ * Build the automatic-update plan: one entry per installation of every scoped
+ * agent, with eligibility, deferral, and the resolved target release already
+ * computed. Never mutates anything — reads only through
+ * {@link listInstallationSnapshots} — so it is genuinely safe to call from
+ * `--check` or before every real pass.
+ */
+export async function planAutoUpdates(opts = {}) {
+    const agents = (opts.agents ?? MANAGED_AGENT_IDS).filter((agent) => !isAgentHardDeprecated(agent));
+    let commandLines = null;
+    let processScanError;
+    try {
+        commandLines = await realProcessSnapshot.listCommandLines();
+    }
+    catch (err) {
+        processScanError = err instanceof Error ? err.message : String(err);
+    }
+    const plan = [];
+    for (const agent of agents) {
+        const installations = listInstallationSnapshots(agent);
+        if (installations.length === 0)
+            continue;
+        const strategy = autoUpdateStrategyFor(agent);
+        const agentAutoEnabled = isAutoUpdateEnabledForAgent(agent);
+        // Resolve the latest release ONCE per agent — not once per installation —
+        // and only when at least the strategy/switch preconditions hold, so a
+        // harness nobody enabled auto-updates for never triggers a registry read.
+        let target = null;
+        let resolveError;
+        if (strategy && agentAutoEnabled) {
+            try {
+                const ctx = {
+                    agent,
+                    installation: installations[0],
+                    requested: 'latest',
+                    onProgress: opts.onProgress,
+                };
+                target = await strategy.resolveTarget(ctx);
+            }
+            catch (err) {
+                resolveError = err instanceof Error ? err.message : String(err);
+            }
+        }
+        for (const installation of installations) {
+            const policy = effectiveUpdatePolicy(installation);
+            let eligible = true;
+            let reason;
+            if (!strategy) {
+                eligible = false;
+                reason = `${AGENTS[agent].name} is manual/vendor-managed for updates (no isolated, reversible per-installation swap) — update it yourself.`;
+            }
+            else if (!agentAutoEnabled) {
+                eligible = false;
+                reason = 'automatic updates are disabled for this harness (updates.auto / updates.<agent>.auto).';
+            }
+            else if (policy === 'pinned') {
+                eligible = false;
+                reason = 'installation is pinned to a concrete release (agents update … --to <release> unpins with --to latest).';
+            }
+            else if (resolveError) {
+                eligible = false;
+                reason = `could not resolve the latest release: ${resolveError}`;
+            }
+            let deferred = false;
+            if (eligible) {
+                if (hasLiveLaunchLease(installation.agent, installation.label)) {
+                    deferred = true;
+                    reason = 'a launch is in flight for this installation (live launch lease); deferring.';
+                }
+                else if (commandLines) {
+                    deferred = installationLooksActive(installation, commandLines);
+                    if (deferred)
+                        reason = 'the installation appears to have a process running right now; deferring.';
+                }
+                else {
+                    // The process scan itself failed — fail closed for every installation
+                    // this pass would otherwise touch, not just the ones a scan would have
+                    // flagged as active.
+                    deferred = true;
+                    reason = `could not confirm no process is running (${processScanError}); deferring.`;
+                }
+            }
+            plan.push({
+                agent,
+                installation,
+                currentRelease: installation.releaseVersion,
+                targetRelease: target,
+                policy,
+                eligible,
+                deferred,
+                reason,
+            });
+        }
+    }
+    return plan;
+}
+/**
+ * Run the automatic-update pass: plan, then drive every eligible,
+ * non-deferred, actually-behind entry through {@link updateInstallation}.
+ * Installations update sequentially — this runs from a bounded daemon-spawned
+ * child process (`harness-update-service.ts`) on its own schedule, not a
+ * user-facing wait, so there is no reason to parallelize and every reason not
+ * to (concurrent npm installs sharing this box's npm cache have a history of
+ * corrupting each other).
+ *
+ * `abortIfPinnedBeforeCommit` / `abortIfAutoDisabledBeforeCommit: true` on
+ * every call: this is the ONE caller for whom a policy or switch change
+ * mid-staging must cancel the commit (see `update.ts`'s docblock on those
+ * options) — a manual `agents update` never routes through here.
+ */
+export async function runAutoUpdatePass(opts = {}) {
+    // Cancellation is wired from IPC (the daemon's cross-platform request),
+    // channel `disconnect` (daemon gone), and SIGTERM/SIGINT — never a forced
+    // process kill (see `update-cancellation.ts`). The guard it holds is what lets
+    // `index.ts` defer its SIGINT hard-exit while a swap is in flight.
+    return withGuardedUpdateCancellation(async (cancelled) => {
+        const result = await runAutoUpdatePassUntilCancelled(opts, cancelled);
+        return { ...result, cancelled: cancelled() };
+    });
+}
+/**
+ * The hidden `__harness-update-run` verb the daemon spawns with an IPC channel
+ * (dispatched in `index.ts`). Runs ONE auto-update pass with the cooperative,
+ * cross-platform cancellation above, writes a compact JSON summary to stdout for
+ * the daemon's log, and returns the process exit code.
+ *
+ * Exit code mirrors the manual `agents update --auto` path
+ * (`commands/update.ts`): a per-installation error is a NORMAL tick outcome (a
+ * bad vendor release) surfaced as a non-zero exit the daemon logs as a warning,
+ * not a service failure. A cooperative cancel is not itself an error, so it does
+ * not force a non-zero exit — the child exits on its own and the daemon observes
+ * that true completion rather than reading a killed process.
+ */
+export async function runHarnessUpdateChild() {
+    const result = await runAutoUpdatePass({});
+    const anyError = result.outcomes.some((o) => o.error);
+    const summary = {
+        v: 1,
+        cancelled: result.cancelled ?? false,
+        outcomes: result.outcomes.map((o) => ({
+            agent: o.entry.agent,
+            label: o.entry.installation.label,
+            fromRelease: o.outcome?.fromRelease ?? null,
+            toRelease: o.outcome?.toRelease ?? null,
+            unchanged: o.outcome?.unchanged ?? null,
+            deferred: o.outcome?.deferred ?? null,
+            error: o.error ?? null,
+        })),
+    };
+    process.stdout.write(JSON.stringify(summary));
+    return anyError ? 1 : 0;
+}
+async function runAutoUpdatePassUntilCancelled(opts, cancelled) {
+    const plan = await planAutoUpdates(opts);
+    const outcomes = [];
+    // One shim resolves every installation of an agent dynamically at launch
+    // time, so regenerating it once per agent (not once per installation) this
+    // pass touches is enough — a second entry for the same agent would just
+    // redo `ensureShimCurrent`'s own no-op "already current" check.
+    for (const entry of plan) {
+        if (cancelled())
+            break;
+        if (!entry.eligible || entry.deferred)
+            continue;
+        if (!entry.targetRelease || entry.targetRelease === entry.currentRelease)
+            continue;
+        try {
+            // The plan above is deliberately read-only (`listInstallationSnapshots`),
+            // so a legacy version dir with no persisted `installation.json` yet is
+            // represented there by an ephemeral, never-written snapshot. A REAL
+            // pass must migrate it for real before acting on it — done here, under
+            // the SAME per-installation lock `updateInstallation` itself takes
+            // (`INSTALLATION_LOCK_OPTIONS`), so two concurrent real passes can never
+            // mint two different ids for the same legacy install. Already-migrated
+            // installations round-trip through this unchanged (`ensureInstallation`
+            // is a plain read when a record already exists).
+            const installation = await withFileLockAsync(installationLockTarget(entry.agent, entry.installation.label), () => ensureInstallationLocked(entry.agent, entry.installation.label, entry.installation.createdAt), INSTALLATION_LOCK_OPTIONS);
+            // Regenerate only what this pass already owns — the agent's generated
+            // shim, and this installation's versioned alias if it was installed
+            // isolated — using the existing upgrade-in-place helpers
+            // (`ensureShimCurrent`/`ensureVersionedAliasCurrent`). Deliberately
+            // NEVER `adoptShadowingLauncher`: that seizes a launcher this pass does
+            // not own (a user's own PATH entry, or another install's), and is an
+            // operator-triggered `doctor --fix` action, not something an unattended
+            // background pass may do on its own. Real-pass-only, same reason as the
+            // migration above — a `--check` preview must not touch PATH or a
+            // config-dir symlink.
+            refreshOwnedLaunchers(entry.agent, installation.label);
+            const outcome = await updateInstallation(installation, {
+                to: entry.targetRelease,
+                onProgress: opts.onProgress,
+                abortIfPinnedBeforeCommit: true,
+                abortIfAutoDisabledBeforeCommit: true,
+                shouldCancel: cancelled,
+            });
+            outcomes.push({ entry, outcome });
+        }
+        catch (err) {
+            outcomes.push({ entry, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return { plan, outcomes };
+}

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

@@ -1,6 +1,10 @@
 import { type UpdateStrategy } from './strategies.js';
 import type { Installation, UpdateOutcome } from './types.js';
 export interface UpdateInstallationOptions {
+    /** Persist together with a successfully selected release, under this transaction's lock. */
+    updatePolicy?: Installation['updatePolicy'];
+    /** Cooperative cancellation is honored before the swap, never during record/rollback. */
+    shouldCancel?: () => boolean;
     /** `latest` (default), `oldest`, or a concrete release. */
     to?: string;
     onProgress?: (message: string) => void;
@@ -12,6 +16,27 @@ export interface UpdateInstallationOptions {
      * Omitted in every normal call — `selectUpdateStrategy` is the default.
      */
     strategy?: UpdateStrategy;
+    /**
+     * Abort just before `commit()` if the installation's update policy has
+     * flipped to `'pinned'` since staging began, instead of making the staged
+     * release live. Set only by the automatic-update pass
+     * (`update-runtime.ts`): a manual `agents update` is itself the user's
+     * request and must never be undercut by a policy read mid-flight, but an
+     * automatic run must not commit an update the operator pinned away from
+     * while the (potentially minutes-long) stage was in flight.
+     */
+    abortIfPinnedBeforeCommit?: boolean;
+    /**
+     * Set only by the automatic-update pass (`update-runtime.ts`). Right before
+     * `commit()`, re-reads the global/per-harness `updates.auto` switches
+     * (`update-policy.ts`) in addition to the pin check above, aborting the
+     * commit if automatic updates were turned off for this harness while the
+     * (potentially minutes-long) stage was in flight. Same reasoning as
+     * {@link abortIfPinnedBeforeCommit}: a manual `agents update` is itself the
+     * user's own current request and must never be undercut by a policy read
+     * mid-flight, so it never sets this.
+     */
+    abortIfAutoDisabledBeforeCommit?: boolean;
 }
 /**
  * Move one frozen installation to a new vendor release, preserving its identity.

package/dist/lib/installations/update.js

@@ -1,9 +1,13 @@
 import * as fs from 'fs';
 import { AGENTS, isAgentHardDeprecated, hardDeprecationError } from '../agents.js';
 import { emit } from '../feed/events.js';
+import { withFileLockAsync } from '../fs-atomic.js';
 import { getBinaryPath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, verifyBinaryLaunches, } from './versions.js';
 import { assertValidRelease, selectUpdateStrategy, } from './strategies.js';
-import { listInstallations, recordRelease } from './store.js';
+import { listInstallations, readInstallation, recordRelease, writeInstallation } from './store.js';
+import { effectiveUpdatePolicy, isAutoUpdateEnabledForAgent } from './update-policy.js';
+import { isInstallationLikelyActive } from './active-check.js';
+import { installationLockTarget, INSTALLATION_LOCK_OPTIONS } from './installation-lock.js';
 /**
  * Move one frozen installation to a new vendor release, preserving its identity.
  *
@@ -32,12 +36,32 @@ export async function updateInstallation(installation, options = {}) {
     const agent = installation.agent;
     if (isAgentHardDeprecated(agent))
         throw new Error(hardDeprecationError(agent));
+    // Serialize every update of this SAME installation — manual and automatic
+    // alike — behind a cross-process lock keyed on its own record file. Without
+    // it, an operator's `agents update claude@2.0.65` racing the automatic pass
+    // (or two automatic passes on two boxes sharing this ~/.agents, which
+    // shouldn't happen but isn't prevented at this layer) could stage two
+    // releases into the same version dir and interleave their swaps. The record
+    // is re-read fresh under the lock (never trusting the possibly-stale
+    // `installation` the caller passed in) so a concurrent update that already
+    // landed is observed before this one decides what to do; a corrupted record
+    // makes `readInstallation` throw, which propagates out of the locked section
+    // and fails the update closed rather than proceeding on unreadable state.
+    return withFileLockAsync(installationLockTarget(agent, installation.label), () => runUpdateInstallation(agent, installation, options), INSTALLATION_LOCK_OPTIONS);
+}
+async function runUpdateInstallation(agent, requestedInstallation, options) {
+    const installation = readInstallation(agent, requestedInstallation.label) ?? requestedInstallation;
     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) {
+        if (options.updatePolicy) {
+            installation.updatePolicy = options.updatePolicy;
+            installation.updatedAt = new Date().toISOString();
+            writeInstallation(installation);
+        }
         options.onProgress?.(`${AGENTS[agent].name}@${installation.label} is already on release ${target}; nothing to update.`);
         return {
             installation,
@@ -48,6 +72,35 @@ export async function updateInstallation(installation, options = {}) {
             alsoUpdated: [],
         };
     }
+    // Mandatory for every transactional strategy, every caller — manual
+    // `agents update` included, not just the automatic pass. A transactional
+    // strategy's commit is a swap of THIS installation's own directory, so a
+    // live process or launch lease naming it (`active-check.ts`) means staging
+    // right now risks a launch racing the swap. This is the pre-STAGE half of
+    // the check, taken under the same lock this whole transaction holds — the
+    // identical check runs again immediately before commit below, since staging
+    // an npm package can take the better part of `INSTALL_TIMEOUT_MS` and a
+    // launch can start during that window. Non-transactional strategies (a
+    // global-binary/install-script harness) have no reversible swap to protect,
+    // so they are unaffected by either check.
+    if (options.shouldCancel?.() || (options.abortIfPinnedBeforeCommit && effectiveUpdatePolicy(installation) === 'pinned')
+        || (options.abortIfAutoDisabledBeforeCommit && !isAutoUpdateEnabledForAgent(agent))) {
+        return { installation, strategy: strategy.id, fromRelease: installation.releaseVersion, toRelease: target,
+            unchanged: true, deferred: 'Update cancelled or automatic update policy changed.', alsoUpdated: [] };
+    }
+    if (strategy.transactional && await isInstallationLikelyActive(installation)) {
+        options.onProgress?.(`${AGENTS[agent].name}@${installation.label} looks active right now (a process or launch lease); `
+            + `not staging release ${target}.`);
+        return {
+            installation,
+            strategy: strategy.id,
+            fromRelease: installation.releaseVersion,
+            toRelease: target,
+            unchanged: true,
+            deferred: 'Account home is in use; retry after its sessions finish.',
+            alsoUpdated: [],
+        };
+    }
     let staged = null;
     try {
         staged = await strategy.stage(ctx, target);
@@ -61,6 +114,11 @@ export async function updateInstallation(installation, options = {}) {
         // (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) {
+            if (options.updatePolicy) {
+                installation.updatePolicy = options.updatePolicy;
+                installation.updatedAt = new Date().toISOString();
+                writeInstallation(installation);
+            }
             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
@@ -75,6 +133,65 @@ export async function updateInstallation(installation, options = {}) {
                 alsoUpdated: [],
             };
         }
+        // The automatic pass may have started staging while the installation was
+        // still eligible, then had it pinned out from under it — staging an npm
+        // package can legitimately take the better part of INSTALL_TIMEOUT_MS. Check
+        // ONE more time, right before the point of no return, so a policy change
+        // that lands mid-staging is honored instead of committed anyway. A manual
+        // `agents update` never sets this option: the user's own invocation IS their
+        // current intent, so there is nothing to defer to.
+        if (options.abortIfPinnedBeforeCommit) {
+            const fresh = readInstallation(agent, installation.label);
+            if (fresh && effectiveUpdatePolicy(fresh) === 'pinned') {
+                options.onProgress?.(`${AGENTS[agent].name}@${installation.label} was pinned while ${staged.release} was staging; not committing it.`);
+                return {
+                    installation: fresh,
+                    strategy: strategy.id,
+                    fromRelease: fresh.releaseVersion,
+                    toRelease: staged.release,
+                    unchanged: true,
+                    deferred: 'Installation was pinned while the update was being prepared.',
+                    alsoUpdated: [],
+                };
+            }
+        }
+        // Automatic-only, same reasoning as the pin recheck above: the operator
+        // may have flipped `updates.auto` / `updates.<agent>.auto` off while this
+        // release was staging (minutes for a real npm install), and an automatic
+        // run must honor that instead of committing an update the operator just
+        // asked to stop. A manual `agents update` never sets this — the user's
+        // own invocation already IS the decision to update, regardless of the
+        // switch that only gates the UNATTENDED pass.
+        if (options.abortIfAutoDisabledBeforeCommit && !isAutoUpdateEnabledForAgent(agent)) {
+            options.onProgress?.(`${AGENTS[agent].name}@${installation.label}: automatic updates were turned off while ${staged.release} `
+                + `was staging; not committing it.`);
+            return {
+                installation,
+                strategy: strategy.id,
+                fromRelease: installation.releaseVersion,
+                toRelease: staged.release,
+                unchanged: true,
+                deferred: 'Automatic updates were turned off while the update was being prepared.',
+                alsoUpdated: [],
+            };
+        }
+        // Mandatory for every transactional strategy, every caller — see the
+        // identical pre-stage check above for why this cannot be opt-in: a launch
+        // that starts AFTER that first check but before this swap is exactly the
+        // window this closes.
+        if (options.shouldCancel?.() || (strategy.transactional && await isInstallationLikelyActive(installation))) {
+            options.onProgress?.(`${AGENTS[agent].name}@${installation.label} looks active now (a process or launch lease appeared while `
+                + `${staged.release} was staging); not committing it.`);
+            return {
+                installation,
+                strategy: strategy.id,
+                fromRelease: installation.releaseVersion,
+                toRelease: staged.release,
+                unchanged: true,
+                deferred: 'Update cancelled or the account home became active.',
+                alsoUpdated: [],
+            };
+        }
         const handles = await strategy.commit(ctx, staged);
         try {
             // Probe what will actually execute — `getBinaryPath` is the same resolver
@@ -98,8 +215,30 @@ export async function updateInstallation(installation, options = {}) {
                 : `${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`);
         }
+        // Record BEFORE finalizing the commit's rollback material — not after.
+        // `finalize()` discards the only thing that can put the previous release
+        // back (deletes the rollback dir / no-ops for a non-transactional
+        // strategy). If `recordRelease` throws (e.g. disk full, an unwritable
+        // installation.json) AFTER finalize, the new release is live on disk with
+        // no rollback path AND no record of it — an installation whose directory
+        // and its own metadata now disagree, with no way back. Recording first
+        // means a record-write failure still has the rollback material available
+        // to undo the live swap, so the failure mode stays "nothing changed"
+        // instead of "half updated, unrecoverable."
+        let updated;
+        try {
+            updated = recordRelease({ ...installation, ...(options.updatePolicy ? { updatePolicy: options.updatePolicy } : {}) }, staged.release);
+        }
+        catch (err) {
+            handles.undo();
+            throw new Error(strategy.transactional
+                ? `${err.message} ${AGENTS[agent].name} release ${staged.release} could not be recorded. `
+                    + `Rolled back to ${installation.releaseVersion}.`
+                : `${err.message} ${AGENTS[agent].name} release ${staged.release} could not be recorded. `
+                    + `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

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

@@ -87,6 +87,7 @@ export declare function setIsolatedDefault(agent: AgentId, version: string | und
 /** Install a specific version of an agent. */
 export declare function installVersion(agent: AgentId, version: string, onProgress?: (message: string) => void, opts?: {
     clean?: boolean;
+    installationLabel?: string;
 }): Promise<{
     success: boolean;
     installedVersion: string;