@phnx-labs/agents-cli 1.22.31 → 1.22.33

package/dist/lib/drift.js

@@ -60,6 +60,12 @@ export function checkSyncStatus(cwd) {
             // never fires. Surface that for every version, fresh or stale, so overview
             // AND `agents doctor --check` flag it (claude/droid; other agents report unsupported).
             const wiring = checkVersionHookWiring(agent, version);
+            if (wiring.runtimeBroken.length > 0) {
+                row.brokenHookRuntime = wiring.runtimeBroken.length;
+                const names = wiring.runtimeBroken.map((issue) => issue.name);
+                const shown = names.slice(0, 3).join(', ');
+                divergence.push(`hooks       ${names.length} generated wrapper${names.length === 1 ? '' : 's'} broken (${shown}${names.length > 3 ? ', …' : ''})`);
+            }
             if (wiring.supported) {
                 const expected = wiring.expected ?? 0;
                 if (wiring.settingsMissing && expected > 0) {
@@ -147,6 +153,7 @@ export function computeDrift(cwd) {
     const staleCount = syncRows.filter((r) => r.status === 'stale').length;
     const neverSyncedCount = syncRows.filter((r) => r.status === 'never-synced').length;
     const unwiredHookVersions = syncRows.filter((r) => (r.unwiredHooks ?? 0) > 0).length;
+    const brokenHookRuntimeVersions = syncRows.filter((r) => (r.brokenHookRuntime ?? 0) > 0).length;
     const sourceBehind = computeSourceBehind();
     return {
         syncRows,
@@ -155,9 +162,11 @@ export function computeDrift(cwd) {
         neverSyncedCount,
         orphanVersionCount: orphanRows.length,
         unwiredHookVersions,
+        brokenHookRuntimeVersions,
         sourceBehind,
         hasDrift: syncRows.some((r) => r.status !== 'fresh') ||
             unwiredHookVersions > 0 ||
+            brokenHookRuntimeVersions > 0 ||
             sourceBehind.length > 0,
     };
 }

package/dist/lib/hooks/cache.js

@@ -18,6 +18,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import * as crypto from 'crypto';
 import { getHookCacheDir, getHookShimsDir, getLogsDir, getPerfDir } from '../state.js';
 /**
  * Parse a `cache:` value from hooks.yaml into the canonical config form.
@@ -128,7 +129,25 @@ export function generateHookShim(args) {
         catch { /* rewrite */ }
     }
     if (existing !== content) {
-        fs.writeFileSync(shimPath, content, { mode: 0o755 });
+        // A hook may fire while a background self-heal repairs another stale shim.
+        // Write in the destination directory and rename only after its mode and
+        // complete contents are ready, so observers see either the old complete
+        // wrapper or the new complete wrapper — never a truncated shell script.
+        const tempPath = path.join(shimsDir, `.${path.basename(shimPath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+        try {
+            fs.writeFileSync(tempPath, content, { mode: 0o755 });
+            fs.chmodSync(tempPath, 0o755);
+            fs.renameSync(tempPath, shimPath);
+        }
+        finally {
+            // Rename removes the temp path on success. On a failed write/rename this
+            // best-effort cleanup prevents a bounded repair failure from leaving
+            // growing debris behind for every periodic pass.
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch { /* already renamed or unavailable */ }
+        }
     }
     else {
         // Ensure exec bit even when content unchanged (file mode can drift).

package/dist/lib/hooks.d.ts

@@ -28,7 +28,7 @@ export declare function toPortableCommand(absPath: string, home?: string, sep?:
  * outside version homes are user-owned and remain untouched.
  */
 export declare function deduplicateVersionHookCommands(commands: string[], activeVersionHome: string): string[];
-import type { AgentId, InstalledHook, ManifestHook } from './types.js';
+import type { AgentId, HookCacheConfig, HookMatches, InstalledHook, ManifestHook } from './types.js';
 export type HookEntry = {
     name: string;
     scriptPath: string;
@@ -110,6 +110,27 @@ export interface HookWiringIssue {
     /** The command the harness-native config should reference under `event`. */
     command: string;
 }
+/** A generated, agents-managed hook wrapper and the inputs needed to recreate it. */
+export interface ManagedHookRuntimeArtifact {
+    agent: AgentId;
+    version: string;
+    name: string;
+    scriptPath: string;
+    shimPath: string;
+    cache: HookCacheConfig | null;
+    matches?: HookMatches;
+}
+/** A generated hook wrapper that is referenced by managed configuration but cannot run. */
+export interface BrokenManagedHookRuntimeArtifact extends ManagedHookRuntimeArtifact {
+    /** Stable, human-readable filesystem failure; the hook is never executed to find it. */
+    reason: string;
+}
+/** Public, doctor-safe shape for a broken generated hook wrapper. */
+export interface HookRuntimeIssue {
+    name: string;
+    path: string;
+    reason: string;
+}
 export interface HookWiringReport {
     /** Whether this agent's hook config format is understood by the inspector. */
     supported: boolean;
@@ -128,7 +149,76 @@ export interface HookWiringReport {
      *  Empty whenever wiring cannot be verified (unsupported family, missing or
      *  unparseable settings). */
     wired: HookWiringIssue[];
+    /** Generated agents-managed wrappers that are absent or unusable. This is
+     * independent of whether the native config format itself is understood. */
+    runtimeBroken: HookRuntimeIssue[];
+}
+/** Inspect managed generated hook wrappers without executing user hook code. */
+export declare function inspectBrokenManagedHookRuntimeArtifacts(filter?: {
+    agent?: AgentId;
+    version?: string;
+}, platform?: NodeJS.Platform): BrokenManagedHookRuntimeArtifact[];
+/** Outcome of one generation attempt for a unique shim path. */
+export interface HookRuntimeRepairAttempt {
+    name: string;
+    path: string;
+    reasonBefore: string;
+    /** True when generateHookShim ran for this path in this pass. */
+    attempted: boolean;
+    repaired: boolean;
+    /** Stable failure text when not repaired after an attempt (or dry-run skip). */
+    reason?: string;
+}
+/**
+ * Result of one bounded repair pass over agents-managed generated hook shims.
+ * Shared by self-heal and doctor --fix; additive types for the doctor track.
+ */
+export interface HookRuntimeRepairReport {
+    /** Broken artifacts found before any write (inspect-only snapshot). */
+    brokenBefore: BrokenManagedHookRuntimeArtifact[];
+    /** Unique shim paths considered for generation in this pass. */
+    attemptedPaths: string[];
+    attempts: HookRuntimeRepairAttempt[];
+    /** Human-readable lines for CheckResult.fixed (includes dry-run would-fix). */
+    fixed: string[];
+    /** Human-readable lines for CheckResult.needsAttention — stable wording. */
+    needsAttention: string[];
 }
+export interface RepairManagedHookRuntimeOptions {
+    /** Detect only — never write. Default false. */
+    dryRun?: boolean;
+    filter?: {
+        agent?: AgentId;
+        version?: string;
+    };
+    platform?: NodeJS.Platform;
+}
+/**
+ * Regenerate one known-broken wrapper and prove the result is usable. Callers
+ * provide a snapshot from inspectBrokenManagedHookRuntimeArtifacts; this never
+ * loops or retries and returns a stable error for the current pass.
+ *
+ * Generation is delegated to generateHookShim (idempotent — preserves mtime when
+ * content already matches). This path never calls registerHooksToSettings,
+ * installHooks, or any sync routine.
+ */
+export declare function repairManagedHookRuntimeArtifact(artifact: ManagedHookRuntimeArtifact, platform?: NodeJS.Platform): {
+    repaired: boolean;
+    reason?: string;
+};
+/**
+ * Bounded repair of all broken agents-managed generated hook shims.
+ *
+ * - Inspect first (read-only, no hook execution).
+ * - One generation attempt per unique shim path per call (no retry, no timer).
+ * - Canonical owner per shared path: global default, else newest non-isolated.
+ * - Post-repair reinspection; unresolved findings become stable needsAttention.
+ * - Never recurses into resource sync / registerHooksToSettings.
+ *
+ * This is the shared routine used by the self-heal `hook-runtime` check and
+ * exported for the doctor track.
+ */
+export declare function repairManagedHookRuntimeArtifacts(opts?: RepairManagedHookRuntimeOptions): HookRuntimeRepairReport;
 /**
  * Verify that every hook the manifest says should be wired is actually
  * referenced in that version's harness-native config, not merely present as a

package/dist/lib/hooks.js

@@ -264,7 +264,7 @@ function collapseVersionHookEntries(entries, activeVersionHome) {
         return true;
     });
 }
-import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
+import { getEffectiveHome, getGlobalDefault, getVersionHomePath, isVersionIsolated, listInstalledVersions, resolveVersion, } from './versions.js';
 import { generateHookShim, getHookShimPath, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
 import { getHookShimsDir } from './state.js';
 function hookContentHash(scriptPath) {
@@ -772,6 +772,285 @@ export function listHooksInVersionHome(agent, version) {
 const SETTINGS_JSON_HOOK_FAMILY = ['claude', 'droid', 'muse'];
 const HOOKS_JSON_HOOK_FAMILY = ['grok'];
 const TOML_ARRAY_HOOK_FAMILY = ['kimi'];
+/**
+ * Check the filesystem properties a shell hook needs without invoking it. A
+ * dangling symlink is deliberately distinguished from an absent file because
+ * the repair/remediation is the same but the diagnostic is materially clearer.
+ */
+function shellQuoteForHookShim(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function hookRuntimeProblem(artifact, platform = process.platform) {
+    const { shimPath } = artifact;
+    let link;
+    try {
+        link = fs.lstatSync(shimPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            return 'missing';
+        // Stable: errno code only — never absolute path text (fleet/menu aggregation).
+        return `cannot inspect (${code || 'error'})`;
+    }
+    let target;
+    try {
+        target = link.isSymbolicLink() ? fs.statSync(shimPath) : link;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            return 'broken symlink';
+        return `cannot inspect (${code || 'error'})`;
+    }
+    if (!target.isFile())
+        return 'not a regular file';
+    // Generation always writes non-empty content; an empty placeholder is broken.
+    if (target.size === 0)
+        return 'broken (empty)';
+    // Windows does not use a POSIX executable bit; requiring it there would
+    // continuously rewrite healthy .sh files on Windows hosts.
+    if (platform !== 'win32' && (target.mode & 0o111) === 0)
+        return 'not executable';
+    try {
+        const body = fs.readFileSync(shimPath, 'utf-8');
+        // The global shim must name the selected live version-home script. A
+        // wrapper can remain executable while its SOURCE points to an older or
+        // deleted version; detect that without running either script.
+        if (!body.includes(`SOURCE=${shellQuoteForHookShim(artifact.scriptPath)}`)) {
+            return 'source mismatch';
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        return `cannot inspect (${code || 'error'})`;
+    }
+    return null;
+}
+/**
+ * Gather managed generated-shim expectations for one installed version. The
+ * script must resolve inside that version home (or be an existing absolute
+ * subrule), matching the registrar's selection rules. This function never
+ * creates a shim or runs a hook.
+ */
+function managedHookRuntimeArtifactsForVersion(agent, version) {
+    if (!AGENTS[agent].supportsHooks)
+        return [];
+    const localHooksDir = getVersionHooksDir(agent, version);
+    const resolveScript = (script) => {
+        if (path.isAbsolute(script) && fs.existsSync(script))
+            return script;
+        return resolveContainedHookPath(localHooksDir, script);
+    };
+    const artifacts = [];
+    for (const [name, hookDef] of Object.entries(parseHookManifest({ warn: false }))) {
+        if (!hookDef.events || hookDef.events.length === 0 || !isValidHookShimName(name))
+            continue;
+        const scriptPath = resolveScript(hookDef.script);
+        if (!scriptPath)
+            continue;
+        const cache = parseCacheConfig(hookDef.cache);
+        const hasMatches = hookDef.matches != null && Object.keys(hookDef.matches).length > 0;
+        if (!cache && !hasMatches && !hookDef.matcher)
+            continue;
+        artifacts.push({
+            agent,
+            version,
+            name,
+            scriptPath,
+            shimPath: getHookShimPath(name),
+            cache,
+            matches: hookDef.matches,
+        });
+    }
+    return artifacts;
+}
+/** Inspect managed generated hook wrappers without executing user hook code. */
+export function inspectBrokenManagedHookRuntimeArtifacts(filter, platform = process.platform) {
+    // Generated destinations are shared across every harness. Always select the
+    // owner from the global population first; an agent-scoped doctor call may
+    // restrict which shim names are relevant, but must not change the expected
+    // SOURCE for a shared wrapper.
+    const versions = iterHooksCapableVersions();
+    if (filter?.agent &&
+        filter.version &&
+        !versions.some((v) => v.agent === filter.agent && v.version === filter.version)) {
+        versions.push({ agent: filter.agent, version: filter.version });
+    }
+    const artifacts = [];
+    for (const { agent, version } of versions) {
+        artifacts.push(...managedHookRuntimeArtifactsForVersion(agent, version));
+    }
+    const requestedArtifacts = filter?.agent
+        ? artifacts.filter((artifact) => artifact.agent === filter.agent &&
+            (!filter.version || artifact.version === filter.version))
+        : undefined;
+    const relevantShimPaths = requestedArtifacts
+        ? new Set(eligibleHookRuntimeArtifacts(requestedArtifacts).map((artifact) => artifact.shimPath))
+        : undefined;
+    const broken = [];
+    for (const artifact of selectCanonicalHookRuntimeArtifacts(artifacts)) {
+        if (relevantShimPaths && !relevantShimPaths.has(artifact.shimPath))
+            continue;
+        const reason = hookRuntimeProblem(artifact, platform);
+        if (reason)
+            broken.push({ ...artifact, reason });
+    }
+    return broken.sort((a, b) => a.shimPath.localeCompare(b.shimPath) ||
+        `${a.agent}@${a.version}/${a.name}`.localeCompare(`${b.agent}@${b.version}/${b.name}`));
+}
+/**
+ * Prefer the agent's global default when it appears in the candidate set;
+ * otherwise the newest non-isolated version. Shared shim paths embed a single
+ * SOURCE script — picking the wrong version permanently points every harness
+ * at a stale or dead path.
+ */
+function pickCanonicalHookRuntimeArtifact(candidates) {
+    if (candidates.length === 1)
+        return candidates[0];
+    const agents = Array.from(new Set(candidates.map((c) => c.agent))).sort();
+    for (const agent of agents) {
+        const defaultVersion = getGlobalDefault(agent);
+        if (!defaultVersion || isVersionIsolated(agent, defaultVersion))
+            continue;
+        const active = candidates.find((c) => c.agent === agent && c.version === defaultVersion);
+        if (active)
+            return active;
+    }
+    // listInstalledVersions is the canonical semver ordering. Scan backward
+    // rather than inventing another version comparator at this call site.
+    for (const agent of agents) {
+        for (const version of [...listInstalledVersions(agent)].reverse()) {
+            const newest = candidates.find((c) => c.agent === agent && c.version === version);
+            if (newest)
+                return newest;
+        }
+    }
+    return candidates[0];
+}
+/**
+ * One repair target per unique shim path. Generated shims are global, so both
+ * unattended and explicit repair leave isolated/private version homes out.
+ */
+function selectCanonicalHookRuntimeArtifacts(artifacts) {
+    // No hook runtime exists for a version that does not support hooks. Isolated
+    // versions never own a global generated shim, even when a caller names one:
+    // selecting it would repoint every harness at a private version home.
+    const pool = eligibleHookRuntimeArtifacts(artifacts);
+    const byPath = new Map();
+    for (const artifact of pool) {
+        const list = byPath.get(artifact.shimPath) ?? [];
+        list.push(artifact);
+        byPath.set(artifact.shimPath, list);
+    }
+    const selected = [];
+    for (const group of byPath.values()) {
+        selected.push(pickCanonicalHookRuntimeArtifact(group));
+    }
+    return selected;
+}
+/** Versions that may own — and therefore diagnose — a shared generated shim. */
+function eligibleHookRuntimeArtifacts(artifacts) {
+    return artifacts.filter((artifact) => supports(artifact.agent, 'hooks', artifact.version).ok &&
+        !isVersionIsolated(artifact.agent, artifact.version));
+}
+/**
+ * Stable failure text: errno code + detector reason only.
+ * Never include absolute paths or randomized atomic-temp basenames — those
+ * break cross-device / menu-bar aggregation of identical failures. The hook
+ * name is attached by the caller (`hook shim <name>: …`).
+ */
+function stableHookRuntimeRepairFailure(before, err) {
+    const code = err?.code;
+    return `repair failed [${code || 'UNKNOWN'}]: ${before}`;
+}
+/**
+ * Regenerate one known-broken wrapper and prove the result is usable. Callers
+ * provide a snapshot from inspectBrokenManagedHookRuntimeArtifacts; this never
+ * loops or retries and returns a stable error for the current pass.
+ *
+ * Generation is delegated to generateHookShim (idempotent — preserves mtime when
+ * content already matches). This path never calls registerHooksToSettings,
+ * installHooks, or any sync routine.
+ */
+export function repairManagedHookRuntimeArtifact(artifact, platform = process.platform) {
+    const before = hookRuntimeProblem(artifact, platform);
+    // Already healthy (e.g. race with another pass) — no-op, no needsAttention.
+    if (!before)
+        return { repaired: false };
+    try {
+        generateHookShim({
+            name: artifact.name,
+            scriptPath: artifact.scriptPath,
+            cache: artifact.cache,
+            matches: artifact.matches,
+        });
+    }
+    catch (err) {
+        return { repaired: false, reason: stableHookRuntimeRepairFailure(before, err) };
+    }
+    // Post-repair reinspection — prove the artifact is usable without executing it.
+    const after = hookRuntimeProblem(artifact, platform);
+    return after
+        ? { repaired: false, reason: `${before}; repair did not produce a usable shim (${after})` }
+        : { repaired: true };
+}
+/**
+ * Bounded repair of all broken agents-managed generated hook shims.
+ *
+ * - Inspect first (read-only, no hook execution).
+ * - One generation attempt per unique shim path per call (no retry, no timer).
+ * - Canonical owner per shared path: global default, else newest non-isolated.
+ * - Post-repair reinspection; unresolved findings become stable needsAttention.
+ * - Never recurses into resource sync / registerHooksToSettings.
+ *
+ * This is the shared routine used by the self-heal `hook-runtime` check and
+ * exported for the doctor track.
+ */
+export function repairManagedHookRuntimeArtifacts(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const dryRun = opts.dryRun ?? false;
+    const brokenBefore = inspectBrokenManagedHookRuntimeArtifacts(opts.filter, platform);
+    const targets = selectCanonicalHookRuntimeArtifacts(brokenBefore);
+    const attemptedPaths = [];
+    const attempts = [];
+    const fixed = [];
+    const needsAttention = [];
+    for (const artifact of targets) {
+        attemptedPaths.push(artifact.shimPath);
+        if (dryRun) {
+            // Would-fix: same shape as a real fix so doctor dry-run and daemon previews
+            // stay consistent with other HealChecks.
+            attempts.push({
+                name: artifact.name,
+                path: artifact.shimPath,
+                reasonBefore: artifact.reason,
+                attempted: false,
+                repaired: false,
+            });
+            fixed.push(`hook shim ${artifact.name}`);
+            continue;
+        }
+        const result = repairManagedHookRuntimeArtifact(artifact, platform);
+        attempts.push({
+            name: artifact.name,
+            path: artifact.shimPath,
+            reasonBefore: artifact.reason,
+            attempted: true,
+            repaired: result.repaired,
+            reason: result.reason,
+        });
+        if (result.repaired) {
+            fixed.push(`hook shim ${artifact.name}`);
+        }
+        else if (result.reason) {
+            // Stable needs-attention wording for aggregation across devices / menubar.
+            // No reason means already-healthy no-op (race) — do not emit attention noise.
+            needsAttention.push(`hook shim ${artifact.name}: ${result.reason}`);
+        }
+    }
+    return { brokenBefore, attemptedPaths, attempts, fixed, needsAttention };
+}
 /**
  * Verify that every hook the manifest says should be wired is actually
  * referenced in that version's harness-native config, not merely present as a
@@ -787,11 +1066,16 @@ const TOML_ARRAY_HOOK_FAMILY = ['kimi'];
  * resolveHookCommand performs, so it never mutates the version home.
  */
 export function checkVersionHookWiring(agent, version) {
+    // Runtime verification does not rely on parsing a native settings format.
+    // That lets doctor catch a deleted generated shim for every hooks-capable
+    // harness, including families whose wiring schema is intentionally unsupported.
+    const runtimeBroken = inspectBrokenManagedHookRuntimeArtifacts({ agent, version })
+        .map(({ name, shimPath, reason }) => ({ name, path: shimPath, reason }));
     if (!AGENTS[agent].supportsHooks ||
         (!SETTINGS_JSON_HOOK_FAMILY.includes(agent) &&
             !HOOKS_JSON_HOOK_FAMILY.includes(agent) &&
             !TOML_ARRAY_HOOK_FAMILY.includes(agent))) {
-        return { supported: false, unwired: [], wired: [] };
+        return { supported: false, unwired: [], wired: [], runtimeBroken };
     }
     const versionHome = getVersionHomePath(agent, version);
     const settingsPath = HOOKS_JSON_HOOK_FAMILY.includes(agent)
@@ -855,6 +1139,7 @@ export function checkVersionHookWiring(agent, version) {
             settingsMissing: expected.length > 0,
             unwired: [],
             wired: [],
+            runtimeBroken,
         };
     }
     let config;
@@ -872,6 +1157,7 @@ export function checkVersionHookWiring(agent, version) {
             settingsUnparseable: true,
             unwired: [],
             wired: [],
+            runtimeBroken,
         };
     }
     // Command strings actually referenced, keyed by (event, matcher) — a hook wired
@@ -921,7 +1207,7 @@ export function checkVersionHookWiring(agent, version) {
     const isWired = (entry) => wiredByGroup.get(groupKey(entry.event, entry.matcher))?.has(entry.command) ?? false;
     const unwired = expected.filter((entry) => !isWired(entry));
     const wired = expected.filter(isWired);
-    return { supported: true, settingsPath, expected: expected.length, unwired, wired };
+    return { supported: true, settingsPath, expected: expected.length, unwired, wired, runtimeBroken };
 }
 /**
  * Check if a hook installed in a specific version matches central content.

package/dist/lib/hosts/passthrough.js

@@ -79,6 +79,9 @@ export const REMOTE_PASSTHROUGH = {
     profiles: {},
     defaults: {},
     alias: {},
+    // Installations are per-machine, so updating one on a peer means running it
+    // there — the same local/remote shape `add` would need.
+    update: {},
     // lifecycle
     teams: {},
     message: {},

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

@@ -0,0 +1,14 @@
+/**
+ * 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 { INSTALLATION_RECORD_FILE, INSTALLATION_SCHEMA, type Installation, type InstallationRelease, type UpdateOutcome, type UpdateStrategyId, } from './types.js';
+export { createInstallation, ensureInstallation, installationDir, installationRecordPath, listInstallationLabels, listInstallations, mintInstallationId, readInstallation, recordRelease, writeInstallation, } from './store.js';
+export { InstallationAmbiguousError, InstallationNotFoundError, describeInstallation, resolveInstallation, type ResolveInstallationOptions, } from './resolve.js';
+export { assertValidRelease, selectUpdateStrategy, supportsPinnedUpdate, type UpdateStrategy, } from './strategies.js';
+export { updateInstallation, type UpdateInstallationOptions } from './update.js';

package/dist/lib/installations/index.js

@@ -0,0 +1,14 @@
+/**
+ * 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 { INSTALLATION_RECORD_FILE, INSTALLATION_SCHEMA, } from './types.js';
+export { createInstallation, ensureInstallation, installationDir, installationRecordPath, listInstallationLabels, listInstallations, mintInstallationId, readInstallation, recordRelease, writeInstallation, } from './store.js';
+export { InstallationAmbiguousError, InstallationNotFoundError, describeInstallation, resolveInstallation, } from './resolve.js';
+export { assertValidRelease, selectUpdateStrategy, supportsPinnedUpdate, } from './strategies.js';
+export { updateInstallation } from './update.js';

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

@@ -0,0 +1,43 @@
+import type { AgentId } from '../types.js';
+import type { Installation } from './types.js';
+/**
+ * Addressing a frozen installation.
+ *
+ * A selector matches either the installation's stable {@link Installation.label}
+ * or the vendor release it currently carries — the label because that is what
+ * every persisted reference and every `agents add` invocation uses, the release
+ * because after an update the two differ and a user reading `agents view` may
+ * name either. Matching both is also precisely what makes duplicate same-release
+ * installations addressable at all: two installs can share a release, so the
+ * release alone is not an identifier and the ambiguity has to be reported rather
+ * than silently resolved to whichever sorted first.
+ */
+export declare class InstallationNotFoundError extends Error {
+    readonly agent: AgentId;
+    readonly selector: string | undefined;
+    readonly available: readonly Installation[];
+    constructor(agent: AgentId, selector: string | undefined, available: readonly Installation[]);
+}
+export declare class InstallationAmbiguousError extends Error {
+    readonly agent: AgentId;
+    readonly selector: string | undefined;
+    readonly candidates: readonly Installation[];
+    constructor(agent: AgentId, selector: string | undefined, candidates: readonly Installation[]);
+}
+/** `2.0.65` when frozen at its original release, `2.0.65 (release 2.0.71)` after an update. */
+export declare function describeInstallation(installation: Installation): string;
+export interface ResolveInstallationOptions {
+    /**
+     * An `agents accounts` label. Narrows to the installation currently signed
+     * into that account before the selector is applied.
+     */
+    account?: string;
+}
+/**
+ * Resolve `<agent>[@<selector>]` to exactly one installation.
+ *
+ * With no selector: the agent's default installation when one is pinned, else
+ * the sole installation. Never a "newest wins" guess — picking for the user
+ * across several installs is how an update lands on the wrong one.
+ */
+export declare function resolveInstallation(agent: AgentId, selector: string | undefined, options?: ResolveInstallationOptions): Promise<Installation>;