@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/import.d.ts

@@ -1,21 +1,3 @@
-/**
- * Import existing unmanaged agent installations into agents-cli.
- *
- * Two flavors:
- *
- *  1. Config-only import — moves an agent's config dir (e.g. ~/.openclaw)
- *     into the version structure and symlinks it back. Used by `agents setup`
- *     on first-run when an agent was previously installed via npm/homebrew.
- *
- *  2. Full import — also registers an existing binary install (e.g. a global
- *     `npm i -g openclaw`) under the managed version path so the shim
- *     resolver can find it. This is what `agents import <agent>` does.
- *
- * The binary side never moves files. It creates a thin symlink farm under
- * `~/.agents/.history/versions/<agent>/<version>/` pointing at the original
- * global install, plus a package.json marker so `isVersionInstalled` returns
- * true.
- */
 import type { AgentId } from './types.js';
 interface ImportConfigResult {
     success: boolean;
@@ -29,102 +11,16 @@ interface ImportBinaryResult {
     resolvedFromPath?: string;
 }
 export declare function isValidImportVersion(version: string): boolean;
-/**
- * Move an agent's config dir into the managed version structure and symlink it
- * back to its original location. Sets the imported version as the global
- * default and refreshes the shim so the user's PATH lookup hits the managed
- * version.
- *
- * No-op (returns skipped=true) if the version's config dir is already created.
- */
 export declare function importAgentConfig(agentId: AgentId, version: string): Promise<ImportConfigResult>;
-/**
- * Wire an imported version into the rest of the system so it behaves the same
- * as a freshly installed version:
- *
- *   - registered as the global default in agents.yaml (so `agents view`
- *     reports it correctly and resolvers find it),
- *   - main shim refreshed (`~/.agents/.cache/shims/<cli>`),
- *   - versioned alias created (`~/.agents/.cache/shims/<cli>@<version>`),
- *   - home-file symlinks (CLAUDE.md / AGENTS.md / etc.) repointed at this
- *     version's home dir.
- *
- * Without this, the binary-only import path would leave the version stranded:
- * isVersionInstalled returns true, but the resolver never picks it. Safe to
- * call multiple times — each underlying function is idempotent.
- */
 export declare function finalizeImport(agentId: AgentId, version: string): void;
-/**
- * Agent metadata needed by importAgentBinary. Taking these as explicit
- * inputs (rather than looking up AGENTS internally) decouples the symlink
- * farm from the AGENTS registry, which keeps the function pure and avoids
- * fragile coupling in test setups that stub `lib/agents.ts`.
- */
 interface AgentBinarySpec {
-    /** Agent id used in the marker package.json (`agents-{agentId}-{version}`). */
     agentId: string;
-    /** npm package name (e.g. `openclaw`) — used as the `node_modules/<name>` dir. */
     npmPackage: string;
-    /** Binary name on PATH (e.g. `openclaw`) — used as the `.bin/<name>` entry. */
     cliCommand: string;
 }
-/**
- * Register an existing global npm package install under the managed version
- * path so the shim resolver finds it.
- *
- * Layout produced (everything is a symlink, nothing is copied):
- *
- *   {versionDir}/
- *     package.json                          # marker so isVersionInstalled() is true
- *     home/                                 # empty isolated $HOME for this version
- *     node_modules/{npmPackage}    -> {globalPath}
- *     node_modules/.bin/{cliCommand} -> {binaryEntry}
- */
 export declare function importAgentBinary(spec: AgentBinarySpec, version: string, globalPath: string, versionDir: string): ImportBinaryResult;
-/**
- * Register an existing installScript-based binary (Grok, Antigravity, Cursor,
- * etc. — anything with `npmPackage: ''` and a curl/brew installer) under the
- * managed version path. Unlike `importAgentBinary` this skips the npm
- * package.json walk and just symlinks the resolved PATH binary directly into
- * `{versionDir}/node_modules/.bin/{cliCommand}`. The symlink is what makes
- * `listInstalledVersions` consider the version Managed.
- *
- * Layout produced:
- *
- *   {versionDir}/
- *     package.json                              # marker (private, imported, from)
- *     home/                                     # empty isolated $HOME
- *     node_modules/.bin/{cliCommand} -> {binaryPath}
- *
- * For agents whose binary lookup is special-cased elsewhere (e.g. Grok's
- * `~/.grok/downloads/`), the symlink is still created — `getBinaryPath` won't
- * read it for those agents, but it documents provenance and lets a future
- * refactor consolidate the binary-resolution registry.
- */
 export declare function importInstallScriptBinary(spec: AgentBinarySpec, version: string, binaryPath: string, versionDir: string): ImportBinaryResult;
-/**
- * Resolve the on-disk npm package directory for an agent's CLI binary by
- * walking up from the binary, following any symlinks. Returns null if the
- * package can't be identified.
- *
- * Handles the homebrew/global-npm pattern where:
- *   /opt/homebrew/bin/{cli}  ->  ../lib/node_modules/{pkg}/dist/index.js
- */
 export declare function resolvePackageDirFromBinary(binaryPath: string): string | null;
-/**
- * Seed an ISOLATED version's home from the user's real `~/.<agent>` — the mirror of
- * {@link importAgentConfig}, which adopts.
- *
- * The difference is the whole point: this COPIES and leaves the original in place,
- * never symlinks it, never sets a default, never creates a shim. So an isolated copy
- * can start from the setup the user already has instead of from nothing, which was
- * the only way to get a working sandbox before.
- *
- * Credentials are skipped by default and reported, not silently included. An isolated
- * copy is a separate principal — `agents add --isolated` already tells the user to
- * sign in on first run — and copying tokens into it should be a choice, not a side
- * effect of wanting your settings. `--with-auth` opts in.
- */
 export declare function seedIsolatedConfigFromLocal(agentId: AgentId, version: string, opts?: {
     withAuth?: boolean;
     all?: boolean;

package/dist/lib/import.js

@@ -1,21 +1,3 @@
-/**
- * Import existing unmanaged agent installations into agents-cli.
- *
- * Two flavors:
- *
- *  1. Config-only import — moves an agent's config dir (e.g. ~/.openclaw)
- *     into the version structure and symlinks it back. Used by `agents setup`
- *     on first-run when an agent was previously installed via npm/homebrew.
- *
- *  2. Full import — also registers an existing binary install (e.g. a global
- *     `npm i -g openclaw`) under the managed version path so the shim
- *     resolver can find it. This is what `agents import <agent>` does.
- *
- * The binary side never moves files. It creates a thin symlink farm under
- * `~/.agents/.history/versions/<agent>/<version>/` pointing at the original
- * global install, plus a package.json marker so `isVersionInstalled` returns
- * true.
- */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -27,33 +9,15 @@ const IMPORT_VERSION_RE = /^(?:latest|[A-Za-z0-9._+-]{1,64})$/;
 export function isValidImportVersion(version) {
     return IMPORT_VERSION_RE.test(version);
 }
-/**
- * Move an agent's config dir into the managed version structure and symlink it
- * back to its original location. Sets the imported version as the global
- * default and refreshes the shim so the user's PATH lookup hits the managed
- * version.
- *
- * No-op (returns skipped=true) if the version's config dir is already created.
- */
 export async function importAgentConfig(agentId, version) {
     if (!isValidImportVersion(version)) {
         return { success: false, error: `Invalid version: ${JSON.stringify(version)}` };
     }
-    // Adoption, done inline rather than via switchConfigSymlink — so it needs the gate
-    // directly. commands/import.ts checks at its entry point too (it must: it registers
-    // a normal version first, which would un-protect the agent before this runs), but
-    // an exported function that moves the user's real config must not depend on every
-    // future caller remembering.
     assertIsolationBoundary(agentId, 'adopt your existing install');
     const agent = AGENTS[agentId];
     const configDir = agent.configDir;
     const versionsDir = getVersionsDir();
     const versionHome = path.join(versionsDir, agentId, version, 'home');
-    // Match the shim's derivation in generateShimScript: the per-version config
-    // path mirrors the original configDir's path relative to $HOME. Hardcoding
-    // `.${agentId}` broke for nested configDirs like Antigravity
-    // (`~/.gemini/antigravity-cli`) — the destination would be `.antigravity`,
-    // mismatching the shim's expectation of `.gemini/antigravity-cli`.
     const versionConfigDir = path.join(versionHome, path.relative(os.homedir(), configDir));
     if (fs.existsSync(versionConfigDir)) {
         return { success: false, skipped: true, error: `${version} already installed` };
@@ -71,21 +35,6 @@ export async function importAgentConfig(agentId, version) {
         return { success: false, error: err.message };
     }
 }
-/**
- * Wire an imported version into the rest of the system so it behaves the same
- * as a freshly installed version:
- *
- *   - registered as the global default in agents.yaml (so `agents view`
- *     reports it correctly and resolvers find it),
- *   - main shim refreshed (`~/.agents/.cache/shims/<cli>`),
- *   - versioned alias created (`~/.agents/.cache/shims/<cli>@<version>`),
- *   - home-file symlinks (CLAUDE.md / AGENTS.md / etc.) repointed at this
- *     version's home dir.
- *
- * Without this, the binary-only import path would leave the version stranded:
- * isVersionInstalled returns true, but the resolver never picks it. Safe to
- * call multiple times — each underlying function is idempotent.
- */
 export function finalizeImport(agentId, version) {
     setGlobalDefault(agentId, version);
     createShim(agentId);
@@ -93,30 +42,14 @@ export function finalizeImport(agentId, version) {
     switchHomeFileSymlinks(agentId, version);
     ensureShimCurrent(agentId);
 }
-/**
- * Register an existing global npm package install under the managed version
- * path so the shim resolver finds it.
- *
- * Layout produced (everything is a symlink, nothing is copied):
- *
- *   {versionDir}/
- *     package.json                          # marker so isVersionInstalled() is true
- *     home/                                 # empty isolated $HOME for this version
- *     node_modules/{npmPackage}    -> {globalPath}
- *     node_modules/.bin/{cliCommand} -> {binaryEntry}
- */
 export function importAgentBinary(spec, version, globalPath, versionDir) {
     const binaryLink = path.join(versionDir, 'node_modules', '.bin', spec.cliCommand);
-    // lstat — we want to detect the symlink itself, not follow it. fs.existsSync
-    // can return false on dangling symlinks, which would incorrectly let us
-    // proceed to symlinkSync below and throw EEXIST.
     let alreadyExists = false;
     try {
         fs.lstatSync(binaryLink);
         alreadyExists = true;
     }
     catch {
-        /* not present */
     }
     if (alreadyExists) {
         return { success: false, skipped: true, error: `${version} already installed`, resolvedFromPath: globalPath };
@@ -135,9 +68,6 @@ export function importAgentBinary(spec, version, globalPath, versionDir) {
             pkgBinEntry = pkg.bin;
         }
         else if (pkg.bin && typeof pkg.bin === 'object') {
-            // Strict: only accept the exact cliCommand key. Multi-bin packages
-            // (e.g. @anthropic-ai/claude-code ships several bins) would otherwise
-            // silently get a wrong binary chosen by Object.values() ordering.
             pkgBinEntry = pkg.bin[spec.cliCommand];
         }
     }
@@ -167,26 +97,6 @@ export function importAgentBinary(spec, version, globalPath, versionDir) {
         return { success: false, error: err.message };
     }
 }
-/**
- * Register an existing installScript-based binary (Grok, Antigravity, Cursor,
- * etc. — anything with `npmPackage: ''` and a curl/brew installer) under the
- * managed version path. Unlike `importAgentBinary` this skips the npm
- * package.json walk and just symlinks the resolved PATH binary directly into
- * `{versionDir}/node_modules/.bin/{cliCommand}`. The symlink is what makes
- * `listInstalledVersions` consider the version Managed.
- *
- * Layout produced:
- *
- *   {versionDir}/
- *     package.json                              # marker (private, imported, from)
- *     home/                                     # empty isolated $HOME
- *     node_modules/.bin/{cliCommand} -> {binaryPath}
- *
- * For agents whose binary lookup is special-cased elsewhere (e.g. Grok's
- * `~/.grok/downloads/`), the symlink is still created — `getBinaryPath` won't
- * read it for those agents, but it documents provenance and lets a future
- * refactor consolidate the binary-resolution registry.
- */
 export function importInstallScriptBinary(spec, version, binaryPath, versionDir) {
     const binaryLink = path.join(versionDir, 'node_modules', '.bin', spec.cliCommand);
     let alreadyExists = false;
@@ -195,7 +105,6 @@ export function importInstallScriptBinary(spec, version, binaryPath, versionDir)
         alreadyExists = true;
     }
     catch {
-        /* not present */
     }
     if (alreadyExists) {
         return { success: false, skipped: true, error: `${version} already installed`, resolvedFromPath: binaryPath };
@@ -215,19 +124,10 @@ export function importInstallScriptBinary(spec, version, binaryPath, versionDir)
         return { success: false, error: err.message };
     }
 }
-/**
- * Resolve the on-disk npm package directory for an agent's CLI binary by
- * walking up from the binary, following any symlinks. Returns null if the
- * package can't be identified.
- *
- * Handles the homebrew/global-npm pattern where:
- *   /opt/homebrew/bin/{cli}  ->  ../lib/node_modules/{pkg}/dist/index.js
- */
 export function resolvePackageDirFromBinary(binaryPath) {
     try {
         let real = fs.realpathSync(binaryPath);
         let dir = path.dirname(real);
-        // Walk up looking for the nearest package.json
         for (let i = 0; i < 6; i++) {
             const pkg = path.join(dir, 'package.json');
             if (fs.existsSync(pkg)) {
@@ -244,50 +144,20 @@ export function resolvePackageDirFromBinary(binaryPath) {
         return null;
     }
 }
-/**
- * Seed an ISOLATED version's home from the user's real `~/.<agent>` — the mirror of
- * {@link importAgentConfig}, which adopts.
- *
- * The difference is the whole point: this COPIES and leaves the original in place,
- * never symlinks it, never sets a default, never creates a shim. So an isolated copy
- * can start from the setup the user already has instead of from nothing, which was
- * the only way to get a working sandbox before.
- *
- * Credentials are skipped by default and reported, not silently included. An isolated
- * copy is a separate principal — `agents add --isolated` already tells the user to
- * sign in on first run — and copying tokens into it should be a choice, not a side
- * effect of wanting your settings. `--with-auth` opts in.
- */
 export function seedIsolatedConfigFromLocal(agentId, version, opts = {}) {
     const agent = AGENTS[agentId];
     const configDir = agent.configDir;
     const versionHome = path.join(getVersionsDir(), agentId, version, 'home');
-    // Mirror importAgentConfig's derivation so nested config dirs (e.g. Antigravity's
-    // ~/.gemini/antigravity-cli) land where the shim expects them.
     let dest = path.join(versionHome, path.relative(os.homedir(), configDir));
-    // Codex uses a SUN_LEN-safe CODEX_HOME: `home/.codex` is a SYMLINK to
-    // `~/.agents/.codex-homes/<version>/.codex`, because the real path is too long for a
-    // unix socket. cpSync cannot overwrite a symlink with a directory (it fails with
-    // "Cannot overwrite non-directory"), and writing beside it would put settings
-    // somewhere the agent never reads. Follow the link and seed the actual home.
     try {
         if (fs.lstatSync(dest).isSymbolicLink())
             dest = fs.realpathSync(dest);
     }
     catch {
-        /* not created yet — the plain path is correct */
     }
     const result = { seeded: false, from: configDir, to: dest, skippedAuth: [], skippedRuntime: [] };
     if (!fs.existsSync(configDir))
         return result;
-    // Known credential paths, relative to the config dir. `authFiles` covers the agents
-    // that declare them for cross-version carry; the rest are verified filenames for
-    // agents that do not declare any (codex `auth.json`, claude `.credentials.json`).
-    // Runtime state, not settings. Seeding a sandbox with the user's session history,
-    // logs and caches duplicated 757MB on a real machine — 349MB of `sessions` alone —
-    // for a copy that wants config. These are regenerated by the agent as it runs, and
-    // an isolated copy keeps its own; carrying them over also drags conversation history
-    // into a sandbox the user may have created precisely to keep separate.
     const RUNTIME_PREFIXES = ['sessions', 'log', 'logs', 'cache', '.tmp', 'tmp', 'generated_images'];
     const RUNTIME_FILES = ['history.jsonl', 'session_index.jsonl'];
     const isRuntime = (rel) => !opts.all && (RUNTIME_FILES.includes(rel) ||
@@ -305,9 +175,6 @@ export function seedIsolatedConfigFromLocal(agentId, version, opts = {}) {
         const inside = agentsDir + path.sep;
         fs.cpSync(configDir, dest, {
             recursive: true,
-            // `force: true` is Node's default, but Bun drops it when a `filter` is supplied —
-            // existing files are then silently left alone. `dist/bin/agents` is bun-compiled,
-            // so this is a production path, not just a test artifact. State it explicitly.
             force: true,
             filter: (src) => {
                 const rel = path.relative(configDir, src);
@@ -316,14 +183,11 @@ export function seedIsolatedConfigFromLocal(agentId, version, opts = {}) {
                     return false;
                 }
                 if (rel && isRuntime(rel)) {
-                    // Record only the top-level name so the report stays one line per item.
                     const top = rel.split(path.sep)[0];
                     if (!result.skippedRuntime.includes(top))
                         result.skippedRuntime.push(top);
                     return false;
                 }
-                // Same rule as the export path: a link into ~/.agents would dangle for a copy
-                // that is supposed to stand on its own.
                 try {
                     const st = fs.lstatSync(src);
                     if (st.isSymbolicLink()) {
@@ -332,7 +196,7 @@ export function seedIsolatedConfigFromLocal(agentId, version, opts = {}) {
                             return false;
                     }
                 }
-                catch { /* let cpSync surface unreadable entries */ }
+                catch { }
                 return true;
             },
         });

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

@@ -1,31 +1,6 @@
-/**
- * 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[]>;
-    /** Optional richer listing (pid, elapsed, tty) for naming a blocking process. */
     listProcessRows?(): Promise<ProcessRow[]>;
 }
 export interface ProcessRow {
@@ -35,41 +10,13 @@ export interface ProcessRow {
     args: 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>;
 export interface InstallationActivity {
     active: boolean;
-    /** A launch lease is held (a launch is starting and may not be in the process table yet). */
     lease: boolean;
-    /** Live processes naming this installation's directory, one line each. */
     processes: string[];
-    /** The process scan failed; `active` is the fail-closed default. */
     scanError?: string;
 }
-/**
- * Same verdict as {@link isInstallationLikelyActive}, plus WHAT is holding the
- * installation, so a refused update can name the session to finish instead of
- * "in use; retry later" (PHNX-4116 follow-up: an operator on yosemite-s0 had a
- * one-hour-old resumed session on another tty and no way to see it from the
- * refusal).
- */
 export declare function describeInstallationActivity(installation: Pick<Installation, 'agent' | 'label'>, snapshot?: ProcessSnapshot): Promise<InstallationActivity>;
-/** The one-line refusal an update prints for a busy installation. */
 export declare function formatInUseDeferral(name: string, activity: InstallationActivity): string;

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

@@ -1,22 +1,3 @@
-/**
- * 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';
@@ -41,9 +22,6 @@ async function listCommandLinesPosix() {
         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)');
     }
 }
@@ -63,27 +41,10 @@ export const realProcessSnapshot = {
         ? (await listCommandLinesWindows()).map((args) => ({ args }))
         : listProcessRowsPosix()),
 };
-/**
- * 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;
@@ -95,20 +56,11 @@ export async function isInstallationLikelyActive(installation, snapshot = realPr
         return true;
     }
 }
-/** `ps` prints `?` (Linux), `??` (macOS) or `-` for a process with no controlling terminal. */
 const NO_TTY_MARKERS = new Set(['?', '??', '-']);
 function shortenArgs(args, versionDir) {
-    // Strip the long install path so the line reads as the command the user ran.
     const trimmed = args.replace(versionDir, '…').replace(/\/node_modules\/\.bin\//, '/');
     return trimmed.length > 110 ? `${trimmed.slice(0, 107)}...` : trimmed;
 }
-/**
- * Same verdict as {@link isInstallationLikelyActive}, plus WHAT is holding the
- * installation, so a refused update can name the session to finish instead of
- * "in use; retry later" (PHNX-4116 follow-up: an operator on yosemite-s0 had a
- * one-hour-old resumed session on another tty and no way to see it from the
- * refusal).
- */
 export async function describeInstallationActivity(installation, snapshot = realProcessSnapshot) {
     const lease = hasLiveLaunchLease(installation.agent, installation.label);
     const versionDir = getVersionDir(installation.agent, installation.label);
@@ -130,7 +82,6 @@ export async function describeInstallationActivity(installation, snapshot = real
         return { active: true, lease, processes: [], scanError: err instanceof Error ? err.message : String(err) };
     }
 }
-/** The one-line refusal an update prints for a busy installation. */
 export function formatInUseDeferral(name, activity) {
     if (activity.scanError)
         return `${name}: could not confirm nothing is running (${activity.scanError}); not updating.`;

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

@@ -1,12 +1,3 @@
-/**
- * Frozen agent installations.
- *
- * An installation's identity (`id`, `label`) is stable for its whole life; the
- * vendor release it carries moves only on an explicit `agents update`. This
- * barrel is the supported surface — import from here, not from the files behind
- * 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, type UpdatePolicy, } from './types.js';
 export { createInstallation, listInstallations, recordRelease, MANAGED_INSTALLATION_LABEL, resolveManagedInstallation, ensureHarnessInstallation, type EnsureHarnessInstallationResult, } from './store.js';
 export { describeInstallation, resolveInstallation, type ResolveInstallationOptions, } from './resolve.js';

package/dist/lib/installations/index.js

@@ -1,12 +1,3 @@
-/**
- * Frozen agent installations.
- *
- * An installation's identity (`id`, `label`) is stable for its whole life; the
- * vendor release it carries moves only on an explicit `agents update`. This
- * barrel is the supported surface — import from here, not from the files behind
- * it, so the internal split can change without breaking callers (the Cursor
- * per-installation isolation track consumes exactly this).
- */
 export { createInstallation, listInstallations, recordRelease, MANAGED_INSTALLATION_LABEL, resolveManagedInstallation, ensureHarnessInstallation, } from './store.js';
 export { describeInstallation, resolveInstallation, } from './resolve.js';
 export { selectUpdateStrategy, supportsPinnedUpdate, } from './strategies.js';

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

@@ -1,9 +1,3 @@
-/**
- * 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';
@@ -12,8 +6,6 @@ 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);

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

@@ -1,60 +1,4 @@
-/**
- * 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>;
-/** 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>;