@phnx-labs/agents-cli 1.22.77 → 1.22.79

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

@@ -25,6 +25,8 @@ export declare function mintInstallationId(): string;
  * Never mints — use {@link ensureInstallation} for the migrating read.
  */
 export declare function readInstallation(agent: AgentId, label: string): Installation | null;
+/** Semantic feature checks use the release, while paths and settings keep the label. */
+export declare function installedReleaseFor(agent: AgentId, label: string): string;
 export declare function writeInstallation(installation: Installation): void;
 /**
  * Read the record for an existing version dir, minting and persisting one on
@@ -37,12 +39,14 @@ export declare function writeInstallation(installation: Installation): void;
  * describe an install that isn't there.
  */
 export declare function ensureInstallation(agent: AgentId, label: string): Installation;
+/** Migration for callers already holding the canonical installation lock. */
+export declare function ensureInstallationLocked(agent: AgentId, label: string, legacyCreatedAt?: string): Installation;
 /**
  * Create the record for a freshly-installed version dir. Idempotent: a repeat
  * `agents add` of the same label keeps the original id (identity is frozen) and
  * only records the release if it actually moved.
  */
-export declare function createInstallation(agent: AgentId, label: string, releaseVersion: string): Installation;
+export declare function createInstallation(agent: AgentId, label: string, releaseVersion: string, initialPolicy?: Installation['updatePolicy']): Installation;
 /**
  * Move an installation's recorded release forward, preserving identity. Returns
  * the persisted record. Call only AFTER the new release is live on disk — the

package/dist/lib/installations/store.js

@@ -4,7 +4,8 @@ import * as path from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as yaml from 'yaml';
-import { atomicWriteFileSync } from '../fs-atomic.js';
+import { atomicWriteFileSync, withFileLock } from '../fs-atomic.js';
+import { installationLockTarget, INSTALLATION_LOCK_OPTIONS } from './installation-lock.js';
 import { getHomeDir, getUserAgentsDir, getVersionsDir, readMeta } from '../state.js';
 import { VERSION_RE, compareVersions } from '../agent-spec/primitives.js';
 import { AGENTS, findInPath } from '../agents.js';
@@ -60,6 +61,9 @@ function assertValidRecord(value, file) {
     if (!Array.isArray(record.history) || record.history.length === 0) {
         throw new Error(`Installation record corrupted at ${file}: "history" must be a non-empty array.`);
     }
+    if (record.updatePolicy !== undefined && record.updatePolicy !== 'latest' && record.updatePolicy !== 'pinned') {
+        throw new Error(`Installation record corrupted at ${file}: unknown update policy.`);
+    }
     return record;
 }
 /**
@@ -84,6 +88,12 @@ export function readInstallation(agent, label) {
     }
     return assertValidRecord(parsed, file);
 }
+/** Semantic feature checks use the release, while paths and settings keep the label. */
+export function installedReleaseFor(agent, label) {
+    if (!Object.hasOwn(AGENTS, agent) || !VERSION_RE.test(label))
+        return label;
+    return readInstallation(agent, label)?.releaseVersion ?? label;
+}
 export function writeInstallation(installation) {
     const file = installationRecordPath(installation.agent, installation.label);
     fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -100,6 +110,16 @@ export function writeInstallation(installation) {
  * describe an install that isn't there.
  */
 export function ensureInstallation(agent, label) {
+    const existing = readInstallation(agent, label);
+    if (existing)
+        return existing;
+    if (!fs.existsSync(installationDir(agent, label)))
+        throw new Error(`No installation directory for ${agent}@${label}.`);
+    const createdAt = fs.statSync(installationDir(agent, label)).mtime.toISOString();
+    return withFileLock(installationLockTarget(agent, label), () => ensureInstallationLocked(agent, label, createdAt), { ...INSTALLATION_LOCK_OPTIONS, acquireTimeoutMs: 0 });
+}
+/** Migration for callers already holding the canonical installation lock. */
+export function ensureInstallationLocked(agent, label, legacyCreatedAt) {
     const existing = readInstallation(agent, label);
     if (existing)
         return existing;
@@ -109,7 +129,7 @@ export function ensureInstallation(agent, label) {
     }
     let createdAt;
     try {
-        createdAt = fs.statSync(dir).mtime.toISOString();
+        createdAt = legacyCreatedAt ?? fs.statSync(dir).mtime.toISOString();
     }
     catch {
         createdAt = nowIso();
@@ -132,7 +152,7 @@ export function ensureInstallation(agent, label) {
  * `agents add` of the same label keeps the original id (identity is frozen) and
  * only records the release if it actually moved.
  */
-export function createInstallation(agent, label, releaseVersion) {
+export function createInstallation(agent, label, releaseVersion, initialPolicy = 'latest') {
     if (!VERSION_RE.test(label)) {
         throw new Error(`Invalid installation label: ${JSON.stringify(label)}`);
     }
@@ -152,6 +172,7 @@ export function createInstallation(agent, label, releaseVersion) {
         createdAt: at,
         updatedAt: at,
         history: [{ releaseVersion, at }],
+        updatePolicy: initialPolicy,
     };
     writeInstallation(created);
     return created;

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);
+}