@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,54 +1,13 @@
-/**
- * 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 type { AgentId } from '../types.js';
 import { type Installation, type UpdateOutcome, type UpdatePolicy } from './types.js';
 export interface AutoUpdatePlanEntry {
     agent: AgentId;
     installation: Installation;
     currentRelease: string;
-    /** The resolved latest release, or `null` when it could not be resolved (network error, unsupported strategy). */
     targetRelease: string | null;
     policy: UpdatePolicy;
-    /** Whether the automatic pass would act on this installation at all (ignoring whether it is currently deferred). */
     eligible: boolean;
-    /** Whether a live process for this installation held it back THIS pass. Independent of `eligible`. */
     deferred: boolean;
-    /** Human-readable reason `eligible` is false, or `deferred` is true, or `targetRelease` is null. Unset when there is nothing to explain (already current, or a real update would run). */
     reason?: string;
 }
 export interface AutoUpdatePassOutcome {
@@ -59,60 +18,13 @@ export interface AutoUpdatePassOutcome {
 export interface AutoUpdatePassResult {
     plan: AutoUpdatePlanEntry[];
     outcomes: AutoUpdatePassOutcome[];
-    /** True when the pass stopped early on a cancellation request (deadline, daemon shutdown, IPC, or SIGINT/SIGTERM) rather than exhausting the plan. */
     cancelled?: boolean;
 }
 export interface AutoUpdatePassOptions {
-    /** Scope to these agents only. Default: every non-hard-deprecated managed agent. */
     agents?: AgentId[];
     onProgress?: (message: string) => void;
 }
-/**
- * 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 declare function listInstallationSnapshots(agent: AgentId): Installation[];
-/**
- * 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 declare function planAutoUpdates(opts?: AutoUpdatePassOptions): Promise<AutoUpdatePlanEntry[]>;
-/**
- * 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 declare function runAutoUpdatePass(opts?: AutoUpdatePassOptions): Promise<AutoUpdatePassResult>;
-/**
- * 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 declare function runHarnessUpdateChild(): Promise<number>;

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

@@ -1,40 +1,3 @@
-/**
- * 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';
@@ -48,7 +11,6 @@ import { effectiveUpdatePolicy, isAutoUpdateEnabledForAgent } from './update-pol
 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 {
@@ -59,16 +21,6 @@ function autoUpdateStrategyFor(agent) {
     }
     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;
@@ -89,17 +41,6 @@ function ephemeralInstallationSnapshot(agent, label) {
         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)) {
@@ -108,7 +49,7 @@ export function listInstallationSnapshots(agent) {
             record = readInstallation(agent, label);
         }
         catch {
-            continue; // corrupted record — not an installation this pass can act on
+            continue;
         }
         const snapshot = record ?? ephemeralInstallationSnapshot(agent, label);
         if (snapshot)
@@ -116,13 +57,6 @@ export function listInstallationSnapshots(agent) {
     }
     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;
@@ -140,9 +74,6 @@ export async function planAutoUpdates(opts = {}) {
             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) {
@@ -191,9 +122,6 @@ export async function planAutoUpdates(opts = {}) {
                         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.`;
                 }
@@ -212,43 +140,12 @@ export async function planAutoUpdates(opts = {}) {
     }
     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);
@@ -271,10 +168,6 @@ export async function runHarnessUpdateChild() {
 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;
@@ -283,26 +176,7 @@ async function runAutoUpdatePassUntilCancelled(opts, cancelled) {
         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 `agents sync` 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,

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

@@ -1,65 +1,12 @@
 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;
-    /**
-     * 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;
-    /**
-     * 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.
- *
- * 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

@@ -8,45 +8,10 @@ import { listInstallations, readInstallation, recordRelease, writeInstallation }
 import { effectiveUpdatePolicy, isAutoUpdateEnabledForAgent } from './update-policy.js';
 import { describeInstallationActivity, formatInUseDeferral } 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.
- *
- * 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));
-    // 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) {
@@ -72,17 +37,6 @@ async function runUpdateInstallation(agent, requestedInstallation, 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,
@@ -113,9 +67,6 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
                 + `${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) {
             if (options.updatePolicy) {
                 installation.updatePolicy = options.updatePolicy;
@@ -123,10 +74,6 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
                 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
-            // 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,
@@ -136,13 +83,6 @@ async function runUpdateInstallation(agent, requestedInstallation, 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') {
@@ -158,13 +98,6 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
                 };
             }
         }
-        // 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.`);
@@ -178,10 +111,6 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
                 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.
         const lateActivity = strategy.transactional ? await describeInstallationActivity(installation) : null;
         if (options.shouldCancel?.() || lateActivity?.active) {
             options.onProgress?.(`${AGENTS[agent].name}@${installation.label} looks active now (a process or launch lease appeared while `
@@ -200,8 +129,6 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
         }
         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) {
@@ -210,27 +137,12 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
             }
         }
         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`);
         }
-        // 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);
@@ -245,10 +157,6 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
                     + `binary it manages globally — repair it with: agents add ${agent}@latest`);
         }
         handles.finalize();
-        // 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)
@@ -256,9 +164,6 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
             : [];
         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,