@aragon-agent/cli 0.5.0 → 0.5.2

package/dist/config/migrate-home.d.ts

@@ -0,0 +1,63 @@
+/**
+ * One-shot migration of the user's on-disk state from the `env-paths`
+ * directories into `~/.aragon-agent/`.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY THIS EXISTS: up to 0.5.0 the config lived in
+ * `%APPDATA%\aragon-agent-nodejs\Config` and the sessions and skills in
+ * `%LOCALAPPDATA%\aragon-agent-nodejs\Data`. Moving the root without moving the
+ * contents would present to every existing user as a first run: no API key, no
+ * saved sessions, no installed skills — with all of it still on disk somewhere
+ * nobody thinks to look.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * ORDER MATTERS AND IS NOT INTERCHANGEABLE. `migrateLegacyState()` (chain step
+ * ①, pre-rename tree -> current tree) MUST run first. Run this one first and it
+ * finds the `aragon-agent` env-paths tree empty and does nothing; ① then moves
+ * the 0.4.x data into a location no code reads any more. Because the idempotence
+ * keys below are per-artifact, `sessions` and `skills` would still be picked up
+ * on the NEXT launch — but `config.json` would not: by then the user has re-
+ * entered their key, the target file exists, and the original is stranded.
+ *
+ * THIS FUNCTION NEVER THROWS, for the reason spelled out in
+ * `migrate-legacy-state.ts`: a user who has to re-enter an API key is
+ * inconvenienced; a user whose CLI will not start is blocked.
+ *
+ * THE IDEMPOTENCE KEY IS PER-ARTIFACT — "does this target already exist" — and
+ * deliberately NOT "does the home root exist". The logger creates `<home>/logs`
+ * and `skills/usage.ts` creates `<home>` itself, both of them possibly in this
+ * same process; keying on the root would let a half-finished migration be
+ * skipped forever on the next launch.
+ */
+/** Filesystem surface, so tests never touch a real user directory. */
+export interface HomeMigrationFsPort {
+    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;
+    writeFileSync(path: string, data: string): void;
+}
+export declare const nodeHomeFsPort: HomeMigrationFsPort;
+export interface HomeMigrationResult {
+    mode: 'none' | 'renamed' | 'copied' | 'mixed';
+    /** Artifact names that actually moved (`config.json`, `sessions`, …). */
+    moved: string[];
+    /** Populated instead of throwing. */
+    error?: string;
+}
+export declare function migrateToHome(fs?: HomeMigrationFsPort): HomeMigrationResult;
+/** Path of the breadcrumb, for `aragon config home`'s "previous location" line. */
+export declare function getHomeMigrationBreadcrumbPath(): string;
+/**
+ * The one-line notice for a migration that did something.
+ *
+ * Callers MUST write this to stderr: `aragon -p "..." > out.txt` yields model
+ * output and nothing else, and one stray line here breaks every scripted use.
+ * ASCII-only with `->` rather than an arrow glyph — this prints before any
+ * terminal capability probe has run.
+ */
+export declare function formatHomeMigrationNotice(result: HomeMigrationResult): string | null;

package/dist/config/migrate-home.js

@@ -0,0 +1,165 @@
+/**
+ * One-shot migration of the user's on-disk state from the `env-paths`
+ * directories into `~/.aragon-agent/`.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY THIS EXISTS: up to 0.5.0 the config lived in
+ * `%APPDATA%\aragon-agent-nodejs\Config` and the sessions and skills in
+ * `%LOCALAPPDATA%\aragon-agent-nodejs\Data`. Moving the root without moving the
+ * contents would present to every existing user as a first run: no API key, no
+ * saved sessions, no installed skills — with all of it still on disk somewhere
+ * nobody thinks to look.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * ORDER MATTERS AND IS NOT INTERCHANGEABLE. `migrateLegacyState()` (chain step
+ * ①, pre-rename tree -> current tree) MUST run first. Run this one first and it
+ * finds the `aragon-agent` env-paths tree empty and does nothing; ① then moves
+ * the 0.4.x data into a location no code reads any more. Because the idempotence
+ * keys below are per-artifact, `sessions` and `skills` would still be picked up
+ * on the NEXT launch — but `config.json` would not: by then the user has re-
+ * entered their key, the target file exists, and the original is stranded.
+ *
+ * THIS FUNCTION NEVER THROWS, for the reason spelled out in
+ * `migrate-legacy-state.ts`: a user who has to re-enter an API key is
+ * inconvenienced; a user whose CLI will not start is blocked.
+ *
+ * THE IDEMPOTENCE KEY IS PER-ARTIFACT — "does this target already exist" — and
+ * deliberately NOT "does the home root exist". The logger creates `<home>/logs`
+ * and `skills/usage.ts` creates `<home>` itself, both of them possibly in this
+ * same process; keying on the root would let a half-finished migration be
+ * skipped forever on the next launch.
+ */
+import { cpSync, existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getHomeRoot, legacyEnvPaths } from './app-paths.js';
+import { LEGACY_MIGRATION_BREADCRUMB_FILENAME } from './migrate-legacy-state.js';
+export const nodeHomeFsPort = {
+    existsSync,
+    mkdirSync: (path, options) => {
+        mkdirSync(path, options);
+    },
+    renameSync,
+    cpSync,
+    writeFileSync: (path, data) => writeFileSync(path, data, 'utf-8'),
+};
+const BREADCRUMB_FILENAME = '.migrated-from-env-paths';
+function artifacts(homeRoot) {
+    const config = legacyEnvPaths.config;
+    const data = legacyEnvPaths.data;
+    return [
+        {
+            name: 'config.json',
+            from: join(config, 'config.json'),
+            to: join(homeRoot, 'config.json'),
+            copy: true,
+        },
+        { name: 'sessions', from: join(data, 'sessions'), to: join(homeRoot, 'sessions'), copy: false },
+        { name: 'skills', from: join(data, 'skills'), to: join(homeRoot, 'skills'), copy: false },
+        {
+            name: 'skill-usage.json',
+            from: join(data, 'skill-usage.json'),
+            to: join(homeRoot, 'skill-usage.json'),
+            copy: false,
+        },
+        {
+            name: LEGACY_MIGRATION_BREADCRUMB_FILENAME,
+            from: join(config, LEGACY_MIGRATION_BREADCRUMB_FILENAME),
+            to: join(homeRoot, LEGACY_MIGRATION_BREADCRUMB_FILENAME),
+            copy: false,
+        },
+    ];
+}
+export function migrateToHome(fs = nodeHomeFsPort) {
+    const result = { mode: 'none', moved: [] };
+    try {
+        const homeRoot = getHomeRoot();
+        let renamed = false;
+        let copied = false;
+        for (const artifact of artifacts(homeRoot)) {
+            // Already migrated, or built by hand. Either way: never overwrite.
+            if (fs.existsSync(artifact.to))
+                continue;
+            if (!fs.existsSync(artifact.from))
+                continue;
+            fs.mkdirSync(dirname(artifact.to), { recursive: true });
+            if (artifact.copy) {
+                fs.cpSync(artifact.from, artifact.to, { recursive: true });
+                copied = true;
+            }
+            else if (moveOrCopy(fs, artifact)) {
+                renamed = true;
+            }
+            else {
+                copied = true;
+            }
+            result.moved.push(artifact.name);
+        }
+        if (result.moved.length === 0)
+            return result;
+        result.mode = renamed && copied ? 'mixed' : renamed ? 'renamed' : 'copied';
+        writeBreadcrumb(fs, homeRoot, result);
+        return result;
+    }
+    catch (err) {
+        return { mode: 'none', moved: [], error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Rename, falling back to a copy that KEEPS the source. Returns whether the
+ * rename succeeded.
+ *
+ * On Windows `%APPDATA%` and `%LOCALAPPDATA%` can sit on different volumes, so
+ * `EXDEV` here is ordinary rather than exceptional; antivirus contributes
+ * `EPERM`. A half-written copy next to a deleted original is the only outcome
+ * worse than not migrating at all, which is why the source stays.
+ */
+function moveOrCopy(fs, artifact) {
+    try {
+        fs.renameSync(artifact.from, artifact.to);
+        return true;
+    }
+    catch {
+        fs.cpSync(artifact.from, artifact.to, { recursive: true });
+        return false;
+    }
+}
+/**
+ * Support-diagnosis breadcrumb, and deliberately NOT the idempotence key.
+ *
+ * It swallows its own failures for the same reason the brand migration's does:
+ * letting an ENOENT here reach the caller's outer catch would report
+ * `mode: 'none'` for a migration that actually moved the user's data — telling
+ * support the exact opposite of what happened.
+ */
+function writeBreadcrumb(fs, homeRoot, result) {
+    const payload = {
+        migratedAt: new Date().toISOString(),
+        mode: result.mode,
+        from: { config: legacyEnvPaths.config, data: legacyEnvPaths.data },
+        moved: result.moved,
+    };
+    try {
+        fs.mkdirSync(homeRoot, { recursive: true });
+        fs.writeFileSync(join(homeRoot, BREADCRUMB_FILENAME), `${JSON.stringify(payload, null, 2)}\n`);
+    }
+    catch {
+        // Intentionally ignored — see the note above.
+    }
+}
+/** Path of the breadcrumb, for `aragon config home`'s "previous location" line. */
+export function getHomeMigrationBreadcrumbPath() {
+    return join(getHomeRoot(), BREADCRUMB_FILENAME);
+}
+/**
+ * The one-line notice for a migration that did something.
+ *
+ * Callers MUST write this to stderr: `aragon -p "..." > out.txt` yields model
+ * output and nothing else, and one stray line here breaks every scripted use.
+ * ASCII-only with `->` rather than an arrow glyph — this prints before any
+ * terminal capability probe has run.
+ */
+export function formatHomeMigrationNotice(result) {
+    if (result.mode === 'none')
+        return null;
+    return `moved settings to ${getHomeRoot()} (${result.moved.join(', ')})`;
+}

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

@@ -20,6 +20,15 @@
  * 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 }`.
  *
+ * CHAIN POSITION: this is step ① of two. `migrateToHome()` runs immediately
+ * after it and moves the same data on to `~/.aragon-agent/`. The order is not
+ * interchangeable — see the header of `migrate-home.ts` for what running them
+ * the other way round strands, and why the damage is silent.
+ *
+ * The directories this module reads and writes are the `env-paths` roots, which
+ * after `migrateToHome()` hold nothing the CLI reads. That is why they are
+ * imported here as `legacyEnvPaths`: no other module may use them.
+ *
  * 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
@@ -63,6 +72,7 @@ export interface MigrationResult {
     /** Populated instead of throwing. */
     error?: string;
 }
+export declare const LEGACY_MIGRATION_BREADCRUMB_FILENAME = ".migrated-from-argon-agent";
 export declare function migrateLegacyState(fs?: MigrationFsPort): MigrationResult;
 /**
  * The one-line notice for a migration that did something.

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

@@ -20,6 +20,15 @@
  * 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 }`.
  *
+ * CHAIN POSITION: this is step ① of two. `migrateToHome()` runs immediately
+ * after it and moves the same data on to `~/.aragon-agent/`. The order is not
+ * interchangeable — see the header of `migrate-home.ts` for what running them
+ * the other way round strands, and why the damage is silent.
+ *
+ * The directories this module reads and writes are the `env-paths` roots, which
+ * after `migrateToHome()` hold nothing the CLI reads. That is why they are
+ * imported here as `legacyEnvPaths`: no other module may use them.
+ *
  * 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
@@ -33,7 +42,7 @@
 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';
+import { legacyEnvPaths as envPathsRoots } 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
@@ -55,7 +64,7 @@ export const nodeFsPort = {
 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';
+export const LEGACY_MIGRATION_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
@@ -70,7 +79,7 @@ export function migrateLegacyState(fs = nodeFsPort) {
         const from = {};
         for (const root of ROOTS) {
             const legacy = legacyAppPaths[root];
-            const next = appPaths[root];
+            const next = envPathsRoots[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))
@@ -95,7 +104,7 @@ export function migrateLegacyState(fs = nodeFsPort) {
             return result;
         result.mode = copied ? 'copied' : 'renamed';
         if (result.movedRoots.includes('data')) {
-            result.manifestsRenamed = renameSkillManifests(fs, join(appPaths.data, 'skills'));
+            result.manifestsRenamed = renameSkillManifests(fs, join(envPathsRoots.data, 'skills'));
         }
         writeBreadcrumb(fs, result, from);
         return result;
@@ -155,8 +164,8 @@ function writeBreadcrumb(fs, result, from) {
         manifestsRenamed: result.manifestsRenamed,
     };
     try {
-        fs.mkdirSync(appPaths.config, { recursive: true });
-        fs.writeFileSync(join(appPaths.config, BREADCRUMB_FILENAME), `${JSON.stringify(payload, null, 2)}\n`);
+        fs.mkdirSync(envPathsRoots.config, { recursive: true });
+        fs.writeFileSync(join(envPathsRoots.config, LEGACY_MIGRATION_BREADCRUMB_FILENAME), `${JSON.stringify(payload, null, 2)}\n`);
     }
     catch {
         // Intentionally ignored — see the note above.

package/dist/config/schema.d.ts

@@ -6,6 +6,7 @@
  * invariant).
  */
 import type { ThinkingLevel } from '@aragon-agent/core';
+import { type LogLevelName } from '../logging/levels.js';
 /**
  * `ModelRegistry` seeds builtin lists for five providers, but `initProviders()`
  * registers only three adapters. Running a model whose provider has no adapter
@@ -67,6 +68,16 @@ export declare const DEFAULT_TRANSCRIPT_WINDOW = 300;
 export declare const MIN_TRANSCRIPT_WINDOW = 50;
 export declare const MAX_TRANSCRIPT_WINDOW = 2000;
 export declare function clampTranscriptWindow(v: unknown, fallback: number): number;
+/** `ask_user` calls allowed per user turn. */
+export declare const DEFAULT_PLAN_MAX_ASK_ROUNDS = 4;
+/**
+ * Ceiling on ONE human wait, in ms. Thirty minutes is far outside "the user
+ * went to get coffee", but a ceiling has to exist: an unattended terminal must
+ * not wedge a CI job or a stale ssh session forever.
+ */
+export declare const DEFAULT_PLAN_HUMAN_TIMEOUT_MS = 1800000;
+export declare function clampAskRounds(v: unknown, fallback: number): number;
+export declare function clampHumanTimeout(v: unknown, fallback: number): number;
 export interface SkillsConfig {
     enabled: boolean;
     /** Skill names the user has switched off. */
@@ -149,6 +160,36 @@ export interface SkillsRuntimeOptions {
     toolPolicy?: SkillsToolPolicyMode;
 }
 export declare const DEFAULT_SKILLS_RUNTIME: SkillsRuntimeOptions;
+export interface LogConfig {
+    level: LogLevelName;
+    /** Whether records reach a file at all. */
+    toFile: boolean;
+    /** Absolute log directory; empty string means `<home>/logs`. */
+    dir: string;
+    /** Rotate a file once it would exceed this many bytes. */
+    maxFileBytes: number;
+    /** Files kept in the log directory; the oldest beyond this are deleted. */
+    maxFiles: number;
+    /**
+     * Run every record through the redaction pipeline. The ONE switch a user can
+     * flip to put credentials on disk, which is why turning it off prints a
+     * warning and has no settings-screen entry (§4.3).
+     */
+    redactSecrets: boolean;
+    /** Truncation length for user content at `debug`; `trace` is never truncated. */
+    previewChars: number;
+}
+export declare const DEFAULT_LOG_CONFIG: LogConfig;
+/**
+ * THE single gate for every log-config read AND write, exactly like
+ * `clampSkillsConfig`: hardening only the read path leaves a bad value on disk
+ * that reverts on every launch, which presents as "my setting won't stick".
+ *
+ * `previewChars` uses its own coercion because `coercePositiveInt` rejects `0`,
+ * and `0` is a legitimate value here — it means "record that content existed,
+ * but none of it".
+ */
+export declare function clampLogConfig(raw: unknown): LogConfig;
 export interface PersistedConfig {
     version: number;
     provider: string;
@@ -176,10 +217,33 @@ export interface PersistedConfig {
     density: DensityMode;
     /** Show the composer hint row at all. */
     hints: boolean;
+    /**
+     * Enable SGR mouse reporting in full-screen mode so the wheel scrolls the
+     * region under the pointer (mouse-wheel-region-routing §5.7).
+     *
+     * A PLAIN BOOLEAN, not a `fullscreen`-style tri-state: there are no
+     * heuristics for an explicit `true` to override (D-10).
+     */
+    mouse: boolean;
+    /**
+     * Whether the one-time "hold Shift to select text" notice has been shown
+     * (§6.1). Bookkeeping for a one-shot notice, NOT a preference — hence no
+     * flag, no env var and no `config set` key. Giving it a user-facing channel
+     * would invite it to be treated as one.
+     */
+    mouseNoticeSeen: boolean;
     /** Lifetime submit count driving the progressive-disclosure fade (§4.6). */
     submitCount: number;
+    /** Start every session in PLAN mode (plan-mode §4.4). */
+    planModeDefault: boolean;
+    /** `ask_user` rounds allowed per user turn; clamped to [1, 10]. */
+    planModeMaxAskRounds: number;
+    /** Ceiling on a single human wait in ms; clamped to [60_000, 7_200_000]. */
+    planModeHumanTimeoutMs: number;
     /** Skill system settings. The SECOND nested object in this file after apiKeys. */
     skills: SkillsConfig;
+    /** Logging settings. The THIRD nested object; scalars only (see LogConfig). */
+    log: LogConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 export interface CliConfig {
@@ -214,10 +278,27 @@ export interface CliConfig {
     promptHistory: string[];
     density: DensityMode;
     hints: boolean;
+    /**
+     * Whether this session may enable SGR mouse reporting (full-screen + TTY
+     * only). Resolved by `resolveMouse` in `load.ts`.
+     */
+    mouse: boolean;
     submitCount: number;
+    /**
+     * Whether this session opens in PLAN mode.
+     *
+     * Named for what it DOES rather than mirroring the persisted key: after
+     * resolution it is a resolved starting posture, not a preference, and the
+     * live mode from here on belongs to the controller.
+     */
+    startInPlanMode: boolean;
+    planModeMaxAskRounds: number;
+    planModeHumanTimeoutMs: number;
     skills: SkillsConfig;
     /** Flag/env-only skill switches for this run (§7.5). Never persisted. */
     skillsRuntime: SkillsRuntimeOptions;
+    /** Resolved logging settings; the authoritative input to `Logger.reconfigure`. */
+    log: LogConfig;
     /** Working directory for tools (default `process.cwd()`, overridable). */
     cwd: string;
     /** Whether ANSI color is enabled. */

package/dist/config/schema.js

@@ -5,6 +5,8 @@
  * See spec §3.5 (resolution pipeline), §6.1 (config file), and §3.8 (timeout
  * invariant).
  */
+import { isAbsolute } from 'node:path';
+import { clampLogLevel } from '../logging/levels.js';
 // ---------------------------------------------------------------------------
 // Provider set — only the adapter-backed providers are usable at run time (R5).
 // ---------------------------------------------------------------------------
@@ -102,6 +104,30 @@ export function clampTranscriptWindow(v, fallback) {
     const n = coercePositiveInt(v, fallback);
     return Math.min(MAX_TRANSCRIPT_WINDOW, Math.max(MIN_TRANSCRIPT_WINDOW, n));
 }
+// ---------------------------------------------------------------------------
+// Plan mode (plan-mode §4.4)
+//
+// THREE FLAT KEYS, not a nested `planMode` object. `store.ts` documents that its
+// nested-object merge is hand-written and capped at one level; three scalars do
+// not justify a second `clampXConfig` gate plus two more merge sites, and flat
+// keys mean `store.ts` needs ZERO changes.
+// ---------------------------------------------------------------------------
+/** `ask_user` calls allowed per user turn. */
+export const DEFAULT_PLAN_MAX_ASK_ROUNDS = 4;
+const ASK_ROUNDS_RANGE = { min: 1, max: 10 };
+/**
+ * Ceiling on ONE human wait, in ms. Thirty minutes is far outside "the user
+ * went to get coffee", but a ceiling has to exist: an unattended terminal must
+ * not wedge a CI job or a stale ssh session forever.
+ */
+export const DEFAULT_PLAN_HUMAN_TIMEOUT_MS = 1_800_000;
+const HUMAN_TIMEOUT_RANGE = { min: 60_000, max: 7_200_000 };
+export function clampAskRounds(v, fallback) {
+    return clampInt(v, fallback, ASK_ROUNDS_RANGE);
+}
+export function clampHumanTimeout(v, fallback) {
+    return clampInt(v, fallback, HUMAN_TIMEOUT_RANGE);
+}
 export const SKILLS_INTEGRITY_MODES = ['off', 'warn', 'strict'];
 export function clampSkillsIntegrity(v, fallback) {
     return typeof v === 'string' && SKILLS_INTEGRITY_MODES.includes(v)
@@ -181,6 +207,59 @@ export function clampSkillsConfig(raw) {
     };
 }
 export const DEFAULT_SKILLS_RUNTIME = { forcedSkills: [], approveAll: false };
+const DEFAULT_MAX_LOG_FILE_BYTES = 5 * 1024 * 1024;
+const LOG_FILE_BYTES_RANGE = { min: 64 * 1024, max: 256 * 1024 * 1024 };
+const LOG_MAX_FILES_RANGE = { min: 1, max: 200 };
+const LOG_PREVIEW_CHARS_RANGE = { min: 0, max: 8192 };
+export const DEFAULT_LOG_CONFIG = {
+    level: 'info',
+    toFile: true,
+    dir: '',
+    maxFileBytes: DEFAULT_MAX_LOG_FILE_BYTES,
+    maxFiles: 10,
+    redactSecrets: true,
+    previewChars: 512,
+};
+/**
+ * Coerce a log directory. Anything relative is discarded (falling back to
+ * `<home>/logs`) rather than resolved: a relative path would silently mean a
+ * different directory for every working directory the CLI is launched from, and
+ * `debug`-level files carry prompt text (R-13).
+ */
+function logDir(v, fallback) {
+    if (typeof v !== 'string')
+        return fallback;
+    const trimmed = v.trim();
+    if (trimmed.length === 0)
+        return '';
+    return isAbsolute(trimmed) ? trimmed : fallback;
+}
+/**
+ * THE single gate for every log-config read AND write, exactly like
+ * `clampSkillsConfig`: hardening only the read path leaves a bad value on disk
+ * that reverts on every launch, which presents as "my setting won't stick".
+ *
+ * `previewChars` uses its own coercion because `coercePositiveInt` rejects `0`,
+ * and `0` is a legitimate value here — it means "record that content existed,
+ * but none of it".
+ */
+export function clampLogConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    const preview = typeof src.previewChars === 'number' || typeof src.previewChars === 'string'
+        ? Number.parseInt(String(src.previewChars), 10)
+        : Number.NaN;
+    return {
+        level: clampLogLevel(src.level, DEFAULT_LOG_CONFIG.level),
+        toFile: bool(src.toFile, DEFAULT_LOG_CONFIG.toFile),
+        dir: logDir(src.dir, DEFAULT_LOG_CONFIG.dir),
+        maxFileBytes: clampInt(src.maxFileBytes, DEFAULT_LOG_CONFIG.maxFileBytes, LOG_FILE_BYTES_RANGE),
+        maxFiles: clampInt(src.maxFiles, DEFAULT_LOG_CONFIG.maxFiles, LOG_MAX_FILES_RANGE),
+        redactSecrets: bool(src.redactSecrets, DEFAULT_LOG_CONFIG.redactSecrets),
+        previewChars: Number.isFinite(preview)
+            ? Math.min(LOG_PREVIEW_CHARS_RANGE.max, Math.max(LOG_PREVIEW_CHARS_RANGE.min, preview))
+            : DEFAULT_LOG_CONFIG.previewChars,
+    };
+}
 export const DEFAULT_CONFIG = {
     version: CONFIG_VERSION,
     provider: 'anthropic',
@@ -201,8 +280,14 @@ export const DEFAULT_CONFIG = {
     promptHistory: [],
     density: 'comfortable',
     hints: true,
+    mouse: true,
+    mouseNoticeSeen: false,
     submitCount: 0,
+    planModeDefault: false,
+    planModeMaxAskRounds: DEFAULT_PLAN_MAX_ASK_ROUNDS,
+    planModeHumanTimeoutMs: DEFAULT_PLAN_HUMAN_TIMEOUT_MS,
     skills: DEFAULT_SKILLS_CONFIG,
+    log: DEFAULT_LOG_CONFIG,
 };
 // ---------------------------------------------------------------------------
 // Coercion / validation helpers

package/dist/config/store.d.ts

@@ -1,19 +1,35 @@
 /**
- * Config store — read/atomic-write the user config JSON and resolve OS-specific
- * paths via `env-paths`. The file may hold secrets, so it is written with
- * `0600` permissions on POSIX (spec §3.5 / §6.1).
+ * Config store — read/atomic-write the user config JSON. Paths come from
+ * `app-paths.ts`; nothing here does its own path arithmetic. The file may hold
+ * secrets, so it is written with `0600` permissions on POSIX (spec §3.5 / §6.1).
+ *
+ * There is deliberately no `getConfigDir()` / `getSkillsDir()` here any more.
+ * The first would now return the entire user root under a name that says
+ * otherwise (see the test-isolation contract in `app-paths.ts`); the second was
+ * a second name for `skills/paths.ts::getUserSkillsDir()`, which is precisely
+ * the drift the header of that module warns about.
  */
+import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { type PersistedConfig } from './schema.js';
-export declare function getConfigDir(): string;
-export declare function getConfigPath(): string;
-export declare function getSessionsDir(): string;
-/** User-scope skills root — `aragon skills install`'s default target. */
-export declare function getSkillsDir(): string;
+export { getConfigPath, getSessionsDir };
+export interface ConfigFileRead {
+    /** Only the keys the user actually wrote, or `null` when absent/unusable. */
+    config: Partial<PersistedConfig> | null;
+    /** Set when the file EXISTS but could not be parsed. Otherwise undefined. */
+    parseError?: string;
+}
 /**
- * Read the persisted config file. Returns a partial config (only the keys the
- * user actually wrote) or `null` when the file is absent or unparseable.
+ * Read the persisted config file.
+ *
+ * A corrupt config file still must never crash the CLI — the fallback to
+ * defaults is unchanged. What changed is that it is no longer SILENT: a single
+ * stray comma used to reset the model, theme, timeouts, skills and (as far as
+ * the user could tell) the API key, with nothing anywhere saying why. Now the
+ * failure travels out of band in `parseError`, and `loadConfig()` turns it into
+ * a log record plus one visible line. Hand-editing this file is a supported
+ * workflow, so the failure mode had to become visible.
  */
-export declare function readConfigFile(): Partial<PersistedConfig> | null;
+export declare function readConfigFile(): ConfigFileRead;
 /**
  * Atomically write the persisted config: write a temp file in the same
  * directory, then rename over the target, then re-apply `0600` on POSIX.
@@ -39,6 +55,8 @@ export declare function loadPersistedConfig(): PersistedConfig;
  *
  * `SkillsConfig` is therefore capped at ONE level of nesting (scalars and
  * string arrays only). A third level requires replacing this hand-written merge
- * with a real deep-merge utility first, or the same bug returns.
+ * with a real deep-merge utility first, or the same bug returns. `LogConfig` is
+ * a third SECTION, but it is still one level deep (scalars only), so the same
+ * hand-written merge covers it — and it must stay that way for that reason.
  */
 export declare function updatePersistedConfig(patch: Partial<PersistedConfig>): PersistedConfig;