@phnx-labs/agents-cli 1.22.78 → 1.22.79

package/dist/lib/daemon/harness-update-service.js

@@ -0,0 +1,216 @@
+/**
+ * Daemon harness-update service (PHNX-3940).
+ *
+ * Runs the automatic-update pass (`installations/update-runtime.ts`) on a
+ * schedule so a managed, transactional npm harness (Claude, Codex, …) stays
+ * current with no operator action, subject to the `updates.auto` /
+ * `updates.<agent>.auto` switches and each installation's own update policy.
+ *
+ * The pass itself does real, synchronous filesystem work per installation —
+ * staging an npm install into a sibling directory, `fs.renameSync`/`fs.cpSync`
+ * swaps, `fs.rmSync` cleanup — potentially across several installations in one
+ * tick. Running that inline on the daemon's own event loop would stall every
+ * other service (secrets broker, browser IPC, the scheduler) for the
+ * duration, the same class of problem `self-update-service.ts` solves for the
+ * CLI's OWN upgrade by installing into a fresh process it then exits into.
+ * Here there is no "exit and let the supervisor restart" option (the daemon
+ * itself isn't what's being updated), so instead this tick SPAWNS a bounded
+ * child (`agents __harness-update-run`) over a Node IPC channel and only waits
+ * on that child — every sync fs call happens in the child's own event loop /
+ * thread pool, never this one.
+ *
+ * Cancellation is COOPERATIVE and cross-platform (PHNX-3940). On the tick's
+ * deadline or daemon shutdown — both delivered as the supervisor aborting the
+ * tick's `AbortSignal` — the daemon does NOT force-kill the child (execFile's
+ * `timeout`/`signal` would, unconditionally on Windows, mid-swap). It SENDS the
+ * child an IPC cancel message; the child stops at its next safe boundary (see
+ * `installations/update-cancellation.ts` + `update.ts`'s `shouldCancel`) and
+ * exits on its own, and the daemon waits for that TRUE exit. A wedged child that
+ * ignores the request past a generous grace — never the normal path, since the
+ * child's own npm/probe work is bounded — is force-reaped only as an
+ * orphan-prevention backstop, and that abnormal case is reported as a failure,
+ * never as a clean pass.
+ */
+import { spawn } from 'child_process';
+import { BasePeriodicService } from './service.js';
+import { getCliLaunch, getAgentsBinPath } from '../cli-entry.js';
+import { HARNESS_UPDATE_CHILD_CMD, cancelMessage } from '../installations/update-cancellation.js';
+/** Runs every 15 minutes — a design decision, not an externally-fixed cadence (PHNX-3940). */
+const HARNESS_UPDATE_TICK_MS = 15 * 60_000;
+/**
+ * Cancellation deadline per tick. A real pass can touch several installations, each an npm
+ * install (`INSTALL_TIMEOUT_MS` = 120s in strategies.ts) plus two launch
+ * probes; 10 minutes leaves headroom for a handful of harnesses in one pass
+ * while staying comfortably under the 15-minute cadence above.
+ */
+export const HARNESS_UPDATE_DEADLINE_MS = 10 * 60_000;
+/** First tick fires 60 seconds after daemon boot — long enough for shims/PATH to settle, short enough that a fresh box doesn't wait a full interval for its first check. */
+const HARNESS_UPDATE_STARTUP_DELAY_MS = 60_000;
+/**
+ * How long to wait for the child to exit AFTER a cooperative cancel before
+ * force-reaping it as an orphan backstop. The child's own work is bounded — one
+ * npm install (`INSTALL_TIMEOUT_MS` = 120s in strategies.ts) plus two launch
+ * probes, then a fast synchronous swap — so a healthy child stops well within
+ * this window. A slow staging/postinstall can also exhaust it, but a delivered
+ * cancel prevents that stage from committing. The backstop kills the process
+ * group on POSIX and the worker on Windows; the tick reports a failure.
+ */
+export const HARNESS_UPDATE_CANCEL_GRACE_MS = 3 * 60_000;
+export function defaultHarnessUpdateDeps() {
+    return {
+        runAutoUpdatePass(signal) {
+            const { command, args } = getCliLaunch([HARNESS_UPDATE_CHILD_CMD], getAgentsBinPath());
+            return driveCooperativeChild(command, args, signal, HARNESS_UPDATE_CANCEL_GRACE_MS);
+        },
+    };
+}
+/**
+ * Spawn `command args` as a child over a Node IPC channel and drive it to a TRUE
+ * completion, requesting a cooperative stop (never a kill) when `signal` aborts —
+ * the supervisor aborts it on the tick's deadline OR on daemon shutdown.
+ *
+ * Resolves with the child's real exit code and captured output. Rejects only on:
+ *   - a spawn failure (missing binary) — a genuine service failure; and
+ *   - the child having to be force-reaped past the grace window, or dying to an
+ *     external signal — never a clean pass, so the tick logs it as ERROR instead
+ *     of reading a killed process as a completed update.
+ *
+ * A non-zero exit with no kill is resolved (not rejected): the pass exits
+ * non-zero for a per-installation vendor error, which is a normal tick outcome.
+ *
+ * Exported for the real-subprocess cancellation tests.
+ */
+export function driveCooperativeChild(command, args, signal, graceMs, spawnOpts = {}) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(command, args, {
+                // stdio[3] = 'ipc' is the cancel channel. Detached on POSIX so the child
+                // leads its own process group and the backstop below can reap its whole
+                // npm subtree; the parent still waits on it (never unref'd).
+                stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+                detached: process.platform !== 'win32',
+                windowsHide: true,
+                env: spawnOpts.env,
+                cwd: spawnOpts.cwd,
+            });
+        }
+        catch (err) {
+            reject(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        const MAX = 16 * 1024 * 1024;
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let cancelRequested = false;
+        let forceReaped = false;
+        let graceTimer;
+        const cleanup = () => {
+            if (graceTimer)
+                clearTimeout(graceTimer);
+            signal.removeEventListener('abort', requestCancel);
+        };
+        function requestCancel() {
+            if (cancelRequested || settled)
+                return;
+            cancelRequested = true;
+            // Cooperative: a message the child reads at its next safe boundary. NEVER a
+            // signal — that would interrupt a swap (and is fatal on Windows, which has
+            // no cooperative SIGTERM). If the channel is already gone the child's own
+            // `disconnect` handler cancels it, so a failed send is not an error.
+            try {
+                child.send(cancelMessage(), () => { });
+            }
+            catch { /* channel closed; disconnect handles it */ }
+            graceTimer = setTimeout(() => {
+                if (settled)
+                    return;
+                forceReaped = true;
+                try {
+                    if (process.platform !== 'win32' && typeof child.pid === 'number')
+                        process.kill(-child.pid, 'SIGKILL');
+                    else
+                        child.kill('SIGKILL');
+                }
+                catch {
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch { /* already gone */ }
+                }
+            }, graceMs);
+            graceTimer.unref?.();
+        }
+        if (signal.aborted)
+            requestCancel();
+        else
+            signal.addEventListener('abort', requestCancel, { once: true });
+        child.stdout?.on('data', (d) => { if (stdout.length < MAX)
+            stdout += d.toString(); });
+        child.stderr?.on('data', (d) => { if (stderr.length < MAX)
+            stderr += d.toString(); });
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(err);
+        });
+        child.on('close', (code, sigName) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (forceReaped || sigName) {
+                reject(new Error(`harness-update child did not exit cooperatively after cancel `
+                    + `(${forceReaped ? `force-reaped after ${graceMs}ms grace` : `died to ${sigName}`}). `
+                    + (stderr.slice(0, 500) || stdout.slice(0, 500) || 'no output')));
+                return;
+            }
+            resolve({ exitCode: code, stdout: stdout || stderr, cancelled: cancelRequested });
+        });
+    });
+}
+/**
+ * Core decision + spawn, shared so a future on-demand trigger (mirroring
+ * `triggerSelfUpdateInBackground`) can reuse it. Returns rather than throws —
+ * the periodic tick logs the outcome and moves on either way.
+ */
+export async function runHarnessUpdateTick(ctx, signal, deps = defaultHarnessUpdateDeps()) {
+    try {
+        const { exitCode, stdout, cancelled } = await deps.runAutoUpdatePass(signal);
+        if (exitCode !== 0) {
+            ctx.log('WARN', `harness-update: pass exited ${exitCode} — see stdout for per-installation errors: ${stdout.slice(0, 2000)}`);
+        }
+        else if (cancelled) {
+            ctx.log('INFO', 'harness-update: pass cancelled at a safe boundary (deadline or daemon shutdown); no work left half-done');
+        }
+        else {
+            ctx.log('INFO', 'harness-update: pass completed');
+        }
+        return { ran: true, exitCode, stdout, cancelled };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.log('ERROR', `harness-update: pass failed to run: ${message}`);
+        return { ran: false, reason: message };
+    }
+}
+export class HarnessUpdateService extends BasePeriodicService {
+    id = 'harness-update';
+    intervalMs = HARNESS_UPDATE_TICK_MS;
+    deadlineMs = HARNESS_UPDATE_DEADLINE_MS;
+    startupDelayMs = HARNESS_UPDATE_STARTUP_DELAY_MS;
+    async onStart(_ctx) {
+        // No connections/handles to open — each tick spawns its own bounded child.
+    }
+    async onStop() {
+        // The in-flight child (if any) is asked to stop COOPERATIVELY: the supervisor
+        // aborts `signal` on the current tick, which `driveCooperativeChild` turns
+        // into an IPC cancel message, never a kill. Nothing else to release here.
+    }
+    async onTick(ctx, signal) {
+        await runHarnessUpdateTick(ctx, signal);
+    }
+}

package/dist/lib/daemon-services.d.ts

@@ -7,7 +7,7 @@
  * enabled without pulling in the whole daemon lifecycle.
  */
 /** Every service the daemon can host. IDs are kebab-case and stable. */
-export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'keychain-reap' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state' | 'session-summarizer';
+export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'keychain-reap' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state' | 'session-summarizer' | 'harness-update';
 /** Human-readable metadata for each service. */
 export interface DaemonServiceDef {
     id: DaemonServiceId;

package/dist/lib/daemon-services.js

@@ -122,6 +122,11 @@ export const DAEMON_SERVICES = [
         title: 'Usage snapshot sync',
         description: 'Bidirectional per-account usage sync: a headed personal/desktop box pushes its snapshot to worker peers, and a worker with a stale cache pulls from the primary — so workers that cannot read the endpoint themselves still route by real capacity.',
     },
+    {
+        id: 'harness-update',
+        title: 'Harness auto-update',
+        description: 'Moves eligible, non-pinned npm-package harness installations (Claude, Codex, …) to their latest release via a bounded child process, subject to updates.auto / updates.<agent>.auto and each installation\'s own update policy (PHNX-3940).',
+    },
 ];
 /** Stable order of service IDs. */
 export const DAEMON_SERVICE_IDS = DAEMON_SERVICES.map((s) => s.id);

package/dist/lib/device-config.d.ts

@@ -91,7 +91,6 @@ declare const DEVICE_ROLES: readonly ["worker", "personal", "desktop"];
 /** Which devices automatic placement may pick — see the `auto.pool` key below. */
 declare const AUTO_POOL_MODES: readonly ["workers", "all"];
 export declare const CONFIG_KEYS: readonly ConfigKeySpec[];
-/** Look up a key spec by CLI dotted name, or throw listing the known keys. */
 export declare function configKeySpec(name: string): ConfigKeySpec;
 /**
  * Fold the legacy config/pins stores into the current layout, once per

package/dist/lib/device-config.js

@@ -39,6 +39,7 @@ import { atomicWriteFileSync } from './fs-atomic.js';
 import { machineId } from './machine-id.js';
 import { assertValidDeviceName, assertRegistrableDeviceName } from './devices/registry.js';
 import { migrateDeviceConfigStores } from './devices/config-migration.js';
+import { isAgentId } from './types.js';
 const DEVICE_PLATFORMS = ['windows', 'linux', 'macos', 'unknown'];
 const SSH_AUTH_METHODS = ['key', 'password'];
 /** Roles a device can be marked with — see the `role` key below. */
@@ -100,6 +101,18 @@ export const CONFIG_KEYS = [
         type: 'string',
         description: 'Model the summarizer requests from summarizer.baseUrl, e.g. qwen2.5:3b. Overridden per-process by AGENTS_SUMMARIZER_MODEL.',
     },
+    {
+        name: 'updates.auto',
+        yamlKey: 'updatesAuto',
+        scope: 'user',
+        type: 'bool',
+        defaultValue: true,
+        description: 'Whether the daemon\'s automatic-update pass (PHNX-3940) may move any safely-transactional npm harness ' +
+            '(Claude, Codex, …) to its latest release with no operator action. This is the fleet-wide KILL SWITCH: ' +
+            'off, no harness auto-updates regardless of any updates.<agent>.auto override. On (the default), each ' +
+            "harness's own updates.<agent>.auto refines it. Per-installation pins (agents update … --to <release>) " +
+            'apply on top of this either way.',
+    },
     {
         name: 'browser.viewer',
         yamlKey: 'browserViewer',
@@ -333,8 +346,31 @@ export const CONFIG_KEYS = [
     },
 ];
 /** Look up a key spec by CLI dotted name, or throw listing the known keys. */
+/**
+ * Per-harness override of `updates.auto` (PHNX-3940) — `updates.<agent>.auto`,
+ * one boolean key per registered agent id. Use the lightweight canonical ID
+ * catalog: importing the installation/runtime registry here creates a cycle
+ * through the harness adapters and makes ordinary config readers load it all.
+ */
+function dynamicAgentAutoUpdateSpec(name) {
+    const match = name.match(/^updates\.(.+)\.auto$/);
+    if (!match)
+        return null;
+    const agent = match[1];
+    if (!isAgentId(agent))
+        return null;
+    return {
+        name,
+        yamlKey: `updatesAgentAuto.${agent}`,
+        scope: 'user',
+        type: 'bool',
+        description: `Per-harness override of updates.auto for ${agent}. Only takes effect while ` +
+            'updates.auto is on (the global switch is a hard kill switch, not a default this can override). Unset ' +
+            'defers to updates.auto.',
+    };
+}
 export function configKeySpec(name) {
-    const spec = CONFIG_KEYS.find((k) => k.name === name);
+    const spec = CONFIG_KEYS.find((k) => k.name === name) ?? dynamicAgentAutoUpdateSpec(name);
     if (!spec) {
         throw new Error(`Unknown config key '${name}'. Known keys: ${CONFIG_KEYS.map((k) => k.name).join(', ')}.`);
     }
@@ -500,12 +536,19 @@ function assertLocalTarget(spec, device) {
 }
 /** Get one config key's effective value and the layer that set it. */
 export function getConfigValue(name, opts) {
-    ensureDeviceConfigMigrated();
     const spec = configKeySpec(name);
     if (spec.scope === 'user') {
-        const value = readMeta().config?.[spec.yamlKey];
+        // A user-scope key reads purely from central `agents.yaml` (readMeta) and
+        // is untouched by the device-config fold, which only relocates DEVICE-scope
+        // legacy stores (config-migration.ts) — none of them a user key. So a
+        // user-scope read stays a PURE read and MUST NOT trigger the migration
+        // write: a read-only `agents update --check` reads the `updates.auto` /
+        // `updates.<agent>.auto` policy through here, and migrating disk on that
+        // read is exactly the unsolicited startup write --check must not do.
+        const value = readMeta({ migrate: false }).config?.[spec.yamlKey];
         return { spec, value, source: value !== undefined ? 'user' : 'default' };
     }
+    ensureDeviceConfigMigrated();
     if (opts?.fleet) {
         const value = readFleetConfigDefaults()[spec.yamlKey];
         return { spec, value, source: value !== undefined ? 'fleet' : 'default' };
@@ -530,12 +573,14 @@ export function getConfigValue(name, opts) {
  * after the first process-wide fold — neither blocks the loop meaningfully.
  */
 export async function getConfigValueAsync(name, opts) {
-    ensureDeviceConfigMigrated();
     const spec = configKeySpec(name);
     if (spec.scope === 'user') {
-        const value = readMeta().config?.[spec.yamlKey];
+        // Pure user-scope read — same reasoning as the sync twin: no device-config
+        // fold, so a user read never migrates disk.
+        const value = readMeta({ migrate: false }).config?.[spec.yamlKey];
         return { spec, value, source: value !== undefined ? 'user' : 'default' };
     }
+    ensureDeviceConfigMigrated();
     if (opts?.fleet) {
         const value = readFleetConfigDefaults()[spec.yamlKey];
         return { spec, value, source: value !== undefined ? 'fleet' : 'default' };

package/dist/lib/exec.js

@@ -20,6 +20,9 @@ import { resolveActor, actorEnv } from './actor.js';
 import { expandLocalHome } from './project-root.js';
 import { getShimsDir, getHistoryDir, getRuntimeStateDir } from './state.js';
 import { readCodexConfiguredModel } from './installations/shims.js';
+import { withInstallationLease } from './installations/launch-gate.js';
+import { getCliLaunch, getAgentsBinPath } from './cli-entry.js';
+import { installedReleaseFor } from './installations/store.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
 import { writeSessionActorRecord, writeSessionAliasRecord } from './session/actor-sidecar.js';
 import { loadHookSessionIndex, resolveHookSessionId } from './session/hook-sessions.js';
@@ -706,7 +709,7 @@ export function nativeResume(agent, version) {
         return false;
     if (!resume.since)
         return true;
-    return !!version && compareVersions(version, resume.since) >= 0;
+    return !!version && compareVersions(installedReleaseFor(agent, version), resume.since) >= 0;
 }
 /**
  * Build the `-c` value that adds `dir` to codex's workspace-write writable
@@ -1111,6 +1114,12 @@ export function resolveShimSpawn(platform, binary, extraArgs) {
  * keeping version resolution in one place instead of reimplementing it in batch.
  */
 export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
+    const version = pinnedVersion ?? resolveVersion(agent, cwd) ?? undefined;
+    if (!version || !isVersionInstalled(agent, version))
+        return execShimPassthroughLeased(agent, rawArgs, cwd, version);
+    return withInstallationLease(agent, version, () => execShimPassthroughLeased(agent, rawArgs, cwd, version));
+}
+async function execShimPassthroughLeased(agent, rawArgs, cwd, pinnedVersion) {
     const version = pinnedVersion ?? resolveVersion(agent, cwd) ?? undefined;
     if (!version || !isVersionInstalled(agent, version)) {
         process.stderr.write(`agents: no installed default for ${agent}. Set one with: agents use ${agent} <version>\n`);
@@ -1153,6 +1162,8 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     // signed-in verdict from the pinned version home (no rotated pick here).
     await emitRunLaunch({ agent, version, resolvedVia: 'shim' });
     return new Promise((resolve) => {
+        // Register listeners in the same synchronous turn as spawn: awaiting a lock
+        // release after spawn can miss a fast child's exit/error event.
         const child = spawn(command, args, { cwd, stdio: 'inherit', env, shell });
         // Record the launch so `ag sessions --active` can attribute the agent
         // process to its cwd (and exact session when the caller passed
@@ -1507,7 +1518,14 @@ async function runInTmux(options, executable, args) {
     // which never carried real values anyway (RUSH-1758).
     const envFile = path.join(getRuntimeStateDir(), 'tmux-env', `${name}-${randomUUID().slice(0, 8)}.env`);
     writeTmuxEnvFile(execEnv, envFile);
-    const cmd = buildTmuxAgentCommand(executable, args, execEnv, { envFile });
+    let cmd = buildTmuxAgentCommand(executable, args, execEnv, { envFile });
+    const leaseVersion = options.version ?? resolveVersion(options.agent, cwd);
+    if (leaseVersion && isVersionInstalled(options.agent, leaseVersion)) {
+        const leaseCli = getCliLaunch(['__launch-lease', options.agent, leaseVersion], getAgentsBinPath());
+        // The pane outlives a detached launcher. Lease its own exec-replaced shell
+        // before launching, so detaching cannot open an unprotected launch gap.
+        cmd = `${[leaseCli.command, ...leaseCli.args].map(shellQuote).join(' ')} "$$" || exit 1; ${cmd}`;
+    }
     const metaCmd = buildTmuxAgentCommand(executable, args, execEnv, { redactEnvValues: true });
     const labels = { agent: options.agent };
     // Only publish an id the harness actually received. createSession turns this
@@ -1719,6 +1737,12 @@ async function emitRunLaunch(ctx) {
     }
 }
 async function spawnAgent(options) {
+    const version = options.version ?? resolveVersion(options.agent, options.cwd || process.cwd());
+    if (!version || !isVersionInstalled(options.agent, version))
+        return spawnAgentLeased(options);
+    return withInstallationLease(options.agent, version, () => spawnAgentLeased(options));
+}
+async function spawnAgentLeased(options) {
     bootMark('spawn-agent:enter');
     // Assign a known session id up front for agents that accept one, so the
     // launcher can record an EXACT pid -> session mapping (see pid-registry) —

package/dist/lib/fs-atomic.d.ts

@@ -40,6 +40,8 @@ export declare function atomicWriteJsonSync(filePath: string, data: unknown): vo
 export interface FileLockOptions {
     staleMs?: number;
     acquireTimeoutMs?: number;
+    /** Lock a canonical absolute path before its file exists (e.g. a new installation record). */
+    realpath?: boolean;
 }
 export declare function withFileLock<T>(filePath: string, fn: (heartbeat: () => void) => T, opts?: FileLockOptions): T;
 /**

package/dist/lib/fs-atomic.js

@@ -79,6 +79,7 @@ export function withFileLock(filePath, fn, opts = {}) {
         try {
             release = lockfile.lockSync(filePath, {
                 stale: staleMs,
+                realpath: opts.realpath ?? true,
                 onCompromised: (err) => { compromised = err; },
             });
             break;
@@ -147,6 +148,7 @@ export async function withFileLockAsync(filePath, fn, opts = {}) {
         try {
             release = await lockfile.lock(filePath, {
                 stale: staleMs,
+                realpath: opts.realpath ?? true,
                 onCompromised: (err) => { compromised = err; },
             });
             break;

package/dist/lib/hooks/install.js

@@ -3284,7 +3284,7 @@ export async function installSessionTrackerHook(agent, version, home) {
     }
     try {
         await execFileAsync(invocation.command, invocation.args, {
-            env: { ...process.env, HOME: home ?? process.env.HOME },
+            env: sessionTrackerInstallEnv(agent, version, home),
             encoding: 'utf8',
         });
         return { installed: true };
@@ -3326,7 +3326,7 @@ export function installSessionTrackerHookSync(agent, version, home) {
     }
     try {
         execFileSync(invocation.command, invocation.args, {
-            env: { ...process.env, HOME: home ?? process.env.HOME },
+            env: sessionTrackerInstallEnv(agent, version, home),
             stdio: ['ignore', 'pipe', 'pipe'],
             encoding: 'utf8',
         });
@@ -3336,3 +3336,8 @@ export function installSessionTrackerHookSync(agent, version, home) {
         return { installed: false, error: installFailureMessage(err) };
     }
 }
+/** The hook installer must target this account, not the current global home. */
+function sessionTrackerInstallEnv(agent, version, home) {
+    const target = home ?? (version ? getVersionHomePath(agent, version) : undefined);
+    return target ? { ...process.env, HOME: target, USERPROFILE: target } : { ...process.env };
+}

package/dist/lib/installations/active-check.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Real-process-state "is this installation busy right now?" check (PHNX-3940).
+ *
+ * A leaf module deliberately kept free of `update.js`/`update-runtime.js`
+ * imports so both can depend on it without an import cycle: `update.ts` needs
+ * it for the pre-commit re-check (narrowing the launch/update race), and
+ * `update-runtime.ts` (which itself calls into `update.ts`) needs it for the
+ * plan-time deferral decision.
+ *
+ * Two independent signals, either one is enough to defer:
+ *   - A live OS process whose command line names this installation's own
+ *     version-dir path — a real process-table scan, not this box's session
+ *     registry, so a harness launched by a bare generated shim with no
+ *     session bookkeeping still defers correctly.
+ *   - A live launch lease (`shims.ts`) — catches a launch that started after
+ *     the process-table scan ran but hasn't hit the process table yet, e.g.
+ *     mid-staging of a long npm install. See `shims.ts`'s docblock for what
+ *     this does and does not close (it narrows the race, not eliminates it).
+ */
+import type { Installation } from './types.js';
+/**
+ * Raw process-table snapshot, one command line per entry. Injectable so tests
+ * can drive real string matching without shelling out or requiring a live
+ * agent process on the test box.
+ */
+export interface ProcessSnapshot {
+    listCommandLines(): Promise<string[]>;
+}
+export declare const realProcessSnapshot: ProcessSnapshot;
+/**
+ * Does any live process reference this installation's own directory? Matches
+ * on the absolute version-dir path rather than the bare CLI command name, so
+ * it distinguishes between installations of the same agent (two Claude
+ * installs are two different directories) and catches every way the binary
+ * ends up running under that path: an `agents run` session, a bare generated
+ * PATH/`.cmd` shim exec'd directly with no session bookkeeping at all, or a
+ * routine/teammate process — all of them carry the resolved absolute binary
+ * path in their command line, since none of the launch surfaces exec a bare
+ * relative name.
+ */
+export declare function installationLooksActive(installation: Pick<Installation, 'agent' | 'label'>, commandLines: string[]): boolean;
+/**
+ * Whether this installation appears to be busy right now: a live launch
+ * lease, or a live process naming its directory per a fresh OS process-table
+ * scan. On a scan failure, defers (returns true) rather than risking an
+ * update to a harness this check simply failed to observe.
+ */
+export declare function isInstallationLikelyActive(installation: Pick<Installation, 'agent' | 'label'>, snapshot?: ProcessSnapshot): Promise<boolean>;

package/dist/lib/installations/active-check.js

@@ -0,0 +1,84 @@
+/**
+ * Real-process-state "is this installation busy right now?" check (PHNX-3940).
+ *
+ * A leaf module deliberately kept free of `update.js`/`update-runtime.js`
+ * imports so both can depend on it without an import cycle: `update.ts` needs
+ * it for the pre-commit re-check (narrowing the launch/update race), and
+ * `update-runtime.ts` (which itself calls into `update.ts`) needs it for the
+ * plan-time deferral decision.
+ *
+ * Two independent signals, either one is enough to defer:
+ *   - A live OS process whose command line names this installation's own
+ *     version-dir path — a real process-table scan, not this box's session
+ *     registry, so a harness launched by a bare generated shim with no
+ *     session bookkeeping still defers correctly.
+ *   - A live launch lease (`shims.ts`) — catches a launch that started after
+ *     the process-table scan ran but hasn't hit the process table yet, e.g.
+ *     mid-staging of a long npm install. See `shims.ts`'s docblock for what
+ *     this does and does not close (it narrows the race, not eliminates it).
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { getVersionDir } from './store.js';
+import { hasLiveLaunchLease } from './shims.js';
+const execFileAsync = promisify(execFile);
+async function listCommandLinesPosix() {
+    try {
+        const { stdout } = await execFileAsync('ps', ['-Ao', 'args'], {
+            timeout: 5_000,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return stdout.split('\n');
+    }
+    catch {
+        // A ps failure must not silently mean "nothing is running" — that would let
+        // an update proceed against a harness this pass simply failed to observe.
+        // Callers treat a thrown scan as "assume active", the safe default.
+        throw new Error('could not read the process table (ps failed)');
+    }
+}
+async function listCommandLinesWindows() {
+    try {
+        const { stdout } = await execFileAsync('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command',
+            "$ErrorActionPreference = 'Stop'; Get-CimInstance Win32_Process | ForEach-Object { $_.CommandLine }"], { timeout: 5_000, maxBuffer: 16 * 1024 * 1024, windowsHide: true });
+        return stdout.split(/\r?\n/);
+    }
+    catch {
+        throw new Error('could not read the process table (PowerShell CIM query failed)');
+    }
+}
+export const realProcessSnapshot = {
+    listCommandLines: () => (process.platform === 'win32' ? listCommandLinesWindows() : listCommandLinesPosix()),
+};
+/**
+ * Does any live process reference this installation's own directory? Matches
+ * on the absolute version-dir path rather than the bare CLI command name, so
+ * it distinguishes between installations of the same agent (two Claude
+ * installs are two different directories) and catches every way the binary
+ * ends up running under that path: an `agents run` session, a bare generated
+ * PATH/`.cmd` shim exec'd directly with no session bookkeeping at all, or a
+ * routine/teammate process — all of them carry the resolved absolute binary
+ * path in their command line, since none of the launch surfaces exec a bare
+ * relative name.
+ */
+export function installationLooksActive(installation, commandLines) {
+    const versionDir = getVersionDir(installation.agent, installation.label);
+    return commandLines.some((line) => line.includes(versionDir));
+}
+/**
+ * Whether this installation appears to be busy right now: a live launch
+ * lease, or a live process naming its directory per a fresh OS process-table
+ * scan. On a scan failure, defers (returns true) rather than risking an
+ * update to a harness this check simply failed to observe.
+ */
+export async function isInstallationLikelyActive(installation, snapshot = realProcessSnapshot) {
+    if (hasLiveLaunchLease(installation.agent, installation.label))
+        return true;
+    try {
+        const lines = await snapshot.listCommandLines();
+        return installationLooksActive(installation, lines);
+    }
+    catch {
+        return true;
+    }
+}

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

@@ -7,8 +7,12 @@
  * it, so the internal split can change without breaking callers (the Cursor
  * per-installation isolation track consumes exactly this).
  */
-export { type Installation, type InstallationRelease, type UpdateOutcome, type UpdateStrategyId, } from './types.js';
+export { type Installation, type InstallationRelease, type UpdateOutcome, type UpdateStrategyId, type UpdatePolicy, } from './types.js';
 export { createInstallation, listInstallations, recordRelease, } from './store.js';
 export { describeInstallation, resolveInstallation, type ResolveInstallationOptions, } from './resolve.js';
 export { selectUpdateStrategy, supportsPinnedUpdate, type UpdateStrategy, } from './strategies.js';
 export { updateInstallation, type UpdateInstallationOptions } from './update.js';
+export { effectiveUpdatePolicy, isAutoUpdateEnabledForAgent, isGlobalAutoUpdateEnabled, rawAgentAutoUpdateSetting, rawGlobalAutoUpdateSetting, setAgentAutoUpdateEnabled, setGlobalAutoUpdateEnabled, setInstallationUpdatePolicy, unsetAgentAutoUpdateEnabled, unsetGlobalAutoUpdateEnabled, } from './update-policy.js';
+export { planAutoUpdates, runAutoUpdatePass, listInstallationSnapshots, type AutoUpdatePlanEntry, type AutoUpdatePassOutcome, type AutoUpdatePassOptions, type AutoUpdatePassResult, } from './update-runtime.js';
+export { installationLooksActive, isInstallationLikelyActive, realProcessSnapshot, type ProcessSnapshot, } from './active-check.js';
+export { recordLaunchLease, hasLiveLaunchLease } from './shims.js';

package/dist/lib/installations/index.js

@@ -11,3 +11,7 @@ export { createInstallation, listInstallations, recordRelease, } from './store.j
 export { describeInstallation, resolveInstallation, } from './resolve.js';
 export { selectUpdateStrategy, supportsPinnedUpdate, } from './strategies.js';
 export { updateInstallation } from './update.js';
+export { effectiveUpdatePolicy, isAutoUpdateEnabledForAgent, isGlobalAutoUpdateEnabled, rawAgentAutoUpdateSetting, rawGlobalAutoUpdateSetting, setAgentAutoUpdateEnabled, setGlobalAutoUpdateEnabled, setInstallationUpdatePolicy, unsetAgentAutoUpdateEnabled, unsetGlobalAutoUpdateEnabled, } from './update-policy.js';
+export { planAutoUpdates, runAutoUpdatePass, listInstallationSnapshots, } from './update-runtime.js';
+export { installationLooksActive, isInstallationLikelyActive, realProcessSnapshot, } from './active-check.js';
+export { recordLaunchLease, hasLiveLaunchLease } from './shims.js';

package/dist/lib/installations/installation-lock.d.ts

@@ -0,0 +1,6 @@
+import { type FileLockOptions } from '../fs-atomic.js';
+import { type AgentId } from '../types.js';
+export declare function installationLockTarget(agent: AgentId, label: string): string;
+export declare const INSTALLATION_LOCK_STALE_MS: number;
+export declare const INSTALLATION_LOCK_ACQUIRE_TIMEOUT_MS: number;
+export declare const INSTALLATION_LOCK_OPTIONS: Required<FileLockOptions>;