@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/installations/strategies.js

@@ -10,32 +10,15 @@ import { getBinaryPath, getLatestNpmVersion, getOldestNpmVersion, getLiveVersion
 import { installationDir } from './store.js';
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
-/** npm install timeout, matching the install path's own installer budget. */
 const INSTALL_TIMEOUT_MS = 120_000;
 function runId() {
     return `${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
 }
 function moveDir(from, to) {
     fs.mkdirSync(path.dirname(to), { recursive: true });
-    // 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
- * is included deliberately — leaving the previous release's `package-lock.json`
- * beside the new `node_modules` would make the directory describe a release it no
- * longer contains, and the next repair reinstall would resolve from that stale lock.
- * Entries absent on either side are skipped, so a dir without a lockfile is fine.
- */
 const NPM_LIVE_ENTRIES = ['node_modules', 'package.json', 'package-lock.json'];
-/**
- * npm-packaged harnesses (claude, codex, kimi, opencode, …). The only fully
- * transactional class: a pinned release can be fetched into a sibling directory,
- * probed there, and swapped in, with the displaced tree kept until the swap is
- * proven — so a failed update leaves the previous release running.
- */
 const npmPackageStrategy = {
     id: 'npm-package',
     transactional: true,
@@ -60,10 +43,6 @@ const npmPackageStrategy = {
         fs.writeFileSync(path.join(stagingDir, 'package.json'), JSON.stringify({ name: `agents-${ctx.agent}-${target}`, version: '1.0.0', private: true }, null, 2));
         const winShell = process.platform === 'win32';
         ctx.onProgress?.(`Staging ${pkg}@${target}...`);
-        // `--ignore-scripts` for the dependency tree; the first-party package's own
-        // postinstall is re-run below, exactly as the install path does — several
-        // harnesses ship their native binary via that script and are unlaunchable
-        // without it.
         await execFileAsync('npm', ['install', `${pkg}@${target}`, '--ignore-scripts'], {
             cwd: stagingDir,
             shell: winShell,
@@ -79,7 +58,6 @@ const npmPackageStrategy = {
             }
         }
         catch {
-            /* non-fatal: the launch probe in update.ts is the real gate */
         }
         return {
             release: target,
@@ -93,8 +71,6 @@ const npmPackageStrategy = {
         const rollbackDir = path.join(dir, `.rollback-${runId()}`);
         const displaced = [];
         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()) {
@@ -118,13 +94,6 @@ const npmPackageStrategy = {
             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))
@@ -151,26 +120,15 @@ const npmPackageStrategy = {
         };
     },
 };
-/**
- * Harnesses that are ONE global self-updating binary (droid, muse, warp): every
- * installation of the agent points at the same file, so there is nothing
- * per-installation to stage or swap, and updating one necessarily updates all.
- * The honest model is therefore: run the official installer, probe the live
- * binary, and record the new release on every installation that shares it.
- */
 const globalBinaryStrategy = {
     id: 'global-binary',
     transactional: false,
     sharedBinary: true,
     async resolveTarget(ctx) {
-        // The installer for these carries no version token, so a requested release
-        // cannot be honoured. Fail loud rather than install something else and
-        // report it as the pin the user asked for.
         if (ctx.requested !== 'latest') {
             throw new Error(`${AGENTS[ctx.agent].name} is a single self-updating binary with no pinnable releases — `
                 + `it can only be updated to the current one. Re-run: agents update ${ctx.agent}@${ctx.installation.label} --to latest`);
         }
-        // Resolved after the installer runs — `latest` here is whatever it fetches.
         return 'latest';
     },
     async stage(ctx) {
@@ -190,19 +148,9 @@ const globalBinaryStrategy = {
         };
     },
     async commit() {
-        // The installer already replaced the shared binary; there is no per-install
-        // swap to perform and no previous copy to restore.
         return { undo: () => { }, finalize: () => { } };
     },
 };
-/**
- * Harnesses installed by an official script that keeps a per-installation copy
- * or symlink farm (grok, cursor, antigravity, hermes, goose, …). The
- * vendor artifact lands in a global location the installer owns, so the fetch
- * itself is not reversible; what IS per-installation — the version dir's binary
- * link farm — is staged and swapped so a failed re-import cannot strand the
- * installation without a launch target.
- */
 const installScriptStrategy = {
     id: 'install-script',
     transactional: false,
@@ -221,16 +169,10 @@ const installScriptStrategy = {
         ctx.onProgress?.(`Updating ${config.name} via official installer...`);
         await execAsync(script, { timeout: INSTALL_TIMEOUT_MS });
         invalidateLiveVersionCache(ctx.agent);
-        // findInPath skips our own shims dir, so this is the genuine vendor binary
-        // and never our dispatcher (which would produce a self-execing link farm).
         const installed = findInPath(config.cliCommand);
         if (!installed) {
             throw new Error(`${config.name} installer finished but ${config.cliCommand} is not on PATH — the install did not complete.`);
         }
-        // On Windows there is no `.cmd` wrapper beside an imported install-script
-        // binary, so the staged launch probe cannot run and reports healthy. The
-        // gate is therefore weaker here than on POSIX; the unconditional undo in
-        // update.ts is what keeps a bad swap recoverable.
         const release = target === 'latest'
             ? (await getLiveVersion(ctx.agent)) ?? target
             : target;
@@ -239,8 +181,6 @@ const installScriptStrategy = {
         fs.mkdirSync(stagingDir, { recursive: true });
         const imported = importInstallScriptBinary({ agentId: ctx.agent, npmPackage: config.npmPackage, cliCommand: config.cliCommand }, ctx.installation.label, installed, stagingDir);
         if (!imported.success) {
-            // Swallowing this reported the launch probe's generic "binary not found"
-            // instead of the real reason the import failed.
             throw new Error(`${config.name} ${release} was installed but could not be linked into the version directory: ${imported.error ?? 'unknown error'}`);
         }
         return {
@@ -252,15 +192,6 @@ const installScriptStrategy = {
     },
     commit: npmPackageStrategy.commit,
 };
-/**
- * Pick the update strategy for an agent from the registry's declared shape.
- *
- * The ordering mirrors `installVersion`: an npm package wins whenever one is
- * declared (kimi declares both a package and a script, and its package is what
- * `agents add` installs), then a single shared global binary, then a per-install
- * script. Anything else is an integration boundary we do not handle — it throws
- * rather than silently no-opping and reporting success.
- */
 export function selectUpdateStrategy(agent) {
     const config = AGENTS[agent];
     if (config.npmPackage)
@@ -269,11 +200,6 @@ export function selectUpdateStrategy(agent) {
         return globalBinaryStrategy;
     if (config.installScript) {
         if (!usesVersionDirLinkFarm(agent)) {
-            // The install path resolves this harness's binary somewhere the version
-            // dir's link farm does not describe (grok keeps a real per-release copy
-            // under its version home). Staging and swapping the link farm would leave
-            // the launch target untouched, so the update would record a release that
-            // is not actually installed. Refuse instead of reporting a false success.
             throw new Error(`${config.name} keeps its binary outside the managed version directory, so agents-cli cannot yet update an `
                 + `installation in place. Install the current release as a new installation: agents add ${agent}@latest`);
         }
@@ -282,30 +208,17 @@ export function selectUpdateStrategy(agent) {
     throw new Error(`${config.name} is not installed by agents-cli (it declares no npm package and no installer), so there is nothing to update. `
         + `Update it with its own tooling.`);
 }
-/**
- * Does this harness's launch target live in the version dir's own
- * `node_modules/.bin` link farm — the thing an installation can stage and swap?
- *
- * Probed through `getBinaryPath`, the single resolver the shims and `agents run`
- * use, rather than tested against an agent id, so a harness that resolves its
- * binary elsewhere is recognised without being enumerated here.
- */
 function usesVersionDirLinkFarm(agent) {
     const probe = '0.0.0-probe';
     const expected = path.join(installationDir(agent, probe), 'node_modules', '.bin', AGENTS[agent].cliCommand);
     return getBinaryPath(agent, probe) === expected;
 }
-/**
- * Whether a concrete release can be requested for this agent at all. False for
- * every self-updating harness — their installers carry no version token.
- */
 export function supportsPinnedUpdate(agent) {
     const config = AGENTS[agent];
     if (config.npmPackage)
         return true;
     return !isSelfUpdatingAgent(agent);
 }
-/** Guard a user-supplied release token before it reaches a path or a package spec. */
 export function assertValidRelease(requested) {
     if (!VERSION_RE.test(requested)) {
         throw new Error(`Invalid release: ${JSON.stringify(requested)}`);

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

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

package/dist/lib/installations/types.js

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

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

@@ -1,82 +1,8 @@
-/**
- * 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

@@ -1,54 +1,6 @@
-/**
- * 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 };
 }
@@ -57,13 +9,6 @@ function isCancelMessage(msg) {
         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;
 }
@@ -76,25 +21,6 @@ function endGuardedAutoUpdate() {
     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 = () => {

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

@@ -1,69 +1,12 @@
-/**
- * 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

@@ -1,28 +1,3 @@
-/**
- * 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';
@@ -31,7 +6,6 @@ import { installationLockTarget, INSTALLATION_LOCK_OPTIONS } from './installatio
 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;
 }
@@ -41,11 +15,9 @@ export function setGlobalAutoUpdateEnabled(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;
 }
@@ -55,52 +27,18 @@ export function setAgentAutoUpdateEnabled(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);