@aragon-agent/cli 0.5.0 → 0.5.2

package/dist/cli.js

@@ -14,23 +14,31 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
+import '../runtime/insecure-tls-warning.cjs';
 import { render } from 'ink';
 import { Command } from 'commander';
 import { loadConfig } from './config/load.js';
-import { getConfigPath, updatePersistedConfig } from './config/store.js';
+import { getConfigPath, readConfigFile, updatePersistedConfig } from './config/store.js';
 import { formatMigrationNotice, migrateLegacyState } from './config/migrate-legacy-state.js';
-import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampSkillsIntegrity, clampSkillsToolPolicy, clampTranscriptWindow, coerceMaxTokens, coercePositiveInt, isAdapterProvider, DEFAULT_SKILLS_CONFIG, } from './config/schema.js';
+import { formatHomeMigrationNotice, migrateToHome } from './config/migrate-home.js';
+import { LOG_CONFIG_SET_KEYS, applyLogConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
+import { attachAgentEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
+import { getLogger } from './logging/logger.js';
+import { runLogsCommand } from './logging/cli-commands.js';
+import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampTranscriptWindow, coerceMaxTokens, coercePositiveInt, isAdapterProvider, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SKILLS_CONFIG, } from './config/schema.js';
 import { makeGetApiKey } from './config/load.js';
 import { AgentController, DENY_ALL_APPROVAL } from './agent/controller.js';
 import { runSkillsCommand } from './skills/cli-commands.js';
 import { runHeadless } from './agent/headless.js';
 import { App } from './ui/App.js';
 import { decideRenderMode } from './ui/layout/frame.js';
+import { tryCreateMouseFilter } from './input/stdin-mouse-filter.js';
 import { enterAltScreen, writeExitTranscript } from './ui/screen.js';
 import { readExitSnapshot } from './ui/exit-snapshot.js';
 import { renderTranscriptText } from './ui/transcript-text.js';
 import { detectCapabilities } from './ui/capabilities.js';
 import { pickGlyphs } from './ui/glyphs.js';
+import { DENY_ALL_HUMAN_INPUT } from './tools/human-input.js';
 // ---------------------------------------------------------------------------
 // Version (read from the shipped package.json next to dist/)
 // ---------------------------------------------------------------------------
@@ -63,10 +71,19 @@ function toFlags(opts) {
         exitTranscript: opts.exitTranscript,
         compact: opts.compact,
         hints: opts.hints,
+        // Without this line the flag never reaches `CliFlags` and `--no-mouse` is
+        // inert — a failure with no compile error and no runtime error (P1-2).
+        mouse: opts.mouse,
         skills: opts.skills,
         skill: opts.skill,
         skillsYes: opts.skillsYes,
         skillToolPolicy: opts.skillToolPolicy,
+        plan: opts.plan,
+        // `--verbose` is just a shorthand for `--log-level debug`; an explicit
+        // `--log-level` still wins, so the two can be combined without surprise.
+        logLevel: opts.logLevel ?? (opts.verbose ? 'debug' : undefined),
+        logFile: opts.logFile,
+        logDir: opts.logDir,
     };
 }
 // ---------------------------------------------------------------------------
@@ -92,7 +109,14 @@ function toFlags(opts) {
  */
 function makeController(flags, opts = { interactive: true }) {
     const config = loadConfig(flags);
+    // The authoritative log level lands here (§4.4.5). `installLogging()` only
+    // resolved a bootstrap level — it ran before commander and before `.env` were
+    // readable — and without this hand-off the fully resolved one never applies.
+    getLogger().reconfigure(config.log);
     const confirmBridge = { handler: null };
+    // `cancelPending` is replaced by the App's own implementation on mount; this
+    // no-op keeps the object total so nothing has to null-check it.
+    const humanInputBridge = { handler: null, cancelPending: () => { } };
     const controller = new AgentController(config, {
         version: VERSION,
         confirm: (req) => confirmBridge.handler ? confirmBridge.handler(req) : Promise.resolve(true),
@@ -109,11 +133,23 @@ function makeController(flags, opts = { interactive: true }) {
             if (!opts.interactive)
                 process.stderr.write(`[skills] ${level}: ${text}\n`);
         },
+        // A THIRD approval channel, and it must not be conflated with the other two.
+        // `confirm` auto-approves when unattached and `approval` denies; neither can
+        // render a question wizard or a plan card. Headless gets the fail-closed
+        // gate, whose STATIC `neverPrompts` is also what stops `createPlanTools`
+        // registering two tools the model could never use there.
+        humanInput: opts.interactive
+            ? {
+                // Live probe, never cached — same contract as `approval` above.
+                canPrompt: () => humanInputBridge.handler !== null,
+                request: (req, signal) => humanInputBridge.handler
+                    ? humanInputBridge.handler(req, signal)
+                    : Promise.resolve(null),
+            }
+            : DENY_ALL_HUMAN_INPUT,
     });
-    return { controller, confirmBridge };
+    return { controller, confirmBridge, humanInputBridge };
 }
-/** POSIX signal numbers for the `128 + signo` exit-code convention. */
-const SIGNAL_NUMBERS = { SIGINT: 2, SIGTERM: 15, SIGHUP: 1 };
 /**
  * The interactive TUI — and the ONLY place that may touch the screen.
  *
@@ -124,11 +160,39 @@ const SIGNAL_NUMBERS = { SIGINT: 2, SIGTERM: 15, SIGHUP: 1 };
  * renders Ink, `runOneShot()` goes to `runHeadless()`, which never does.
  */
 function runInteractive(flags, extras = {}) {
-    const { controller, confirmBridge } = makeController(flags);
+    const { controller, confirmBridge, humanInputBridge } = makeController(flags);
     const config = controller.getConfig();
     const mode = decideRenderMode({ fullscreen: config.fullscreen }, process.env, process.stdout);
+    const logger = getLogger();
+    logger.info('cli', 'run_interactive', { mode, provider: config.provider, model: config.model });
+    attachAgentEvents(logger, controller);
     let screen = null;
     let replayed = false;
+    // --- Mouse wheel region routing (mouse-wheel-region-routing §4.2). -------
+    //
+    // BUILD THE FILTER FIRST, THEN ENABLE REPORTING. The order is invariant I-8
+    // and it is not negotiable: `\x1b[?1000h` tells the terminal to send SGR
+    // reports, and Ink 5.2.1 has no mouse branch at all, so any report that
+    // reaches its key parser is INSERTED INTO THE USER'S MESSAGE (`[` is 0x5B, so
+    // `PromptInput`'s `isControlSeq` guard passes it). A window in which
+    // reporting is on and Ink holds the raw stream is not a degraded feature — it
+    // is every click typing `[<0;12;5M` into the composer, strictly worse than
+    // the bug being fixed.
+    //
+    // `tryCreateMouseFilter` returns `null` rather than throwing, so a
+    // construction failure degrades to "the wheel is inert" (rung 3 of the
+    // fail-safe ladder), never to "reporting on, no filter".
+    // BOTH streams have to be terminals. `stdout.isTTY` is what decides whether
+    // `enterAltScreen` writes anything at all, but the reports come back on
+    // STDIN, so a TTY stdout with a piped stdin (`aragon config < file`, which
+    // reaches `runInteractive` without the stdin check the default action makes)
+    // would wrap a stream no report can ever arrive on and ask the terminal to
+    // start reporting anyway. §4.2's "non-TTY ⇒ no filter" covers both ends.
+    const wantMouse = mode === 'fullscreen' && config.mouse && !!process.stdout.isTTY && !!process.stdin.isTTY;
+    const mouseFilter = wantMouse
+        ? tryCreateMouseFilter(process.stdin, (reason) => logger.warn('cli', 'mouse_filter_failed', { reason }))
+        : null;
+    const disposeMouse = () => mouseFilter?.dispose();
     const replayTranscript = () => {
         if (replayed || mode !== 'fullscreen' || !config.exitTranscript)
             return;
@@ -146,7 +210,10 @@ function runInteractive(flags, extras = {}) {
         }));
     };
     if (mode === 'fullscreen') {
-        screen = enterAltScreen(process.stdout);
+        // `mouse` here means "a filter is installed", NOT "the user wants mouse
+        // support" — see `AltScreenOptions`. `screen.ts` must never derive it for
+        // itself, or a later refactor re-opens the gap I-8 closes.
+        screen = enterAltScreen(process.stdout, { mouse: mouseFilter !== null });
         const restore = () => screen?.restore();
         // Four idempotent restore paths (§4.4). The signal hook is NOT redundant:
         //   - `waitUntilExit().then()` is a microtask and may never be reached when
@@ -158,27 +225,50 @@ function runInteractive(flags, extras = {}) {
         // parent all leave the user staring at a blank alternate screen with `reset`
         // as their only way out.
         process.on('exit', restore);
-        for (const [name, signo] of Object.entries(SIGNAL_NUMBERS)) {
-            process.on(name, () => {
-                restore(); // Synchronous: stdout.write on a TTY is sync on every platform.
-                process.exit(128 + signo);
-            });
-        }
+        // The signal listeners themselves now belong to `installLogging()`, which
+        // registered them before this function ever ran — and a second listener per
+        // signal would race the first. This branch owns the SCREEN, so it supplies
+        // the two screen-shaped pieces and nothing else: the crash handler calls
+        // `screenRestore` before printing a stack (otherwise the stack vanishes with
+        // the alternate screen), and the signal path restores before exiting.
+        setScreenRestore(restore);
+        setSignalTerminator((signo) => {
+            restore(); // Synchronous: stdout.write on a TTY is sync on every platform.
+            process.exit(128 + signo);
+        });
     }
-    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay }), 
+    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, mouseSource: mouseFilter?.source }), 
     // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
     // straight to stdout and permanently shifts the fixed frame's accounting.
-    { exitOnCtrlC: false, patchConsole: mode === 'inline' });
+    {
+        exitOnCtrlC: false,
+        patchConsole: mode === 'inline',
+        // I-5: with mouse support off the REAL stdin is handed over unwrapped, so
+        // every existing path is provably unchanged.
+        stdin: mouseFilter?.stdin ?? process.stdin,
+    });
     // The return value MUST be captured — `waitUntilExit()` is the normal-exit
-    // restore path and it cannot be registered otherwise.
+    // restore path and it cannot be registered otherwise. `dispose()` runs on
+    // BOTH branches (I-7): a live `'data'` listener on stdin keeps the event loop
+    // alive and `aragon` would never return to the shell. The signal path does
+    // not need it — it calls `process.exit()`.
+    //
+    // RESTORE BEFORE DISPOSE. `restore()` writes `?1000l`, so the terminal stops
+    // reporting first and anything already in flight is still consumed by a live
+    // filter. Disposing first leaves a window — narrow, but real — in which the
+    // terminal is still reporting and nothing is draining stdin, so a notch taken
+    // in that instant survives in the OS buffer and is handed to the shell as
+    // `[<64;12;5M` on exit. That is the I-2 failure mode, just smaller.
     void instance
         .waitUntilExit()
         .then(() => {
         screen?.restore();
+        disposeMouse();
         replayTranscript();
     })
         .catch(() => {
         screen?.restore();
+        disposeMouse();
     });
 }
 async function runOneShot(flags, prompt, quiet) {
@@ -186,11 +276,23 @@ async function runOneShot(flags, prompt, quiet) {
     // install. The gate must know that up front rather than discovering a null
     // handler and defaulting to "yes" (§7.4 / AC-13).
     const { controller } = makeController(flags, { interactive: false });
+    const logger = getLogger();
+    logger.info('cli', 'run_oneshot', { quiet });
+    // Headless has no frame, so a logging failure can safely reach stderr — the
+    // toast channel `App.tsx` uses does not exist here.
+    logger.onFailure((reason) => process.stderr.write(`[log] ${reason}\n`));
+    attachAgentEvents(logger, controller);
     const untrusted = controller.getSkillService().untrustedDirs();
     for (const dir of untrusted) {
         process.stderr.write(`[skills] project skills in ${dir} skipped (untrusted). Run: aragon skills trust ${dir}\n`);
     }
     const code = await runHeadless(controller, prompt, { quiet });
+    // Flushed HERE and not inside `runHeadless`: that module is deliberately
+    // injectable (its own controller interface, its own stdout/stderr) and has an
+    // early `return 2`, so a singleton dependency in there would be both a new
+    // coupling and a branch that skips the flush. `process.on('exit')` remains the
+    // real backstop; this just makes the common path immediate.
+    getLogger().flushSync();
     process.exitCode = code;
 }
 async function readStdin() {
@@ -247,6 +349,14 @@ const CONFIG_SET_KEYS = new Set([
     // flags and never persist -- inconsistent with every other config field.
     'density',
     'hints',
+    // MEMBERSHIP HERE ONLY DECIDES THAT THE KEY IS NOT REJECTED. The `switch`
+    // below is what builds the patch, and a key present here but absent there
+    // falls through every case, writes nothing, and still prints
+    // `Set mouse = false` (P1-2) -- exactly what happened to `density`/`hints`.
+    'mouse',
+    'planModeDefault',
+    'planModeMaxAskRounds',
+    'planModeHumanTimeoutMs',
     // Dotted keys route into the nested `skills` object; see the switch below.
     'skills.enabled',
     'skills.requireApproval',
@@ -255,6 +365,9 @@ const CONFIG_SET_KEYS = new Set([
     'skills.integrity',
     'skills.usageTracking',
     'skills.toolPolicy',
+    // `log.*` keys are handled by `applyLogConfigSet` below, NOT by the switch:
+    // that switch is already past this package's complexity ceiling.
+    ...LOG_CONFIG_SET_KEYS,
 ]);
 function runConfigSet(key, value) {
     if (!CONFIG_SET_KEYS.has(key)) {
@@ -262,6 +375,13 @@ function runConfigSet(key, value) {
         process.exitCode = 2;
         return;
     }
+    const logPatch = applyLogConfigSet(key, value);
+    if (logPatch) {
+        updatePersistedConfig(logPatch);
+        warnIfRedactionDisabled(key, value);
+        process.stdout.write(`Set ${key} = ${value}\n`);
+        return;
+    }
     const patch = {};
     switch (key) {
         case 'provider':
@@ -306,6 +426,22 @@ function runConfigSet(key, value) {
         case 'hints':
             patch.hints = value === 'true' || value === '1';
             break;
+        case 'mouse':
+            patch.mouse = value === 'true' || value === '1';
+            break;
+        // Clamped rather than rejected, for the same reason as `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".
+        case 'planModeDefault':
+            patch.planModeDefault = value === 'true' || value === '1';
+            break;
+        case 'planModeMaxAskRounds':
+            patch.planModeMaxAskRounds = clampAskRounds(value, DEFAULT_PLAN_MAX_ASK_ROUNDS);
+            break;
+        case 'planModeHumanTimeoutMs':
+            patch.planModeHumanTimeoutMs = clampHumanTimeout(value, DEFAULT_PLAN_HUMAN_TIMEOUT_MS);
+            break;
         // The dotted keys write a PARTIAL `skills` object. That is safe only
         // because `updatePersistedConfig` deep-merges this section (§10.3.2) —
         // with the old shallow merge each of these would wipe trustedProjectDirs.
@@ -374,16 +510,34 @@ function buildProgram() {
         .option('--no-compact', 'Comfortable transcript density')
         .option('--hints', 'Always show the composer hint row')
         .option('--no-hints', 'Hide the composer hint row')
+        // Positive form first, same tri-state reason as `--fullscreen` above.
+        .option('--mouse', 'Wheel scrolls the region under the pointer (full-screen mode)')
+        .option('--no-mouse', 'Leave the mouse to the terminal (the wheel does nothing)')
         // Declaring `--fullscreen` BEFORE `--no-fullscreen` keeps the default
         // `undefined` instead of `true`, which is what makes the tri-state work:
         // "no opinion" must stay distinguishable from "force it".
         .option('--fullscreen', 'Force the full-screen TUI (overrides auto-downgrade, except non-TTY)')
         .option('--no-fullscreen', 'Force the inline renderer (v0.2.0 behavior)')
         .option('--no-exit-transcript', 'Do not replay the session summary after exiting')
+        // Same tri-state shape as `--fullscreen`: the positive form is declared
+        // FIRST so the default stays `undefined` and "no opinion" remains
+        // distinguishable from an explicit `--no-plan`, which is what lets the
+        // config layer win when neither flag was given.
+        .option('--plan', 'Start the session in PLAN mode (read-only research + review)')
+        .option('--no-plan', 'Start the session in BUILD mode (overrides planModeDefault)')
         .option('--no-skills', 'Disable the skill system entirely (no catalog, no skill tools)')
         .option('--skill <name>', 'Force-load a skill at Level 2 for this run (repeatable)', (value, previous = []) => [...previous, value])
         .option('--skills-yes', 'Approve skill installs for this run (CI / headless)')
         .option('--skill-tool-policy <mode>', 'Tool ceiling from allowed-tools for this run: off | warn | enforce (not persisted)')
+        // `--log-file` is declared BEFORE `--no-log-file` for the tri-state reason
+        // recorded twice above: negative-only would default it to `true` and make a
+        // persisted `log.toFile: false` permanently unreachable.
+        .option('--log-file', 'Write this run to a log file')
+        .option('--no-log-file', 'Do not write this run to a log file')
+        .option('--log-level <level>', 'silent|error|warn|info|debug|trace (this run only)')
+        // No short form: `-v` is already `--version`.
+        .option('--verbose', 'Shorthand for --log-level debug')
+        .option('--log-dir <dir>', 'Absolute log directory for this run')
         .option('--no-color', 'Disable ANSI color')
         .option('--quiet', '(print mode) suppress tool/usage lines on stderr')
         .action(async (prompt, opts) => {
@@ -433,6 +587,37 @@ function buildProgram() {
         .action(() => {
         process.stdout.write(`${getConfigPath()}\n`);
     });
+    configCmd
+        .command('get <key>')
+        .description('Print a single config value (secrets are masked)')
+        .action((key) => runConfigGet(key));
+    configCmd
+        .command('list')
+        .description('Print the whole config (secrets are masked)')
+        .option('--json', 'Machine-readable output')
+        .action((opts) => runConfigList(opts));
+    configCmd
+        .command('edit')
+        .description('Open config.json in $VISUAL / $EDITOR (backs it up first)')
+        .action(async () => {
+        await runConfigEdit();
+    });
+    configCmd
+        .command('home')
+        .description('Print the user-state root directory')
+        .action(() => runConfigHome());
+    // aragon logs <sub> [-n N] [--follow] [--level lv] [--json] [--yes]
+    program
+        .command('logs [subcommand]')
+        .description('Inspect the log files: path | list | tail | clear | open')
+        .option('-n, --lines <n>', 'Lines for `logs tail` (default 100)')
+        .option('--follow', 'Keep printing new records (`logs tail`)')
+        .option('--level <level>', 'Only show records at this level or more severe')
+        .option('--json', 'Print raw JSONL instead of rendered lines')
+        .option('--yes', 'Confirm destructive actions (required by `logs clear`)')
+        .action(async (subcommand, opts) => {
+        process.exitCode = await runLogsCommand(subcommand ?? 'path', opts, toFlags(program.opts()));
+    });
     // aragon skills <sub> [arg] [--scope] [--name] [--description] [--yes] [--json]
     program
         .command('skills [subcommand] [argument]')
@@ -466,16 +651,55 @@ function buildProgram() {
     return program;
 }
 async function main() {
-    // First statement on purpose: everything below reads config or skills, and
-    // both resolve through `envPaths`. Runs before `loadDotenv()` for the same
-    // reason. Never throws — see migrate-legacy-state.ts.
-    const migration = migrateLegacyState();
-    const notice = formatMigrationNotice(migration);
-    if (notice)
-        process.stderr.write(`${notice}\n`);
+    // ① and ② are the first two statements on purpose: everything below reads
+    // config or skills. THE ORDER IS NOT INTERCHANGEABLE — ① moves 0.4.x data out
+    // of the pre-rename env-paths tree, and only then does ② have anything to
+    // move into `~/.aragon-agent`. Run the other way round, `config.json` is
+    // stranded permanently (see migrate-home.ts). Neither ever throws.
+    const legacy = migrateLegacyState();
+    const home = migrateToHome();
+    for (const notice of [formatMigrationNotice(legacy), formatHomeMigrationNotice(home)]) {
+        if (notice)
+            process.stderr.write(`${notice}\n`);
+    }
+    // ③ comes after both because the log directory lives inside a home that ②
+    // may just have created. What ① and ② did is replayed from `pending` rather
+    // than lost.
+    installLogging({ pending: migrationNotes(legacy, home) });
+    // An unparseable config.json still falls back to defaults — the CLI has to
+    // start — but it must not do so in silence, or a stray comma presents as
+    // "every setting I ever chose is gone". stderr, never stdout, so
+    // `aragon -p "…" > out.txt` keeps carrying model output and nothing else.
+    const { parseError } = readConfigFile();
+    if (parseError) {
+        process.stderr.write(`config: using defaults, could not parse ${parseError}\n`);
+    }
     const program = buildProgram();
     await program.parseAsync(process.argv);
 }
+/** The ①/② outcomes, as records for `installLogging` to write once it exists. */
+function migrationNotes(legacy, home) {
+    const notes = [
+        { level: 'info', scope: 'cli', msg: 'cli_start', data: { version: VERSION } },
+    ];
+    if (legacy.mode !== 'none' || legacy.error) {
+        notes.push({
+            level: legacy.error ? 'warn' : 'info',
+            scope: 'migrate',
+            msg: 'migrate_brand',
+            data: { ...legacy },
+        });
+    }
+    if (home.mode !== 'none' || home.error) {
+        notes.push({
+            level: home.error ? 'warn' : 'info',
+            scope: 'migrate',
+            msg: 'migrate_home',
+            data: { ...home },
+        });
+    }
+    return notes;
+}
 main().catch((err) => {
     process.stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
     process.exitCode = 1;

package/dist/commands/builtins.js

@@ -8,7 +8,10 @@ import { existsSync, statSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import process from 'node:process';
 import { clampThinkingLevel, clampTheme, isThemeName, LEGACY_DARK_THEME, THEME_NAMES, THINKING_LEVELS, } from '../config/schema.js';
+import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
+import { loadConfig } from '../config/load.js';
 import { loadSession, resolveSessionPath, saveSession } from '../session/persist.js';
+import { getLogger } from '../logging/logger.js';
 const COMMANDS = [
     {
         name: 'help',
@@ -63,6 +66,30 @@ const COMMANDS = [
             ctx.toast('success', `Theme set to ${name}.`);
         },
     },
+    {
+        name: 'plan',
+        description: 'Toggle plan mode (on | off | status)',
+        // Exists next to Shift+Tab for two reasons: a handful of terminal
+        // multiplexer and remote-desktop stacks never send `CSI Z` at all (R-P1),
+        // and slash commands are the discoverable surface — `/` opens the palette.
+        run: (ctx) => {
+            const arg = ctx.args.trim().toLowerCase();
+            if (arg === 'status') {
+                const s = ctx.controller.getPlanStatus();
+                const pending = s.pending ? ` (pending ${MODE_LABEL[s.pending]} after this run)` : '';
+                ctx.notify('info', `Mode: ${MODE_LABEL[s.effective]}${pending}. ` +
+                    `Ask rounds used: ${s.askRoundsUsed}/${s.maxAskRounds}.`);
+                return;
+            }
+            if (arg.length > 0 && arg !== 'on' && arg !== 'off') {
+                ctx.notify('warn', `Unknown argument "${arg}" - use /plan [on|off|status].`);
+                return;
+            }
+            const current = ctx.controller.getAgentMode();
+            const target = arg === 'on' ? 'plan' : arg === 'off' ? 'build' : nextMode(current);
+            ctx.applyAgentMode(target);
+        },
+    },
     {
         name: 'expand',
         description: 'Expand / collapse a recent tool card (default: last)',
@@ -179,6 +206,39 @@ const COMMANDS = [
             ctx.toast(ok ? 'success' : 'warn', ok ? 'Copied to clipboard.' : 'Clipboard not available.');
         },
     },
+    {
+        name: 'logs',
+        description: 'Show where this session is being logged',
+        run: (ctx) => {
+            const logger = getLogger();
+            const suffix = logger.sinkDisabled ? `\nLogging is OFF: ${logger.sinkError}` : '';
+            ctx.notify('info', `Log file: ${logger.currentLogPath()}\nLevel: ${logger.level}` +
+                ' (debug/trace record prompt and tool content)' +
+                suffix);
+        },
+    },
+    {
+        name: 'reload',
+        description: 'Re-read config.json (after editing it in another window)',
+        run: (ctx) => {
+            // REFUSED WHILE RUNNING, and not out of caution: swapping provider or
+            // model mid-turn would let the second half of an answer be produced under
+            // different settings than the first, with nothing afterwards able to
+            // explain why that answer looks the way it does.
+            if (ctx.state.status === 'running') {
+                ctx.notify('warn', 'Cannot reload the config while a run is in progress.');
+                return;
+            }
+            const config = loadConfig({ cwd: ctx.controller.getCwd() });
+            ctx.controller.setModel(config.provider, config.model, config.baseUrl);
+            ctx.controller.setThinkingLevel(config.thinkingLevel);
+            ctx.controller.setMaxTokens(config.maxTokens);
+            ctx.controller.setTheme(config.theme);
+            getLogger().reconfigure(config.log);
+            getLogger().info('config', 'reload', { provider: config.provider, model: config.model });
+            ctx.toast('success', `Reloaded config: ${config.provider}:${config.model}.`);
+        },
+    },
     {
         name: 'exit',
         aliases: ['quit'],

package/dist/commands/registry.d.ts

@@ -3,6 +3,7 @@
  * input is routed here instead of to the agent; `//` is the literal-`/` escape.
  */
 import type { AgentController } from '../agent/controller.js';
+import type { AgentMode } from '../agent/agent-mode.js';
 import type { NoticeLevel, Overlay, ToastLevel, ViewAction, ViewState } from '../agent/reducer.js';
 import type { PersistedConfig } from '../config/schema.js';
 export interface CommandContext {
@@ -27,6 +28,22 @@ export interface CommandContext {
     submit: (text: string) => void;
     /** Rebuild the system prompt and the dynamic command list after a skill change. */
     refreshSkills: () => void;
+    /**
+     * Apply a mode change through the App's SINGLE write path (§3.1 / R-P7).
+     *
+     * `controller` and `dispatch` are both already in this context, so `/plan`
+     * COULD write the controller and dispatch the mirror itself — and that would
+     * be a second mode write path, which is the one thing the `setAgentMode`
+     * signature was shaped to forbid. One line here instead keeps `/plan` and
+     * `Shift+Tab` literally the same code.
+     *
+     * Returns the ADOPTED state, because `plan -> build` may be deferred and the
+     * command has to report what actually happened, not what it asked for.
+     */
+    applyAgentMode: (next: AgentMode) => {
+        effective: AgentMode;
+        pending: AgentMode | null;
+    };
 }
 export interface SlashCommand {
     name: string;

package/dist/config/app-paths.d.ts

@@ -1,11 +1,78 @@
 /**
- * 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.
+ * ══════════════════════════════════════════════════════════════════════════
  */
 export declare const APP_NAME = "aragon-agent";
-export declare const appPaths: import("env-paths").Paths;
+export declare 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 declare const legacyEnvPaths: import("env-paths").Paths;
+/** `~/.aragon-agent` (or `$ARAGON_HOME`). The root of everything below. */
+export declare function getHomeRoot(): string;
+export declare function getConfigPath(): string;
+/** Written by `aragon config edit` before spawning the editor. */
+export declare function getConfigBackupPath(): string;
+export declare function getLogsDir(): string;
+export declare function getSessionsDir(): string;
+/** `<home>` — parent of `skills/`, and where sidecar state such as usage lives. */
+export declare function getUserDataDir(): string;
+export declare function getUserSkillsDir(): string;
+/** Whether `ARAGON_HOME` was honoured. Captured at load — see `resolution`. */
+export declare function isHomeOverridden(): boolean;
+/**
+ * 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 declare function getHomeResolutionWarning(): string | undefined;