@aragon-agent/cli 0.4.3 → 0.5.1

package/dist/cli.js

@@ -14,12 +14,18 @@ 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';
@@ -31,6 +37,7 @@ 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/)
 // ---------------------------------------------------------------------------
@@ -67,6 +74,12 @@ function toFlags(opts) {
         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 +105,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 +129,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,9 +156,12 @@ 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;
     const replayTranscript = () => {
@@ -158,14 +193,19 @@ 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 }), 
     // 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' });
@@ -186,11 +226,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 +299,9 @@ const CONFIG_SET_KEYS = new Set([
     // flags and never persist -- inconsistent with every other config field.
     'density',
     'hints',
+    'planModeDefault',
+    'planModeMaxAskRounds',
+    'planModeHumanTimeoutMs',
     // Dotted keys route into the nested `skills` object; see the switch below.
     'skills.enabled',
     'skills.requireApproval',
@@ -255,6 +310,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 +320,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 +371,19 @@ function runConfigSet(key, value) {
         case 'hints':
             patch.hints = 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.
@@ -380,10 +458,25 @@ function buildProgram() {
         .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 +526,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 +590,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;