@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,39 +1,3 @@
-/**
- * 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';
@@ -41,39 +5,12 @@ 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);
@@ -83,18 +20,9 @@ export async function withLaunchGate(agent, label, fn) {
         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.
- */
 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 {
@@ -104,17 +32,6 @@ export async function withInstallationLease(agent, label, fn) {
         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);

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

@@ -1,115 +1,15 @@
-/** One-shot idempotent migrations. Each is guarded by an existence check so re-running is safe. */
 export { foldLegacySystemRepo } from '../migrate-fold.js';
-/** Migrate a legacy single-repo agents.yaml into ~/.agents/agents.yaml. Leaves the tracked system-mirror copy alone to avoid dirtying the npm-shipped defaults. */
 export declare function migrateAgentsYaml(systemDir?: string, userDir?: string): void;
-/**
- * Stop tracking the user repo's CHANGELOG.md. It duplicates the npm-shipped
- * `.system/CHANGELOG.md` (read the canonical copy from there), and as a tracked
- * file that upstream never carries it can only ever show as `M`/`??`
- * — dirtying the tree and, when a peer's publish commit arrives, tripping the
- * dirty-tree pull guard. De-track it into `.git/info/exclude` (per-clone,
- * uncommitted; never `.gitignore`, which would re-introduce the same failure).
- * Idempotent: a no-op once the path is untracked and excluded.
- */
 export declare function detrackUserChangelog(userDir?: string): void;
-/** Fold the legacy global browser/sessions/<task>/ tree into the per-profile browser/<profile>/sessions/<task>/ layout. Unclaimed tasks move under `_legacy`. */
 export declare function foldBrowserSessionsIntoProfiles(browserDir?: string): void;
-/** Repair node_modules/.bin/<cli> symlinks that resolve back into our own shims dir (infinite exec-loop fix). */
 export declare function repairSelfReferentialBinShims(versionsRoot?: string, shimsDir?: string, historyDir?: string): void;
-/** Move the auto-detected `default` browser profile from committed agents.yaml into the per-device file. The device file is written first so a crash cannot lose the profile; central is edited via yaml.Document to preserve comments. */
 export declare function migrateMachineLocalBrowserProfileOutOfCentral(userDir?: string, machine?: string): void;
-/** Rename the legacy `extras-extras/` plugin marketplace dir to `agents-extras/` in every installed version home, and rewrite cross-references in `known_marketplaces.json` and `settings.json`. */
 export declare function migrateExtrasExtrasToAgentsExtras(historyDir?: string): void;
-/**
- * Rewrite every routine YAML that carries the legacy singular `device: <value>`
- * field to the new plural `devices: [<value>]` format. Preserves all other
- * fields. Idempotent: a routine that already has `devices:` (or neither field)
- * is left untouched.
- *
- * Params default to the real routines dir; injectable for tests.
- */
 export declare function migrateRoutineDeviceToDevices(routinesDir?: string): void;
-/**
- * Fold the legacy host-placement `remoteCwd` field into the canonical portable
- * `cwd` (RUSH-2290). Host dispatch used to read `remoteCwd` while a local run
- * inferred its cwd from `repo` — two path semantics for one concept. The runner
- * now resolves every placement from `cwd`, so this idempotently rewrites the
- * field:
- *
- * - `remoteCwd` present, no `cwd`  → rename to `cwd`.
- * - both present and equal          → drop the duplicate `remoteCwd`.
- * - both present and DIFFERENT       → conflict: leave BOTH fields untouched so
- *   the migration never silently chooses one; `validateJob`/`doctor` then flag the
- *   pair and the routine stays paused rather than running against a guessed path.
- *
- * Idempotent: a file with only `cwd` (already migrated) is skipped.
- */
 export declare function migrateRoutineRemoteCwdToCwd(routinesDir?: string): void;
-/**
- * Fold the legacy watchdog enable sentinel into the `watchdog.enabled` config.
- *
- * The always-on watchdog used to be gated by a presence sentinel at
- * `<runtime-state>/watchdog/enabled`; it is now a daemon-owned timer (RUSH-2495)
- * gated by the `watchdog.enabled` device-config flag — the same flag
- * `agents watchdog enable` writes. A user who had run `agents watchdog enable`
- * under the old build has that file on disk; without this, upgrading would
- * silently drop them back to OFF (the nudge just stops), the worst failure mode
- * for a "survives reboots" feature. If the sentinel exists, set
- * `watchdog.enabled: true`, then delete the sentinel so this runs exactly once.
- * If setting it fails, the sentinel is left in place so a later run retries
- * rather than silently losing the opt-in.
- *
- * The setter seam is injectable so the migration is unit-testable without
- * touching the real device config.
- */
 export declare function migrateWatchdogSentinelToConfig(sentinelPath?: string, enable?: (value: boolean) => void): void;
-/**
- * Rename cli/ → clis/ in each of the given `.agents/` directories.
- *
- * One-way, idempotent: no-op when src is absent. Throws when both
- * `<dir>/cli` and `<dir>/clis` exist — the user must resolve the conflict
- * manually before proceeding. Exported for unit-testing with temp dirs.
- */
 export declare function migrateCliDirToClis(agentsDirs: string[]): void;
-/**
- * An earlier agents-cli release put Cursor's file-backed OAuth token at
- * ~/.config/cursor/auth.json. Current Cursor actually writes the file store to
- * HOME-relative ~/.cursor/auth.json. Copy that legacy token into the active
- * account's version home. The active account
- * is the home the ~/.cursor symlink currently targets. Idempotent: skips when
- * the home already has its own token, and a no-op for unmanaged Cursor installs
- * (where ~/.cursor is a real dir, not a symlink into a version home).
- */
 export declare function seedActiveCursorLoginPerVersion(): void;
-/**
- * Fold the pre-markdown Kimi subagent layout out of every kimi version home.
- *
- * agents-cli used to write each Kimi subagent as a `<name>.yaml` +
- * `<name>.system.md` pair plus a managed `_agents-cli.yaml` index, against the
- * agentspec of `kimi-cli` — a different product from the `kimi-code` harness we
- * install, which never read any of it. Those files are inert, but not harmless:
- * `<name>.system.md` ends in `.md`, so the subagent enumerator would surface it
- * as a phantom subagent named `<name>.system`, and kimi-code logs
- * `Missing frontmatter` for it once per session.
- *
- * This is the ONE place that knows about the old layout — the registry target
- * describes only the current `<name>.md` shape. A pair is identified by its
- * signature (a `<name>.yaml` with a sibling `<name>.system.md`), so a subagent a
- * user legitimately named e.g. `foo.system` is never touched: it has no
- * `foo.yaml` beside it. Idempotent; a no-op once the dirs are clean.
- */
 export declare function migrateKimiSubagentsToMarkdown(versionsDir?: string): void;
-/**
- * Remove the compiled "project" ruleset the compiler used to write into $HOME
- * (RUSH-2725). `compileRulesForProject` treated any cwd with `.agents/rules`
- * as a project — and the user layer at ~/.agents satisfies that test — so it
- * wrote ~/AGENTS.md plus per-agent symlinks, and every session under $HOME
- * then loaded the entire ruleset twice (global memory + "project" memory).
- * The compiler now refuses reserved roots; this removes the artifact already
- * on disk. Only files we provably own are touched: an AGENTS.md carrying the
- * compiled-project header, symlinks pointing at it, and copy-fallback files
- * (symlink-less filesystems) carrying the same header.
- */
 export declare function removeHomeCompiledProjectRules(homeDir?: string): void;
-/** Run all idempotent migrations. Safe to call multiple times. */
 export declare function runMigration(): Promise<void>;