@aragon-agent/cli 0.4.3

package/dist/config/env.js

@@ -0,0 +1,92 @@
+/**
+ * Environment + `.env` loading and mapping to config fields.
+ *
+ * Recognized keys (spec §3.5):
+ *   - Provider secrets: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY /
+ *     GEMINI_API_KEY.
+ *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
+ *     ARAGON_MAX_TOKENS, ARAGON_THEME.
+ */
+import { join } from 'node:path';
+import process from 'node:process';
+import dotenv from 'dotenv';
+import { clampTheme, clampThinkingLevel, coerceMaxTokens, } from './schema.js';
+/**
+ * Load a project `.env` from the given directory into `process.env` (existing
+ * process env wins — dotenv never overrides already-set variables).
+ */
+export function loadDotenv(cwd) {
+    dotenv.config({ path: join(cwd, '.env') });
+}
+/** Provider -> the env vars that may carry its key (first non-empty wins). */
+const PROVIDER_ENV_KEYS = {
+    anthropic: ['ANTHROPIC_API_KEY'],
+    openai: ['OPENAI_API_KEY'],
+    google: ['GOOGLE_API_KEY', 'GEMINI_API_KEY'],
+};
+function firstEnv(names) {
+    for (const name of names) {
+        const v = process.env[name];
+        if (v && v.trim().length > 0)
+            return v.trim();
+    }
+    return undefined;
+}
+/**
+ * Read ARAGON_* overrides and provider secrets from the current environment.
+ * Must be called after `loadDotenv()` so `.env` values are visible.
+ */
+export function readEnvConfig() {
+    const partial = {};
+    const provider = process.env.ARAGON_PROVIDER?.trim();
+    if (provider)
+        partial.provider = provider;
+    const model = process.env.ARAGON_MODEL?.trim();
+    if (model)
+        partial.model = model;
+    const baseUrl = process.env.ARAGON_BASE_URL?.trim();
+    if (baseUrl)
+        partial.baseUrl = baseUrl;
+    if (process.env.ARAGON_THINKING) {
+        partial.thinkingLevel = clampThinkingLevel(process.env.ARAGON_THINKING.trim(), 'off');
+    }
+    if (process.env.ARAGON_MAX_TOKENS) {
+        const mt = coerceMaxTokens(process.env.ARAGON_MAX_TOKENS);
+        partial.maxTokens = mt ?? null;
+    }
+    if (process.env.ARAGON_THEME) {
+        partial.theme = clampTheme(process.env.ARAGON_THEME.trim(), 'auto');
+    }
+    // ARAGON_FULLSCREEN=0|1 — the one channel that works where neither a flag nor
+    // a config file is reachable (containers, SSH, being spawned by another tool).
+    const fullscreen = process.env.ARAGON_FULLSCREEN?.trim().toLowerCase();
+    if (fullscreen !== undefined && fullscreen.length > 0) {
+        partial.fullscreen = fullscreen === '1' || fullscreen === 'true' || fullscreen === 'on' || fullscreen === 'yes';
+    }
+    // ARAGON_SKILLS=0 is the kill switch for the whole skill subsystem; the other
+    // two skill env vars (ARAGON_SKILLS_PATH, ARAGON_SKILLS_DISABLED) are read where
+    // they are used — the search-root resolver and the service respectively —
+    // because neither maps onto a single persisted field.
+    const skills = process.env.ARAGON_SKILLS?.trim().toLowerCase();
+    if (skills !== undefined && skills.length > 0) {
+        partial.skills = {
+            ...(partial.skills ?? {}),
+            enabled: !(skills === '0' || skills === 'false' || skills === 'off' || skills === 'no'),
+        };
+    }
+    const apiKeys = {};
+    for (const [prov, names] of Object.entries(PROVIDER_ENV_KEYS)) {
+        apiKeys[prov] = firstEnv(names);
+    }
+    return { partial, apiKeys };
+}
+/** Skill names disabled for this run via `ARAGON_SKILLS_DISABLED` (comma-separated). */
+export function readEnvDisabledSkills() {
+    const raw = process.env.ARAGON_SKILLS_DISABLED;
+    if (!raw || raw.trim().length === 0)
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}

package/dist/config/load.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Layered config resolution: defaults › user file › env/.env › CLI flags.
+ *
+ * Also enforces the timeout invariant (spec §3.8 / R1): after merging all
+ * layers, `idleTimeout` is re-derived to be strictly ≥ `toolTimeout` so a
+ * legitimately long single tool run can never be watchdog-killed.
+ */
+import { type CliConfig } from './schema.js';
+export interface CliFlags {
+    provider?: string;
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    thinking?: string;
+    maxTokens?: string | number;
+    cwd?: string;
+    theme?: string;
+    color?: boolean;
+    confirm?: boolean;
+    toolTimeout?: string | number;
+    idleTimeout?: string | number;
+    /** `--fullscreen` ⇒ true, `--no-fullscreen` ⇒ false, absent ⇒ undefined. */
+    fullscreen?: boolean;
+    /** `--no-exit-transcript` ⇒ false. */
+    exitTranscript?: boolean;
+    /** `--compact` ⇒ true, `--no-compact` ⇒ false, absent ⇒ undefined. */
+    compact?: boolean;
+    /** `--hints` ⇒ true, `--no-hints` ⇒ false, absent ⇒ undefined. */
+    hints?: boolean;
+    /** `--no-skills` ⇒ false. Turns the whole skill subsystem off (§7.5). */
+    skills?: boolean;
+    /** `--skill <name>` ×N — force Level 2 injection for this run. */
+    skill?: string[];
+    /** `--skills-yes` — approve skill installs for this run only. */
+    skillsYes?: boolean;
+    /** `--skill-tool-policy <mode>` — override the tool ceiling for this run (§5.5). */
+    skillToolPolicy?: string;
+}
+/**
+ * Resolve the effective config by merging all layers, then derive the runtime
+ * (non-persisted) fields and enforce the timeout invariant.
+ */
+export declare function loadConfig(flags?: CliFlags): CliConfig;
+/**
+ * Build the `getApiKey(providerId)` resolver the core `Agent` consumes.
+ * The one-shot `--api-key` override wins, but only for the active provider.
+ */
+export declare function makeGetApiKey(config: CliConfig): (providerId: string) => string | undefined;

package/dist/config/load.js

@@ -0,0 +1,158 @@
+/**
+ * Layered config resolution: defaults › user file › env/.env › CLI flags.
+ *
+ * Also enforces the timeout invariant (spec §3.8 / R1): after merging all
+ * layers, `idleTimeout` is re-derived to be strictly ≥ `toolTimeout` so a
+ * legitimately long single tool run can never be watchdog-killed.
+ */
+import process from 'node:process';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampDensity, clampSkillsConfig, clampTheme, clampThinkingLevel, clampTranscriptWindow, coerceMaxTokens, coercePositiveInt, isSkillsToolPolicyMode, } from './schema.js';
+import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
+import { readConfigFile } from './store.js';
+import { detectCapabilities } from '../ui/capabilities.js';
+/** Interpret a boolean-ish env value (`1/true/on/yes`) as `true`. */
+function envFlagTrue(value) {
+    if (!value)
+        return false;
+    const v = value.trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'on' || v === 'yes';
+}
+/**
+ * Resolve the tri-state full-screen preference (see `CliConfig.fullscreen`).
+ * Only a flag or the env var counts as an explicit FORCE; a config file holding
+ * the default `true` must not disable the automatic downgrades.
+ */
+function resolveFullscreen(flags, env, file) {
+    if (flags.fullscreen !== undefined)
+        return flags.fullscreen;
+    if (env.fullscreen !== undefined)
+        return env.fullscreen;
+    if (file.fullscreen === false)
+        return false;
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// loadConfig
+// ---------------------------------------------------------------------------
+function pick(...vals) {
+    for (const v of vals) {
+        if (v !== undefined && v !== null && v !== '')
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Resolve the effective config by merging all layers, then derive the runtime
+ * (non-persisted) fields and enforce the timeout invariant.
+ */
+export function loadConfig(flags = {}) {
+    const cwd = flags.cwd ? flags.cwd : process.cwd();
+    // `.env` must be loaded before reading env overrides.
+    loadDotenv(cwd);
+    const file = readConfigFile() ?? {};
+    const env = readEnvConfig();
+    const provider = pick(flags.provider, env.partial.provider, file.provider) ?? DEFAULT_CONFIG.provider;
+    const model = pick(flags.model, env.partial.model, file.model) ?? DEFAULT_CONFIG.model;
+    const baseUrl = pick(flags.baseUrl, env.partial.baseUrl ?? undefined, file.baseUrl ?? undefined);
+    const thinkingLevel = clampThinkingLevel(pick(flags.thinking, env.partial.thinkingLevel, file.thinkingLevel), DEFAULT_CONFIG.thinkingLevel);
+    const maxTokens = coerceMaxTokens(pick(flags.maxTokens, env.partial.maxTokens, file.maxTokens));
+    // `clampTheme` is also where the v0.3.0 `dark` name is migrated to `cool`,
+    // so reading a legacy config file needs no extra step here (§4.5 / R-4).
+    const theme = clampTheme(pick(flags.theme, env.partial.theme, file.theme), DEFAULT_CONFIG.theme);
+    const density = flags.compact !== undefined
+        ? flags.compact
+            ? 'compact'
+            : 'comfortable'
+        : clampDensity(file.density, DEFAULT_CONFIG.density);
+    const hints = flags.hints !== undefined ? flags.hints : file.hints ?? DEFAULT_CONFIG.hints;
+    const confirmTools = flags.confirm !== undefined ? flags.confirm : file.confirmTools ?? DEFAULT_CONFIG.confirmTools;
+    const toolTimeoutMs = coercePositiveInt(pick(flags.toolTimeout, file.toolTimeoutMs), DEFAULT_CONFIG.toolTimeoutMs);
+    let idleTimeoutMs = coercePositiveInt(pick(flags.idleTimeout, file.idleTimeoutMs), DEFAULT_CONFIG.idleTimeoutMs);
+    // Timeout invariant (R1): idle must be strictly greater than the tool ceiling
+    // so a long single tool run is never aborted by the idle watchdog.
+    idleTimeoutMs = Math.max(idleTimeoutMs, toolTimeoutMs + IDLE_TIMEOUT_MARGIN_MS);
+    // Resolve API keys: config-file key wins over the provider env var.
+    const fileKeys = file.apiKeys ?? {};
+    const apiKeys = {};
+    const providerSet = new Set([
+        ...Object.keys(env.apiKeys),
+        ...Object.keys(fileKeys),
+        provider,
+    ]);
+    for (const prov of providerSet) {
+        const fileKey = fileKeys[prov];
+        apiKeys[prov] =
+            fileKey && fileKey.trim().length > 0 ? fileKey.trim() : env.apiKeys[prov];
+    }
+    // Skills: file › env › flags, with `--no-skills` as the final word. The env
+    // layer only ever carries `enabled`, so the file's other fields survive it.
+    const skills = clampSkillsConfig({
+        ...DEFAULT_CONFIG.skills,
+        ...(file.skills ?? {}),
+        ...(env.partial.skills ?? {}),
+        ...(flags.skills === false ? { enabled: false } : {}),
+        disabled: [
+            ...new Set([...(file.skills?.disabled ?? []), ...readEnvDisabledSkills()]),
+        ],
+    });
+    const color = flags.color !== undefined ? flags.color : !process.env.NO_COLOR;
+    // `--no-color` implies calmer chrome; env / file may also opt in explicitly.
+    const reducedMotion = envFlagTrue(process.env.ARAGON_REDUCED_MOTION) ||
+        (file.reducedMotion ?? DEFAULT_CONFIG.reducedMotion) ||
+        !color;
+    // Detect terminal capabilities once; force monochrome when color is disabled.
+    const caps = detectCapabilities(process.env, process.stdout);
+    const colorLevel = color ? caps.colorLevel : 0;
+    return {
+        provider,
+        model,
+        baseUrl,
+        thinkingLevel,
+        maxTokens,
+        theme,
+        reducedMotion,
+        fullscreen: resolveFullscreen(flags, env.partial, file),
+        exitTranscript: flags.exitTranscript !== undefined
+            ? flags.exitTranscript
+            : file.exitTranscript ?? DEFAULT_CONFIG.exitTranscript,
+        transcriptWindow: clampTranscriptWindow(file.transcriptWindow, DEFAULT_CONFIG.transcriptWindow),
+        confirmTools,
+        toolTimeoutMs,
+        idleTimeoutMs,
+        apiKeys,
+        recentModels: file.recentModels ?? [],
+        promptHistory: file.promptHistory ?? [],
+        density,
+        hints,
+        submitCount: coercePositiveInt(file.submitCount, 0),
+        skills,
+        skillsRuntime: {
+            forcedSkills: flags.skill ?? [],
+            approveAll: flags.skillsYes === true,
+            // Left ABSENT when the flag was not given (or was given a bad value), so
+            // `effectiveToolPolicy()` can fall through to the config layer. Writing a
+            // resolved default here instead would make the flag look permanently
+            // supplied and mask the config file for the whole session.
+            ...(isSkillsToolPolicyMode(flags.skillToolPolicy)
+                ? { toolPolicy: flags.skillToolPolicy }
+                : {}),
+        },
+        cwd,
+        color,
+        colorLevel,
+        unicode: caps.unicode,
+        apiKeyOverride: flags.apiKey && flags.apiKey.trim().length > 0 ? flags.apiKey.trim() : undefined,
+    };
+}
+/**
+ * Build the `getApiKey(providerId)` resolver the core `Agent` consumes.
+ * The one-shot `--api-key` override wins, but only for the active provider.
+ */
+export function makeGetApiKey(config) {
+    return (providerId) => {
+        if (config.apiKeyOverride && providerId === config.provider) {
+            return config.apiKeyOverride;
+        }
+        return config.apiKeys[providerId];
+    };
+}

package/dist/config/migrate-legacy-state.d.ts

@@ -0,0 +1,78 @@
+/**
+ * One-shot migration of the user's on-disk state from the pre-rename
+ * `argon-agent` namespace to `aragon-agent`.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY THIS EXISTS: `envPaths()` derives the config and data directories from
+ * the application name, so changing the name relocates them. Without this
+ * module a user upgrading from 0.4.x would find their API key, their sessions
+ * and every installed skill gone — not renamed, gone, with the old directory
+ * still on disk where nobody thinks to look. That is data loss wearing a
+ * rename's clothing.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * The dividing line (spec §3.4): what the user cannot see, the code migrates
+ * for them; what the user can see — the project-level `.argon/skills` directory
+ * inside their own repository — the CHANGELOG tells them to `git mv`.
+ *
+ * THIS FUNCTION NEVER THROWS. It runs as the first statement of `main()`, and a
+ * migration failure must never be the reason the CLI will not start: a user who
+ * has to re-enter an API key is inconvenienced, a user whose CLI refuses to
+ * launch is blocked. Every failure path degrades to `{ mode: 'none', error }`.
+ *
+ * IDEMPOTENCE KEY is "does the new directory already exist" — not the
+ * breadcrumb file, which is written for support diagnosis only. Two cold starts
+ * racing each other therefore both observe `existsSync(next) === false` and
+ * both attempt the rename; the loser gets ENOENT (source already moved) or
+ * EPERM (Windows, target now busy), which the outer catch absorbs. That is the
+ * designed outcome, not an accident: the winner completed the whole migration,
+ * and the loser's view of the world is identical to the already-migrated
+ * branch. No lock file is introduced — a stale lock is precisely the class of
+ * cross-version residue step 5 exists to delete.
+ */
+/**
+ * The pre-rename `env-paths` application name. Deliberately declared here and
+ * not alongside `APP_NAME`: this module is the only consumer, and it is the
+ * only file in the package that is *supposed* to spell the old brand.
+ */
+export declare const LEGACY_APP_NAME = "argon-agent";
+export declare const legacyAppPaths: import("env-paths").Paths;
+/** Filesystem surface this module needs, so tests never touch a real user directory. */
+export interface MigrationFsPort {
+    existsSync(path: string): boolean;
+    mkdirSync(path: string, options: {
+        recursive: true;
+    }): void;
+    renameSync(from: string, to: string): void;
+    cpSync(from: string, to: string, options: {
+        recursive: true;
+    }): void;
+    readdirSync(path: string): string[];
+    rmSync(path: string, options: {
+        force: true;
+    }): void;
+    writeFileSync(path: string, data: string): void;
+}
+export declare const nodeFsPort: MigrationFsPort;
+export interface MigrationResult {
+    mode: 'none' | 'renamed' | 'copied';
+    /** Which roots actually moved — `'config'` and/or `'data'`. */
+    movedRoots: string[];
+    /** How many `.argon-skill.json` files were renamed to `.aragon-skill.json`. */
+    manifestsRenamed: number;
+    /** Populated instead of throwing. */
+    error?: string;
+}
+export declare function migrateLegacyState(fs?: MigrationFsPort): MigrationResult;
+/**
+ * The one-line notice for a migration that did something.
+ *
+ * Callers MUST write this to stderr. `screen.ts` holds stdout to the invariant
+ * that `aragon -p "..." > out.txt` yields model output and nothing else, and
+ * one stray line here would break every scripted invocation.
+ *
+ * ASCII-only, and `->` rather than an arrow glyph: this prints before any
+ * terminal capability probe runs, so a legacy console would render a nicer
+ * character as mojibake. Same rule `glyphs.test.ts` enforces across the CLI.
+ */
+export declare function formatMigrationNotice(result: MigrationResult): string | null;

package/dist/config/migrate-legacy-state.js

@@ -0,0 +1,181 @@
+/**
+ * One-shot migration of the user's on-disk state from the pre-rename
+ * `argon-agent` namespace to `aragon-agent`.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY THIS EXISTS: `envPaths()` derives the config and data directories from
+ * the application name, so changing the name relocates them. Without this
+ * module a user upgrading from 0.4.x would find their API key, their sessions
+ * and every installed skill gone — not renamed, gone, with the old directory
+ * still on disk where nobody thinks to look. That is data loss wearing a
+ * rename's clothing.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * The dividing line (spec §3.4): what the user cannot see, the code migrates
+ * for them; what the user can see — the project-level `.argon/skills` directory
+ * inside their own repository — the CHANGELOG tells them to `git mv`.
+ *
+ * THIS FUNCTION NEVER THROWS. It runs as the first statement of `main()`, and a
+ * migration failure must never be the reason the CLI will not start: a user who
+ * has to re-enter an API key is inconvenienced, a user whose CLI refuses to
+ * launch is blocked. Every failure path degrades to `{ mode: 'none', error }`.
+ *
+ * IDEMPOTENCE KEY is "does the new directory already exist" — not the
+ * breadcrumb file, which is written for support diagnosis only. Two cold starts
+ * racing each other therefore both observe `existsSync(next) === false` and
+ * both attempt the rename; the loser gets ENOENT (source already moved) or
+ * EPERM (Windows, target now busy), which the outer catch absorbs. That is the
+ * designed outcome, not an accident: the winner completed the whole migration,
+ * and the loser's view of the world is identical to the already-migrated
+ * branch. No lock file is introduced — a stale lock is precisely the class of
+ * cross-version residue step 5 exists to delete.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import envPaths from 'env-paths';
+import { appPaths } from './app-paths.js';
+/**
+ * The pre-rename `env-paths` application name. Deliberately declared here and
+ * not alongside `APP_NAME`: this module is the only consumer, and it is the
+ * only file in the package that is *supposed* to spell the old brand.
+ */
+export const LEGACY_APP_NAME = 'argon-agent';
+export const legacyAppPaths = envPaths(LEGACY_APP_NAME);
+export const nodeFsPort = {
+    existsSync,
+    mkdirSync: (path, options) => {
+        mkdirSync(path, options);
+    },
+    renameSync,
+    cpSync,
+    readdirSync: (path) => readdirSync(path),
+    rmSync,
+    writeFileSync: (path, data) => writeFileSync(path, data, 'utf-8'),
+};
+const LEGACY_MANIFEST_FILENAME = '.argon-skill.json';
+const MANIFEST_FILENAME = '.aragon-skill.json';
+const LEGACY_LOCK_FILENAME = '.argon-skills.lock';
+const BREADCRUMB_FILENAME = '.migrated-from-argon-agent';
+/**
+ * The roots the CLI actually uses. `envPaths` also exposes `cache`, `log` and
+ * `temp`; none of them hold anything the user would miss, and migrating a
+ * directory nobody reads is a way to move a bug rather than fix one. A future
+ * root must be added here explicitly.
+ */
+const ROOTS = ['config', 'data'];
+export function migrateLegacyState(fs = nodeFsPort) {
+    const result = { mode: 'none', movedRoots: [], manifestsRenamed: 0 };
+    try {
+        let copied = false;
+        const from = {};
+        for (const root of ROOTS) {
+            const legacy = legacyAppPaths[root];
+            const next = appPaths[root];
+            // Already migrated, or the user built the new directory by hand. Either
+            // way: do not migrate, and above all do not overwrite.
+            if (fs.existsSync(next))
+                continue;
+            if (!fs.existsSync(legacy))
+                continue;
+            fs.mkdirSync(dirname(next), { recursive: true });
+            try {
+                fs.renameSync(legacy, next);
+            }
+            catch {
+                // EXDEV (separate volumes) or EPERM. Copy instead, and KEEP the legacy
+                // tree: a half-finished copy plus a deleted original is the one outcome
+                // worse than not migrating at all.
+                fs.cpSync(legacy, next, { recursive: true });
+                copied = true;
+            }
+            result.movedRoots.push(root);
+            from[root] = legacy;
+        }
+        if (result.movedRoots.length === 0)
+            return result;
+        result.mode = copied ? 'copied' : 'renamed';
+        if (result.movedRoots.includes('data')) {
+            result.manifestsRenamed = renameSkillManifests(fs, join(appPaths.data, 'skills'));
+        }
+        writeBreadcrumb(fs, result, from);
+        return result;
+    }
+    catch (err) {
+        return {
+            mode: 'none',
+            movedRoots: [],
+            manifestsRenamed: 0,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Rename each installed skill's manifest and drop the stale install lock.
+ *
+ * Without the rename an installed skill keeps a manifest the new version cannot
+ * see, so `skills update` and `skills uninstall` stop recognising it and the
+ * skill becomes an orphan directory that still loads. The lock is transient
+ * state; carrying one across versions only lets the new build conclude that
+ * some other process is mid-install.
+ */
+function renameSkillManifests(fs, skillsDir) {
+    if (!fs.existsSync(skillsDir))
+        return 0;
+    let renamed = 0;
+    for (const entry of fs.readdirSync(skillsDir)) {
+        const legacyManifest = join(skillsDir, entry, LEGACY_MANIFEST_FILENAME);
+        if (!fs.existsSync(legacyManifest))
+            continue;
+        fs.renameSync(legacyManifest, join(skillsDir, entry, MANIFEST_FILENAME));
+        renamed += 1;
+    }
+    const staleLock = join(skillsDir, LEGACY_LOCK_FILENAME);
+    if (fs.existsSync(staleLock))
+        fs.rmSync(staleLock, { force: true });
+    return renamed;
+}
+/**
+ * Support-diagnosis breadcrumb. Deliberately NOT the idempotence key.
+ *
+ * Swallows its own failures, and that is the whole point of it being a separate
+ * function. It writes into the CONFIG root while the migration that just
+ * succeeded may only have moved the DATA root — on Windows those are two
+ * different trees (`%APPDATA%` vs `%LOCALAPPDATA%`), so the config directory can
+ * legitimately not exist yet. Letting an ENOENT here reach the caller's outer
+ * catch would report `mode: 'none'` for a migration that in fact moved the
+ * user's data, suppressing the stderr notice and telling support the exact
+ * opposite of what happened. A missing breadcrumb is a lost diagnostic; a
+ * mislabelled result is a lost afternoon.
+ */
+function writeBreadcrumb(fs, result, from) {
+    const payload = {
+        migratedAt: new Date().toISOString(),
+        mode: result.mode,
+        from,
+        manifestsRenamed: result.manifestsRenamed,
+    };
+    try {
+        fs.mkdirSync(appPaths.config, { recursive: true });
+        fs.writeFileSync(join(appPaths.config, BREADCRUMB_FILENAME), `${JSON.stringify(payload, null, 2)}\n`);
+    }
+    catch {
+        // Intentionally ignored — see the note above.
+    }
+}
+/**
+ * The one-line notice for a migration that did something.
+ *
+ * Callers MUST write this to stderr. `screen.ts` holds stdout to the invariant
+ * that `aragon -p "..." > out.txt` yields model output and nothing else, and
+ * one stray line here would break every scripted invocation.
+ *
+ * ASCII-only, and `->` rather than an arrow glyph: this prints before any
+ * terminal capability probe runs, so a legacy console would render a nicer
+ * character as mojibake. Same rule `glyphs.test.ts` enforces across the CLI.
+ */
+export function formatMigrationNotice(result) {
+    if (result.mode === 'none')
+        return null;
+    const skills = result.manifestsRenamed > 0 ? ` (${result.manifestsRenamed} skills)` : '';
+    return `migrated settings from argon-agent -> aragon-agent${skills}`;
+}