@aragon-agent/cli 0.5.2 → 0.5.3

package/dist/config/cli-commands.d.ts

@@ -1,6 +1,6 @@
 /**
- * `aragon config get | list | edit | home`, plus the `log.*` branch of
- * `config set`.
+ * `aragon config get | list | edit | home`, plus the `log.*` and `team.*`
+ * branches of `config set`.
  *
  * These live here rather than in `cli.tsx` because `runConfigSet` is already a
  * 21-case switch — well past the complexity ceiling this package writes down —
@@ -10,6 +10,17 @@
 import { type PersistedConfig } from './schema.js';
 /** Config keys under `log.` that `aragon config set` accepts. */
 export declare const LOG_CONFIG_SET_KEYS: readonly ["log.level", "log.toFile", "log.dir", "log.maxFileBytes", "log.maxFiles", "log.redactSecrets", "log.previewChars"];
+/**
+ * Config keys under `team.` that `aragon config set` accepts (team-subagents
+ * §4.3).
+ *
+ * Handled here rather than in `cli.tsx`'s switch for the reason this module's
+ * header already gives about `log.*`: that switch is past this package's
+ * complexity ceiling, and a key added to the membership set but forgotten in the
+ * switch falls through every case, writes nothing, and still prints
+ * `Set team.enabled = false`.
+ */
+export declare const TEAM_CONFIG_SET_KEYS: readonly ["team.enabled", "team.maxSubagents", "team.maxConcurrent", "team.subagentTimeoutMs", "team.dispatchTimeoutMs", "team.maxTurnsPerSubagent"];
 /**
  * Translate a `log.*` dotted key into a patch, or `null` for anything else.
  *
@@ -19,6 +30,19 @@ export declare const LOG_CONFIG_SET_KEYS: readonly ["log.level", "log.toFile", "
  * included.
  */
 export declare function applyLogConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
+/**
+ * Translate a `team.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `team` section, safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge,
+ * setting the fan-out width would silently reset every timeout in the section.
+ *
+ * Values are CLAMPED rather than rejected, exactly like `theme` and
+ * `skills.integrity`: hardening only the read path leaves a bad value on disk
+ * that reverts to the default on every launch, which presents as "my setting
+ * won't stick". `clampTeamConfig` is the one gate both directions pass through.
+ */
+export declare function applyTeamConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
 /**
  * `log.redactSecrets false` is the one setting that lets credentials reach the
  * disk. It is command-line-only (there is no settings-screen entry) and it says

package/dist/config/cli-commands.js

@@ -1,6 +1,6 @@
 /**
- * `aragon config get | list | edit | home`, plus the `log.*` branch of
- * `config set`.
+ * `aragon config get | list | edit | home`, plus the `log.*` and `team.*`
+ * branches of `config set`.
  *
  * These live here rather than in `cli.tsx` because `runConfigSet` is already a
  * 21-case switch — well past the complexity ceiling this package writes down —
@@ -10,10 +10,10 @@
 import { spawnSync } from 'node:child_process';
 import { copyFileSync, existsSync, readFileSync } from 'node:fs';
 import process from 'node:process';
-import { getConfigBackupPath, getConfigPath, getHomeRoot, getLogsDir, isHomeOverridden, } from './app-paths.js';
+import { getConfigBackupPath, getConfigPath, getHomeRoot, getLogsDir, getPromptHistoryPath, getUiStatePath, isHomeOverridden, } from './app-paths.js';
 import { getHomeMigrationBreadcrumbPath } from './migrate-home.js';
 import { loadPersistedConfig, updatePersistedConfig } from './store.js';
-import { coercePositiveInt, maskSecret, } from './schema.js';
+import { coercePositiveInt, maskSecret, DEFAULT_TEAM_CONFIG, } from './schema.js';
 import { clampLogLevel } from '../logging/levels.js';
 /** Config keys under `log.` that `aragon config set` accepts. */
 export const LOG_CONFIG_SET_KEYS = [
@@ -25,6 +25,24 @@ export const LOG_CONFIG_SET_KEYS = [
     'log.redactSecrets',
     'log.previewChars',
 ];
+/**
+ * Config keys under `team.` that `aragon config set` accepts (team-subagents
+ * §4.3).
+ *
+ * Handled here rather than in `cli.tsx`'s switch for the reason this module's
+ * header already gives about `log.*`: that switch is past this package's
+ * complexity ceiling, and a key added to the membership set but forgotten in the
+ * switch falls through every case, writes nothing, and still prints
+ * `Set team.enabled = false`.
+ */
+export const TEAM_CONFIG_SET_KEYS = [
+    'team.enabled',
+    'team.maxSubagents',
+    'team.maxConcurrent',
+    'team.subagentTimeoutMs',
+    'team.dispatchTimeoutMs',
+    'team.maxTurnsPerSubagent',
+];
 function isTrue(value) {
     return value === 'true' || value === '1';
 }
@@ -57,6 +75,43 @@ export function applyLogConfigSet(key, value) {
             return null;
     }
 }
+/**
+ * Translate a `team.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `team` section, safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge,
+ * setting the fan-out width would silently reset every timeout in the section.
+ *
+ * Values are CLAMPED rather than rejected, exactly like `theme` and
+ * `skills.integrity`: hardening only the read path leaves a bad value on disk
+ * that reverts to the default on every launch, which presents as "my setting
+ * won't stick". `clampTeamConfig` is the one gate both directions pass through.
+ */
+export function applyTeamConfigSet(key, value) {
+    const patch = (team) => ({ team });
+    switch (key) {
+        case 'team.enabled':
+            return patch({ enabled: isTrue(value) });
+        case 'team.maxSubagents':
+            return patch({ maxSubagents: coercePositiveInt(value, DEFAULT_TEAM_CONFIG.maxSubagents) });
+        case 'team.maxConcurrent':
+            return patch({ maxConcurrent: coercePositiveInt(value, DEFAULT_TEAM_CONFIG.maxConcurrent) });
+        case 'team.subagentTimeoutMs':
+            return patch({
+                subagentTimeoutMs: coercePositiveInt(value, DEFAULT_TEAM_CONFIG.subagentTimeoutMs),
+            });
+        case 'team.dispatchTimeoutMs':
+            return patch({
+                dispatchTimeoutMs: coercePositiveInt(value, DEFAULT_TEAM_CONFIG.dispatchTimeoutMs),
+            });
+        case 'team.maxTurnsPerSubagent':
+            return patch({
+                maxTurnsPerSubagent: coercePositiveInt(value, DEFAULT_TEAM_CONFIG.maxTurnsPerSubagent),
+            });
+        default:
+            return null;
+    }
+}
 /**
  * `log.redactSecrets false` is the one setting that lets credentials reach the
  * disk. It is command-line-only (there is no settings-screen entry) and it says
@@ -177,6 +232,10 @@ export function runConfigHome() {
     process.stdout.write(`${getHomeRoot()}\n`);
     if (isHomeOverridden())
         process.stdout.write('  (overridden by ARAGON_HOME)\n');
+    // Named here because config.json no longer holds either of them, and a user
+    // looking for "where did my prompt history go" has to land somewhere.
+    process.stdout.write(`  prompt history: ${getPromptHistoryPath()}\n`);
+    process.stdout.write(`  ui state: ${getUiStatePath()}\n`);
     const breadcrumb = getHomeMigrationBreadcrumbPath();
     if (!existsSync(breadcrumb))
         return;

package/dist/config/env.d.ts

@@ -5,8 +5,8 @@
  *   - 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, ARAGON_MOUSE, ARAGON_PLAN,
- *     ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
+ *     ARAGON_MAX_TOKENS, ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
+ *     ARAGON_TEAM_MAX, ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
  * evaluated, which is long before `loadDotenv()` runs, so a `.env` can never

package/dist/config/env.js

@@ -5,8 +5,8 @@
  *   - 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, ARAGON_MOUSE, ARAGON_PLAN,
- *     ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
+ *     ARAGON_MAX_TOKENS, ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
+ *     ARAGON_TEAM_MAX, ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
  * evaluated, which is long before `loadDotenv()` runs, so a `.env` can never
@@ -96,6 +96,32 @@ export function readEnvConfig() {
             enabled: !(skills === '0' || skills === 'false' || skills === 'off' || skills === 'no'),
         };
     }
+    // ARAGON_TEAM=0 turns team mode off; ARAGON_TEAM_MAX=<n> overrides the fan-out
+    // width. Parsed by the POSITIVE list, exactly as ARAGON_FULLSCREEN /
+    // ARAGON_MOUSE / ARAGON_PLAN are — NOT by `envBool` below, which uses a
+    // negative list. The two readers disagree on `ARAGON_TEAM=disable`, and the
+    // documented-but-dead outcome of copying the wrong one is what `load.ts`
+    // records for `ARAGON_MOUSE`.
+    const team = process.env.ARAGON_TEAM?.trim().toLowerCase();
+    const teamMax = process.env.ARAGON_TEAM_MAX?.trim();
+    if ((team !== undefined && team.length > 0) || (teamMax !== undefined && teamMax.length > 0)) {
+        const section = {};
+        if (team !== undefined && team.length > 0) {
+            section.enabled = team === '1' || team === 'true' || team === 'on' || team === 'yes';
+        }
+        if (teamMax !== undefined && teamMax.length > 0) {
+            const parsed = Number.parseInt(teamMax, 10);
+            // Left ABSENT when unparseable rather than written as a default, so the
+            // config file can still win. A resolved default here would make the env
+            // var look permanently supplied.
+            if (Number.isFinite(parsed) && parsed > 0)
+                section.maxSubagents = parsed;
+        }
+        // A PARTIAL section, safe only because every consumer deep-merges it — the
+        // same contract `partial.skills` and `partial.log` rely on.
+        if (Object.keys(section).length > 0)
+            partial.team = section;
+    }
     const log = readEnvLogConfig();
     if (log)
         partial.log = log;

package/dist/config/history-commands.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `aragon history path | list | clear` — the prompt history's operations
+ * surface (config-state-separation §5.5).
+ *
+ * Exit codes follow the existing convention: 0 success · 1 run-time failure ·
+ * 2 usage error.
+ *
+ * EXEMPT from the "every subcommand records one info line" rule, for the same
+ * reason `logging/cli-commands.ts` is: recording a line opens today's log file,
+ * and a command whose job is to delete the user's data should not be creating
+ * files as a side effect of announcing itself.
+ */
+export interface HistoryCliOptions {
+    /** `-n <N>` — entries printed by `list` (default 20). */
+    lines?: string;
+    json?: boolean;
+    /** Required by `clear`; without it the command refuses. */
+    yes?: boolean;
+}
+export declare function runHistoryCommand(subcommand: string, opts: HistoryCliOptions): number;

package/dist/config/history-commands.js

@@ -0,0 +1,71 @@
+/**
+ * `aragon history path | list | clear` — the prompt history's operations
+ * surface (config-state-separation §5.5).
+ *
+ * Exit codes follow the existing convention: 0 success · 1 run-time failure ·
+ * 2 usage error.
+ *
+ * EXEMPT from the "every subcommand records one info line" rule, for the same
+ * reason `logging/cli-commands.ts` is: recording a line opens today's log file,
+ * and a command whose job is to delete the user's data should not be creating
+ * files as a side effect of announcing itself.
+ */
+import { existsSync } from 'node:fs';
+import process from 'node:process';
+import { getPromptHistoryPath } from './app-paths.js';
+import { clearPromptHistory, listPromptHistory } from './prompt-history.js';
+const EXIT_OK = 0;
+const EXIT_USAGE = 2;
+const DEFAULT_LIST_ENTRIES = 20;
+export function runHistoryCommand(subcommand, opts) {
+    switch (subcommand) {
+        case 'path':
+            return runPath();
+        case 'list':
+            return runList(opts);
+        case 'clear':
+            return runClear(opts);
+        default:
+            process.stderr.write(`Unknown history subcommand "${subcommand}". Try: path | list | clear.\n`);
+            return EXIT_USAGE;
+    }
+}
+function runPath() {
+    const path = getPromptHistoryPath();
+    process.stdout.write(`${path}\n`);
+    if (!existsSync(path))
+        process.stdout.write('(no history recorded yet)\n');
+    // The file holds prompts verbatim — the one thing to say out loud before
+    // someone attaches it to a bug report or copies it to another machine.
+    process.stdout.write('entries are stored verbatim; clear them with: aragon history clear --yes\n');
+    return EXIT_OK;
+}
+function runList(opts) {
+    const entries = listPromptHistory();
+    if (entries.length === 0) {
+        process.stdout.write('No prompt history recorded.\n');
+        return EXIT_OK;
+    }
+    const parsed = Number.parseInt(opts.lines ?? '', 10);
+    const wanted = Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_LIST_ENTRIES;
+    const shown = entries.slice(0, wanted);
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(shown, null, 2)}\n`);
+        return EXIT_OK;
+    }
+    for (const entry of shown) {
+        // Newlines would break the one-entry-per-line reading this output invites.
+        const text = entry.text.replace(/\r?\n/g, ' ');
+        process.stdout.write(`${new Date(entry.ts).toISOString()}  ${text}\n`);
+    }
+    return EXIT_OK;
+}
+function runClear(opts) {
+    if (!opts.yes) {
+        process.stderr.write('Refusing to delete the prompt history without --yes.\n');
+        return EXIT_USAGE;
+    }
+    const removed = clearPromptHistory();
+    process.stdout.write(`Removed ${removed} entries.\n`);
+    return EXIT_OK;
+}

package/dist/config/load.d.ts

@@ -39,6 +39,19 @@ export interface CliFlags {
     skillToolPolicy?: string;
     /** `--plan` ⇒ true, `--no-plan` ⇒ false, absent ⇒ undefined (plan-mode §4.4). */
     plan?: boolean;
+    /**
+     * `--team` ⇒ true, `--no-team` ⇒ false, absent ⇒ undefined (team-subagents §4.4).
+     *
+     * BOTH commander forms must be declared and this field must be carried through
+     * `toFlags`, or the flag is inert with no compile error and no runtime error —
+     * the failure `cli.tsx` already records in its own words for `--no-mouse`
+     * (P1-4). Declaring only the negative form additionally makes commander
+     * default `opts.team` to `true`, at which point the flag is indistinguishable
+     * from its own default and silently overrides `config.json` on EVERY run.
+     */
+    team?: boolean;
+    /** `--team-max <n>` — override `team.maxSubagents` for this run (still clamped). */
+    teamMax?: string | number;
     /** `--log-level <lv>` — this run only, never persisted. */
     logLevel?: string;
     /** `--log-file` ⇒ true, `--no-log-file` ⇒ false, absent ⇒ undefined. */

package/dist/config/load.js

@@ -6,9 +6,12 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTheme, clampThinkingLevel, clampTranscriptWindow, coerceMaxTokens, coercePositiveInt, isSkillsToolPolicyMode, } from './schema.js';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTeamConfig, clampTheme, clampThinkingLevel, clampTranscriptWindow, coerceMaxTokens, coercePositiveInt, isSkillsToolPolicyMode, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile } from './store.js';
+import { getConfigPath } from './app-paths.js';
+import { setHistoryEnabled } from './prompt-history.js';
+import { readSubmitCount } from './ui-state.js';
 import { getLogger } from '../logging/logger.js';
 import { registerSecret, registerSecretsFrom } from '../logging/secret-registry.js';
 import { detectCapabilities } from '../ui/capabilities.js';
@@ -73,6 +76,27 @@ function resolveLogToFile(flags, env, file) {
         return false;
     return true;
 }
+/**
+ * Merge the `team` section across all four layers (defaults › file › env ›
+ * flags), team-subagents §3.10.
+ *
+ * `flags.team !== undefined` rather than a truthiness check, and that is the
+ * whole point (P1-4): a truthiness check cannot tell `--no-team` from "not
+ * passed", so `--no-team` would resolve to the config file's value and the off
+ * switch would not be off. `--no-skills` gets away with a one-directional test
+ * only because nothing ever needs to distinguish `--skills` from silence.
+ */
+function resolveTeamConfig(flags, env, file) {
+    return clampTeamConfig({
+        ...DEFAULT_CONFIG.team,
+        ...(file.team ?? {}),
+        ...(env.team ?? {}),
+        ...(flags.team !== undefined ? { enabled: flags.team } : {}),
+        ...(flags.teamMax !== undefined && flags.teamMax !== ''
+            ? { maxSubagents: flags.teamMax }
+            : {}),
+    });
+}
 /** Merge the `log` section across all four layers (defaults › file › env › flags). */
 function resolveLogConfig(flags, env, file) {
     const merged = clampLogConfig({
@@ -178,7 +202,12 @@ export function loadConfig(flags = {}) {
     // Detect terminal capabilities once; force monochrome when color is disabled.
     const caps = detectCapabilities(process.env, process.stdout);
     const colorLevel = color ? caps.colorLevel : 0;
-    return {
+    // No flag and no env var: a privacy switch you set once, not a per-run knob.
+    const historyEnabled = file.historyEnabled ?? DEFAULT_CONFIG.historyEnabled;
+    // The prompt-history store is a module-level singleton, so the resolved value
+    // has to be pushed into it — this is the ONLY place that happens.
+    setHistoryEnabled(historyEnabled);
+    const config = {
         provider,
         model,
         baseUrl,
@@ -195,12 +224,12 @@ export function loadConfig(flags = {}) {
         toolTimeoutMs,
         idleTimeoutMs,
         apiKeys,
-        recentModels: file.recentModels ?? [],
-        promptHistory: file.promptHistory ?? [],
+        historyEnabled,
         density,
         hints,
         mouse: resolveMouse(flags, env.partial, file),
-        submitCount: coercePositiveInt(file.submitCount, 0),
+        // From `<home>/state.json`, not the config file — see `ui-state.ts`.
+        submitCount: readSubmitCount(),
         startInPlanMode,
         planModeMaxAskRounds,
         planModeHumanTimeoutMs,
@@ -217,12 +246,43 @@ export function loadConfig(flags = {}) {
                 : {}),
         },
         log: resolveLogConfig(flags, env.partial, file),
+        team: resolveTeamConfig(flags, env.partial, file),
         cwd,
         color,
         colorLevel,
         unicode: caps.unicode,
         apiKeyOverride: flags.apiKey && flags.apiKey.trim().length > 0 ? flags.apiKey.trim() : undefined,
     };
+    recordResolvedConfig(config);
+    return config;
+}
+/**
+ * One record naming the values this run actually resolved to.
+ *
+ * "I changed the model in config.json and it still uses the old one" was, until
+ * this line existed, unanswerable after the fact: four layers feed this
+ * function and none of them left a trace. Now the answer is in the log next to
+ * the path the values came from.
+ *
+ * NO SECRET VALUES — only whether a key was found. `logging/redact.ts` would
+ * catch one anyway, but a record that never carries the secret does not depend
+ * on that backstop being configured.
+ */
+function recordResolvedConfig(config) {
+    getLogger().info('config', 'config_loaded', {
+        provider: config.provider,
+        model: config.model,
+        baseUrl: config.baseUrl,
+        thinkingLevel: config.thinkingLevel,
+        theme: config.theme,
+        fullscreen: config.fullscreen,
+        toolTimeoutMs: config.toolTimeoutMs,
+        idleTimeoutMs: config.idleTimeoutMs,
+        historyEnabled: config.historyEnabled,
+        logLevel: config.log.level,
+        hasApiKey: Boolean(config.apiKeys[config.provider]),
+        configPath: getConfigPath(),
+    });
 }
 /**
  * Build the `getApiKey(providerId)` resolver the core `Agent` consumes.

package/dist/config/migrate-state-out-of-config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * One-shot move of the four runtime-state keys out of `config.json`
+ * (config-state-separation §4.6).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY THIS EXISTS: the schema change alone would strip `promptHistory`,
+ * `submitCount` and `mouseNoticeSeen` from an existing user's config file on
+ * the first write after upgrading, with nowhere for the values to go. That is
+ * the only path in this feature that can actually LOSE data, which is why the
+ * strip and this migration must ship together.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * THE IDEMPOTENCE KEY IS THE SOURCE DATA — "are those keys still in
+ * config.json" — not a breadcrumb and not "does prompt-history.jsonl exist".
+ * Same reasoning as `migrate-home.ts`: a breadcrumb written before a failed
+ * step makes a half-finished migration skip itself forever. Keyed on the source,
+ * a failure simply retries next launch, and the two import functions are
+ * written so that retrying imports nothing twice.
+ *
+ * NEVER THROWS (C3) and never prints (D-8). The user sees no difference —
+ * history still recalls, the counter still counts — so a line on stderr would
+ * be noise, and `aragon config home` names the new files for anyone curious.
+ */
+export interface StateMigrationResult {
+    /** The keys actually carried out of the file, e.g. `['promptHistory']`. */
+    moved: string[];
+    /** History entries imported, for the log record. */
+    promptEntries: number;
+    /** Returned rather than thrown (C3). */
+    error?: string;
+}
+export declare function migrateStateOutOfConfig(): StateMigrationResult;

package/dist/config/migrate-state-out-of-config.js

@@ -0,0 +1,85 @@
+/**
+ * One-shot move of the four runtime-state keys out of `config.json`
+ * (config-state-separation §4.6).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY THIS EXISTS: the schema change alone would strip `promptHistory`,
+ * `submitCount` and `mouseNoticeSeen` from an existing user's config file on
+ * the first write after upgrading, with nowhere for the values to go. That is
+ * the only path in this feature that can actually LOSE data, which is why the
+ * strip and this migration must ship together.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * THE IDEMPOTENCE KEY IS THE SOURCE DATA — "are those keys still in
+ * config.json" — not a breadcrumb and not "does prompt-history.jsonl exist".
+ * Same reasoning as `migrate-home.ts`: a breadcrumb written before a failed
+ * step makes a half-finished migration skip itself forever. Keyed on the source,
+ * a failure simply retries next launch, and the two import functions are
+ * written so that retrying imports nothing twice.
+ *
+ * NEVER THROWS (C3) and never prints (D-8). The user sees no difference —
+ * history still recalls, the counter still counts — so a line on stderr would
+ * be noise, and `aragon config home` names the new files for anyone curious.
+ */
+import { readConfigFile, updatePersistedConfig } from './store.js';
+import { importLegacyPromptHistory } from './prompt-history.js';
+import { importLegacyUiState } from './ui-state.js';
+import { LEGACY_STATE_KEYS } from './schema.js';
+import { getLogger } from '../logging/logger.js';
+export function migrateStateOutOfConfig() {
+    const result = { moved: [], promptEntries: 0 };
+    try {
+        const { config } = readConfigFile();
+        // A missing file has nothing to move; an UNPARSEABLE one must be left
+        // exactly as it is, or the user's chance to fix their typo is gone.
+        if (!config)
+            return result;
+        const legacy = config;
+        const present = LEGACY_STATE_KEYS.filter((key) => legacy[key] !== undefined);
+        if (present.length === 0)
+            return result;
+        result.promptEntries = importHistory(legacy);
+        importCounters(legacy);
+        // An empty patch still goes read-strip-merge-write, so this is what makes
+        // the legacy keys leave the file — `stripLegacyStateKeys` does the work.
+        updatePersistedConfig({});
+        result.moved = [...present];
+        getLogger().info('migrate', 'migrate_state_split', {
+            moved: result.moved,
+            promptEntries: result.promptEntries,
+        });
+        return result;
+    }
+    catch (err) {
+        return { moved: [], promptEntries: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Import the recall list, unless the user turned recording off.
+ *
+ * THE `historyEnabled` CHECK IS NOT REDUNDANT with the one inside
+ * `appendPrompt`. This runs before any `loadConfig()`, so the module-level
+ * switch is still at its `true` default; the only place the user's real answer
+ * exists at this moment is the config object read above. The path that makes it
+ * matter: upgrade, switch recording off, downgrade to 0.5.x (which writes
+ * `promptHistory` back into config.json), upgrade again. Without this, prompts
+ * the user explicitly refused to have recorded get copied into the new file.
+ */
+function importHistory(legacy) {
+    if (!Array.isArray(legacy.promptHistory) || legacy.promptHistory.length === 0)
+        return 0;
+    if (legacy.historyEnabled === false)
+        return 0;
+    const entries = legacy.promptHistory.filter((item) => typeof item === 'string');
+    return importLegacyPromptHistory(entries);
+}
+function importCounters(legacy) {
+    const patch = {};
+    if (typeof legacy.submitCount === 'number')
+        patch.submitCount = legacy.submitCount;
+    if (typeof legacy.mouseNoticeSeen === 'boolean')
+        patch.mouseNoticeSeen = legacy.mouseNoticeSeen;
+    if (Object.keys(patch).length === 0)
+        return;
+    importLegacyUiState(patch);
+}

package/dist/config/prompt-history.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The prompts the user submitted, as an append-only JSON Lines file at
+ * `<home>/prompt-history.jsonl` (config-state-separation §4.3).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY THIS IS NOT IN config.json ANY MORE: it used to be a `promptHistory`
+ * array inside the config file, which meant every single submit rewrote the
+ * whole file — API key section included — and left a user who opened
+ * `config.json` to change their model scrolling past their own typing. A
+ * config file holds what the user DECLARED; this holds what they DID.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * APPEND, never read-modify-write. Two `aragon` windows are an ordinary setup,
+ * and `O_APPEND` + one `writeSync` per entry means they interleave instead of
+ * overwriting each other's snapshots. It also means a process killed mid-write
+ * costs one broken line rather than a truncated array that reads back as "your
+ * history is gone" — hence the per-line tolerance in `parseLine`.
+ *
+ * FAILURE POLICY (C2), the same one `skills/usage.ts` documents: every function
+ * here swallows its errors. This is recall convenience; a read-only home
+ * directory must degrade to "no history", never to a CLI that will not start.
+ * The one thing that policy makes dangerous is a MISSING WRITE — it would be
+ * invisible — which is why the write path creates `<home>` first and why a
+ * failed append is logged rather than merely ignored.
+ */
+export declare const PROMPT_HISTORY_FILENAME = "prompt-history.jsonl";
+export declare const PROMPT_HISTORY_LINE_VERSION = 1;
+/**
+ * Longer submissions are not recorded at all (D-6).
+ *
+ * Storing a TRUNCATED copy would be worse than storing nothing: the user
+ * presses `↑`, gets back something that looks complete, and sends half a
+ * prompt. 16 KiB is far past anything typed by hand.
+ */
+export declare const PROMPT_ENTRY_MAX_CHARS = 16384;
+/** Physical lines tolerated before the file is rewritten down to the cap. */
+export declare const HISTORY_COMPACT_AT_LINES = 400;
+export interface PromptHistoryEntry {
+    /** Line schema version. Lines with any other value are skipped, not fatal. */
+    v: number;
+    /** `Date.now()` at submit time. */
+    ts: number;
+    /** The prompt verbatim — never redacted (D-5). */
+    text: string;
+}
+/**
+ * The recall list: oldest first, de-duplicated, capped. Cached for the life of
+ * the process so `/reload` — which calls `loadConfig()` again — cannot discard
+ * entries added during this session.
+ *
+ * Reads even when `historyEnabled` is false (RV-12): turning recording off
+ * stops new writes, but someone who wants to see what is already stored before
+ * deleting it must not be told "nothing here" while the file still exists.
+ */
+export declare function loadPromptHistory(): string[];
+/** Every entry on disk with its timestamp, newest first. For `history list`. */
+export declare function listPromptHistory(): PromptHistoryEntry[];
+/**
+ * Record one submitted prompt and return THE UPDATED LIST.
+ *
+ * The return value is the whole point of the signature (RV-1). `App.tsx` writes
+ * `setPromptHistory(appendPrompt(text))`: the recall list rendered by the
+ * composer is React state, and a module-level array updated in here re-renders
+ * nothing. Drop the return value and `↑` stops recalling what was just
+ * submitted — but only until the next restart, which makes it about as hard to
+ * diagnose as a bug in this area gets.
+ *
+ * Returns the current list unchanged when recording is off, the text is blank,
+ * or the text is oversized, so callers never need a branch.
+ */
+export declare function appendPrompt(text: string, now?: number): string[];
+/**
+ * Migration-only: append the texts that are not in the file yet, returning how
+ * many were written.
+ *
+ * Ignores `historyEnabled` on purpose — the caller decides, because it is the
+ * only code that can see an explicit `historyEnabled: false` in the config file
+ * before `loadConfig()` has run (§4.6 step 3).
+ */
+export declare function importLegacyPromptHistory(entries: string[]): number;
+/** Delete the file and empty the cache. Returns how many entries were removed. */
+export declare function clearPromptHistory(): number;
+/** Called once by `loadConfig()` after `historyEnabled` has been resolved. */
+export declare function setHistoryEnabled(enabled: boolean): void;
+/** Test-only: forget the cache, the line counters and the switch. */
+export declare function resetPromptHistoryForTests(): void;