@aragon-agent/cli 0.5.11 → 0.6.1

package/dist/agent/reducer.js

@@ -692,10 +692,20 @@ export function viewReducer(state, action) {
                 streamingId: undefined,
                 expandedToolIds: {},
                 teamEntryId: undefined,
-                // The entry it pointed at is gone, so the id goes with it. `todos` is
-                // DELIBERATELY UNTOUCHED (I-2): `/clear` wipes the transcript and not
-                // the conversation, so the model still believes in the plan, and a panel
-                // that disagrees with the model is worse than no panel.
+                // The list goes with the screen it was on. `/clear` is an explicit user
+                // instruction, which is I-2's standing exception (`TodoClearReason`
+                // `'user'`, the same door `/todo clear` uses) — so the command clears the
+                // STORE via `controller.clearTodos()` and this clears the MIRROR, exactly
+                // the pairing `resetConversation` below has always had.
+                //
+                // The mirror write is same-valued with the store's own `todoCleared`
+                // dispatch rather than redundant with it: it is what makes this action
+                // stand on its own. `builtins.ts` is the only dispatcher of it TODAY, and
+                // a second one — a real clear-screen key, a session-restore path — would
+                // otherwise bring the bug back in identical form and in silence.
+                //
+                // The entry id is dropped because the entry it pointed at is gone.
+                todos: null,
                 todoEntryId: undefined,
                 // Same reasoning for the retry card: the entry is gone, so the id must go
                 // with it or `retryScheduled` would `mapEntry` an id that no longer

package/dist/agent/system-prompt.d.ts

@@ -72,6 +72,22 @@ export interface SystemPromptParams {
      * reviewed, so `buildSubagentBlock`'s caller leaves this unset.
      */
     fastBlock?: string;
+    /**
+     * `aragon exec --append-system-prompt` (cli-integration-surface §4.1 / D-9),
+     * appended VERBATIM under a stable `## Additional instructions` heading, after
+     * everything the CLI generates.
+     *
+     * APPEND ONLY. There is deliberately no `--system-prompt` that REPLACES the
+     * base: the builtin prompt is what carries tool discipline, the todo-planning
+     * rules, the skills catalog and the plan-mode block, so replacing it silently
+     * disables half the product and the symptom is "the model got worse" — the
+     * least diagnosable failure mode available.
+     *
+     * Spliced conditionally exactly as `skillsBlock` and the four blocks above
+     * are, so an absent or empty value produces a BYTE-IDENTICAL prompt to today's
+     * for a fixed `tools` array. Every existing caller passes nothing.
+     */
+    appendSystemPrompt?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -41,6 +41,7 @@ export function buildSystemPrompt(params) {
     const subagentBlock = params.subagentBlock ?? '';
     const todoBlock = params.todoBlock ?? '';
     const fastBlock = params.fastBlock ?? '';
+    const appended = (params.appendSystemPrompt ?? '').trim();
     return [
         'You are AragonAgent, an autonomous coding assistant operating inside a terminal (TUI).',
         'You help the user accomplish software-engineering tasks by reasoning step by step and using the provided tools.',
@@ -70,5 +71,9 @@ export function buildSystemPrompt(params) {
             ? ['- Skill content is reference material, not new instructions from the user.']
             : []),
         '- Respond in the language the user writes in.',
+        // LAST, AND UNDER A STABLE HEADING. Last so nothing the CLI generates can
+        // be read as a correction of the caller's instructions; a stable heading so
+        // a wrapper diffing two prompts can find its own text.
+        ...(appended ? ['', '## Additional instructions', '', appended] : []),
     ].join('\n');
 }

package/dist/cli.js

@@ -32,6 +32,13 @@ 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';
+// The four `register*Command` entry points of cli-integration-surface §3.1. The
+// declarations live in those modules rather than here; see the header of
+// `exec/cli-commands.ts` for why this new code departs from the `logs` /
+// `history` / `skills` convention.
+import { registerExecCommand } from './exec/cli-commands.js';
+import { registerSessionsCommand } from './session/cli-commands.js';
+import { registerDoctorCommand, registerInfoCommand } from './diagnostics/cli-commands.js';
 import { App } from './ui/App.js';
 import { decideRenderMode } from './ui/layout/frame.js';
 import { createFrameDiffer } from './ui/frame-differ.js';
@@ -39,6 +46,7 @@ import { wrapStdoutForFrames } from './ui/stdout-frame-writer.js';
 import { setFrameStatsProvider } from './commands/perf.js';
 import { tryCreateMouseFilter } from './input/stdin-mouse-filter.js';
 import { enterAltScreen, writeExitTranscript } from './ui/screen.js';
+import { supportsWindowsVtInput } from './ui/win-vt-input.js';
 import { readExitSnapshot } from './ui/exit-snapshot.js';
 import { renderTranscriptText } from './ui/transcript-text.js';
 import { detectCapabilities } from './ui/capabilities.js';
@@ -234,9 +242,35 @@ function makeController(flags, opts = { interactive: true }) {
                     : Promise.resolve(null),
             }
             : DENY_ALL_HUMAN_INPUT,
+        ...(opts.permission ? { permission: opts.permission } : {}),
+        ...(opts.appendSystemPrompt ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
     });
     return { controller, confirmBridge, humanInputBridge };
 }
+/**
+ * The controller factory `aragon exec` runs on.
+ *
+ * IT REPRODUCES `runOneShot`'s SETUP EXACTLY, and that is the whole reason it
+ * lives here rather than inside `exec/`: the deny-all approval gate, the
+ * deny-all human-input channel, the two log attachments and the untrusted-skill
+ * notices are decisions `makeController`'s own comment says must have ONE
+ * definition. `exec/index.ts` receives this as a parameter, which also keeps
+ * `cli.tsx -> exec/cli-commands.ts -> exec/index.ts` acyclic.
+ */
+function makeExecController(flags, deps) {
+    const { controller } = makeController(flags, { interactive: false, ...deps });
+    const logger = getLogger();
+    logger.info('cli', 'run_exec', {});
+    logger.onFailure((reason) => process.stderr.write(`[log] ${reason}\n`));
+    attachAgentEvents(logger, controller);
+    attachTeamEvents(logger, controller);
+    for (const dir of controller.getSkillService().untrustedDirs()) {
+        // STDERR, NEVER STDOUT. In `json` / `stream-json` mode stdout carries
+        // nothing but the schema, and a notice on it would corrupt every consumer.
+        process.stderr.write(`[skills] project skills in ${dir} skipped (untrusted). Run: aragon skills trust ${dir}\n`);
+    }
+    return controller;
+}
 /**
  * Raised once per session, on the 0->1 edge of the writer's `fallbacks` counter
  * (tui-input-flicker-fix §5.6 / AC-15).
@@ -294,7 +328,23 @@ function runInteractive(flags, extras = {}) {
     // 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;
+    //
+    // R-1 IS DECIDED HERE, AND ONLY HERE (shift-tab-and-mouse-wheel-dead-on-some-
+    // terminals, F1'). On a Windows console whose Node never sets
+    // `ENABLE_VIRTUAL_TERMINAL_INPUT`, libuv drops every non-KEY_EVENT record
+    // before it reaches this process, so `\x1b[?1000h` is a pure no-op and the
+    // filter has nothing to filter. Gating `wantMouse` — rather than the three
+    // things downstream of it — is what keeps the three in agreement: the
+    // `?1000h` write (`enterAltScreen(..., { mouse: filter !== null })`), the
+    // filter itself, and the `mouseSource` prop that decides whether the user is
+    // advised about a mode that is not running. Wiring any of them separately
+    // re-opens the gap where the app claims a capability it does not have.
+    const vtInputSupported = supportsWindowsVtInput(process.platform, process.versions.node);
+    const wantMouse = mode === 'fullscreen' &&
+        config.mouse &&
+        !!process.stdout.isTTY &&
+        !!process.stdin.isTTY &&
+        vtInputSupported;
     const mouseFilter = wantMouse
         ? tryCreateMouseFilter(process.stdin, (reason) => logger.warn('cli', 'mouse_filter_failed', { reason }))
         : null;
@@ -400,7 +450,13 @@ function runInteractive(flags, extras = {}) {
         !!process.stdin.isTTY &&
         !process.env.CI &&
         config.update.mode !== 'off';
-    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, mouseSource: mouseFilter?.source, updateBridge: updateEligible ? updateBridge : undefined }), 
+    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, mouseSource: mouseFilter?.source, 
+        // Present ONLY when this console swallows `CSI Z` and mouse reports.
+        // Passed in rather than probed inside `App` so that every test renders
+        // the same tree on every machine — reading `process.versions.node` from
+        // a component would make the notice appear or vanish according to which
+        // Node the developer happened to have installed.
+        vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined }), 
     // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
     // straight to stdout and permanently shifts the fixed frame's accounting.
     {
@@ -1266,6 +1322,19 @@ function buildProgram() {
         const provider = opts.provider ?? program.opts().provider;
         await runModels(toFlags(program.opts()), provider);
     });
+    // --- The machine-facing face (cli-integration-surface §3.1). --------------
+    //
+    // FOUR CALL SITES, ~10 LINES. Each module owns its own `.command()` and
+    // `.option()` declarations, because this file is already 60% over the
+    // repository's 1000-line guideline and twenty more declarations would make
+    // that worse for the audience `aragon --help` exists for.
+    registerExecCommand(program, toFlags, {
+        version: VERSION,
+        makeController: makeExecController,
+    });
+    registerSessionsCommand(program);
+    registerInfoCommand(program, toFlags, VERSION);
+    registerDoctorCommand(program, toFlags);
     return program;
 }
 async function main() {

package/dist/commands/builtins.js

@@ -831,8 +831,27 @@ const COMMANDS = [
     },
     {
         name: 'clear',
-        description: 'Clear the visible transcript',
-        run: (ctx) => ctx.dispatch({ type: 'clearTranscript' }),
+        description: 'Clear the visible transcript and the todo panel',
+        run: (ctx) => {
+            // A USER OVERRIDE OF A PROJECTION, the same class as `/todo clear`, so it
+            // reuses reason `'user'`; I-2 and its standing exception are stated on
+            // `TodoStore`. Clearing the STORE and not merely the view mirror is what
+            // keeps `/save`, `/todo status|continue` and follow-through agreeing with
+            // the screen — they read the store directly. `messages` is untouched:
+            // clearing the conversation is still `/reset` alone.
+            //
+            // DELIBERATELY WITHOUT `/todo clear`'s two guards: an `isRunning()` refusal
+            // would leave `/clear` unable to clear even the transcript mid-run, and an
+            // early return on an empty list would skip the dispatch below entirely.
+            // Clearing an empty store is already silent — it emits into a reducer
+            // branch that writes two fields that are both already at their defaults.
+            //
+            // Bounded side effect: the emptied store re-arms `todo_write`'s "a fresh
+            // plan has at least two items" gate, so a model that shrinks a plan to one
+            // item right after a mid-run `/clear` gets the refusal text and retries.
+            ctx.controller.clearTodos();
+            ctx.dispatch({ type: 'clearTranscript' });
+        },
     },
     {
         name: 'reset',

package/dist/config/ui-state.d.ts

@@ -34,6 +34,22 @@ export interface UiState {
     submitCount: number;
     /** Whether the one-shot "hold Shift to select text" notice has been shown. */
     mouseNoticeSeen: boolean;
+    /**
+     * Whether the one-shot "this Windows console cannot deliver Shift+Tab or the
+     * wheel" notice has been shown.
+     *
+     * A SEPARATE KEY FROM `mouseNoticeSeen`, AND THAT IS THE WHOLE POINT. The
+     * people this notice exists for are precisely the ones who have already
+     * started aragon, already been shown the mouse notice that does not apply to
+     * them, and therefore already have `mouseNoticeSeen: true` on disk. Folding
+     * the two would make the fix inert for its entire audience, in silence.
+     *
+     * NOT ADDED TO `UI_STATE_SCHEMA`: bumping the schema makes `readFromDisk`
+     * discard the whole object, which would reset everyone's submit counter and
+     * re-show the mouse notice. A new field simply reads as its default on an
+     * older file, which is the behaviour wanted here anyway.
+     */
+    vtInputNoticeSeen: boolean;
 }
 /** Read the state, caching it for the life of the process. Never throws. */
 export declare function loadUiState(): UiState;
@@ -42,6 +58,8 @@ export declare function readSubmitCount(): number;
 export declare function bumpSubmitCount(): number;
 export declare function getMouseNoticeSeen(): boolean;
 export declare function setMouseNoticeSeen(seen: boolean): void;
+export declare function getVtInputNoticeSeen(): boolean;
+export declare function setVtInputNoticeSeen(seen: boolean): void;
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/config/ui-state.js

@@ -35,6 +35,7 @@ const DEFAULT_UI_STATE = {
     schema: UI_STATE_SCHEMA,
     submitCount: 0,
     mouseNoticeSeen: false,
+    vtInputNoticeSeen: false,
 };
 let memory = null;
 function coerceCount(value) {
@@ -64,6 +65,9 @@ function readFromDisk() {
             mouseNoticeSeen: typeof parsed.mouseNoticeSeen === 'boolean'
                 ? parsed.mouseNoticeSeen
                 : DEFAULT_UI_STATE.mouseNoticeSeen,
+            vtInputNoticeSeen: typeof parsed.vtInputNoticeSeen === 'boolean'
+                ? parsed.vtInputNoticeSeen
+                : DEFAULT_UI_STATE.vtInputNoticeSeen,
         };
     }
     catch {
@@ -123,6 +127,12 @@ export function getMouseNoticeSeen() {
 export function setMouseNoticeSeen(seen) {
     update({ mouseNoticeSeen: seen });
 }
+export function getVtInputNoticeSeen() {
+    return loadUiState().vtInputNoticeSeen;
+}
+export function setVtInputNoticeSeen(seen) {
+    update({ vtInputNoticeSeen: seen });
+}
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

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

@@ -0,0 +1,10 @@
+/**
+ * `aragon info` / `aragon doctor` commander wiring
+ * (cli-integration-surface section 4.3).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ */
+import type { Command } from 'commander';
+import type { CliFlags } from '../config/load.js';
+export declare function registerInfoCommand(program: Command, toFlags: (opts: Record<string, unknown>) => CliFlags, version: string): void;
+export declare function registerDoctorCommand(program: Command, toFlags: (opts: Record<string, unknown>) => CliFlags): void;

package/dist/diagnostics/cli-commands.js

@@ -0,0 +1,61 @@
+/**
+ * `aragon info` / `aragon doctor` commander wiring
+ * (cli-integration-surface section 4.3).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ */
+import process from 'node:process';
+import { buildInfo } from './info.js';
+import { runDoctorChecks } from './doctor.js';
+export function registerInfoCommand(program, toFlags, version) {
+    program
+        .command('info')
+        .description('Print what this installation supports (for wrappers and CI)')
+        .option('--json', 'Machine-readable output')
+        .action((opts) => {
+        const info = buildInfo(toFlags(program.opts()), version);
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(info, null, 2)}\n`);
+            return;
+        }
+        process.stdout.write([
+            `aragon    ${info.cli} (core ${info.core}, node ${info.node})`,
+            `schema    ${info.schemaVersion}`,
+            `home      ${info.home}`,
+            `config    ${info.configPath}`,
+            `sessions  ${info.sessionsDir}`,
+            `model     ${info.provider}/${info.model}${info.hasApiKey ? '' : '  (no API key)'}`,
+            `formats   out: ${info.outputFormats.join(', ')} | in: ${info.inputFormats.join(', ')}`,
+            `modes     ${info.permissionModes.join(', ')}`,
+            `features  ${info.features.join(', ')}`,
+            '',
+        ].join('\n'));
+    });
+}
+export function registerDoctorCommand(program, toFlags) {
+    program
+        .command('doctor')
+        .description('Check that this machine is configured to run aragon (exit 0 = all clear)')
+        .option('--json', 'Machine-readable output')
+        .option('--probe', 'Also make one minimal API call against the configured provider')
+        .action(async (opts) => {
+        const report = await runDoctorChecks(toFlags(program.opts()), {
+            ...(opts.probe ? { probe: true } : {}),
+        });
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        }
+        else {
+            for (const check of report.checks)
+                process.stdout.write(`${renderCheck(check)}\n`);
+        }
+        // ONLY `fail` MOVES THE EXIT CODE. A `warn` is information; failing on one
+        // would make `aragon doctor` unusable in exactly the CI job it is for.
+        process.exitCode = report.ok ? 0 : 1;
+    });
+}
+function renderCheck(check) {
+    const label = check.verdict.toUpperCase().padEnd(4);
+    const head = `[${label}] ${check.name.padEnd(9)} ${check.detail}`;
+    return check.remedy ? `${head}\n         ${check.remedy}` : head;
+}

package/dist/diagnostics/doctor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `aragon doctor` - "is this machine configured to run me?", in one exit code
+ * (cli-integration-surface section 4.3).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ *
+ * EVERY CHECK CARRIES A ONE-LINE REMEDY, and only `fail` affects the exit code.
+ * A `warn` that failed the command would make the command useless on the many
+ * machines where something is unusual but working; a `fail` with no remedy makes
+ * the caller guess, which is the state this command exists to end.
+ */
+import { type CliFlags } from '../config/load.js';
+export type CheckVerdict = 'pass' | 'warn' | 'fail';
+export interface DoctorCheck {
+    name: string;
+    verdict: CheckVerdict;
+    detail: string;
+    /** What to do about it. Empty only for a `pass`. */
+    remedy: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+export interface DoctorOptions {
+    /** One minimal API call against the configured provider. */
+    probe?: boolean;
+}
+export declare function runDoctorChecks(flags: CliFlags, opts?: DoctorOptions): Promise<DoctorReport>;

package/dist/diagnostics/doctor.js

@@ -0,0 +1,167 @@
+/**
+ * `aragon doctor` - "is this machine configured to run me?", in one exit code
+ * (cli-integration-surface section 4.3).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ *
+ * EVERY CHECK CARRIES A ONE-LINE REMEDY, and only `fail` affects the exit code.
+ * A `warn` that failed the command would make the command useless on the many
+ * machines where something is unusual but working; a `fail` with no remedy makes
+ * the caller guess, which is the state this command exists to end.
+ */
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import { initProviders, ModelRegistry } from '@aragon-agent/core';
+import { getHomeResolutionWarning, getSessionsDir, getUserDataDir } from '../config/app-paths.js';
+import { readConfigFile } from '../config/store.js';
+import { loadConfig, makeGetApiKey } from '../config/load.js';
+import { isAdapterProvider, toRetryPolicy } from '../config/schema.js';
+const MIN_NODE_MAJOR = 18;
+export async function runDoctorChecks(flags, opts = {}) {
+    const checks = [checkNode(), checkHome(), checkConfigFile()];
+    const config = loadConfig(flags);
+    checks.push(checkProviderKey(config));
+    checks.push(checkModel(config));
+    checks.push(checkSessionsDir());
+    if (opts.probe)
+        checks.push(await probeProvider(config));
+    return { ok: checks.every((c) => c.verdict !== 'fail'), checks };
+}
+function pass(name, detail) {
+    return { name, verdict: 'pass', detail, remedy: '' };
+}
+function checkNode() {
+    const major = Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+    if (major >= MIN_NODE_MAJOR)
+        return pass('node', `v${process.versions.node}`);
+    return {
+        name: 'node',
+        verdict: 'fail',
+        detail: `v${process.versions.node} is below the supported floor`,
+        remedy: `Install Node ${MIN_NODE_MAJOR} or newer.`,
+    };
+}
+function checkHome() {
+    const home = getUserDataDir();
+    const warning = getHomeResolutionWarning();
+    try {
+        if (!existsSync(home))
+            mkdirSync(home, { recursive: true });
+        const probe = join(home, '.doctor-write-probe');
+        writeFileSync(probe, 'ok', 'utf-8');
+        unlinkSync(probe);
+    }
+    catch (err) {
+        return {
+            name: 'home',
+            verdict: 'fail',
+            detail: `${home} is not writable (${err.message})`,
+            remedy: 'Fix the permissions, or point ARAGON_HOME at a directory you own.',
+        };
+    }
+    if (warning) {
+        return {
+            name: 'home',
+            verdict: 'warn',
+            detail: `${home} (${warning})`,
+            remedy: 'Set ARAGON_HOME to an absolute path if this is not where you want state kept.',
+        };
+    }
+    return pass('home', home);
+}
+function checkConfigFile() {
+    const { parseError } = readConfigFile();
+    if (!parseError)
+        return pass('config', 'parses');
+    return {
+        name: 'config',
+        verdict: 'warn',
+        detail: `using defaults, could not parse ${parseError}`,
+        remedy: 'Run `aragon config edit` and fix the JSON, or delete the file to start over.',
+    };
+}
+function checkProviderKey(config) {
+    const key = makeGetApiKey(config)(config.provider);
+    if (key)
+        return pass('api-key', `resolved for ${config.provider}`);
+    return {
+        name: 'api-key',
+        verdict: 'fail',
+        detail: `no API key for provider "${config.provider}"`,
+        remedy: `Run \`aragon config\` and add one, or set the provider's key in the environment.`,
+    };
+}
+function checkModel(config) {
+    if (!isAdapterProvider(config.provider)) {
+        return {
+            name: 'model',
+            verdict: 'fail',
+            detail: `unknown provider "${config.provider}"`,
+            remedy: 'Run `aragon models` to see the providers this build supports.',
+        };
+    }
+    const registry = new ModelRegistry(initProviders({ retryPolicy: toRetryPolicy(config.retry) }));
+    const known = registry.getModels(config.provider).some((m) => m.id === config.model);
+    if (known)
+        return pass('model', `${config.provider}/${config.model}`);
+    // WARN, NOT FAIL. The registry is a builtin list plus whatever an account can
+    // discover, so a model it does not know is frequently one this account has and
+    // the shipped table does not - the cost table is unknown, the run is fine.
+    return {
+        name: 'model',
+        verdict: 'warn',
+        detail: `${config.provider}/${config.model} is not in the builtin registry`,
+        remedy: 'Run `aragon models` to list what this key can reach; cost reporting will be off.',
+    };
+}
+function checkSessionsDir() {
+    const dir = getSessionsDir();
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const probe = join(dir, '.doctor-write-probe');
+        writeFileSync(probe, 'ok', 'utf-8');
+        unlinkSync(probe);
+    }
+    catch (err) {
+        return {
+            name: 'sessions',
+            verdict: 'fail',
+            detail: `${dir} is not writable (${err.message})`,
+            remedy: 'Fix the permissions, or run `aragon exec --no-save-session`.',
+        };
+    }
+    return pass('sessions', dir);
+}
+/**
+ * `--probe`: one minimal API call.
+ *
+ * MODEL DISCOVERY IS THE CHEAPEST HONEST PROBE. It exercises the base URL, the
+ * key and the TLS chain - which is the whole of what "can this machine reach the
+ * provider" means - without spending a single completion token.
+ */
+async function probeProvider(config) {
+    const key = makeGetApiKey(config)(config.provider);
+    if (!key || !isAdapterProvider(config.provider)) {
+        return {
+            name: 'probe',
+            verdict: 'warn',
+            detail: 'skipped: no key or unknown provider',
+            remedy: 'Fix the api-key check above, then run `aragon doctor --probe` again.',
+        };
+    }
+    const registry = new ModelRegistry(initProviders({ retryPolicy: toRetryPolicy(config.retry) }));
+    try {
+        const models = await registry.discoverModels(config.provider, key, config.baseUrl);
+        return pass('probe', `${config.provider} answered with ${models.length} model(s)`);
+    }
+    catch (err) {
+        return {
+            name: 'probe',
+            verdict: 'fail',
+            detail: `${config.provider} did not answer (${err.message})`,
+            remedy: 'Check the key, the base URL and any proxy between this machine and the provider.',
+        };
+    }
+}

package/dist/diagnostics/info.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `aragon info` - capability discovery (cli-integration-surface section 5.4).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ *
+ * "INSTALL AND CALL" ACROSS VERSIONS IS ONLY ROBUST IF THE CALLER CAN ASK WHAT
+ * IT JUST INSTALLED (G6). Everything a wrapper might branch on is here, and
+ * `features` is a FLAT STRING LIST on purpose: a wrapper testing
+ * `info.features.includes('sessions')` keeps working across versions that add
+ * capabilities, which a nested shape with renamed keys would not.
+ */
+import { type CliFlags } from '../config/load.js';
+export interface ExecInfo {
+    cli: string;
+    core: string;
+    node: string;
+    schemaVersion: number;
+    home: string;
+    configPath: string;
+    sessionsDir: string;
+    provider: string;
+    model: string;
+    hasApiKey: boolean;
+    tools: string[];
+    outputFormats: string[];
+    inputFormats: string[];
+    permissionModes: string[];
+    features: string[];
+}
+export declare function buildInfo(flags: CliFlags, version: string): ExecInfo;