@aragon-agent/cli 0.5.0 → 0.5.1

package/dist/config/app-paths.js

@@ -1,16 +1,147 @@
 /**
- * The `env-paths` application name, in one place.
+ * The user-state root, in one place.
  *
  * `config/store.ts` and `skills/paths.ts` each used to carry their own copy of
- * this string literal. Two copies of a name is exactly the shape that lets a
+ * the path arithmetic. Two copies of a name is exactly the shape that lets a
  * rename land in one of them and not the other, and the failure is silent: the
  * config file and the skills directory simply stop agreeing about where the
- * user's data lives.
+ * user's data lives. Everything below derives from `homeRoot`.
+ *
+ * LAYOUT (aragon-home-config-and-logging §4.1):
+ *
+ *   ~/.aragon-agent/
+ *   ├── config.json            persisted config (0600 on POSIX)
+ *   ├── config.json.bak        `aragon config edit` pre-edit backup
+ *   ├── logs/                  JSONL logs (0700 on POSIX)
+ *   ├── sessions/              /save · /resume
+ *   ├── skills/                `aragon skills install` target
+ *   └── skill-usage.json
+ *
+ * The same path on all three platforms, deliberately. Claude Code, git and npm
+ * all put their dot-directory in the user's home; one path means documentation,
+ * support scripts and community answers have exactly one thing to say. A user
+ * who wants XDG has `ARAGON_HOME=$XDG_CONFIG_HOME/aragon-agent`.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * TEST-ISOLATION CONTRACT — read before editing anything here or in the tests.
+ *
+ * `getHomeRoot()` returns the WHOLE user root, not just a config directory.
+ * Under the old `env-paths` layout the config directory held one file; here it
+ * holds the API key, every saved session and every installed skill. That makes
+ * a careless `rmSync(<root>, { recursive: true })` in a test an unrecoverable
+ * data loss on the developer's own machine, at a moment when nobody expects the
+ * filesystem to be touched at all. Four rules keep that impossible:
+ *
+ *   1. There is NO `getConfigDir()`. A function whose name says "config dir"
+ *      must never hand back the user root. Code that needs the root calls
+ *      `getHomeRoot()`, where the size of what you are holding is obvious.
+ *   2. `config.test.ts::clearEnv()` must EXEMPT `ARAGON_HOME` — deleting it
+ *      would send any later, non-module-level resolution at the developer's
+ *      real home.
+ *   3. Tests never recursively delete a path a function returned. Delete a
+ *      single file (`rmSync(getConfigPath(), { force: true })`), or delete a
+ *      directory the test itself built under `os.tmpdir()`.
+ *   4. The VITEST branch below. In a test process with no explicit
+ *      `ARAGON_HOME`, the root is redirected into `os.tmpdir()`. Redirecting
+ *      rather than throwing is deliberate: throwing would turn every unrelated
+ *      test that merely imports this module red, and that cost is what tempts
+ *      someone to delete the guard.
+ * ══════════════════════════════════════════════════════════════════════════
  */
+import { existsSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import process from 'node:process';
 import envPaths from 'env-paths';
 export const APP_NAME = 'aragon-agent';
-export const appPaths = envPaths(APP_NAME);
-// The pre-rename name lives in `migrate-legacy-state.ts`, not here. It has
-// exactly one consumer, it is transitional, and keeping it out of this module
-// means retiring the migration some day is a single-file delete rather than an
-// edit that has to remember to come back through here.
+export const HOME_DIR_NAME = '.aragon-agent';
+/**
+ * The pre-0.6.0 `env-paths` roots.
+ *
+ * ONLY the two migration modules may read this. Any other reference is a bug:
+ * it would point new code at the directory the migration exists to empty.
+ */
+export const legacyEnvPaths = envPaths(APP_NAME);
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where to land when `ARAGON_HOME` is absent or unusable.
+ *
+ * Inside vitest this is a per-pid temp root, never the developer's real home —
+ * rule 4 of the contract above, and it has to apply to the FALLBACK too, or a
+ * test that sets `ARAGON_HOME` to something bogus quietly gets the real one.
+ */
+function fallbackRoot() {
+    if (process.env.VITEST)
+        return join(tmpdir(), `aragon-agent-vitest-${process.pid}`);
+    return join(homedir(), HOME_DIR_NAME);
+}
+function resolveHomeRoot() {
+    const raw = process.env.ARAGON_HOME?.trim();
+    if (raw && raw.length > 0) {
+        const candidate = resolve(raw);
+        if (existsSync(candidate) && !isDirectory(candidate)) {
+            return {
+                root: fallbackRoot(),
+                overridden: false,
+                warning: `ARAGON_HOME=${candidate} is not a directory; using ${fallbackRoot()}`,
+            };
+        }
+        return { root: candidate, overridden: true };
+    }
+    return { root: fallbackRoot(), overridden: false };
+}
+/**
+ * Resolved ONCE at module load, matching what `envPaths()` did here before.
+ *
+ * The existing tests set their environment and then `await import(...)`; keeping
+ * the same model means test isolation stays "set the env first", not a new mock
+ * framework. It also means `isHomeOverridden()` must report the value captured
+ * here rather than re-reading `process.env` — `config.test.ts::clearEnv()` wipes
+ * `ARAGON_*` before every test, and a live read would answer `false` for a run
+ * that really is overridden.
+ */
+const resolution = resolveHomeRoot();
+/** `~/.aragon-agent` (or `$ARAGON_HOME`). The root of everything below. */
+export function getHomeRoot() {
+    return resolution.root;
+}
+export function getConfigPath() {
+    return join(resolution.root, 'config.json');
+}
+/** Written by `aragon config edit` before spawning the editor. */
+export function getConfigBackupPath() {
+    return join(resolution.root, 'config.json.bak');
+}
+export function getLogsDir() {
+    return join(resolution.root, 'logs');
+}
+export function getSessionsDir() {
+    return join(resolution.root, 'sessions');
+}
+/** `<home>` — parent of `skills/`, and where sidecar state such as usage lives. */
+export function getUserDataDir() {
+    return resolution.root;
+}
+export function getUserSkillsDir() {
+    return join(resolution.root, 'skills');
+}
+/** Whether `ARAGON_HOME` was honoured. Captured at load — see `resolution`. */
+export function isHomeOverridden() {
+    return resolution.overridden;
+}
+/**
+ * Why an `ARAGON_HOME` override was ignored, if it was.
+ *
+ * Path resolution happens before the logger exists, so the reason is parked
+ * here and written out by `installLogging()` once there is somewhere to put it.
+ */
+export function getHomeResolutionWarning() {
+    return resolution.warning;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * `aragon config get | list | edit | home`, plus the `log.*` branch 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 —
+ * and `cli.tsx` has two other designs queued up against it. `cli.tsx` keeps the
+ * wiring; the behaviour is here.
+ */
+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"];
+/**
+ * Translate a `log.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `log` section, which is safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge each
+ * of these would silently reset every other log setting, `redactSecrets`
+ * included.
+ */
+export declare function applyLogConfigSet(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
+ * so out loud, because a user who turns it off and forgets is the user who
+ * later pastes a log into an issue.
+ */
+export declare function warnIfRedactionDisabled(key: string, value: string): void;
+export declare function runConfigGet(key: string): void;
+export declare function runConfigList(opts?: {
+    json?: boolean;
+}): void;
+/**
+ * Open `config.json` in the user's editor.
+ *
+ * Backs the file up FIRST and re-parses afterwards. Hand-editing is a supported
+ * workflow here, and a stray comma otherwise resets every setting the next time
+ * the CLI starts, with nothing connecting the two events. Telling the user
+ * immediately — and naming the backup — turns a confusing regression into a
+ * one-command recovery.
+ */
+export declare function runConfigEdit(): Promise<void>;
+export declare function runConfigHome(): void;

package/dist/config/cli-commands.js

@@ -0,0 +1,196 @@
+/**
+ * `aragon config get | list | edit | home`, plus the `log.*` branch 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 —
+ * and `cli.tsx` has two other designs queued up against it. `cli.tsx` keeps the
+ * wiring; the behaviour is here.
+ */
+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 { getHomeMigrationBreadcrumbPath } from './migrate-home.js';
+import { loadPersistedConfig, updatePersistedConfig } from './store.js';
+import { coercePositiveInt, maskSecret, } from './schema.js';
+import { clampLogLevel } from '../logging/levels.js';
+/** Config keys under `log.` that `aragon config set` accepts. */
+export const LOG_CONFIG_SET_KEYS = [
+    'log.level',
+    'log.toFile',
+    'log.dir',
+    'log.maxFileBytes',
+    'log.maxFiles',
+    'log.redactSecrets',
+    'log.previewChars',
+];
+function isTrue(value) {
+    return value === 'true' || value === '1';
+}
+/**
+ * Translate a `log.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `log` section, which is safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge each
+ * of these would silently reset every other log setting, `redactSecrets`
+ * included.
+ */
+export function applyLogConfigSet(key, value) {
+    const patch = (log) => ({ log });
+    switch (key) {
+        case 'log.level':
+            return patch({ level: clampLogLevel(value, 'info') });
+        case 'log.toFile':
+            return patch({ toFile: isTrue(value) });
+        case 'log.dir':
+            return patch({ dir: value.trim() });
+        case 'log.maxFileBytes':
+            return patch({ maxFileBytes: coercePositiveInt(value, 5 * 1024 * 1024) });
+        case 'log.maxFiles':
+            return patch({ maxFiles: coercePositiveInt(value, 10) });
+        case 'log.redactSecrets':
+            return patch({ redactSecrets: isTrue(value) });
+        case 'log.previewChars':
+            return patch({ previewChars: Number.parseInt(value, 10) });
+        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
+ * so out loud, because a user who turns it off and forgets is the user who
+ * later pastes a log into an issue.
+ */
+export function warnIfRedactionDisabled(key, value) {
+    if (key !== 'log.redactSecrets' || isTrue(value))
+        return;
+    process.stdout.write('WARNING: secret redaction is OFF. API keys may now be written to the log files ' +
+        `in ${getLogsDir()}. Re-enable with: aragon config set log.redactSecrets true\n`);
+}
+// ---------------------------------------------------------------------------
+// get / list
+// ---------------------------------------------------------------------------
+/** Every secret is masked wherever it is printed, `--json` included (R-12). */
+function maskConfig(config) {
+    const apiKeys = {};
+    for (const [provider, key] of Object.entries(config.apiKeys)) {
+        apiKeys[provider] = maskSecret(key);
+    }
+    return { ...config, apiKeys };
+}
+/** Resolve a flat or one-level-dotted key against the persisted config. */
+function readKey(config, key) {
+    const [head, tail] = key.split('.', 2);
+    const top = config[head];
+    if (tail === undefined)
+        return top;
+    if (!top || typeof top !== 'object')
+        return undefined;
+    return top[tail];
+}
+export function runConfigGet(key) {
+    const masked = maskConfig(loadPersistedConfig());
+    const value = readKey(masked, key);
+    if (value === undefined) {
+        process.stderr.write(`Unknown config key "${key}".\n`);
+        process.exitCode = 2;
+        return;
+    }
+    process.stdout.write(`${typeof value === 'string' ? value : JSON.stringify(value)}\n`);
+}
+export function runConfigList(opts = {}) {
+    const masked = maskConfig(loadPersistedConfig());
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(masked, null, 2)}\n`);
+        return;
+    }
+    for (const [key, value] of Object.entries(masked)) {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            for (const [sub, subValue] of Object.entries(value)) {
+                process.stdout.write(`${key}.${sub} = ${JSON.stringify(subValue)}\n`);
+            }
+            continue;
+        }
+        process.stdout.write(`${key} = ${JSON.stringify(value)}\n`);
+    }
+}
+// ---------------------------------------------------------------------------
+// edit / home
+// ---------------------------------------------------------------------------
+function pickEditor() {
+    const configured = process.env.VISUAL?.trim() || process.env.EDITOR?.trim();
+    if (configured)
+        return configured;
+    return process.platform === 'win32' ? 'notepad' : 'vi';
+}
+/**
+ * Open `config.json` in the user's editor.
+ *
+ * Backs the file up FIRST and re-parses afterwards. Hand-editing is a supported
+ * workflow here, and a stray comma otherwise resets every setting the next time
+ * the CLI starts, with nothing connecting the two events. Telling the user
+ * immediately — and naming the backup — turns a confusing regression into a
+ * one-command recovery.
+ */
+export async function runConfigEdit() {
+    const file = getConfigPath();
+    if (!existsSync(file)) {
+        // Materialise defaults so the editor has something to show.
+        updatePersistedConfig({});
+    }
+    const backup = getConfigBackupPath();
+    try {
+        copyFileSync(file, backup);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Could not write ${backup}: ${reason}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const editor = pickEditor();
+    // A shell is needed on Windows so an `EDITOR` pointing at a `.cmd` / `.bat`
+    // launcher (`code.cmd`, most of them) still runs — but a shell re-splits the
+    // command line, so the path has to be quoted or `C:\Users\Jane Doe\...` would
+    // reach the editor as two arguments and open two empty buffers.
+    const useShell = process.platform === 'win32';
+    const target = useShell ? `"${file}"` : file;
+    const result = spawnSync(editor, [target], { stdio: 'inherit', shell: useShell });
+    if (result.error) {
+        process.stderr.write(`Could not launch "${editor}": ${result.error.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        JSON.parse(readFileSync(file, 'utf-8'));
+        process.stdout.write(`${file} saved.\n`);
+    }
+    catch (err) {
+        process.stderr.write(`${file} is not valid JSON (${err instanceof Error ? err.message : String(err)}).\n` +
+            `The previous version is still at ${backup}.\n`);
+        process.exitCode = 1;
+    }
+}
+export function runConfigHome() {
+    process.stdout.write(`${getHomeRoot()}\n`);
+    if (isHomeOverridden())
+        process.stdout.write('  (overridden by ARAGON_HOME)\n');
+    const breadcrumb = getHomeMigrationBreadcrumbPath();
+    if (!existsSync(breadcrumb))
+        return;
+    // The env-paths directories are left in place on purpose so reinstalling an
+    // older build stays lossless; pointing at them is how the user knows they can
+    // be deleted once the new location has proved itself.
+    try {
+        const parsed = JSON.parse(readFileSync(breadcrumb, 'utf-8'));
+        if (parsed.from?.config)
+            process.stdout.write(`  previously: ${parsed.from.config}\n`);
+        if (parsed.from?.data)
+            process.stdout.write(`  previously: ${parsed.from.data}\n`);
+    }
+    catch {
+        // A damaged breadcrumb is a lost diagnostic, not an error worth reporting.
+    }
+}

package/dist/config/env.d.ts

@@ -5,7 +5,13 @@
  *   - 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_MAX_TOKENS, ARAGON_THEME, ARAGON_PLAN, 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
+ * supply it. README and §5.2 of the design say so explicitly — otherwise "I set
+ * ARAGON_HOME in .env and it did nothing" is an unexplainable bug report.
  */
 import { type PersistedConfig } from './schema.js';
 /**

package/dist/config/env.js

@@ -5,11 +5,19 @@
  *   - 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_MAX_TOKENS, ARAGON_THEME, ARAGON_PLAN, 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
+ * supply it. README and §5.2 of the design say so explicitly — otherwise "I set
+ * ARAGON_HOME in .env and it did nothing" is an unexplainable bug report.
  */
 import { join } from 'node:path';
 import process from 'node:process';
 import dotenv from 'dotenv';
+import { registerSecretsFrom } from '../logging/secret-registry.js';
+import { clampLogLevel } from '../logging/levels.js';
 import { clampTheme, clampThinkingLevel, coerceMaxTokens, } from './schema.js';
 /**
  * Load a project `.env` from the given directory into `process.env` (existing
@@ -63,6 +71,12 @@ export function readEnvConfig() {
     if (fullscreen !== undefined && fullscreen.length > 0) {
         partial.fullscreen = fullscreen === '1' || fullscreen === 'true' || fullscreen === 'on' || fullscreen === 'yes';
     }
+    // ARAGON_PLAN=1 starts the session in PLAN mode — the same channel story as
+    // ARAGON_FULLSCREEN, for terminals reached through a wrapper that owns argv.
+    const plan = process.env.ARAGON_PLAN?.trim().toLowerCase();
+    if (plan !== undefined && plan.length > 0) {
+        partial.planModeDefault = plan === '1' || plan === 'true' || plan === 'on' || plan === '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 —
@@ -74,12 +88,42 @@ export function readEnvConfig() {
             enabled: !(skills === '0' || skills === 'false' || skills === 'off' || skills === 'no'),
         };
     }
+    const log = readEnvLogConfig();
+    if (log)
+        partial.log = log;
     const apiKeys = {};
     for (const [prov, names] of Object.entries(PROVIDER_ENV_KEYS)) {
         apiKeys[prov] = firstEnv(names);
     }
+    // Registration site 2 (§4.4.3). A key that only ever lives in the environment
+    // never passes through `updatePersistedConfig`, so this is its only chance to
+    // reach the redactor's backstop.
+    registerSecretsFrom(apiKeys);
     return { partial, apiKeys };
 }
+/** Interpret `0/false/off/no` as false; anything else non-empty as true. */
+function envBool(value) {
+    const v = value.trim().toLowerCase();
+    return !(v === '0' || v === 'false' || v === 'off' || v === 'no');
+}
+/**
+ * Assemble the `log` section from the environment, or `undefined` when the user
+ * said nothing about it. Same shape as the `partial.skills` assembly above: a
+ * PARTIAL section, safe only because every consumer deep-merges it.
+ */
+function readEnvLogConfig() {
+    const out = {};
+    const level = process.env.ARAGON_LOG_LEVEL?.trim();
+    if (level)
+        out.level = clampLogLevel(level, 'info');
+    const toFile = process.env.ARAGON_LOG_FILE?.trim();
+    if (toFile !== undefined && toFile.length > 0)
+        out.toFile = envBool(toFile);
+    const dir = process.env.ARAGON_LOG_DIR?.trim();
+    if (dir)
+        out.dir = dir;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 /** Skill names disabled for this run via `ARAGON_SKILLS_DISABLED` (comma-separated). */
 export function readEnvDisabledSkills() {
     const raw = process.env.ARAGON_SKILLS_DISABLED;

package/dist/config/load.d.ts

@@ -35,6 +35,14 @@ export interface CliFlags {
     skillsYes?: boolean;
     /** `--skill-tool-policy <mode>` — override the tool ceiling for this run (§5.5). */
     skillToolPolicy?: string;
+    /** `--plan` ⇒ true, `--no-plan` ⇒ false, absent ⇒ undefined (plan-mode §4.4). */
+    plan?: boolean;
+    /** `--log-level <lv>` — this run only, never persisted. */
+    logLevel?: string;
+    /** `--log-file` ⇒ true, `--no-log-file` ⇒ false, absent ⇒ undefined. */
+    logFile?: boolean;
+    /** `--log-dir <dir>` — this run only. */
+    logDir?: string;
 }
 /**
  * Resolve the effective config by merging all layers, then derive the runtime

package/dist/config/load.js

@@ -6,9 +6,11 @@
  * 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 { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTheme, clampThinkingLevel, clampTranscriptWindow, coerceMaxTokens, coercePositiveInt, isSkillsToolPolicyMode, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile } from './store.js';
+import { getLogger } from '../logging/logger.js';
+import { registerSecret, registerSecretsFrom } from '../logging/secret-registry.js';
 import { detectCapabilities } from '../ui/capabilities.js';
 /** Interpret a boolean-ish env value (`1/true/on/yes`) as `true`. */
 function envFlagTrue(value) {
@@ -31,6 +33,35 @@ function resolveFullscreen(flags, env, file) {
         return false;
     return undefined;
 }
+/**
+ * Resolve whether logs reach a file: flag › env › an explicit `false` in the
+ * file › default `true`.
+ *
+ * Shaped exactly like `resolveFullscreen` above, and for the same reason: the
+ * config file's DEFAULT `true` must not be mistaken for an opinion, or
+ * `--no-log-file` would be the only way to ever turn logging off and a stored
+ * `toFile: false` would be unreachable.
+ */
+function resolveLogToFile(flags, env, file) {
+    if (flags.logFile !== undefined)
+        return flags.logFile;
+    if (env.log?.toFile !== undefined)
+        return env.log.toFile;
+    if (file.log?.toFile === false)
+        return false;
+    return true;
+}
+/** Merge the `log` section across all four layers (defaults › file › env › flags). */
+function resolveLogConfig(flags, env, file) {
+    const merged = clampLogConfig({
+        ...DEFAULT_CONFIG.log,
+        ...(file.log ?? {}),
+        ...(env.log ?? {}),
+        ...(flags.logLevel ? { level: flags.logLevel } : {}),
+        ...(flags.logDir ? { dir: flags.logDir } : {}),
+    });
+    return { ...merged, toFile: resolveLogToFile(flags, env, file) };
+}
 // ---------------------------------------------------------------------------
 // loadConfig
 // ---------------------------------------------------------------------------
@@ -49,8 +80,18 @@ 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 read = readConfigFile();
+    const file = read.config ?? {};
     const env = readEnvConfig();
+    // A config file that exists but will not parse used to reset EVERY setting
+    // with nothing anywhere explaining it. The fallback is unchanged; what is new
+    // is that it leaves a trace. The record alone is not the explanation, so the
+    // two owners of a user-visible channel say it too: `main()` writes one stderr
+    // line (headless, inline and every subcommand) and `App.tsx` raises a toast
+    // (full-screen, where the alternate screen wipes that line away).
+    if (read.parseError) {
+        getLogger().error('config', 'config_parse_failed', { error: read.parseError });
+    }
     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);
@@ -66,6 +107,13 @@ export function loadConfig(flags = {}) {
         : 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;
+    // Plan mode: defaults -> file -> env -> flags, the same order as every other
+    // field. `pick` keeps an explicit `false`, so `--no-plan` really does override
+    // a config file that turned plan mode on.
+    const startInPlanMode = pick(flags.plan, env.partial.planModeDefault, file.planModeDefault) ??
+        DEFAULT_CONFIG.planModeDefault;
+    const planModeMaxAskRounds = clampAskRounds(file.planModeMaxAskRounds, DEFAULT_CONFIG.planModeMaxAskRounds);
+    const planModeHumanTimeoutMs = clampHumanTimeout(file.planModeHumanTimeoutMs, DEFAULT_CONFIG.planModeHumanTimeoutMs);
     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
@@ -95,6 +143,11 @@ export function loadConfig(flags = {}) {
             ...new Set([...(file.skills?.disabled ?? []), ...readEnvDisabledSkills()]),
         ],
     });
+    // Registration site 3 (§4.4.3): the merged view plus the one-shot `--api-key`,
+    // which exists nowhere else. Overlaps with sites 1 and 2 on purpose —
+    // registering twice costs a `Set.add`, missing once costs a credential.
+    registerSecretsFrom(apiKeys);
+    registerSecret(flags.apiKey);
     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) ||
@@ -125,6 +178,9 @@ export function loadConfig(flags = {}) {
         density,
         hints,
         submitCount: coercePositiveInt(file.submitCount, 0),
+        startInPlanMode,
+        planModeMaxAskRounds,
+        planModeHumanTimeoutMs,
         skills,
         skillsRuntime: {
             forcedSkills: flags.skill ?? [],
@@ -137,6 +193,7 @@ export function loadConfig(flags = {}) {
                 ? { toolPolicy: flags.skillToolPolicy }
                 : {}),
         },
+        log: resolveLogConfig(flags, env.partial, file),
         cwd,
         color,
         colorLevel,