@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/lib/exec.js

@@ -15,10 +15,13 @@ import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion }
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
+import { resolveActor, actorEnv } from './actor.js';
 import { getShimsDir, getHistoryDir } from './state.js';
 import { resolveCodexHome } from './codex-home.js';
 import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
+import { loadHookSessionIndex, resolveHookSessionId } from './session/hook-sessions.js';
+import { sessionIdMarkerLine } from './hosts/session-marker.js';
 import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
@@ -312,14 +315,29 @@ export function buildExecEnv(options) {
     // iterations share one inbox.
     if (options.sessionId && isValidMailboxId(options.sessionId)) {
         result.AGENTS_MAILBOX_DIR = mailboxDir(options.sessionId);
+        // Full session id for agent-callable tools (`agents feed post`, etc.).
+        result.AGENT_SESSION_ID = options.sessionId;
+        result.AGENTS_SESSION_ID = options.sessionId;
     }
     result.AGENTS_RUNTIME = resolveInteractive(options) ? 'terminal' : 'headless';
+    // So activity / feed posts stamp the right harness without re-detecting.
+    if (options.agent) {
+        result.AGENTS_AGENT_NAME = options.agent;
+    }
+    if (options.cwd) {
+        result.AGENTS_CWD = options.cwd;
+    }
     // Export the run's durable name (companion to AGENT_SESSION_ID) so a
     // SessionStart hook / the agent can associate its transcript with the handle
     // the user gave the run. Only set when --name was passed.
     if (options.name) {
         result.AGENT_SESSION_NAME = options.name;
     }
+    // Actor provenance -- who initiated this run. Rides the env so the whole spawn
+    // tree shares one actor, and (for a resolved human) so the agent's own git
+    // commits are credited to the person instead of the shared account. options.env
+    // (spread last) overrides any of these keys a caller sets explicitly.
+    Object.assign(result, actorEnv(resolveActor()));
     return {
         ...result,
         ...options.env,
@@ -666,10 +684,16 @@ export function buildExecCommand(options) {
     else {
         cmd.push(...modeFlags);
     }
-    // Add print/headless flags only when a prompt is provided. Without a prompt
-    // the caller wants an interactive REPL -- passing --print would immediately
-    // wait on stdin and never render the TUI.
-    if (!interactive && options.headless && template.printFlags) {
+    // Add print/headless flags whenever the run RESOLVED headless -- gate on the
+    // resolved state (`!interactive`), not the raw `--headless` flag. Headless is
+    // inferred from prompt presence (resolveInteractive), and `--headless` defaults
+    // to `false` at the CLI layer, so gating on `options.headless` skipped these
+    // flags for a bare `agents run <agent> "prompt"`. For antigravity that meant
+    // `agy <prompt>` with no `--print`, launching the TUI and dying on `/dev/tty`
+    // in any non-terminal shell. `!interactive` is true for both an explicit
+    // `--headless` and a prompt-inferred headless run; an interactive run (no
+    // prompt, or `--interactive`) still skips them so the CLI opens its REPL.
+    if (!interactive && template.printFlags) {
         cmd.push(...template.printFlags);
     }
     // Resume vs. create. With `resume`, emit the agent's NATIVE resume reference:
@@ -842,9 +866,15 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     }
     // The only flag the bash shim injects (codex); everything else is transparent.
     const launchArgs = agent === 'codex' ? ['-c', 'check_for_update_on_startup=false'] : [];
+    // Mint a launch id and export it as AGENT_LAUNCH_ID so the agent's SessionStart
+    // hook records the same id — the join key that maps this launch to its exact
+    // session even though the recorded pid here is the cmd.exe wrapper (Windows) or
+    // a shell, while the hook runs under the agent descendant. This is the primary
+    // attribution path on Windows (no lsof), so the launchId join matters most here.
+    const launchId = randomUUID();
     // mode/effort are required by ExecOptions but unused by buildExecEnv (which only
     // derives the per-version config-dir env); pass the agent's default to satisfy the type.
-    const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto' });
+    const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto', env: { AGENT_LAUNCH_ID: launchId } });
     const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     return new Promise((resolve) => {
         const child = spawn(command, args, { cwd, stdio: 'inherit', env, shell });
@@ -860,6 +890,8 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
                 agent,
                 sessionId: extractSessionIdArg(rawArgs),
                 cwd,
+                launchId,
+                terminalId: process.env.AGENT_TERMINAL_ID,
                 startedAtMs: Date.now(),
             });
         }
@@ -1008,6 +1040,12 @@ async function runInTmux(options, executable, args) {
             agent: options.agent,
             sessionId: options.sessionId,
             cwd,
+            // spawnAgent injected AGENT_LAUNCH_ID into options.env before delegating
+            // here; record the same id so the hook (running under the pane-leaf agent
+            // pid) reconciles by launchId. This pane's pid usually IS the agent pid,
+            // but the launchId join is robust even when it isn't.
+            launchId: options.env?.AGENT_LAUNCH_ID,
+            terminalId: process.env.AGENT_TERMINAL_ID,
             tmuxPane: pane,
             startedAtMs: Date.now(),
         });
@@ -1066,6 +1104,36 @@ async function runInTmux(options, executable, args) {
     // Pane still alive → the user detached; keep the session for `agents focus`.
     return { exitCode: 0, stderr: '', stdout: '' };
 }
+/**
+ * Print the run's resolved session id as a one-line stdout sentinel so a `--host`
+ * launcher can relate the remote-created session back to itself (see the
+ * `emitSessionId` option and hosts/session-marker.ts).
+ *
+ * For Claude the id was forced up front (`options.sessionId`, wired as
+ * `--session-id`), so it's authoritative with no lookup. Every other agent coined
+ * its OWN id, which its SessionStart hook recorded under this run's launchId — the
+ * exact join key `agents sessions --active` uses — so we read it back from the hook
+ * index by launchId (falling back to the child pid the hook may have recorded
+ * under). Nothing to emit when the hook hasn't landed an id (hookless harness):
+ * the launcher simply keeps the un-mapped task, never a fabricated id.
+ */
+function emitResolvedSessionId(options, launchId, childPid) {
+    let sessionId = options.sessionId;
+    if (!sessionId) {
+        try {
+            sessionId = resolveHookSessionId(loadHookSessionIndex(), {
+                pid: childPid ?? 0,
+                kind: options.agent,
+                launchId,
+            });
+        }
+        catch {
+            /* hook index unreadable — emit nothing rather than a guess */
+        }
+    }
+    if (sessionId)
+        process.stdout.write(sessionIdMarkerLine(sessionId));
+}
 /**
  * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
  *
@@ -1104,7 +1172,17 @@ async function spawnAgent(options) {
     // timeout. Spend is recorded to the shared ledger in the close handler. The
     // watcher is dormant (and zero-cost) when no caps are configured.
     const cwd = options.cwd || process.cwd();
-    const runId = randomUUID();
+    // Mint the launch id once. It doubles as the budget watcher's run id AND is
+    // exported to the child as AGENT_LAUNCH_ID, so the agent's SessionStart hook
+    // records the SAME id in its own state file (terminals/sessions/<pid>.json).
+    // That id is the join key that reconciles this launch's pid-registry entry
+    // with the hook's authoritative session id even when the hook runs under a
+    // different pid (tmux pane leaf / cmd.exe wrapper) — see pid-registry.ts and
+    // session/hook-sessions.ts. Injected into options.env so every downstream env
+    // build (the bare spawn below AND the tmux env prefix in runInTmux) carries it.
+    const launchId = randomUUID();
+    const runId = launchId;
+    options = { ...options, env: { ...options.env, AGENT_LAUNCH_ID: launchId } };
     const watcherState = await setupBudgetWatcher(options, cwd, runId);
     maybeRotate();
     const timer = createTimer('agent.run', {
@@ -1178,6 +1256,8 @@ async function spawnAgent(options) {
             agent: options.agent,
             sessionId: options.sessionId,
             cwd: options.cwd || process.cwd(),
+            launchId,
+            terminalId: process.env.AGENT_TERMINAL_ID,
             tmuxPane: process.env.TMUX_PANE,
             startedAtMs: Date.now(),
         });
@@ -1264,6 +1344,12 @@ async function spawnAgent(options) {
             // Budget kill resolves with a DISTINCT non-zero exit so CI/headless and
             // teams/cloud can tell a budget termination apart from a normal failure.
             const exitCode = budgetKilled ? BUDGET_KILL_EXIT_CODE : (code ?? 0);
+            // Relate the session id back to a `--host` launcher (see the emitSessionId
+            // doc). Claude's id is the one we forced; every other agent coined its own,
+            // which the SessionStart hook recorded under this run's launchId — resolve
+            // and print it as a one-line sentinel that rides the followed log home.
+            if (options.emitSessionId)
+                emitResolvedSessionId(options, launchId, child.pid);
             timer.end({ exitCode, status: budgetKilled ? 'budget_killed' : code === 0 ? 'success' : 'failed' });
             resolve({ exitCode, stderr: stderrBuffer, stdout: stdoutTail });
         });
@@ -1358,6 +1444,109 @@ export const RATE_LIMIT_PATTERNS = [
 export function detectRateLimit(text) {
     return RATE_LIMIT_PATTERNS.some(pattern => pattern.test(text));
 }
+/**
+ * Patterns that indicate an authentication failure — the agent is logged out,
+ * its token was revoked, or the session expired. These are the user-visible
+ * strings a logged-out agent surfaces (observed across the routine-run corpus).
+ * Unlike a rate limit, an auth failure is NOT self-healing by failover — every
+ * chain entry on the same account fails identically — so it is classified
+ * separately and never triggers a fallback attempt.
+ *
+ * The bare `401` is deliberately paired with an auth keyword: a plain "401" can
+ * appear in legitimate output (an HTTP-status table, a log line), so it only
+ * counts when it co-occurs with OAuth/authentication/credentials/Unauthorized.
+ */
+export const AUTH_FAILURE_PATTERNS = [
+    /OAuth (?:access token has been revoked|session expired)/i,
+    /(?:Please run|run) \/login/i,
+    /\bNot logged in\b/i,
+    /Invalid authentication credentials/i,
+    /Failed to authenticate/i,
+    /organization has (?:disabled|revoked) .*(?:subscription|access)/i,
+    /401\b[^\n]*(?:OAuth|authenticat|credential|Unauthorized)/i,
+];
+/**
+ * Return true if the text contains any known authentication-failure indicator.
+ * Agent-agnostic: matches the user-visible error string wherever it surfaces
+ * (stdout tail, a captured error message, a plain-text agent's output).
+ */
+export function detectAuthFailure(text) {
+    return AUTH_FAILURE_PATTERNS.some(pattern => pattern.test(text));
+}
+/**
+ * Return true if a stream-json log carries the structural markers of an auth
+ * failure. This is the authoritative signal for Claude: a logged-out run emits
+ *   {"type":"system","subtype":"api_retry","error":"authentication_failed",…}
+ *   {"type":"assistant",…,"error":"authentication_failed"}
+ *   {"type":"result","is_error":true,"result":"Failed to authenticate…"}
+ * Note `terminal_reason` is "completed" on such a run, so exit-code / terminal-
+ * reason logic can never catch it — the `error:"authentication_failed"` marker
+ * and the `result`+`is_error` text are the reliable signals.
+ *
+ * Gated on the Claude stream-json shape; other agents don't emit these fields,
+ * so callers pass their agent and this returns false for non-claude.
+ */
+export function detectAuthFailureEvent(logText, agent) {
+    if (agent !== 'claude')
+        return false;
+    const lines = logText.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed[0] !== '{')
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed?.error === 'authentication_failed')
+            return true;
+        if (parsed?.type === 'result' &&
+            parsed?.is_error === true &&
+            typeof parsed?.result === 'string' &&
+            detectAuthFailure(parsed.result)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Return the first human-readable auth-failure phrase found in the text, for use
+ * as a stable, short run `errorMessage` reason. Falls back to null when the only
+ * signal was the structural `error:"authentication_failed"` marker with no
+ * user-visible string.
+ */
+export function authFailureReason(text) {
+    for (const pattern of AUTH_FAILURE_PATTERNS) {
+        const m = text.match(pattern);
+        if (m)
+            return m[0];
+    }
+    return null;
+}
+/**
+ * Decide whether a run's stream-json log is an authentication failure. The
+ * single source of truth for both the foreground and detached run paths.
+ *
+ * The structural marker (`detectAuthFailureEvent`, gated on `is_error:true`) is
+ * authoritative and safe on ANY exit — it catches a logged-out Claude that exits
+ * 0 (its `result` event carries `is_error:true` while `terminal_reason` is
+ * "completed"). The raw user-visible string (`detectAuthFailure`) is only
+ * consulted when the process actually FAILED, as a fallback for a run that died
+ * mid-stream before emitting a `result` event. That gate is what prevents a
+ * genuinely-completed run whose output merely *mentions* an auth phrase (e.g. a
+ * routine documenting a login flow) from being misclassified and having its
+ * legitimate report suppressed.
+ */
+export function isAuthFailureFromLog(logText, agent, opts) {
+    if (detectAuthFailureEvent(logText, agent))
+        return true;
+    if (opts.processFailed && detectAuthFailure(logText))
+        return true;
+    return false;
+}
 /**
  * Build the prompt handed to the fallback agent when the primary was stopped
  * mid-task by a rate limit.

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;

package/dist/lib/export.js

@@ -0,0 +1,269 @@
+/**
+ * `agents export` — copy an ISOLATED install's config back out to the user's real
+ * `~/.<agent>`, so they can keep their settings and delete agents-cli entirely.
+ *
+ * Isolation is currently a one-way door: `agents add <agent>@<v> --isolated` builds a
+ * self-contained home under the version dir, and nothing ever brings that work back.
+ * Reversibility is what makes a sandbox safe to try.
+ *
+ * Three modes, because "export" means different things depending on which config you
+ * consider authoritative:
+ *
+ *   merge (default) — additive. Copy only paths the user doesn't already have. A
+ *                     collision is NOT silently skipped: the incoming file is written
+ *                     beside theirs as `<name>.from-agents-cli` so they can diff and
+ *                     take the parts they want. Nothing of theirs is ever modified.
+ *   replace         — the isolated config becomes `~/.<agent>`; theirs moves to
+ *                     `backups/<agent>/<ts>`. For when you've been living in the
+ *                     sandbox and want to promote it wholesale.
+ *   staged          — write the whole tree to `~/.<agent>/.agents-export-<ts>/` and
+ *                     activate nothing. For inspecting first.
+ *
+ * Every mode leaves a receipt at `~/.<agent>/.agents-cli-export.json` recording what
+ * came from the export. That is what makes provenance answerable ("which of these
+ * files are mine?") and the whole operation reversible.
+ *
+ * Deliberately NOT implemented: key-level merging of file *contents*. The TOML
+ * library here does not preserve comments across parse+stringify, so auto-merging a
+ * `config.toml` would silently delete the user's comments. Handing over both files
+ * and a diff is honest; rewriting their config behind a "merge" flag is not.
+ *
+ * Split into a read-only {@link planExport} and a mutating {@link executeExport} so
+ * `--dry-run` and the real run share one code path, mirroring `lib/uninstall.ts`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS } from './agents.js';
+import { getAgentConfigPath, getConfigSymlinkVersion } from './shims.js';
+import { getVersionHomePath, isVersionIsolated, isVersionInstalled } from './versions.js';
+import { getUserAgentsDir, getBackupsDir } from './state.js';
+import { copyDirStrippingAgentsSymlinks, moveDirCrossDevice } from './config-transfer.js';
+/** Filename of the provenance receipt written into the agent's config dir. */
+export const RECEIPT_NAME = '.agents-cli-export.json';
+/** Suffix for the incoming copy of a file the user already has. */
+export const CONFLICT_SUFFIX = '.from-agents-cli';
+/** The config dir's basename (`.codex`), used to locate it inside a version home. */
+function configBasename(agent) {
+    return path.basename(AGENTS[agent].configDir);
+}
+/**
+ * Every regular file under `root`, as paths relative to it. Symlinks pointing back
+ * into `~/.agents` are omitted for the same reason `copyDirStrippingAgentsSymlinks`
+ * drops them: they dangle the moment `~/.agents` is disposed, and an export that
+ * leaves dangling links is not an export.
+ */
+function walkFiles(root, agentsDir, rel = '') {
+    const inside = agentsDir + path.sep;
+    const out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const childRel = rel ? path.join(rel, entry.name) : entry.name;
+        const abs = path.join(root, childRel);
+        if (entry.isSymbolicLink()) {
+            try {
+                const tgt = path.resolve(path.dirname(abs), fs.readlinkSync(abs));
+                if (tgt === agentsDir || tgt.startsWith(inside))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            out.push(childRel);
+            continue;
+        }
+        if (entry.isDirectory()) {
+            out.push(...walkFiles(root, agentsDir, childRel));
+            continue;
+        }
+        out.push(childRel);
+    }
+    return out;
+}
+/** Build a read-only plan. Performs no mutations. */
+export function planExport(agent, version, timestamp, mode = 'merge') {
+    const source = path.join(getVersionHomePath(agent, version), configBasename(agent));
+    const dest = getAgentConfigPath(agent);
+    const base = {
+        agent,
+        version,
+        mode,
+        source,
+        dest,
+        destKind: 'absent',
+        writes: [],
+        conflicts: [],
+        backupPath: null,
+        stagedPath: null,
+        receiptPath: path.join(dest, RECEIPT_NAME),
+    };
+    if (!isVersionInstalled(agent, version))
+        return { ...base, blocker: { kind: 'not-installed' } };
+    if (!isVersionIsolated(agent, version))
+        return { ...base, blocker: { kind: 'not-isolated' } };
+    if (!fs.existsSync(source))
+        return { ...base, blocker: { kind: 'no-config', source } };
+    // Refuse when `~/.<agent>` is a symlink agents-cli owns: the agent has a normal
+    // install that adopted it, so writing there would land inside a version home
+    // rather than in the user's real config, and silently mutate that other install.
+    const adopted = getConfigSymlinkVersion(agent);
+    if (adopted !== null) {
+        return { ...base, blocker: { kind: 'dest-adopted', realPath: dest, adoptedVersion: adopted } };
+    }
+    let destKind = 'absent';
+    try {
+        destKind = fs.lstatSync(dest).isSymbolicLink() ? 'foreign-symlink' : 'real-dir';
+    }
+    catch {
+        destKind = 'absent';
+    }
+    const agentsDir = getUserAgentsDir();
+    const rels = walkFiles(source, agentsDir).sort();
+    if (mode === 'staged') {
+        const stagedPath = path.join(dest, `.agents-export-${timestamp}`);
+        return {
+            ...base,
+            destKind,
+            stagedPath,
+            writes: rels.map((rel) => ({
+                rel,
+                source: path.join(source, rel),
+                target: path.join(stagedPath, rel),
+            })),
+            blocker: null,
+        };
+    }
+    if (mode === 'replace') {
+        return {
+            ...base,
+            destKind,
+            backupPath: destKind === 'real-dir' ? path.join(getBackupsDir(), agent, String(timestamp)) : null,
+            writes: rels.map((rel) => ({
+                rel,
+                source: path.join(source, rel),
+                target: path.join(dest, rel),
+            })),
+            blocker: null,
+        };
+    }
+    // merge: additive. Anything the user already has becomes a conflict written
+    // alongside, so their file is never the thing that changes.
+    const writes = [];
+    const conflicts = [];
+    for (const rel of rels) {
+        const target = path.join(dest, rel);
+        let exists = false;
+        try {
+            fs.lstatSync(target);
+            exists = true;
+        }
+        catch {
+            exists = false;
+        }
+        if (exists) {
+            conflicts.push({
+                rel,
+                source: path.join(source, rel),
+                target: target + CONFLICT_SUFFIX,
+                existing: target,
+            });
+        }
+        else {
+            writes.push({ rel, source: path.join(source, rel), target });
+        }
+    }
+    return { ...base, destKind, writes, conflicts, blocker: null };
+}
+/** Copy one file, creating parent dirs. Symlinks are recreated, not followed. */
+function placeFile(entry) {
+    fs.mkdirSync(path.dirname(entry.target), { recursive: true });
+    const st = fs.lstatSync(entry.source);
+    if (st.isSymbolicLink()) {
+        const link = fs.readlinkSync(entry.source);
+        try {
+            fs.unlinkSync(entry.target);
+        }
+        catch {
+            /* nothing there */
+        }
+        fs.symlinkSync(link, entry.target);
+        return;
+    }
+    fs.copyFileSync(entry.source, entry.target);
+}
+function writeReceipt(plan, result, timestamp) {
+    const receipt = {
+        exportedAt: new Date(timestamp).toISOString(),
+        from: `${plan.agent}@${plan.version} (isolated)`,
+        mode: plan.mode,
+        written: result.written,
+        conflicts: result.conflicts,
+        ...(result.backupPath ? { backupPath: result.backupPath } : {}),
+        ...(result.stagedPath ? { stagedAt: result.stagedPath } : {}),
+        note: plan.mode === 'merge'
+            ? `Files under "written" came from this export. Paths under "conflicts" already existed and were NOT modified — the incoming version sits beside yours with the ${CONFLICT_SUFFIX} suffix.`
+            : plan.mode === 'replace'
+                ? 'This config was replaced wholesale by the export; the previous one is at backupPath.'
+                : 'Nothing was activated — the exported tree sits under stagedAt.',
+    };
+    fs.mkdirSync(path.dirname(plan.receiptPath), { recursive: true });
+    fs.writeFileSync(plan.receiptPath, JSON.stringify(receipt, null, 2) + '\n');
+}
+/** Execute a plan from {@link planExport}. */
+export function executeExport(plan, timestamp) {
+    const result = {
+        exported: false,
+        dest: plan.dest,
+        written: [],
+        conflicts: [],
+        backupPath: null,
+        stagedPath: null,
+        receiptPath: null,
+        errors: [],
+    };
+    if (plan.blocker) {
+        result.errors.push(`refusing to export: ${plan.blocker.kind}`);
+        return result;
+    }
+    try {
+        if (plan.mode === 'replace') {
+            if (plan.backupPath) {
+                fs.mkdirSync(path.dirname(plan.backupPath), { recursive: true });
+                moveDirCrossDevice(plan.dest, plan.backupPath);
+                result.backupPath = plan.backupPath;
+            }
+            else if (plan.destKind === 'foreign-symlink') {
+                // Not ours to back up, but it must go or cpSync would write through it.
+                fs.unlinkSync(plan.dest);
+            }
+            copyDirStrippingAgentsSymlinks(plan.source, plan.dest, getUserAgentsDir());
+            result.written = plan.writes.map((w) => w.rel);
+        }
+        else {
+            // merge and staged both place individual files; neither disturbs anything
+            // the user already has.
+            for (const entry of plan.writes) {
+                placeFile(entry);
+                result.written.push(entry.rel);
+            }
+            for (const entry of plan.conflicts) {
+                placeFile(entry);
+                result.conflicts.push({ path: entry.rel, theirs: entry.target });
+            }
+            if (plan.stagedPath)
+                result.stagedPath = plan.stagedPath;
+        }
+        writeReceipt(plan, result, timestamp);
+        result.receiptPath = plan.receiptPath;
+        result.exported = true;
+    }
+    catch (err) {
+        result.errors.push(err instanceof Error ? err.message : String(err));
+    }
+    return result;
+}