@phnx-labs/agents-cli 1.20.73 → 1.20.74

package/dist/commands/view.js

@@ -4,13 +4,13 @@ import { visibleWidth, termLink } from '../lib/format.js';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
-import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getUnmanagedCliState, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { loginHint } from '../lib/signin-badge.js';
 import { machineId } from '../lib/machine-id.js';
 import { authCacheKey, formatCheckedAge, readAuthHealthCache } from '../lib/auth-health.js';
 import { agentReportsUsage, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, } from '../lib/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { resolveVersionFilter, AgentSpecError } from '../lib/agent-spec/index.js';
@@ -243,9 +243,27 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         ? `Checking ${agentLabel(filterAgentId)} agents...`
         : 'Checking installed agents...';
     const spinner = ora({ text: spinnerText, isSilent: !process.stdout.isTTY }).start();
-    const cliStates = await getAllCliStates();
-    spinner.stop();
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
+    // A globally-installed CLI is superseded only by a NORMAL managed version — that
+    // is when agents-cli owns the launcher and a "global" row would just be our own
+    // shim reported back. `--isolated` promises the opposite: no default, no bare
+    // shim, no adopted launcher, the user's own `~/.<agent>` untouched. So an
+    // isolated-only install must not make that still-live global CLI disappear from
+    // `agents view` — the two are genuinely separate installs and both get listed.
+    const hasNonIsolatedVersion = (agentId) => listInstalledVersions(agentId).some((v) => !isVersionIsolated(agentId, v));
+    // Every `cliStates` read in this function feeds the "Not Managed by Agents CLI"
+    // block, so resolve it the way that block means it: the user's own CLI on PATH.
+    // `getCliState` would answer with a version-dir install — including an isolated
+    // copy that is deliberately absent from PATH — and print it as "(global)".
+    //
+    // Resolved only for agents that can actually reach that block. `getCliState`
+    // deliberately avoids subprocesses for a version-managed agent, and PATH
+    // resolution costs a `<cli> --version` spawn on a cold cache — so probing an
+    // agent whose global row is suppressed anyway would be pure added latency.
+    const cliStates = Object.fromEntries(await Promise.all(agentsToShow
+        .filter((agentId) => !hasNonIsolatedVersion(agentId))
+        .map(async (agentId) => [agentId, await getUnmanagedCliState(agentId)])));
+    spinner.stop();
     const showPaths = !!filterAgentId;
     const profilesByAgent = getProfilesByAgent(filterAgentId);
     const profileSummaries = [...profilesByAgent.values()].flat();
@@ -276,19 +294,18 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
     const infoFetches = [];
     const globalInfoFetches = [];
     for (const agentId of agentsToShow) {
-        const versions = listInstalledVersions(agentId);
-        if (versions.length > 0) {
-            for (const ver of versions) {
-                const home = getVersionHomePath(agentId, ver);
-                infoFetches.push(getAccountInfo(agentId, home).then((info) => ({
-                    agentId,
-                    version: ver,
-                    home,
-                    info,
-                })));
-            }
+        for (const ver of listInstalledVersions(agentId)) {
+            const home = getVersionHomePath(agentId, ver);
+            infoFetches.push(getAccountInfo(agentId, home).then((info) => ({
+                agentId,
+                version: ver,
+                home,
+                info,
+            })));
         }
-        else {
+        // Mirrors the classification below: fetch the global account whenever the
+        // global install will still be rendered (no versions at all, or isolated-only).
+        if (!hasNonIsolatedVersion(agentId)) {
             globalInfoFetches.push(getAccountInfo(agentId).then((info) => ({
                 agentId,
                 cliVersion: cliStates[agentId]?.version || null,
@@ -356,10 +373,12 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         if (versions.length > 0) {
             versionManaged.push(agentId);
         }
-        else if (cliState?.installed) {
-            globallyInstalled.push(agentId);
+        if (cliState?.installed) {
+            // Isolated-only installs sit alongside the global CLI rather than replacing it.
+            if (!hasNonIsolatedVersion(agentId))
+                globallyInstalled.push(agentId);
         }
-        else if (hasProfiles) {
+        else if (versions.length === 0 && hasProfiles) {
             profileOnly.push(agentId);
         }
     }
@@ -376,6 +395,22 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             liveVersionByAgent.set(agentId, live);
     }));
     const displayVersion = (agentId, dirVersion) => liveVersionByAgent.get(agentId) ?? dirVersion;
+    // Uncolored row label, shared by the width pass and the render so padding lines
+    // up. An isolated copy is never the global default (installing one deliberately
+    // records no default), so the two tags can't collide.
+    const versionRowLabel = (agentId, version, globalDefault) => {
+        const shown = displayVersion(agentId, version);
+        if (version === globalDefault)
+            return `${shown} (default)`;
+        if (isVersionIsolated(agentId, version)) {
+            // The isolated default is what a bare `agents run <agent>` reaches, so it is
+            // worth distinguishing from the other isolated copies sitting beside it.
+            return getIsolatedDefault(agentId) === version
+                ? `${shown} (isolated default)`
+                : `${shown} (isolated)`;
+        }
+        return shown;
+    };
     // Show version-managed agents
     if (versionManaged.length > 0) {
         // Calculate column widths across all agents for alignment
@@ -388,9 +423,7 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             const versions = listInstalledVersions(agentId);
             const globalDefault = getGlobalDefault(agentId);
             for (const v of versions) {
-                const shown = displayVersion(agentId, v);
-                const label = v === globalDefault ? `${shown} (default)` : shown;
-                maxVerLabel = Math.max(maxVerLabel, label.length);
+                maxVerLabel = Math.max(maxVerLabel, versionRowLabel(agentId, v, globalDefault).length);
                 const rawInfo = infoMap.get(`${agentId}:${v}`);
                 const info = rawInfo ? mergeCanonical(rawInfo) : undefined;
                 const accountLabel = accountColumnLabel(info);
@@ -431,7 +464,14 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             const globalDefault = getGlobalDefault(agentId);
             const runStrategy = getConfiguredRunStrategy(agentId);
             const strategyLabel = chalk.gray(` (${runStrategy})`);
-            const noDefaultLabel = !globalDefault ? chalk.yellow(' (no default)') : '';
+            // `(no default)` is a nudge to go set one. It would read as a contradiction
+            // directly above a row tagged `(isolated default)`, and it would be bad
+            // advice besides: for an isolated-only agent the pointer below IS how a
+            // bare `agents run <agent>` resolves, and setting a global default is
+            // precisely what `--isolated` exists to avoid.
+            const noDefaultLabel = !globalDefault && !getIsolatedDefault(agentId)
+                ? chalk.yellow(' (no default)')
+                : '';
             console.log(`  ${chalk.bold(agentLabel(agentId))}${strategyLabel}${noDefaultLabel}`);
             // Sort versions with default first, then by semver descending
             const sortedVersions = [...versions].sort((a, b) => {
@@ -443,10 +483,16 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             });
             for (const version of sortedVersions) {
                 const isDefault = version === globalDefault;
+                const isolated = !isDefault && isVersionIsolated(agentId, version);
+                const isolatedTag = getIsolatedDefault(agentId) === version ? ' (isolated default)' : ' (isolated)';
                 const shown = displayVersion(agentId, version);
-                const base = isDefault ? `${shown} (default)` : shown;
-                const padded = base.padEnd(maxVerLabel);
-                const label = isDefault ? `${shown}${chalk.green(' (default)')}${' '.repeat(maxVerLabel - base.length)}` : padded;
+                const base = versionRowLabel(agentId, version, globalDefault);
+                const tagPad = ' '.repeat(maxVerLabel - base.length);
+                const label = isDefault
+                    ? `${shown}${chalk.green(' (default)')}${tagPad}`
+                    : isolated
+                        ? `${shown}${chalk.gray(isolatedTag)}${tagPad}`
+                        : base.padEnd(maxVerLabel);
                 const rawInfo = infoMap.get(`${agentId}:${version}`);
                 const vInfo = rawInfo ? mergeCanonical(rawInfo) : undefined;
                 const usageKey = getUsageLookupKey(vInfo);
@@ -580,7 +626,9 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             // Profile rows under a globally-installed harness. Use a simpler
             // alignment here since this section doesn't share column state with
             // the version-managed block.
-            const profilesHere = profilesByAgent.get(agentId) ?? [];
+            // An isolated-only agent now appears in BOTH blocks; its profiles already
+            // rendered under the version-managed one, so don't print them twice.
+            const profilesHere = versionManaged.includes(agentId) ? [] : (profilesByAgent.get(agentId) ?? []);
             if (profilesHere.length > 0) {
                 const nameWidth = Math.max(globalMaxVerLabel, ...profilesHere.map((p) => p.name.length));
                 const authWidth = Math.max(...profilesHere.map((p) => p.auth.length));

package/dist/index.js

@@ -55,7 +55,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadResources, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadRoutines, loadMonitors, loadRun, loadFork, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadCheck, loadStatus, loadProfiles, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadHq, loadFeed, loadActivity, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadResources, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadRun, loadFork, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadCheck, loadStatus, loadProfiles, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadHq, loadFeed, loadActivity, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { emit, redactArgs } from './lib/events.js';
@@ -730,6 +730,7 @@ async function registerAllEagerCommands() {
     await reg(loadWorktree);
     await reg(loadVersions);
     await reg(loadImport);
+    await reg(loadExport);
     await reg(loadPackages);
     await reg(loadRoutines);
     await reg(loadMonitors);

package/dist/lib/agents.d.ts

@@ -71,6 +71,17 @@ export declare function getCliPath(agentId: AgentId): Promise<string | null>;
  * back to a plain PATH lookup.
  */
 export declare function getCliState(agentId: AgentId): Promise<CliState>;
+/**
+ * Resolve the agent's OWN install — the one agents-cli does not manage — by plain
+ * PATH lookup, ignoring the version dirs entirely.
+ *
+ * Callers that specifically mean "the user's own globally-installed CLI" must use
+ * this rather than `getCliState`, whose managed fast path reports an installed
+ * version (any version dir, in readdir order) and would therefore hand back an
+ * isolated copy — a copy that is deliberately unreachable from PATH — labelled as
+ * the global install.
+ */
+export declare function getUnmanagedCliState(agentId: AgentId): Promise<CliState>;
 /** Resolve CLI state for all registered agents in parallel. */
 export declare function getAllCliStates(): Promise<Partial<Record<AgentId, CliState>>>;
 /** Info about an existing unmanaged agent installation. */
@@ -230,6 +241,30 @@ export declare function antigravityOsKeyringProbe(platform?: NodeJS.Platform): {
 } | null;
 /** @internal test hook — clear the per-process keyring probe cache. */
 export declare function __resetAntigravityKeychainCacheForTest(): void;
+/**
+ * Whether a Claude version home's credential file is present but carries no
+ * token — the "must have a real credential" floor (see
+ * `isValidOpenCodeCredential`) applied to claude.
+ *
+ * A FAILED OAuth refresh leaves exactly this state behind: Claude Code rewrites
+ * `.claude/.credentials.json` with `accessToken: ""`, `refreshToken: ""` and
+ * `expiresAt: 0`, keeping only the descriptive fields (`subscriptionType`,
+ * `rateLimitTier`, `refreshTokenExpiresAt`). Everything we derive from
+ * `.claude.json` — email, plan — still looks healthy, so the install reported
+ * `signedIn: true`, `agents view` drew usage bars for it, and balanced rotation
+ * (whose `authValid` is just "email present") kept picking it — every pick dying
+ * at spawn on "OAuth session expired and could not be refreshed".
+ *
+ * Only decidable off macOS: there the login Keychain is the canonical store and
+ * this file is not authoritative, and probing the Keychain would raise an
+ * authorization sheet per installed version on every `agents run` — the reason
+ * rotation stopped calling `isClaudeAuthValid` at all. Off macOS the file IS the
+ * only store, so a token-less file is proof of signed-out. `platform` is a
+ * parameter so both branches are testable on any host.
+ *
+ * Sync, no Keychain, no network — safe on the `agents run` hot path.
+ */
+export declare function isClaudeCredentialFileBlank(base: string, platform?: NodeJS.Platform): boolean;
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
 /**
  * Determine when the agent was last used by checking session file mtimes,

package/dist/lib/agents.js

@@ -860,7 +860,20 @@ export async function getCliState(agentId) {
             }
         }
     }
-    // Non-version-managed: single PATH lookup + cached version read
+    return getUnmanagedCliState(agentId);
+}
+/**
+ * Resolve the agent's OWN install — the one agents-cli does not manage — by plain
+ * PATH lookup, ignoring the version dirs entirely.
+ *
+ * Callers that specifically mean "the user's own globally-installed CLI" must use
+ * this rather than `getCliState`, whose managed fast path reports an installed
+ * version (any version dir, in readdir order) and would therefore hand back an
+ * isolated copy — a copy that is deliberately unreachable from PATH — labelled as
+ * the global install.
+ */
+export async function getUnmanagedCliState(agentId) {
+    const agent = AGENTS[agentId];
     // Special case for grok: it manages its own binaries in ~/.grok/downloads/
     if (agentId === 'grok') {
         const grokBin = resolveGrokBinary();
@@ -1322,6 +1335,48 @@ function isValidOpenCodeCredential(value) {
         default: return false;
     }
 }
+/**
+ * Whether a Claude version home's credential file is present but carries no
+ * token — the "must have a real credential" floor (see
+ * `isValidOpenCodeCredential`) applied to claude.
+ *
+ * A FAILED OAuth refresh leaves exactly this state behind: Claude Code rewrites
+ * `.claude/.credentials.json` with `accessToken: ""`, `refreshToken: ""` and
+ * `expiresAt: 0`, keeping only the descriptive fields (`subscriptionType`,
+ * `rateLimitTier`, `refreshTokenExpiresAt`). Everything we derive from
+ * `.claude.json` — email, plan — still looks healthy, so the install reported
+ * `signedIn: true`, `agents view` drew usage bars for it, and balanced rotation
+ * (whose `authValid` is just "email present") kept picking it — every pick dying
+ * at spawn on "OAuth session expired and could not be refreshed".
+ *
+ * Only decidable off macOS: there the login Keychain is the canonical store and
+ * this file is not authoritative, and probing the Keychain would raise an
+ * authorization sheet per installed version on every `agents run` — the reason
+ * rotation stopped calling `isClaudeAuthValid` at all. Off macOS the file IS the
+ * only store, so a token-less file is proof of signed-out. `platform` is a
+ * parameter so both branches are testable on any host.
+ *
+ * Sync, no Keychain, no network — safe on the `agents run` hot path.
+ */
+export function isClaudeCredentialFileBlank(base, platform = process.platform) {
+    if (platform === 'darwin')
+        return false;
+    try {
+        const raw = fs.readFileSync(path.join(base, '.claude', '.credentials.json'), 'utf-8');
+        const oauth = JSON.parse(raw).claudeAiOauth;
+        if (!oauth)
+            return false;
+        const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0;
+        return !nonEmpty(oauth.accessToken) && !nonEmpty(oauth.refreshToken);
+    }
+    catch {
+        // No file (a Keychain-backed home, or never logged in here) or an
+        // unreadable/corrupt one: not positive evidence of a blank credential, so
+        // leave the existing signal alone rather than declaring a working install
+        // signed out.
+        return false;
+    }
+}
 export async function getAccountInfo(agentId, home) {
     const base = home || os.homedir();
     const empty = {
@@ -1358,6 +1413,13 @@ export async function getAccountInfo(agentId, home) {
                 const accountId = normalizeIdentityPart(oa?.accountUuid);
                 const organizationId = normalizeIdentityPart(oa?.organizationUuid);
                 const email = oa?.emailAddress || null;
+                // Credential floor: a blanked credential file means this home cannot
+                // authenticate, whatever `.claude.json` still says. Report it signed out
+                // so `agents view` prompts a re-login and rotation routes around it,
+                // instead of handing runs to an install that dies at spawn.
+                if (email && isClaudeCredentialFileBlank(base)) {
+                    return { ...empty, lastActive };
+                }
                 const accountKey = buildIdentityKey(agentId, [
                     ['account', accountId],
                     ['org', organizationId],

package/dist/lib/config-transfer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Move `source` onto `dest` across possibly-different volumes. `renameSync` is
+ * atomic but throws EXDEV when `~/.agents` lives on a different filesystem than
+ * `$HOME`; fall back to copy-then-remove so the restore still completes. The
+ * source is removed only after the copy succeeds, so a mid-copy failure never
+ * destroys the sole surviving copy.
+ */
+export declare function moveDirCrossDevice(source: string, dest: string): void;
+/**
+ * Copy `source` to `dest`, dropping any symlink whose target resolves back into
+ * `~/.agents`. Managed resources (skills/commands) are synced into a version home
+ * as symlinks into `~/.agents`; copying them verbatim would leave the result full
+ * of links that dangle the moment `~/.agents` is disposed. Stripping them yields a
+ * clean, self-contained copy — which is the entire point of an export.
+ */
+export declare function copyDirStrippingAgentsSymlinks(source: string, dest: string, agentsDir: string): void;

package/dist/lib/config-transfer.js

@@ -0,0 +1,56 @@
+/**
+ * Primitives for moving an agent config directory across the agents-cli boundary.
+ *
+ * Both helpers were part of {@link ./uninstall.ts} and are unchanged — teardown was
+ * simply the first caller. `agents export` needs the same two operations (relocate a
+ * directory that may sit on another volume; copy one without dragging `~/.agents`
+ * symlinks along), so they live here rather than being duplicated or imported out of
+ * a module named for teardown.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Move `source` onto `dest` across possibly-different volumes. `renameSync` is
+ * atomic but throws EXDEV when `~/.agents` lives on a different filesystem than
+ * `$HOME`; fall back to copy-then-remove so the restore still completes. The
+ * source is removed only after the copy succeeds, so a mid-copy failure never
+ * destroys the sole surviving copy.
+ */
+export function moveDirCrossDevice(source, dest) {
+    try {
+        fs.renameSync(source, dest);
+    }
+    catch (err) {
+        if (err.code !== 'EXDEV')
+            throw err;
+        fs.cpSync(source, dest, { recursive: true });
+        fs.rmSync(source, { recursive: true, force: true });
+    }
+}
+/**
+ * Copy `source` to `dest`, dropping any symlink whose target resolves back into
+ * `~/.agents`. Managed resources (skills/commands) are synced into a version home
+ * as symlinks into `~/.agents`; copying them verbatim would leave the result full
+ * of links that dangle the moment `~/.agents` is disposed. Stripping them yields a
+ * clean, self-contained copy — which is the entire point of an export.
+ */
+export function copyDirStrippingAgentsSymlinks(source, dest, agentsDir) {
+    const inside = agentsDir + path.sep;
+    fs.cpSync(source, dest, {
+        recursive: true,
+        filter: (src) => {
+            try {
+                const st = fs.lstatSync(src);
+                if (st.isSymbolicLink()) {
+                    const tgt = path.resolve(path.dirname(src), fs.readlinkSync(src));
+                    if (tgt === agentsDir || tgt.startsWith(inside))
+                        return false;
+                }
+            }
+            catch {
+                /* unreadable entry — let cpSync surface it on the real copy */
+            }
+            return true;
+        },
+    });
+}

package/dist/lib/export.d.ts

@@ -0,0 +1,72 @@
+import type { AgentId } from './types.js';
+export type ExportMode = 'merge' | 'replace' | 'staged';
+/** Filename of the provenance receipt written into the agent's config dir. */
+export declare const RECEIPT_NAME = ".agents-cli-export.json";
+/** Suffix for the incoming copy of a file the user already has. */
+export declare const CONFLICT_SUFFIX = ".from-agents-cli";
+/** Why an export cannot proceed. Each maps to a distinct user-facing remedy. */
+export type ExportBlocker = {
+    kind: 'not-installed';
+} | {
+    kind: 'not-isolated';
+} | {
+    kind: 'no-config';
+    source: string;
+} | {
+    kind: 'dest-adopted';
+    realPath: string;
+    adoptedVersion: string;
+};
+/** What the destination `~/.<agent>` currently is. */
+export type DestKind = 'absent' | 'real-dir' | 'foreign-symlink';
+/** One file the export would place, relative to the config dir root. */
+export interface ExportEntry {
+    /** Path relative to the config dir, e.g. `prompts/review.md`. */
+    rel: string;
+    /** Absolute source file inside the isolated home. */
+    source: string;
+    /** Absolute path this file will be written to. */
+    target: string;
+    /**
+     * Set when the user already has `rel`. `target` then points at the
+     * `.from-agents-cli` sibling, and `existing` is the untouched original.
+     */
+    existing?: string;
+}
+export interface ExportPlan {
+    agent: AgentId;
+    version: string;
+    mode: ExportMode;
+    /** The isolated config dir, e.g. `<versionDir>/home/.codex`. */
+    source: string;
+    /** The user's real config dir, e.g. `~/.codex`. */
+    dest: string;
+    destKind: DestKind;
+    /** Files with no counterpart in `dest` — written in place. */
+    writes: ExportEntry[];
+    /** Files the user already has — written alongside, never over. */
+    conflicts: ExportEntry[];
+    /** replace mode only: where `dest` gets moved first. */
+    backupPath: string | null;
+    /** staged mode only: the subdirectory receiving the whole tree. */
+    stagedPath: string | null;
+    receiptPath: string;
+    blocker: ExportBlocker | null;
+}
+export interface ExportResult {
+    exported: boolean;
+    dest: string;
+    written: string[];
+    conflicts: Array<{
+        path: string;
+        theirs: string;
+    }>;
+    backupPath: string | null;
+    stagedPath: string | null;
+    receiptPath: string | null;
+    errors: string[];
+}
+/** Build a read-only plan. Performs no mutations. */
+export declare function planExport(agent: AgentId, version: string, timestamp: number, mode?: ExportMode): ExportPlan;
+/** Execute a plan from {@link planExport}. */
+export declare function executeExport(plan: ExportPlan, timestamp: number): ExportResult;