@phnx-labs/agents-cli 1.22.78 → 1.22.79

package/dist/lib/installations/installation-lock.js

@@ -0,0 +1,29 @@
+/**
+ * One lock for install, migration, launch, update, and policy changes.
+ * Keep its target OUTSIDE the installation directory: a fresh install must
+ * acquire exclusion before publishing a directory that readers can migrate.
+ * Every holder agrees on the stale threshold so none breaks a live npm install.
+ */
+import * as path from 'node:path';
+import { ensureLockTarget } from '../fs-atomic.js';
+import { getHistoryDir } from '../state.js';
+import { VERSION_RE } from '../agent-spec/primitives.js';
+import { isAgentId } from '../types.js';
+export function installationLockTarget(agent, label) {
+    if (!isAgentId(agent) || !VERSION_RE.test(label))
+        throw new Error('Invalid managed installation.');
+    // Encode labels so a valid "foo.lock" cannot collide with the lock directory
+    // for "foo". Windows aliases must still contend for the same physical home.
+    const canonicalLabel = process.platform === 'win32' ? label.toLowerCase().replace(/\.+$/, '') : label;
+    const key = Buffer.from(canonicalLabel).toString('hex') || 'empty';
+    const target = path.join(getHistoryDir(), 'installation-locks', agent, key);
+    ensureLockTarget(target, '', 0o700);
+    return target;
+}
+export const INSTALLATION_LOCK_STALE_MS = 10 * 60_000;
+export const INSTALLATION_LOCK_ACQUIRE_TIMEOUT_MS = 5 * 60_000;
+export const INSTALLATION_LOCK_OPTIONS = {
+    staleMs: INSTALLATION_LOCK_STALE_MS,
+    acquireTimeoutMs: INSTALLATION_LOCK_ACQUIRE_TIMEOUT_MS,
+    realpath: false,
+};

package/dist/lib/installations/launch-gate.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The launch side of the launch/update mutual exclusion (PHNX-3940).
+ *
+ * `updateInstallation` (`update.ts`) holds an exclusive lock on
+ * `installationLockTarget(agent, label)` for its ENTIRE stage->verify->
+ * commit->record transaction. This module makes every launch of that same
+ * installation take the SAME lock, briefly, before the real binary starts
+ * running:
+ *
+ *   1. Acquire the lock. If an automatic update of this exact installation is
+ *      currently in flight, this BLOCKS here until it finishes (commits or
+ *      rolls back) — the launch cannot proceed past this point while a swap
+ *      could be underway. This is deliberately not a short, fail-open wait: a
+ *      short timeout that gave up and launched anyway would reintroduce
+ *      exactly the race this exists to close, on the one case where waiting
+ *      actually matters (genuine contention).
+ *   2. While still holding the lock, record a launch lease for the caller's
+ *      pid (`shims.ts`'s `recordLaunchLease`) — so if an update instead starts
+ *      AFTER this launch already has the lock, it will see the lease as soon
+ *      as it acquires the lock itself and defer (`active-check.ts`).
+ *   3. Release the lock. The actual exec/spawn happens immediately after,
+ *      outside the lock — for an exec-replacing native shim (see
+ *      `shims.ts`'s `generateShimScript`/`generateVersionedAliasScript`) that
+ *      gap is a single shell statement; for a Node-spawned launch it is the
+ *      `spawn()` call itself, whose pid is already the one just leased.
+ *
+ * Called from three places, so no launch surface is exempt: the native POSIX
+ * shim and versioned-alias scripts invoke the hidden `agents __launch-lease`
+ * verb (see `index.ts`) right before their final `exec` and FAIL CLOSED (a
+ * non-zero exit refuses the launch) rather than falling through on error —
+ * silently proceeding would mean "the lock was unavailable" and "no update is
+ * running" become indistinguishable to the one check that exists to tell them
+ * apart; `execShimPassthrough` and the main `agents run` spawn path
+ * (`exec.ts`) call {@link withLaunchGate} directly, in-process, wrapping the
+ * `spawn()` call itself.
+ */
+import type { AgentId } from '../types.js';
+/**
+ * Acquire the per-installation update lock, run `fn` while holding it, then
+ * release. Use this to wrap the SPAWN itself (not just the lease write) so an
+ * in-flight update cannot be mid-commit while the new process is starting —
+ * see the module docblock. `fn` should be fast (a spawn call plus a lease
+ * write): this lock is held by every launch of this installation, so slow
+ * work here serializes launches against each other unnecessarily.
+ */
+export declare function withLaunchGate<T>(agent: AgentId, label: string, fn: () => T): Promise<T>;
+/**
+ * Acquire the per-installation update lock, register a launch lease for
+ * `pid`, then release. For a caller that already has its own pid before the
+ * risky operation (the native shim's `$$`, exec-replaced so the pid is
+ * final) — a Node caller that spawns a child should use {@link withLaunchGate}
+ * around the spawn itself instead, since here the process already exists by
+ * the time the lock is acquired.
+ */
+export declare function acquireLaunchGate(agent: AgentId, label: string, pid: number): Promise<() => void>;
+/** Keep a live launcher's lease until its operation ends, without holding the lock. */
+export declare function withInstallationLease<T>(agent: AgentId, label: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Entry point for the hidden `agents __launch-lease <agent> <label> <pid>`
+ * verb the generated native shims call right before their final `exec`. A
+ * non-zero return makes the calling shim `exit 1` instead of proceeding to
+ * exec (see `shims.ts`) — the shim's other pre-launch step (`agents sync
+ * --launch`) is best-effort and swallows failure, but this one exists
+ * specifically to prevent a launch from racing an in-progress update, so a
+ * failure here (most commonly: the lock is genuinely held past
+ * `LAUNCH_GATE_ACQUIRE_TIMEOUT_MS`) must refuse the launch, not silently
+ * allow it. The printed message is what the operator sees.
+ */
+export declare function runLaunchLeaseCli(argv: string[]): Promise<number>;

package/dist/lib/installations/launch-gate.js

@@ -0,0 +1,133 @@
+/**
+ * The launch side of the launch/update mutual exclusion (PHNX-3940).
+ *
+ * `updateInstallation` (`update.ts`) holds an exclusive lock on
+ * `installationLockTarget(agent, label)` for its ENTIRE stage->verify->
+ * commit->record transaction. This module makes every launch of that same
+ * installation take the SAME lock, briefly, before the real binary starts
+ * running:
+ *
+ *   1. Acquire the lock. If an automatic update of this exact installation is
+ *      currently in flight, this BLOCKS here until it finishes (commits or
+ *      rolls back) — the launch cannot proceed past this point while a swap
+ *      could be underway. This is deliberately not a short, fail-open wait: a
+ *      short timeout that gave up and launched anyway would reintroduce
+ *      exactly the race this exists to close, on the one case where waiting
+ *      actually matters (genuine contention).
+ *   2. While still holding the lock, record a launch lease for the caller's
+ *      pid (`shims.ts`'s `recordLaunchLease`) — so if an update instead starts
+ *      AFTER this launch already has the lock, it will see the lease as soon
+ *      as it acquires the lock itself and defer (`active-check.ts`).
+ *   3. Release the lock. The actual exec/spawn happens immediately after,
+ *      outside the lock — for an exec-replacing native shim (see
+ *      `shims.ts`'s `generateShimScript`/`generateVersionedAliasScript`) that
+ *      gap is a single shell statement; for a Node-spawned launch it is the
+ *      `spawn()` call itself, whose pid is already the one just leased.
+ *
+ * Called from three places, so no launch surface is exempt: the native POSIX
+ * shim and versioned-alias scripts invoke the hidden `agents __launch-lease`
+ * verb (see `index.ts`) right before their final `exec` and FAIL CLOSED (a
+ * non-zero exit refuses the launch) rather than falling through on error —
+ * silently proceeding would mean "the lock was unavailable" and "no update is
+ * running" become indistinguishable to the one check that exists to tell them
+ * apart; `execShimPassthrough` and the main `agents run` spawn path
+ * (`exec.ts`) call {@link withLaunchGate} directly, in-process, wrapping the
+ * `spawn()` call itself.
+ */
+import { withFileLockAsync } from '../fs-atomic.js';
+import * as fs from 'node:fs';
+import { ensureInstallationLocked, installationDir } from './store.js';
+import { recordLaunchLease } from './shims.js';
+import { AGENTS } from '../agents.js';
+import { VERSION_RE } from '../agent-spec/primitives.js';
+import { installationLockTarget, INSTALLATION_LOCK_OPTIONS } from './installation-lock.js';
+/**
+ * Matches `update.ts`'s `UPDATE_LOCK_STALE_MS` — the same lock, so a stale
+ * threshold that doesn't match would let one side break a lock the other
+ * legitimately still holds mid-transaction.
+ */
+/**
+ * How long a launch will wait for an in-flight update of the SAME
+ * installation to finish. Bounded by the real worst case an update should
+ * ever take (a 120s npm install plus two launch probes), not a hot-path
+ * budget — see the module docblock for why this must not be a short,
+ * fail-open timeout.
+ */
+const LAUNCH_GATE_ACQUIRE_TIMEOUT_MS = 3 * 60_000;
+/**
+ * Acquire the per-installation update lock, run `fn` while holding it, then
+ * release. Use this to wrap the SPAWN itself (not just the lease write) so an
+ * in-flight update cannot be mid-commit while the new process is starting —
+ * see the module docblock. `fn` should be fast (a spawn call plus a lease
+ * write): this lock is held by every launch of this installation, so slow
+ * work here serializes launches against each other unnecessarily.
+ */
+export async function withLaunchGate(agent, label, fn) {
+    if (!Object.hasOwn(AGENTS, agent) || !VERSION_RE.test(label))
+        throw new Error('Invalid managed installation.');
+    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, exactly like every
+    // other reader (`listInstallations`). Seeding an EMPTY file as a bare lock
+    // target (the earlier version of this code) would make a subsequent
+    // `readInstallation` see "corrupted, not valid JSON" instead of running that
+    // migration, permanently wedging a legacy installation the first time
+    // anything launched it.
+    const recordPath = installationLockTarget(agent, label);
+    return withFileLockAsync(recordPath, () => {
+        ensureInstallationLocked(agent, label);
+        return fn();
+    }, {
+        ...INSTALLATION_LOCK_OPTIONS,
+        acquireTimeoutMs: LAUNCH_GATE_ACQUIRE_TIMEOUT_MS,
+    });
+}
+/**
+ * Acquire the per-installation update lock, register a launch lease for
+ * `pid`, then release. For a caller that already has its own pid before the
+ * risky operation (the native shim's `$$`, exec-replaced so the pid is
+ * final) — a Node caller that spawns a child should use {@link withLaunchGate}
+ * around the spawn itself instead, since here the process already exists by
+ * the time the lock is acquired.
+ */
+export async function acquireLaunchGate(agent, label, pid) {
+    return withLaunchGate(agent, label, () => recordLaunchLease(agent, label, pid));
+}
+/** Keep a live launcher's lease until its operation ends, without holding the lock. */
+export async function withInstallationLease(agent, label, fn) {
+    const release = await acquireLaunchGate(agent, label, process.pid);
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Entry point for the hidden `agents __launch-lease <agent> <label> <pid>`
+ * verb the generated native shims call right before their final `exec`. A
+ * non-zero return makes the calling shim `exit 1` instead of proceeding to
+ * exec (see `shims.ts`) — the shim's other pre-launch step (`agents sync
+ * --launch`) is best-effort and swallows failure, but this one exists
+ * specifically to prevent a launch from racing an in-progress update, so a
+ * failure here (most commonly: the lock is genuinely held past
+ * `LAUNCH_GATE_ACQUIRE_TIMEOUT_MS`) must refuse the launch, not silently
+ * allow it. The printed message is what the operator sees.
+ */
+export async function runLaunchLeaseCli(argv) {
+    const [agentRaw, label, pidRaw] = argv;
+    const pid = Number(pidRaw);
+    if (!agentRaw || !label || !Number.isInteger(pid) || pid <= 0) {
+        process.stderr.write('usage: agents __launch-lease <agent> <label> <pid>\n');
+        return 2;
+    }
+    try {
+        await acquireLaunchGate(agentRaw, label, pid);
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`agents __launch-lease: ${err.message}\n`);
+        return 1;
+    }
+}

package/dist/lib/installations/native-command.d.ts

@@ -0,0 +1,5 @@
+import type { AgentId } from '../types.js';
+/** Run a finite native login/logout command in an already-selected home. */
+export declare function runNativeAccountCommand(agent: AgentId, label: string, args: string[], env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<{
+    code: number | null;
+}>;

package/dist/lib/installations/native-command.js

@@ -0,0 +1,52 @@
+import * as fs from 'node:fs';
+import { execFile, spawn } from 'node:child_process';
+import { composeWin32CommandLine } from '../platform/index.js';
+import { getBinaryPath } from './store.js';
+import { withInstallationLease } from './launch-gate.js';
+/** Run a finite native login/logout command in an already-selected home. */
+export async function runNativeAccountCommand(agent, label, args, env, signal) {
+    return withInstallationLease(agent, label, () => new Promise((resolve, reject) => {
+        signal?.throwIfAborted();
+        let binary = getBinaryPath(agent, label);
+        if (process.platform === 'win32' && fs.existsSync(`${binary}.cmd`))
+            binary += '.cmd';
+        const shell = process.platform === 'win32' && binary.endsWith('.cmd');
+        const child = spawn(shell ? composeWin32CommandLine(binary, args) : binary, shell ? [] : args, {
+            env, stdio: 'inherit', shell,
+        });
+        let failure;
+        let termination;
+        const abort = () => {
+            failure = signal?.reason instanceof Error ? signal.reason : new Error('Authentication was cancelled.');
+            // A Windows .cmd wrapper is a process tree: killing only cmd.exe leaves
+            // the native login alive. Scope termination to this child that we own.
+            if (process.platform === 'win32' && child.pid) {
+                termination = new Promise((done) => {
+                    execFile('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true }, (error) => {
+                        if (error)
+                            failure = new Error(`Could not stop the native authentication process tree: ${error.message}`);
+                        done();
+                    });
+                });
+            }
+            else {
+                child.kill('SIGTERM');
+            }
+        };
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        // An AbortError is not completion: keep the installation lease until the
+        // native process has actually closed.
+        child.once('error', (error) => { failure = error; });
+        child.once('close', async (code) => {
+            signal?.removeEventListener('abort', abort);
+            // cmd.exe closing is not proof that its native descendants are gone.
+            await termination;
+            if (failure)
+                reject(failure);
+            else
+                resolve({ code });
+        });
+    }));
+}

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

@@ -1,6 +1,10 @@
 import type { AgentId } from '../types.js';
 import { getShimsDir } from '../state.js';
 export { getShimsDir };
+/** Record that `pid` is about to execute this installation's binary. Call right before handing off to it. */
+export declare function recordLaunchLease(agent: AgentId, label: string, pid: number): () => void;
+/** Read-only: stale leases cannot defer an update, and preview never deletes files. */
+export declare function hasLiveLaunchLease(agent: AgentId, label: string): boolean;
 export type ConflictStrategy = 'keep-dest' | 'overwrite' | 'ask-per-file';
 export interface ConflictInfo {
     agent: AgentId;
@@ -60,7 +64,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 30;
+export declare const SHIM_SCHEMA_VERSION = 31;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -175,7 +179,7 @@ export declare function removeShim(agent: AgentId): boolean;
  *        sorted alphabetically before the real self-updated grok binary and
  *        was silently launched instead.
  */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 18;
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 19;
 /**
  * Agents whose config directory can be relocated by an environment variable
  * (the per-agent `managedEnv` block in `generateVersionedAliasScript` below).
@@ -348,6 +352,8 @@ export declare function listShimFileNames(): string[];
 export declare function pruneOrphanedCommandShim(fileName: string): boolean;
 /** Regenerate the shim if missing or older than the current schema; never downgrade a newer on-disk shim. */
 export declare function ensureShimCurrent(agent: AgentId): 'created' | 'updated' | 'current';
+/** Refresh only existing generated launchers before unattended binary changes. */
+export declare function refreshOwnedLaunchers(agent: AgentId, label: string): void;
 /** Get the logical (extensionless) shim path for an agent. */
 export declare function getShimPath(agent: AgentId): string;
 /** Return the first executable on PATH that would shadow the managed shim, excluding the shim itself and legacy pre-split files. */

package/dist/lib/installations/shims.js

@@ -12,6 +12,9 @@ export { getShimsDir };
 import { AGENTS, agentConfigDirName, readAuthAccountIdentity } from '../agents.js';
 import { codexHomeShimBash } from '../codex-home.js';
 import { resolveHarnessAdapter } from '../harness/index.js';
+import { randomUUID } from 'node:crypto';
+import { captureProcessStartTime } from '../platform/process.js';
+import { atomicWriteFileSync } from '../fs-atomic.js';
 /** Files and directories to always skip during conflict detection and migration. */
 const MIGRATION_IGNORE_LIST = new Set([
     'node_modules',
@@ -31,6 +34,62 @@ function shouldIgnore(name) {
         return true;
     return false;
 }
+// Launch leases are written under the shared launch/update gate BEFORE exec or
+// spawn. A live launcher protects the gap until its child appears in ps; an
+// exec-replacing shim keeps the same PID. A birth fingerprint defeats PID reuse.
+function launchLeaseDir(agent, label) {
+    return path.join(getVersionsDir(), agent, label, '.launch-leases');
+}
+/** Record that `pid` is about to execute this installation's binary. Call right before handing off to it. */
+export function recordLaunchLease(agent, label, pid) {
+    const dir = launchLeaseDir(agent, label);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `${pid}-${randomUUID()}.json`);
+    atomicWriteFileSync(file, JSON.stringify({ pid, birth: captureProcessStartTime(pid, { fresh: true }) }));
+    return () => { try {
+        fs.unlinkSync(file);
+    }
+    catch { /* dead leases are also ignored by readers */ } };
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== 'ESRCH';
+    }
+}
+/** Read-only: stale leases cannot defer an update, and preview never deletes files. */
+export function hasLiveLaunchLease(agent, label) {
+    const dir = launchLeaseDir(agent, label);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch (err) {
+        return err.code !== 'ENOENT';
+    }
+    let live = false;
+    for (const entry of entries) {
+        const match = entry.match(/^(\d+)(?:-[a-f0-9-]+)?\.json$/);
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        if (!pidAlive(pid))
+            continue;
+        try {
+            const lease = JSON.parse(fs.readFileSync(path.join(dir, entry), 'utf8'));
+            const birth = captureProcessStartTime(pid, { fresh: true });
+            if (!lease.birth || !birth || lease.birth === birth)
+                live = true;
+        }
+        catch {
+            live = true;
+        } // Unknown state is busy, never permission to swap.
+    }
+    return live;
+}
 /** Detect filenames that exist in both `src` and `dest`, excluding symlinks in `dest`. */
 function detectConflicts(src, dest, prefix = '') {
     const conflicts = [];
@@ -207,7 +266,7 @@ async function promptConflictStrategy(conflictInfos) {
 //        grok-0.2.118-* file — a 99-byte wrapper that exec'd cursor-agent —
 //        sorted alphabetically before the real self-updated grok binary and
 //        was silently launched instead.
-export const SHIM_SCHEMA_VERSION = 30;
+export const SHIM_SCHEMA_VERSION = 31;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -699,6 +758,23 @@ if [ "\$LAUNCH_SKIP" = "0" ]; then
   "\$AGENTS_BIN" sync --agent "\$AGENT" --agent-version "\$VERSION" --launch --cwd "\$PWD" --quiet 2>/dev/null || true
 fi
 
+# Register a launch lease for THIS pid before the exec below replaces this
+# process image (PHNX-3940) — \$\$ survives exec, so the lease's pid matches
+# the real running binary. Takes the SAME per-installation lock the automatic
+# background update uses for its whole stage->commit transaction, so this
+# call blocks here (never past the exec below) for as long as an update of
+# this exact installation is actively in flight, and otherwise returns almost
+# immediately. Unlike the sync call above, this is NOT best-effort: silently
+# falling through on failure (a lock the updater is genuinely still holding,
+# or any other error) would let this process exec straight into a binary an
+# update could be mid-swap on — exactly the race this exists to close. Fail
+# closed instead.
+if ! "\$AGENTS_BIN" __launch-lease "\$AGENT" "\$VERSION" "\$\$"; then
+  echo "agents: could not safely coordinate this launch with a possibly in-progress update of \$AGENT@\$VERSION." >&2
+  echo "  Check: agents update \$AGENT@\$VERSION --check    Retry once any update finishes." >&2
+  exit 1
+fi
+
 ${resolveHarnessAdapter(agent).shimExecTail?.(launchArgs) ?? `exec "$BINARY"${launchArgs} "$@"`}
 `;
 }
@@ -1018,7 +1094,7 @@ export function removeShim(agent) {
 // v18 — Cursor aliases select the file credential store and swap HOME to the
 //       version home because current Cursor writes auth.json under ~/.cursor
 //       and ignores XDG_CONFIG_HOME for credential storage.
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 18;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 19;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -1061,6 +1137,7 @@ export function supportsIsolatedInstall(agent) {
 export function generateVersionedAliasScript(agent, version) {
     assertSafeVersion(version);
     const agentConfig = AGENTS[agent];
+    const agentsBin = shellQuote(getAgentsBinForGeneratedShim());
     // Same derivation as `generateShimScript` so nested layouts (e.g.,
     // Antigravity's `~/.gemini/antigravity-cli`) land in the right place.
     const configDirName = path.relative(os.homedir(), agentConfig.configDir);
@@ -1209,6 +1286,15 @@ if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
 fi
 ${managedEnv}
 
+# Register a launch lease for THIS pid before the exec below (PHNX-3940) — see
+# generateShimScript's identical call for what this closes and why it fails
+# closed rather than falling through on error. \$\$ survives exec.
+if ! ${agentsBin} __launch-lease "${agent}" "${version}" "\$\$"; then
+  echo "agents: could not safely coordinate this launch with a possibly in-progress update of ${agent}@${version}." >&2
+  echo "  Check: agents update ${agent}@${version} --check    Retry once any update finishes." >&2
+  exit 1
+fi
+
 ${resolveHarnessAdapter(agent).shimExecTail?.(launchArgs) ?? `exec "$BINARY"${launchArgs} "$@"`}
 `;
 }
@@ -2061,6 +2147,23 @@ export function ensureShimCurrent(agent) {
     }
     return 'current';
 }
+/** Refresh only existing generated launchers before unattended binary changes. */
+export function refreshOwnedLaunchers(agent, label) {
+    const owned = (file) => {
+        try {
+            return fs.readFileSync(file, 'utf8').includes('Auto-generated by agents-cli - do not edit');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return false;
+            throw err;
+        }
+    };
+    if (owned(onDiskShimPath(agent)))
+        ensureShimCurrent(agent);
+    if (owned(versionedAliasOnDiskPath(agent, label)))
+        ensureVersionedAliasCurrent(agent, label);
+}
 /** Get the logical (extensionless) shim path for an agent. */
 export function getShimPath(agent) {
     const shimsDir = getShimsDir();

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;