@phnx-labs/agents-cli 1.22.31 → 1.22.32

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>;

package/dist/lib/installations/resolve.js

@@ -0,0 +1,93 @@
+import { resolveAccountLabel } from '../account-labels.js';
+import { AGENTS } from '../agents.js';
+import { getGlobalDefault } from '../versions.js';
+import { listInstallations } from './store.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 class InstallationNotFoundError extends Error {
+    agent;
+    selector;
+    available;
+    constructor(agent, selector, available) {
+        // Nothing installed is a different problem from "your selector missed", and
+        // the remedy differs — say which one it is rather than printing an empty list.
+        super(available.length === 0
+            ? `No ${AGENTS[agent].name} installations are managed by agents-cli. Install one with: agents add ${agent}@latest`
+            : `No ${AGENTS[agent].name} installation matches '${selector}'. Installed: ${available.map((i) => describeInstallation(i)).join(', ')}`);
+        this.agent = agent;
+        this.selector = selector;
+        this.available = available;
+        this.name = 'InstallationNotFoundError';
+    }
+}
+export class InstallationAmbiguousError extends Error {
+    agent;
+    selector;
+    candidates;
+    constructor(agent, selector, candidates) {
+        super(`'${selector ?? agent}' matches ${candidates.length} ${AGENTS[agent].name} installations `
+            + `(${candidates.map((i) => describeInstallation(i)).join(', ')}). `
+            + `Name one by its installation label, or disambiguate with --account <label>.`);
+        this.agent = agent;
+        this.selector = selector;
+        this.candidates = candidates;
+        this.name = 'InstallationAmbiguousError';
+    }
+}
+/** `2.0.65` when frozen at its original release, `2.0.65 (release 2.0.71)` after an update. */
+export function describeInstallation(installation) {
+    return installation.releaseVersion === installation.label
+        ? installation.label
+        : `${installation.label} (release ${installation.releaseVersion})`;
+}
+/**
+ * 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 async function resolveInstallation(agent, selector, options = {}) {
+    const all = listInstallations(agent);
+    if (all.length === 0)
+        throw new InstallationNotFoundError(agent, selector, all);
+    let candidates = all;
+    if (options.account) {
+        // resolveAccountLabel answers with the version-dir label of the install that
+        // is signed into that account — i.e. an installation label.
+        const label = await resolveAccountLabel(agent, options.account);
+        candidates = candidates.filter((i) => i.label === label);
+        if (candidates.length === 0)
+            throw new InstallationNotFoundError(agent, selector, all);
+    }
+    if (selector) {
+        const byLabel = candidates.filter((i) => i.label === selector);
+        // A label is unique by construction (it is a directory name), so a label hit
+        // is decisive and never competes with a release hit on another installation.
+        if (byLabel.length === 1)
+            return byLabel[0];
+        const byRelease = candidates.filter((i) => i.releaseVersion === selector);
+        if (byRelease.length === 1)
+            return byRelease[0];
+        if (byRelease.length > 1)
+            throw new InstallationAmbiguousError(agent, selector, byRelease);
+        throw new InstallationNotFoundError(agent, selector, all);
+    }
+    if (candidates.length === 1)
+        return candidates[0];
+    const defaultLabel = getGlobalDefault(agent);
+    const pinned = defaultLabel ? candidates.find((i) => i.label === defaultLabel) : undefined;
+    if (pinned)
+        return pinned;
+    throw new InstallationAmbiguousError(agent, selector, candidates);
+}

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

@@ -0,0 +1,56 @@
+import type { AgentId } from '../types.js';
+import { type Installation } from './types.js';
+/**
+ * Persistence for {@link Installation} records.
+ *
+ * The record lives at `<versionDir>/installation.json` rather than in one
+ * central index: the version dir is what `agents trash`/`agents prune` move,
+ * copy and restore wholesale, so keeping identity inside it means identity
+ * travels with the install instead of dangling in a registry that forgets to
+ * follow. It is also why the file name is registered in versions.ts's
+ * `PRESERVED_ON_CLEAN_REINSTALL` — a repair reinstall must not mint a new id.
+ *
+ * Deliberately depends on nothing but `state`/`fs-atomic`/`primitives` so
+ * versions.ts can import it without an import cycle.
+ */
+/** Directory holding one installation. Mirrors versions.ts `getVersionDir`. */
+export declare function installationDir(agent: AgentId, label: string): string;
+export declare function installationRecordPath(agent: AgentId, label: string): string;
+/** Mint an opaque installation id. Random, never derived from the release. */
+export declare function mintInstallationId(): string;
+/**
+ * Read the record for one installation, or null when the version dir has none.
+ * Never mints — use {@link ensureInstallation} for the migrating read.
+ */
+export declare function readInstallation(agent: AgentId, label: string): Installation | null;
+export declare function writeInstallation(installation: Installation): void;
+/**
+ * Read the record for an existing version dir, minting and persisting one on
+ * first sight. This is the migration path for every installation created before
+ * frozen identity existed: their directory name IS their release, so the
+ * migrated record seeds `label === releaseVersion` and dates the install from
+ * the directory's own mtime rather than pretending it was created now.
+ *
+ * Throws when the version dir does not exist — an installation record must never
+ * describe an install that isn't there.
+ */
+export declare function ensureInstallation(agent: AgentId, label: string): Installation;
+/**
+ * Create the record for a freshly-installed version dir. Idempotent: a repeat
+ * `agents add` of the same label keeps the original id (identity is frozen) and
+ * only records the release if it actually moved.
+ */
+export declare function createInstallation(agent: AgentId, label: string, releaseVersion: string): Installation;
+/**
+ * Move an installation's recorded release forward, preserving identity. Returns
+ * the persisted record. Call only AFTER the new release is live on disk — the
+ * record is the claim that it is.
+ */
+export declare function recordRelease(installation: Installation, releaseVersion: string): Installation;
+/** Version-dir basenames present for an agent, oldest-first by directory name. */
+export declare function listInstallationLabels(agent: AgentId): string[];
+/**
+ * Every installation of an agent, migrating records as needed. A version dir
+ * that disappears mid-scan is skipped rather than failing the whole listing.
+ */
+export declare function listInstallations(agent: AgentId): Installation[];