@phnx-labs/agents-cli 1.22.78 → 1.22.80

package/dist/lib/installations/strategies.js

@@ -17,19 +17,10 @@ function runId() {
 }
 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 });
-    }
+    // Staging and rollback are siblings on the installation filesystem. Never
+    // turn an atomic rename failure into a partially successful copy-and-delete:
+    // an open Windows file or unexpected mount must leave the source intact.
+    fs.renameSync(from, to);
 }
 /**
  * Entries a swap replaces: everything npm owns inside a version dir. The lockfile
@@ -101,32 +92,61 @@ const npmPackageStrategy = {
         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) {
+        const stagedIn = [];
+        // Restore each displaced entry. If restoration itself fails, retain every
+        // remaining backup and surface its path; never erase the only good copy.
+        const restorePreCommitState = () => {
+            const errors = [];
+            for (const entry of [...stagedIn].reverse()) {
+                try {
                     fs.rmSync(path.join(dir, entry), { recursive: true, force: true });
                 }
-                for (const entry of displaced) {
+                catch (err) {
+                    errors.push(`${entry}: ${err.message}`);
+                }
+            }
+            for (const entry of [...displaced].reverse()) {
+                try {
                     moveDir(path.join(rollbackDir, entry), path.join(dir, entry));
                 }
-                fs.rmSync(rollbackDir, { recursive: true, force: true });
-            },
+                catch (err) {
+                    errors.push(`${entry}: ${err.message}`);
+                }
+            }
+            if (errors.length)
+                throw new Error(`Rollback incomplete; recovery files retained at ${rollbackDir}: ${errors.join('; ')}`);
+            fs.rmSync(rollbackDir, { recursive: true, force: true });
+        };
+        try {
+            // 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 on
+            // its own: either the old entries are all aside (restorable) or the new
+            // ones are all in place — the try/catch below is what makes a throw
+            // BETWEEN those two loops (or partway through the second one) recover
+            // to the pre-commit state instead of leaving whichever entries already
+            // moved exactly where the exception left them.
+            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));
+                    stagedIn.push(entry);
+                }
+            }
+        }
+        catch (err) {
+            restorePreCommitState();
+            throw new Error(`${err.message} The swap was interrupted partway through and has been rolled back to `
+                + `${ctx.installation.releaseVersion}.`);
+        }
+        return {
+            undo: restorePreCommitState,
             finalize: () => fs.rmSync(rollbackDir, { recursive: true, force: true }),
         };
     },

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

@@ -50,7 +50,22 @@ export interface Installation {
     updatedAt: string;
     /** Newest last. Always non-empty: creation seeds it with the first release. */
     history: InstallationRelease[];
+    /**
+     * How the automatic-update pass (`installations/update-runtime.ts`) treats
+     * this installation. `'latest'` (the default) lets it ride the automatic
+     * pass; `'pinned'` excludes it — set implicitly by `agents update
+     * <agent>@<label> --to <concrete-release>` and cleared by `--to latest`.
+     *
+     * Absent means `'latest'`: every installation created before this field
+     * existed is legacy data, not an opt-out, so a missing key must resolve the
+     * same as an explicit `'latest'` rather than being treated as unset/invalid.
+     * Read through {@link effectiveUpdatePolicy} in `update-policy.ts` — never
+     * compare this field directly, so that default stays in one place.
+     */
+    updatePolicy?: UpdatePolicy;
 }
+/** See {@link Installation.updatePolicy}. */
+export type UpdatePolicy = 'latest' | 'pinned';
 /**
  * How an installation's release is replaced. Selected from the agent registry's
  * capabilities, never from an agent id — see `selectUpdateStrategy`.
@@ -70,6 +85,8 @@ export interface UpdateOutcome {
     toRelease: string;
     /** True when the resolved target already matched the installed release. */
     unchanged: boolean;
+    /** No swap occurred because activity, cancellation, or policy prevented it. */
+    deferred?: string;
     /**
      * Installations other than the target whose recorded release also moved,
      * because the strategy replaced a binary they share (global-binary only).

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

@@ -0,0 +1,82 @@
+/**
+ * Cross-platform cooperative cancellation for the harness auto-update pass
+ * (PHNX-3940).
+ *
+ * The pass mutates the filesystem transactionally — stage an npm install into a
+ * sibling dir, launch-probe it, swap it in, record the new release, drop the
+ * rollback material (see `update.ts`). Interrupting it mid-swap can leave an
+ * installation whose directory and its own metadata disagree, with no way back.
+ * So it must be cancellable from OUTSIDE the process — on the daemon's per-tick
+ * deadline, or on daemon shutdown — WITHOUT terminating a process that is mid-swap.
+ *
+ * `execFile`'s `timeout`/`AbortSignal` do exactly the wrong thing here: they
+ * FORCE-terminate the child. On Windows that is unconditional (there are no POSIX
+ * signals to cooperate with — the SIGTERM listener the pass installs never runs),
+ * so a Windows daemon would kill its own update worker mid-rename. Even on POSIX
+ * the forced kill races the swap.
+ *
+ * The fix is a request, not a kill: the daemon spawns the pass as a child over a
+ * Node IPC channel and asks it to stop by SENDING A MESSAGE. The child flips a
+ * flag that `update.ts`'s existing `shouldCancel` reads at each safe boundary
+ * (before the next installation, before staging, and immediately before commit)
+ * and finishes what it is doing cleanly. The channel closing (parent gone) and a
+ * received SIGTERM/SIGINT are treated as the same request, so a force-killed
+ * daemon can never strand a child mutating forever, and a manual `agents update
+ * --auto` interrupted with Ctrl+C also stops at a boundary rather than mid-swap.
+ *
+ * This module is a dependency-free LEAF on purpose: `index.ts` reads the guard
+ * depth below through the shared {@link GUARDED_AUTO_UPDATE_SYMBOL} registry key
+ * (never importing this module, so the slim CLI shell stays slim), and the daemon
+ * child fixture in tests imports {@link withGuardedUpdateCancellation} without
+ * pulling the installations graph.
+ */
+/**
+ * The hidden verb the daemon spawns to run one auto-update pass with IPC-driven
+ * cancellation (dispatched in `index.ts`, handled by
+ * `update-runtime.ts`'s `runHarnessUpdateChild`). Internal protocol — not a
+ * public command.
+ */
+export declare const HARNESS_UPDATE_CHILD_CMD = "__harness-update-run";
+/** IPC message `type` the daemon sends to request a cooperative stop. */
+export declare const HARNESS_UPDATE_CANCEL_MSG = "harness-update:cancel";
+/**
+ * Well-known cross-realm key naming the count of guarded auto-update passes
+ * running IN THIS PROCESS right now. `index.ts`'s top-level SIGINT handler reads
+ * it via `Symbol.for(...)` WITHOUT importing this module (keeping the slim entry
+ * shell free of a heavy static import — see `agent.test.ts`'s import guard), so
+ * the guard state has to live somewhere both can reach: the global symbol
+ * registry.
+ */
+export declare const GUARDED_AUTO_UPDATE_SYMBOL: unique symbol;
+/** The IPC payload the daemon sends; `child.send(cancelMessage())`. */
+export declare function cancelMessage(): {
+    type: typeof HARNESS_UPDATE_CANCEL_MSG;
+};
+/**
+ * True while a guarded auto-update pass is mutating this process. Read by
+ * `index.ts`'s SIGINT handler (which reads the same registry symbol directly) to
+ * DEFER its default `process.exit(130)` so a Ctrl+C can't tear a swap apart; the
+ * pass still observes the SIGINT cooperatively and stops at its next boundary.
+ * Ref-counted (a depth, not a boolean) so it is correct even if a pass ever nests.
+ */
+export declare function isGuardedAutoUpdateActive(): boolean;
+/**
+ * Run `run(cancelled)` with cooperative cancellation wired from every source
+ * that can reach this process, and the SIGINT guard held for its duration:
+ *
+ *   - **IPC message** `{ type: HARNESS_UPDATE_CANCEL_MSG }` — the primary,
+ *     cross-platform request the daemon sends. Works on Windows, where a signal
+ *     would force-kill.
+ *   - **`disconnect`** — the IPC channel closed (the daemon went away). Stop
+ *     rather than continue mutating orphaned.
+ *   - **SIGTERM / SIGINT** — a direct `kill`/Ctrl+C on this process. Cooperative,
+ *     not fatal; paired with `index.ts`'s guard, which defers its hard exit while
+ *     {@link isGuardedAutoUpdateActive} holds.
+ *
+ * `cancelled()` never un-sets once set. Listeners are installed for the call's
+ * lifetime only and removed in `finally`, and the process-wide `message`/
+ * `disconnect` listeners are harmless when there is no IPC channel (they simply
+ * never fire), so this is safe on the in-process manual `agents update --auto`
+ * path too.
+ */
+export declare function withGuardedUpdateCancellation<T>(run: (cancelled: () => boolean) => Promise<T>): Promise<T>;

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

@@ -0,0 +1,122 @@
+/**
+ * Cross-platform cooperative cancellation for the harness auto-update pass
+ * (PHNX-3940).
+ *
+ * The pass mutates the filesystem transactionally — stage an npm install into a
+ * sibling dir, launch-probe it, swap it in, record the new release, drop the
+ * rollback material (see `update.ts`). Interrupting it mid-swap can leave an
+ * installation whose directory and its own metadata disagree, with no way back.
+ * So it must be cancellable from OUTSIDE the process — on the daemon's per-tick
+ * deadline, or on daemon shutdown — WITHOUT terminating a process that is mid-swap.
+ *
+ * `execFile`'s `timeout`/`AbortSignal` do exactly the wrong thing here: they
+ * FORCE-terminate the child. On Windows that is unconditional (there are no POSIX
+ * signals to cooperate with — the SIGTERM listener the pass installs never runs),
+ * so a Windows daemon would kill its own update worker mid-rename. Even on POSIX
+ * the forced kill races the swap.
+ *
+ * The fix is a request, not a kill: the daemon spawns the pass as a child over a
+ * Node IPC channel and asks it to stop by SENDING A MESSAGE. The child flips a
+ * flag that `update.ts`'s existing `shouldCancel` reads at each safe boundary
+ * (before the next installation, before staging, and immediately before commit)
+ * and finishes what it is doing cleanly. The channel closing (parent gone) and a
+ * received SIGTERM/SIGINT are treated as the same request, so a force-killed
+ * daemon can never strand a child mutating forever, and a manual `agents update
+ * --auto` interrupted with Ctrl+C also stops at a boundary rather than mid-swap.
+ *
+ * This module is a dependency-free LEAF on purpose: `index.ts` reads the guard
+ * depth below through the shared {@link GUARDED_AUTO_UPDATE_SYMBOL} registry key
+ * (never importing this module, so the slim CLI shell stays slim), and the daemon
+ * child fixture in tests imports {@link withGuardedUpdateCancellation} without
+ * pulling the installations graph.
+ */
+/**
+ * The hidden verb the daemon spawns to run one auto-update pass with IPC-driven
+ * cancellation (dispatched in `index.ts`, handled by
+ * `update-runtime.ts`'s `runHarnessUpdateChild`). Internal protocol — not a
+ * public command.
+ */
+export const HARNESS_UPDATE_CHILD_CMD = '__harness-update-run';
+/** IPC message `type` the daemon sends to request a cooperative stop. */
+export const HARNESS_UPDATE_CANCEL_MSG = 'harness-update:cancel';
+/**
+ * Well-known cross-realm key naming the count of guarded auto-update passes
+ * running IN THIS PROCESS right now. `index.ts`'s top-level SIGINT handler reads
+ * it via `Symbol.for(...)` WITHOUT importing this module (keeping the slim entry
+ * shell free of a heavy static import — see `agent.test.ts`'s import guard), so
+ * the guard state has to live somewhere both can reach: the global symbol
+ * registry.
+ */
+export const GUARDED_AUTO_UPDATE_SYMBOL = Symbol.for('agents.guardedAutoUpdateDepth');
+/** The IPC payload the daemon sends; `child.send(cancelMessage())`. */
+export function cancelMessage() {
+    return { type: HARNESS_UPDATE_CANCEL_MSG };
+}
+function isCancelMessage(msg) {
+    return (typeof msg === 'object' &&
+        msg !== null &&
+        msg.type === HARNESS_UPDATE_CANCEL_MSG);
+}
+/**
+ * True while a guarded auto-update pass is mutating this process. Read by
+ * `index.ts`'s SIGINT handler (which reads the same registry symbol directly) to
+ * DEFER its default `process.exit(130)` so a Ctrl+C can't tear a swap apart; the
+ * pass still observes the SIGINT cooperatively and stops at its next boundary.
+ * Ref-counted (a depth, not a boolean) so it is correct even if a pass ever nests.
+ */
+export function isGuardedAutoUpdateActive() {
+    return (globalThis[GUARDED_AUTO_UPDATE_SYMBOL] ?? 0) > 0;
+}
+function beginGuardedAutoUpdate() {
+    const holder = globalThis;
+    holder[GUARDED_AUTO_UPDATE_SYMBOL] = (holder[GUARDED_AUTO_UPDATE_SYMBOL] ?? 0) + 1;
+}
+function endGuardedAutoUpdate() {
+    const holder = globalThis;
+    const depth = holder[GUARDED_AUTO_UPDATE_SYMBOL] ?? 0;
+    holder[GUARDED_AUTO_UPDATE_SYMBOL] = depth > 0 ? depth - 1 : 0;
+}
+/**
+ * Run `run(cancelled)` with cooperative cancellation wired from every source
+ * that can reach this process, and the SIGINT guard held for its duration:
+ *
+ *   - **IPC message** `{ type: HARNESS_UPDATE_CANCEL_MSG }` — the primary,
+ *     cross-platform request the daemon sends. Works on Windows, where a signal
+ *     would force-kill.
+ *   - **`disconnect`** — the IPC channel closed (the daemon went away). Stop
+ *     rather than continue mutating orphaned.
+ *   - **SIGTERM / SIGINT** — a direct `kill`/Ctrl+C on this process. Cooperative,
+ *     not fatal; paired with `index.ts`'s guard, which defers its hard exit while
+ *     {@link isGuardedAutoUpdateActive} holds.
+ *
+ * `cancelled()` never un-sets once set. Listeners are installed for the call's
+ * lifetime only and removed in `finally`, and the process-wide `message`/
+ * `disconnect` listeners are harmless when there is no IPC channel (they simply
+ * never fire), so this is safe on the in-process manual `agents update --auto`
+ * path too.
+ */
+export async function withGuardedUpdateCancellation(run) {
+    let cancelled = typeof process.send === 'function' && process.connected === false;
+    const requestStop = () => {
+        cancelled = true;
+    };
+    const onMessage = (msg) => {
+        if (isCancelMessage(msg))
+            requestStop();
+    };
+    process.on('SIGTERM', requestStop);
+    process.on('SIGINT', requestStop);
+    process.on('message', onMessage);
+    process.on('disconnect', requestStop);
+    beginGuardedAutoUpdate();
+    try {
+        return await run(() => cancelled);
+    }
+    finally {
+        endGuardedAutoUpdate();
+        process.removeListener('SIGTERM', requestStop);
+        process.removeListener('SIGINT', requestStop);
+        process.removeListener('message', onMessage);
+        process.removeListener('disconnect', requestStop);
+    }
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Settings that gate the AUTOMATIC update pass (PHNX-3940): whether it runs at
+ * all (global + per-harness), and whether one installation participates.
+ *
+ * Two independent axes, deliberately kept apart:
+ *   - `updates.auto` / `updates.<agent>.auto` — an OPERATOR switch, global and
+ *     per-harness, stored centrally (`~/.agents/agents.yaml` `config:`) so it
+ *     syncs fleet-wide like `summarizer.*`. Both are registered as ordinary
+ *     TYPED entries in `device-config.ts`'s `CONFIG_KEYS` — the one canonical
+ *     store for user-scope config — rather than a second untyped read/write
+ *     path against `Meta.config` directly, so a config rewrite that only knows
+ *     about the registry (validation, `agents config list`, the fleet sync
+ *     that round-trips `config:`) can't silently drop these keys.
+ *   - `Installation.updatePolicy` — an INSTALLATION property. Manual
+ *     `agents update <agent>@<label> --to <concrete>` pins it; `--to latest`
+ *     (or a fresh install) leaves/returns it to `'latest'`.
+ *
+ * The global switch is a HARD KILL SWITCH, not a default an explicit
+ * per-harness `true` can override: `updates.auto=false` must stop every
+ * harness's automatic pass even when an operator separately turned one
+ * harness's switch on, because the global switch is the "something is
+ * wrong, stop touching installations fleet-wide" lever and a forgotten
+ * per-harness override must never defeat it. See
+ * {@link isAutoUpdateEnabledForAgent}.
+ */
+import type { AgentId } from '../types.js';
+import type { Installation, UpdatePolicy } from './types.js';
+/** The raw, explicitly-set global switch, or `undefined` when never set (default: on). */
+export declare function rawGlobalAutoUpdateSetting(): boolean | undefined;
+export declare function setGlobalAutoUpdateEnabled(enabled: boolean): void;
+export declare function unsetGlobalAutoUpdateEnabled(): void;
+/** True unless the operator explicitly turned automatic updates off globally. */
+export declare function isGlobalAutoUpdateEnabled(): boolean;
+/** The raw, explicitly-set per-harness switch, or `undefined` when it defers to the global one. */
+export declare function rawAgentAutoUpdateSetting(agent: AgentId): boolean | undefined;
+export declare function setAgentAutoUpdateEnabled(agent: AgentId, enabled: boolean): void;
+export declare function unsetAgentAutoUpdateEnabled(agent: AgentId): void;
+/**
+ * Whether the automatic-update pass may consider this agent at all.
+ *
+ * `updates.auto=false` is a hard kill switch: it wins even over an explicit
+ * `updates.<agent>.auto=true` (see the module docblock). With the global
+ * switch on (the default), the per-harness switch refines it when explicitly
+ * set, else the harness is enabled too.
+ */
+export declare function isAutoUpdateEnabledForAgent(agent: AgentId): boolean;
+/**
+ * The effective policy for one installation. Absent (legacy data, or a fresh
+ * install that never set it) means `'latest'` — see {@link Installation.updatePolicy}.
+ * Read through this everywhere rather than comparing the field directly.
+ */
+export declare function effectiveUpdatePolicy(installation: Pick<Installation, 'updatePolicy'>): UpdatePolicy;
+/**
+ * Persist an installation's update policy. Takes the SAME per-installation
+ * lock `updateInstallation` (`update.ts`) holds for its whole transaction —
+ * without it, a manual `--to <release>`/`--to latest` pin racing an automatic
+ * pass's own `recordRelease` write (both a read-modify-write of the same
+ * `installation.json`) could lose whichever wrote second, silently reverting
+ * a just-applied pin or an update's own release bump. Reloads the record
+ * fresh from disk under the lock (never trusts a possibly-stale in-memory
+ * copy) and writes back only the policy field — never touches
+ * `history`/`releaseVersion`, since pinning or unpinning is not a release
+ * change. Locks with the SAME `staleMs`/`acquireTimeoutMs`
+ * ({@link INSTALLATION_LOCK_OPTIONS}) as that transaction — the fs-atomic
+ * default (5s stale) is far shorter than an update can legitimately run, so
+ * using it here would let this write break the transaction's
+ * still-legitimately-held lock out from under it.
+ */
+export declare function setInstallationUpdatePolicy(agent: AgentId, label: string, policy: UpdatePolicy): Promise<Installation>;

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

@@ -0,0 +1,114 @@
+/**
+ * Settings that gate the AUTOMATIC update pass (PHNX-3940): whether it runs at
+ * all (global + per-harness), and whether one installation participates.
+ *
+ * Two independent axes, deliberately kept apart:
+ *   - `updates.auto` / `updates.<agent>.auto` — an OPERATOR switch, global and
+ *     per-harness, stored centrally (`~/.agents/agents.yaml` `config:`) so it
+ *     syncs fleet-wide like `summarizer.*`. Both are registered as ordinary
+ *     TYPED entries in `device-config.ts`'s `CONFIG_KEYS` — the one canonical
+ *     store for user-scope config — rather than a second untyped read/write
+ *     path against `Meta.config` directly, so a config rewrite that only knows
+ *     about the registry (validation, `agents config list`, the fleet sync
+ *     that round-trips `config:`) can't silently drop these keys.
+ *   - `Installation.updatePolicy` — an INSTALLATION property. Manual
+ *     `agents update <agent>@<label> --to <concrete>` pins it; `--to latest`
+ *     (or a fresh install) leaves/returns it to `'latest'`.
+ *
+ * The global switch is a HARD KILL SWITCH, not a default an explicit
+ * per-harness `true` can override: `updates.auto=false` must stop every
+ * harness's automatic pass even when an operator separately turned one
+ * harness's switch on, because the global switch is the "something is
+ * wrong, stop touching installations fleet-wide" lever and a forgotten
+ * per-harness override must never defeat it. See
+ * {@link isAutoUpdateEnabledForAgent}.
+ */
+import { getConfigValue, setConfigValue, unsetConfigValue } from '../device-config.js';
+import { withFileLockAsync } from '../fs-atomic.js';
+import * as fs from 'node:fs';
+import { ensureInstallationLocked, installationDir, writeInstallation } from './store.js';
+import { installationLockTarget, INSTALLATION_LOCK_OPTIONS } from './installation-lock.js';
+function agentAutoKey(agent) {
+    return `updates.${agent}.auto`;
+}
+/** The raw, explicitly-set global switch, or `undefined` when never set (default: on). */
+export function rawGlobalAutoUpdateSetting() {
+    return getConfigValue('updates.auto').value;
+}
+export function setGlobalAutoUpdateEnabled(enabled) {
+    setConfigValue('updates.auto', enabled);
+}
+export function unsetGlobalAutoUpdateEnabled() {
+    unsetConfigValue('updates.auto');
+}
+/** True unless the operator explicitly turned automatic updates off globally. */
+export function isGlobalAutoUpdateEnabled() {
+    return rawGlobalAutoUpdateSetting() !== false;
+}
+/** The raw, explicitly-set per-harness switch, or `undefined` when it defers to the global one. */
+export function rawAgentAutoUpdateSetting(agent) {
+    return getConfigValue(agentAutoKey(agent)).value;
+}
+export function setAgentAutoUpdateEnabled(agent, enabled) {
+    setConfigValue(agentAutoKey(agent), enabled);
+}
+export function unsetAgentAutoUpdateEnabled(agent) {
+    unsetConfigValue(agentAutoKey(agent));
+}
+/**
+ * Whether the automatic-update pass may consider this agent at all.
+ *
+ * `updates.auto=false` is a hard kill switch: it wins even over an explicit
+ * `updates.<agent>.auto=true` (see the module docblock). With the global
+ * switch on (the default), the per-harness switch refines it when explicitly
+ * set, else the harness is enabled too.
+ */
+export function isAutoUpdateEnabledForAgent(agent) {
+    if (!isGlobalAutoUpdateEnabled())
+        return false;
+    const perAgent = rawAgentAutoUpdateSetting(agent);
+    return perAgent !== false;
+}
+/**
+ * The effective policy for one installation. Absent (legacy data, or a fresh
+ * install that never set it) means `'latest'` — see {@link Installation.updatePolicy}.
+ * Read through this everywhere rather than comparing the field directly.
+ */
+export function effectiveUpdatePolicy(installation) {
+    return installation.updatePolicy ?? 'latest';
+}
+/**
+ * Persist an installation's update policy. Takes the SAME per-installation
+ * lock `updateInstallation` (`update.ts`) holds for its whole transaction —
+ * without it, a manual `--to <release>`/`--to latest` pin racing an automatic
+ * pass's own `recordRelease` write (both a read-modify-write of the same
+ * `installation.json`) could lose whichever wrote second, silently reverting
+ * a just-applied pin or an update's own release bump. Reloads the record
+ * fresh from disk under the lock (never trusts a possibly-stale in-memory
+ * copy) and writes back only the policy field — never touches
+ * `history`/`releaseVersion`, since pinning or unpinning is not a release
+ * change. Locks with the SAME `staleMs`/`acquireTimeoutMs`
+ * ({@link INSTALLATION_LOCK_OPTIONS}) as that transaction — the fs-atomic
+ * default (5s stale) is far shorter than an update can legitimately run, so
+ * using it here would let this write break the transaction's
+ * still-legitimately-held lock out from under it.
+ */
+export async function setInstallationUpdatePolicy(agent, label, policy) {
+    if (!fs.existsSync(installationDir(agent, label)))
+        throw new Error(`No installation directory for ${agent}@${label}.`);
+    // Guarantees `installation.json` exists and is VALID before locking on it,
+    // migrating a legacy pre-frozen version dir when needed — same reasoning as
+    // `launch-gate.ts`'s identical call. Throws its own clear
+    // "no installation directory" error when `label` was never installed at
+    // all, which is a real caller bug, not a race to reconcile under the lock.
+    const recordPath = installationLockTarget(agent, label);
+    return withFileLockAsync(recordPath, () => {
+        const current = ensureInstallationLocked(agent, label);
+        if (!current) {
+            throw new Error(`No installation record for ${agent}@${label} — cannot set its update policy.`);
+        }
+        const next = { ...current, updatePolicy: policy, updatedAt: new Date().toISOString() };
+        writeInstallation(next);
+        return next;
+    }, INSTALLATION_LOCK_OPTIONS);
+}

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

@@ -0,0 +1,118 @@
+/**
+ * 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 {
+    entry: AutoUpdatePlanEntry;
+    outcome?: UpdateOutcome;
+    error?: string;
+}
+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>;