@phnx-labs/agents-cli 1.22.78 → 1.22.80

package/dist/lib/installations/versions.js

@@ -22,7 +22,7 @@ import { discoverPermissionGroups, getActivePermissionPresetName, readPermission
 import { parseMcpConfigForScan, isProjectMcpTrusted } from '../mcp.js';
 import { createVersionedAlias, removeVersionedAlias, switchConfigSymlink, getConfigSymlinkVersion, ensureClaudeInsideSymlink, assertIsolationBoundary, isIsolationProtected, } from './shims.js';
 import { importInstallScriptBinary } from '../import.js';
-import { createInstallation, getBinaryPath, getCliVersionFromPath, getGlobalDefault, getIsolatedDefault, getLiveVersion, getVersionDir, getVersionHomePath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, isGlobalBinaryAgent, isVersionInstalled, isVersionIsolated, listInstalledVersions, pickCanonicalGlobalBinaryVersion, resolveGrokFallbackBinary, resolveVersion, } from './store.js';
+import { createInstallation, readInstallation, getBinaryPath, getCliVersionFromPath, getGlobalDefault, getIsolatedDefault, getLiveVersion, getVersionDir, getVersionHomePath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, isGlobalBinaryAgent, isVersionInstalled, isVersionIsolated, listInstalledVersions, pickCanonicalGlobalBinaryVersion, resolveGrokFallbackBinary, resolveVersion, } from './store.js';
 export * from './store.js';
 import { INSTALLATION_RECORD_FILE } from './types.js';
 import { composeWin32CommandLine } from '../platform/index.js';
@@ -34,6 +34,9 @@ import { discoverPlugins, syncPluginToVersion, pluginSupportsAgent, cleanOrphane
 import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from '../staleness/index.js';
 import { pruneRemovedResources } from '../staleness/prune.js';
 import { emit } from '../feed/events.js';
+import { withFileLockAsync } from '../fs-atomic.js';
+import { installationLockTarget, INSTALLATION_LOCK_OPTIONS } from './installation-lock.js';
+import { isInstallationLikelyActive } from './active-check.js';
 import { safeJoin } from '../paths.js';
 import { readSkillSourceCommandMarker, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from '../command-skills.js';
 import { getWriter, getDetector } from '../staleness/registry.js';
@@ -1031,7 +1034,8 @@ async function checkGrokAccountCollision(installedVersion) {
 /** Install a specific version of an agent. */
 export async function installVersion(agent, version, onProgress, opts) {
     const agentConfig = AGENTS[agent];
-    const requestedLabel = version;
+    const requestedLabel = opts?.installationLabel ?? version;
+    const initialUpdatePolicy = version === 'latest' ? 'latest' : 'pinned';
     if (isAgentHardDeprecated(agent)) {
         return { success: false, installedVersion: version, error: hardDeprecationError(agent) };
     }
@@ -1039,6 +1043,20 @@ export async function installVersion(agent, version, onProgress, opts) {
     if (!VERSION_RE.test(version)) {
         throw new Error(`Invalid version: ${JSON.stringify(version)}`);
     }
+    // A caller-supplied installation label decouples the addressable version-dir
+    // name from the vendor release (PHNX-3940): `agents accounts connect` mints an
+    // opaque stable label so ten accounts can share the same upstream `latest`
+    // under distinct isolated homes, each with its own native login. It follows
+    // the same identity/release split the installScript branch already uses via
+    // `requestedLabel`, and must be a real label, never a release alias.
+    if (opts?.installationLabel !== undefined) {
+        if (!VERSION_RE.test(opts.installationLabel)) {
+            throw new Error(`Invalid installation label: ${JSON.stringify(opts.installationLabel)}`);
+        }
+        if (opts.installationLabel === 'latest' || opts.installationLabel === 'oldest') {
+            throw new Error(`Installation label cannot be a release alias ('${opts.installationLabel}').`);
+        }
+    }
     if (!agentConfig.npmPackage) {
         if (!agentConfig.installScript) {
             return { success: false, installedVersion: version, error: 'Agent has no npm package' };
@@ -1149,7 +1167,7 @@ export async function installVersion(agent, version, onProgress, opts) {
         // Freeze this installation's identity. The dir name is its stable label from
         // here on; the release it carries is recorded separately so `agents update`
         // can move the release without invalidating any reference to the label.
-        createInstallation(agent, installationLabel, releaseVersion);
+        createInstallation(agent, installationLabel, releaseVersion, initialUpdatePolicy);
         const trackerInstall = await installSessionTrackerHook(agent, installationLabel);
         if (!trackerInstall.installed && trackerInstall.error) {
             console.warn(`agents: SessionStart hook not installed for ${agent}@${installationLabel}: ${trackerInstall.error}`);
@@ -1183,142 +1201,158 @@ export async function installVersion(agent, version, onProgress, opts) {
         }
         version = resolved;
     }
+    // `version` is now the concrete vendor release. The addressable slot is the
+    // caller's opaque installation label when given (connect), else the release
+    // itself — the identity/release split (PHNX-3940). Everything on disk (dir,
+    // alias, record, tracker) keys on `label`; only the npm spec uses `release`.
+    const releaseVersion = version;
+    const label = opts?.installationLabel ?? releaseVersion;
     ensureAgentsDir();
-    const versionDir = getVersionDir(agent, version);
-    // A `clean` (repair) reinstall wipes a possibly partially-extracted
-    // node_modules first. npm treats a present-but-gutted platform package (its
-    // package.json landed, its vendored native binary did not) as already
-    // installed and would skip re-fetching it — so without this the corrupt
-    // vendor/ survives the reinstall and the ENOENT persists. home/ is preserved.
-    if (opts?.clean && fs.existsSync(versionDir)) {
-        removeInstallArtifacts(versionDir);
-    }
-    // Create version directory and isolated home
-    fs.mkdirSync(versionDir, { recursive: true });
-    fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
-    // Initialize package.json (only for real npm agents)
-    const packageJson = {
-        name: `agents-${agent}-${version}`,
-        version: '1.0.0',
-        private: true,
-    };
-    fs.writeFileSync(path.join(versionDir, 'package.json'), JSON.stringify(packageJson, null, 2));
-    // Install the package. `version` is always concrete here (`latest`/`oldest`
-    // were resolved above), so the spec is always pinned. The `@` prefix is
-    // load-bearing: it ensures `version` (which VERSION_RE permits to start with
-    // `-`) is never passed as a standalone npm CLI flag.
-    const packageSpec = `${agentConfig.npmPackage}@${version}`;
-    // Set once the install has passed its integrity gate; read after the try so
-    // the success path's bookkeeping sits outside the catch's cleanup.
-    let healthyVersion;
-    try {
-        // Check npm is available
-        const winShell = process.platform === 'win32';
-        try {
-            await execFileAsync('npm', ['--version'], { shell: winShell });
-        }
-        catch {
-            return {
-                success: false,
-                installedVersion: version,
-                error: 'npm is not installed. Install Node.js and npm first: https://nodejs.org/',
-            };
+    const versionDir = getVersionDir(agent, label);
+    return withFileLockAsync(installationLockTarget(agent, label), async () => {
+        // Installs and repairs mutate the same executable as updates. Hold the same
+        // lock before touching artifacts, even before the first record exists.
+        if (await isInstallationLikelyActive({ agent, label })) {
+            return { success: false, installedVersion: label, error: `${agent} account home ${label} is in use. Retry after its sessions finish.` };
+        }
+        // A `clean` (repair) reinstall wipes a possibly partially-extracted
+        // node_modules first. npm treats a present-but-gutted platform package (its
+        // package.json landed, its vendored native binary did not) as already
+        // installed and would skip re-fetching it — so without this the corrupt
+        // vendor/ survives the reinstall and the ENOENT persists. home/ is preserved.
+        if (opts?.clean && fs.existsSync(versionDir)) {
+            removeInstallArtifacts(versionDir);
         }
-        onProgress?.(`Installing ${packageSpec}...`);
-        await execFileAsync('npm', ['install', packageSpec, '--ignore-scripts'], { cwd: versionDir, shell: winShell });
-        // `version` is concrete (the `latest`/`oldest` aliases were resolved up
-        // front), so the package installed directly into its final versioned dir —
-        // no post-install rename, and no shared `latest/` dir for a concurrent
-        // process to move out from under us.
-        const installedVersion = version;
-        // Create versioned alias (e.g., claude@2.0.65)
-        createVersionedAlias(agent, installedVersion);
-        // Claude reads its global config from CLAUDE_CONFIG_DIR/.claude.json —
-        // i.e. inside the per-version .claude dir — while the rest of agents-cli
-        // manages the home-level file. Symlink INSIDE to OUTSIDE so Claude and
-        // agents-cli see the same content.
-        if (agent === 'claude') {
+        // Create version directory and isolated home
+        fs.mkdirSync(versionDir, { recursive: true });
+        fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
+        // Initialize package.json (only for real npm agents)
+        const packageJson = {
+            name: `agents-${agent}-${version}`,
+            version: '1.0.0',
+            private: true,
+        };
+        fs.writeFileSync(path.join(versionDir, 'package.json'), JSON.stringify(packageJson, null, 2));
+        // Install the package. `version` is always concrete here (`latest`/`oldest`
+        // were resolved above), so the spec is always pinned. The `@` prefix is
+        // load-bearing: it ensures `version` (which VERSION_RE permits to start with
+        // `-`) is never passed as a standalone npm CLI flag.
+        const packageSpec = `${agentConfig.npmPackage}@${version}`;
+        // Set once the install has passed its integrity gate; read after the try so
+        // the success path's bookkeeping sits outside the catch's cleanup.
+        let healthyVersion;
+        try {
+            // Check npm is available
+            const winShell = process.platform === 'win32';
             try {
-                ensureClaudeInsideSymlink(installedVersion);
+                await execFileAsync('npm', ['--version'], { shell: winShell });
             }
             catch {
-                /* non-fatal; the install itself succeeded */
+                return {
+                    success: false,
+                    installedVersion: version,
+                    error: 'npm is not installed. Install Node.js and npm first: https://nodejs.org/',
+                };
             }
-        }
-        // The `npm install` above ran with `--ignore-scripts` — the right posture for
-        // the dependency TREE (never run arbitrary transitive postinstalls), but it
-        // also skips the agent package's OWN postinstall, which for some agents is a
-        // required install step. @anthropic-ai/claude-code ships a ~500-byte stub at
-        // `bin/claude.exe` plus per-arch native binaries as optional deps; its
-        // `postinstall` (`node install.cjs`) is what copies the correct native binary
-        // over the stub. Skip it and every launch dies with "native binary not
-        // installed". So run the first-party package's declared postinstall here —
-        // scoped to that one package, never `prepare` (claude-code's `prepare` is an
-        // unconditional `exit 1` publish guard). Same precedent as the keychain-helper
-        // postinstall re-run after a `--ignore-scripts` upgrade (see index.ts).
-        // Best-effort: the integrity gate below is the real backstop — a still-broken
-        // binary (postinstall failed, or a platform with no published native dep)
-        // fails there with the correct message rather than throwing here.
-        if (agentConfig.npmPackage) {
-            // `installedVersion === version`, so this is exactly `versionDir` — the
-            // install landed in its final dir with no rename to chase.
-            const pkgRoot = path.join(versionDir, 'node_modules', agentConfig.npmPackage);
-            try {
-                const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf-8'));
-                const postinstall = pkg?.scripts?.postinstall;
-                if (typeof postinstall === 'string' && postinstall.trim()) {
-                    onProgress?.(`Running ${agentConfig.name} postinstall...`);
-                    // The declared postinstall is a shell command string (e.g. `node
-                    // install.cjs`), so it must run through a shell on ALL platforms —
-                    // shell:true, empty args. cwd is the package root; install.cjs anchors
-                    // its paths to __dirname, so that is correct and sufficient.
-                    await execFileAsync(postinstall, [], { cwd: pkgRoot, shell: true });
+            onProgress?.(`Installing ${packageSpec}...`);
+            await execFileAsync('npm', ['install', packageSpec, '--ignore-scripts'], { cwd: versionDir, shell: winShell });
+            // The release installed directly into its final labeled dir (`versionDir` is
+            // keyed on `label`) — no post-install rename, no shared `latest/` dir for a
+            // concurrent process to move out from under us. The addressable slot is the
+            // label; `releaseVersion` is what npm actually staged.
+            const installedVersion = label;
+            // Create versioned alias (e.g., claude@2.0.65, or claude@ins_… for connect)
+            createVersionedAlias(agent, installedVersion);
+            // Claude reads its global config from CLAUDE_CONFIG_DIR/.claude.json —
+            // i.e. inside the per-version .claude dir — while the rest of agents-cli
+            // manages the home-level file. Symlink INSIDE to OUTSIDE so Claude and
+            // agents-cli see the same content.
+            if (agent === 'claude') {
+                try {
+                    ensureClaudeInsideSymlink(installedVersion);
+                }
+                catch {
+                    /* non-fatal; the install itself succeeded */
                 }
             }
-            catch {
-                /* non-fatal; the integrity gate below catches a still-broken binary */
+            // The `npm install` above ran with `--ignore-scripts` — the right posture for
+            // the dependency TREE (never run arbitrary transitive postinstalls), but it
+            // also skips the agent package's OWN postinstall, which for some agents is a
+            // required install step. @anthropic-ai/claude-code ships a ~500-byte stub at
+            // `bin/claude.exe` plus per-arch native binaries as optional deps; its
+            // `postinstall` (`node install.cjs`) is what copies the correct native binary
+            // over the stub. Skip it and every launch dies with "native binary not
+            // installed". So run the first-party package's declared postinstall here —
+            // scoped to that one package, never `prepare` (claude-code's `prepare` is an
+            // unconditional `exit 1` publish guard). Same precedent as the keychain-helper
+            // postinstall re-run after a `--ignore-scripts` upgrade (see index.ts).
+            // Best-effort: the integrity gate below is the real backstop — a still-broken
+            // binary (postinstall failed, or a platform with no published native dep)
+            // fails there with the correct message rather than throwing here.
+            if (agentConfig.npmPackage) {
+                // The install landed in `versionDir` (the labeled dir) with no rename to
+                // chase, so the package root is exactly there.
+                const pkgRoot = path.join(versionDir, 'node_modules', agentConfig.npmPackage);
+                try {
+                    const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf-8'));
+                    const postinstall = pkg?.scripts?.postinstall;
+                    if (typeof postinstall === 'string' && postinstall.trim()) {
+                        onProgress?.(`Running ${agentConfig.name} postinstall...`);
+                        // The declared postinstall is a shell command string (e.g. `node
+                        // install.cjs`), so it must run through a shell on ALL platforms —
+                        // shell:true, empty args. cwd is the package root; install.cjs anchors
+                        // its paths to __dirname, so that is correct and sufficient.
+                        await execFileAsync(postinstall, [], { cwd: pkgRoot, shell: true });
+                    }
+                }
+                catch {
+                    /* non-fatal; the integrity gate below catches a still-broken binary */
+                }
+            }
+            // Integrity gate: confirm the install actually launches, not just that the
+            // JS wrapper landed. A gutted install (wrapper present, native platform
+            // binary missing) otherwise gets silently pinned as the default and crashes
+            // with ENOENT on run. Fail loudly here so `agents add` never records a
+            // broken version as healthy — the caller then won't set it as default.
+            const health = await verifyInstalledBinaryLaunches(agent, installedVersion);
+            if (!health.ok) {
+                if (fs.existsSync(versionDir))
+                    removeInstallArtifacts(versionDir);
+                const detail = health.detail ? ` (${health.detail})` : '';
+                emit('version.install', { agent, version: installedVersion, error: `binary failed to launch${detail}` });
+                return {
+                    success: false,
+                    installedVersion,
+                    error: `${agentConfig.name}@${installedVersion} installed but its binary failed to launch${detail}. `
+                        + `The install is incomplete — the platform binary is missing. Re-run: agents add ${agent}@${installedVersion}`,
+                };
             }
+            // The install is healthy from here. Identity is frozen AFTER the try (see
+            // below) so a bookkeeping write failure cannot fall into the catch and wipe
+            // a working install.
+            healthyVersion = installedVersion;
         }
-        // Integrity gate: confirm the install actually launches, not just that the
-        // JS wrapper landed. A gutted install (wrapper present, native platform
-        // binary missing) otherwise gets silently pinned as the default and crashes
-        // with ENOENT on run. Fail loudly here so `agents add` never records a
-        // broken version as healthy — the caller then won't set it as default.
-        const health = await verifyInstalledBinaryLaunches(agent, installedVersion);
-        if (!health.ok) {
-            if (fs.existsSync(versionDir))
+        catch (err) {
+            // Clean up on failure — preserve `home/` in case a prior install left
+            // conversation history behind that we must not wipe on a failed reinstall.
+            if (fs.existsSync(versionDir)) {
                 removeInstallArtifacts(versionDir);
-            const detail = health.detail ? ` (${health.detail})` : '';
-            emit('version.install', { agent, version: installedVersion, error: `binary failed to launch${detail}` });
-            return {
-                success: false,
-                installedVersion,
-                error: `${agentConfig.name}@${installedVersion} installed but its binary failed to launch${detail}. `
-                    + `The install is incomplete — the platform binary is missing. Re-run: agents add ${agent}@${installedVersion}`,
-            };
-        }
-        // The install is healthy from here. Identity is frozen AFTER the try (see
-        // below) so a bookkeeping write failure cannot fall into the catch and wipe
-        // a working install.
-        healthyVersion = installedVersion;
-    }
-    catch (err) {
-        // Clean up on failure — preserve `home/` in case a prior install left
-        // conversation history behind that we must not wipe on a failed reinstall.
-        if (fs.existsSync(versionDir)) {
-            removeInstallArtifacts(versionDir);
+            }
+            emit('version.install', { agent, version, error: err.message });
+            return { success: false, installedVersion: version, error: err.message };
+        }
+        // Freeze this installation's identity (see the installScript branch above).
+        // The label is the frozen identity; the release it carries is recorded
+        // separately so a connect home under an opaque label records the real vendor
+        // release it installed rather than the label string.
+        createInstallation(agent, healthyVersion, releaseVersion, initialUpdatePolicy);
+        const trackerInstall = await installSessionTrackerHook(agent, healthyVersion);
+        if (!trackerInstall.installed && trackerInstall.error) {
+            console.warn(`agents: SessionStart hook not installed for ${agent}@${healthyVersion}: ${trackerInstall.error}`);
         }
-        emit('version.install', { agent, version, error: err.message });
-        return { success: false, installedVersion: version, error: err.message };
-    }
-    // Freeze this installation's identity (see the installScript branch above).
-    createInstallation(agent, healthyVersion, healthyVersion);
-    const trackerInstall = await installSessionTrackerHook(agent, healthyVersion);
-    if (!trackerInstall.installed && trackerInstall.error) {
-        console.warn(`agents: SessionStart hook not installed for ${agent}@${healthyVersion}: ${trackerInstall.error}`);
-    }
-    emit('version.install', { agent, version: healthyVersion });
-    return { success: true, installedVersion: healthyVersion };
+        emit('version.install', { agent, version: healthyVersion });
+        return { success: true, installedVersion: healthyVersion };
+    }, { ...INSTALLATION_LOCK_OPTIONS, realpath: false });
 }
 // Version-dir entries that are STATE, not install output, and so must survive a
 // clean reinstall: `home/`, the `.isolated` marker that is the single source
@@ -1328,7 +1362,7 @@ export async function installVersion(agent, version, onProgress, opts) {
 // self-heal would hand it a bare `<agent>` shim and a PATH entry. Losing the
 // installation record would mint a NEW id for the same install on its first
 // repair, discarding its release history.
-const PRESERVED_ON_CLEAN_REINSTALL = new Set(['home', '.isolated', INSTALLATION_RECORD_FILE]);
+const PRESERVED_ON_CLEAN_REINSTALL = new Set(['home', '.isolated', '.launch-leases', INSTALLATION_RECORD_FILE, `${INSTALLATION_RECORD_FILE}.lock`]);
 /**
  * Remove install artifacts from a version directory, preserving `home/` which
  * contains the user's conversation history, sessions, history.jsonl, tasks,
@@ -1339,7 +1373,7 @@ const PRESERVED_ON_CLEAN_REINSTALL = new Set(['home', '.isolated', INSTALLATION_
  */
 function removeInstallArtifacts(versionDir) {
     for (const entry of fs.readdirSync(versionDir)) {
-        if (PRESERVED_ON_CLEAN_REINSTALL.has(entry))
+        if (PRESERVED_ON_CLEAN_REINSTALL.has(entry) || entry.startsWith('.rollback-'))
             continue;
         fs.rmSync(path.join(versionDir, entry), { recursive: true, force: true });
     }
@@ -1906,7 +1940,8 @@ export async function ensureAgentRunnable(agent, version, log, opts) {
     // so isolation must be decided from the pre-repair state, not re-read after.
     const targetIsolated = isVersionIsolated(agent, version);
     log?.(`${cfg.name}@${version} is broken (platform binary missing) — repairing…`);
-    const repair = await installVersion(agent, version, undefined, { clean: true });
+    const record = readInstallation(agent, version);
+    const repair = await installVersion(agent, record?.releaseVersion ?? version, undefined, { clean: true, installationLabel: version });
     if (repair.success && (await verifyInstalledBinaryLaunches(agent, version)).ok) {
         log?.(`repaired ${cfg.name}@${version}.`);
         return version;
@@ -1914,7 +1949,7 @@ export async function ensureAgentRunnable(agent, version, log, opts) {
     // An isolated copy is walled off from the rest of the setup: repairing it in
     // place is the ONLY thing we may do. No fallback, no install, no default
     // switch — surface the failure and let the caller tell the user.
-    if (targetIsolated) {
+    if (targetIsolated || (record && record.label !== record.releaseVersion)) {
         log?.(`${cfg.name}@${version} is an isolated install and could not be repaired — leaving your default ${cfg.name} untouched.`);
         return null;
     }

package/dist/lib/platform/process.d.ts

@@ -78,4 +78,6 @@ export declare function isAlive(pid: number): boolean;
  * caller there silently ran with NO pid-reuse protection — including
  * `agents teams stop`, which is how it could SIGKILL an unrelated process group.
  */
-export declare function captureProcessStartTime(pid: number): string | null;
+export declare function captureProcessStartTime(pid: number, opts?: {
+    fresh?: boolean;
+}): string | null;

package/dist/lib/platform/process.js

@@ -158,11 +158,11 @@ const startTimeByPid = new Map();
  * caller there silently ran with NO pid-reuse protection — including
  * `agents teams stop`, which is how it could SIGKILL an unrelated process group.
  */
-export function captureProcessStartTime(pid) {
+export function captureProcessStartTime(pid, opts = {}) {
     if (!Number.isInteger(pid) || pid <= 0)
         return null;
     const cached = startTimeByPid.get(pid);
-    if (cached !== undefined)
+    if (!opts.fresh && cached !== undefined)
         return cached;
     const value = readProcessStartTime(pid);
     startTimeByPid.set(pid, value);

package/dist/lib/staleness/detectors/commands.d.ts

@@ -1,3 +1,2 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
-export declare const commandsDetectors: Partial<Record<AgentId, ResourceDetector>>;
+export declare const commandsDetectors: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceDetector>>;

package/dist/lib/staleness/detectors/hooks.d.ts

@@ -1,3 +1,2 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
-export declare const hooksDetectors: Partial<Record<AgentId, ResourceDetector>>;
+export declare const hooksDetectors: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceDetector>>;

package/dist/lib/staleness/detectors/mcp.d.ts

@@ -1,3 +1,2 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
-export declare const mcpDetectors: Partial<Record<AgentId, ResourceDetector>>;
+export declare const mcpDetectors: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceDetector>>;

package/dist/lib/staleness/detectors/permissions.d.ts

@@ -1,3 +1,2 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
-export declare const permissionsDetectors: Partial<Record<AgentId, ResourceDetector>>;
+export declare const permissionsDetectors: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceDetector>>;

package/dist/lib/staleness/detectors/plugins.d.ts

@@ -1,8 +1,2 @@
-/**
- * Plugins detector — for each discovered plugin, ask `isPluginSynced` whether
- * its expected artifacts are present in the version home. Mirrors
- * versions.ts:541-549.
- */
-import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
-export declare const pluginsDetectors: Partial<Record<AgentId, ResourceDetector>>;
+export declare const pluginsDetectors: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceDetector>>;

package/dist/lib/staleness/detectors/rules.d.ts

@@ -1,3 +1,2 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
-export declare const rulesDetectors: Partial<Record<AgentId, ResourceDetector>>;
+export declare const rulesDetectors: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceDetector>>;

package/dist/lib/staleness/detectors/skills.d.ts

@@ -1,5 +1,4 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
 /** Exported for unit tests (RUSH-2320 #2). Production callers: list() below. */
 export declare function skillDirsMatch(src: string, dest: string): boolean;
-export declare const skillsDetectors: Partial<Record<AgentId, ResourceDetector>>;
+export declare const skillsDetectors: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceDetector>>;

package/dist/lib/staleness/detectors/subagents.d.ts

@@ -1,8 +1,2 @@
-/**
- * Subagents detector. The installed-name enumeration for every agent's on-disk
- * layout is declared once in the subagent registry; this detector is generic
- * and delegates to `listInstalledSubagentNames` instead of a per-agent builder.
- */
-import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
-export declare const subagentsDetectors: Partial<Record<AgentId, ResourceDetector>>;
+export declare const subagentsDetectors: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceDetector>>;

package/dist/lib/staleness/detectors/workflows.d.ts

@@ -1,3 +1,2 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
-export declare const workflowsDetectors: Partial<Record<AgentId, ResourceDetector>>;
+export declare const workflowsDetectors: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceDetector>>;

package/dist/lib/staleness/writers/commands.d.ts

@@ -1,3 +1,2 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceWriter } from './types.js';
-export declare const commandsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;
+export declare const commandsWriters: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/hooks.d.ts

@@ -1,3 +1,2 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceWriter } from './types.js';
-export declare const hooksWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;
+export declare const hooksWriters: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/mcp.d.ts

@@ -1,3 +1,2 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceWriter } from './types.js';
-export declare const mcpWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;
+export declare const mcpWriters: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/permissions.d.ts

@@ -1,13 +1,2 @@
-/**
- * Permissions writer — selection is a list of permission GROUP names. We
- * build the PermissionSet from the discovered groups, then dispatch into the
- * per-agent format writer in `lib/permissions.ts:applyPermissionsToVersion`.
- *
- * The per-agent format work lives in lib/permissions.ts because the format
- * conversions (Claude settings.json vs Codex TOML+rules vs Gemini tools vs
- * Antigravity permissions{} vs Grok [permission].rules) are tightly coupled
- * to the converters defined alongside them.
- */
-import type { AgentId } from '../../types.js';
 import type { ResourceWriter } from './types.js';
-export declare const permissionsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;
+export declare const permissionsWriters: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/plugins.d.ts

@@ -1,7 +1,2 @@
-/**
- * Plugins writer — thin wrapper around `syncPluginToVersion`. Discovery and
- * per-agent format work lives in lib/plugins.ts.
- */
-import type { AgentId } from '../../types.js';
 import type { ResourceWriter } from './types.js';
-export declare const pluginsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;
+export declare const pluginsWriters: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/rules.d.ts

@@ -1,7 +1,6 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceWriter } from './types.js';
 export interface RulesSelection {
     /** Preset name to compose. Empty string falls through to `"default"` in the composer. */
     preset: string;
 }
-export declare const rulesWriters: Partial<Record<AgentId, ResourceWriter<RulesSelection>>>;
+export declare const rulesWriters: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceWriter<RulesSelection>>>;

package/dist/lib/staleness/writers/skills.d.ts

@@ -1,3 +1,2 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceWriter } from './types.js';
-export declare const skillsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;
+export declare const skillsWriters: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/subagents.d.ts

@@ -1,3 +1,2 @@
-import type { AgentId } from '../../types.js';
 import type { ResourceWriter } from './types.js';
-export declare const subagentsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;
+export declare const subagentsWriters: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceWriter<string[]>>>;

package/dist/lib/staleness/writers/workflows.d.ts

@@ -1,9 +1,2 @@
-/**
- * Workflows writer — copies each selected workflow into the agent-specific
- * on-disk layout via `syncWorkflowToVersion` (Claude: WORKFLOW.md tree under
- * `{versionHome}/workflows/`; Grok: native `.rhai` under
- * `{versionHome}/.grok/workflows/`).
- */
-import type { AgentId } from '../../types.js';
 import type { ResourceWriter } from './types.js';
-export declare const workflowsWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;
+export declare const workflowsWriters: Partial<Record<"claude" | "codex" | "gemini" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceWriter<string[]>>>;

package/dist/lib/state.d.ts

@@ -475,7 +475,9 @@ export declare function writeMetaUnlocked(meta: Meta): boolean;
  *   mtime check below catches it on the next read (assuming the mtime advanced).
  * - The cache stores the merged system+user meta; both files' mtimes contribute.
  */
-export declare function readMeta(): Meta;
+export declare function readMeta(options?: {
+    migrate?: boolean;
+}): Meta;
 /** Serialize and write agents.yaml to the user repo, invalidating the in-memory cache. */
 export declare function writeMeta(meta: Meta): void;
 /** Update agents.yaml under lock and return the new state. */