@aragon-agent/cli 0.5.8 → 0.5.10

package/dist/commands/builtins.d.ts

@@ -1,7 +1,7 @@
 /**
  * Built-in slash commands (spec §5.2):
  * /help /model /settings /thinking /max-tokens /tools /clear /reset /cwd /save
- * /resume /copy /exit (/quit).
+ * /resume /copy /exit (/quit), plus the /team, /fast and /todo subsystems.
  */
 import { CommandRegistry } from './registry.js';
 export declare function registerBuiltinCommands(registry: CommandRegistry): void;

package/dist/commands/builtins.js

@@ -1,14 +1,15 @@
 /**
  * Built-in slash commands (spec §5.2):
  * /help /model /settings /thinking /max-tokens /tools /clear /reset /cwd /save
- * /resume /copy /exit (/quit).
+ * /resume /copy /exit (/quit), plus the /team, /fast and /todo subsystems.
  */
 import { spawn } from 'node:child_process';
 import { existsSync, statSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import process from 'node:process';
 import { resolveOutputTokens } from '@aragon-agent/core';
-import { clampThinkingLevel, clampTheme, isThemeName, parseMaxTokensInput, DEFAULT_MAX_TOKENS, LEGACY_DARK_THEME, THEME_NAMES, THINKING_LEVELS, } from '../config/schema.js';
+import { clampThinkingLevel, clampTheme, isAdapterProvider, isThemeName, parseMaxTokensInput, ADAPTER_PROVIDERS, DEFAULT_MAX_TOKENS, HARD_MAX_RETRIES, LEGACY_DARK_THEME, THEME_NAMES, THINKING_LEVELS, } from '../config/schema.js';
+import { computeCost, formatCost, formatTokens } from '../agent/usage.js';
 import { TODO_FOLLOW_LIMITS } from '../todo/limits.js';
 import { buildContinuationMessage } from '../todo/follow-through.js';
 import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
@@ -16,6 +17,115 @@ import { loadConfig } from '../config/load.js';
 import { loadSession, resolveSessionPath, saveSession } from '../session/persist.js';
 import { getLogger } from '../logging/logger.js';
 import { perfCommand } from './perf.js';
+/**
+ * `/fast status` — THE GUARANTEED REPORTING SURFACE for the tier (§4.4 / R-8).
+ *
+ * The chip degrades on a narrow terminal and the card only appears when a review
+ * happens; this is the one place that always answers "is it on, what is it, and
+ * has it done anything". The session totals are here rather than on the status
+ * bar because the aggregate there cannot answer "is the cheap tier actually
+ * saving me anything?".
+ *
+ * `unknown (no price table for <model>)` RATHER THAN A CURRENCY AMOUNT when the
+ * static table has never seen the model (C-11 / RV-4 / AC-34): `$0.00` on a
+ * feature that is spending money is the same class of lie as pricing a Haiku
+ * child at Sonnet rates.
+ */
+/**
+ * `/update status` - the human-readable readout (cli-auto-update §4.4).
+ *
+ * ASCII ONLY and NO GLYPHS: this string goes into a transcript `notice`, which
+ * `Transcript.tsx` renders with its own marker; the glyph tier belongs to the
+ * bottom-row line, not here. Everything a user could want to act on is named:
+ * what is running, what is available, how it got installed, and when we look
+ * again.
+ */
+function formatUpdateStatus(port, override) {
+    const snapshot = override ?? port.snapshot();
+    const lines = [
+        `Auto-update: ${snapshot.phase}`,
+        `  running   ${snapshot.currentVersion}`,
+        `  latest    ${snapshot.latestVersion ?? 'unknown'}`,
+        `  source    ${snapshot.source}`,
+    ];
+    if (snapshot.reason)
+        lines.push(`  reason    ${snapshot.reason}`);
+    if (snapshot.advice)
+        lines.push(`  install   ${snapshot.advice}`);
+    // The three hardening lines, each only when it has something to say
+    // (cli-auto-update-hardening section 6.3).
+    //
+    // THE KEY COLUMN IS TEN WIDE, WHICH IS WHY THE FIRST KEY IS `rollback` AND NOT
+    // `rolledback`. Section 6.3 asks for "a padded key, matching the six lines
+    // `formatUpdateStatus` already emits", and every one of those pads the key to
+    // ten so the values start in the same column - the entire reason a readout is
+    // padded at all. `rolledback` is ten characters on its own, so it cannot take
+    // a separating space without pushing its value one column past the other six,
+    // which is the misalignment the padding exists to prevent. The spec's sample
+    // block is internally consistent (all three new lines at eleven) and
+    // inconsistent with the six it says it matches; the prose is the requirement.
+    //
+    // THE ROLLBACK LINE CARRIES NO FAILURE COUNT on purpose: `bootFailures` is
+    // zeroed by the rollback itself, so any number printed here would be `0`. The
+    // count that mattered is in the `update_rolled_back` log record.
+    if (snapshot.rolledBackFrom) {
+        const to = snapshot.rolledBackTo ?? snapshot.currentVersion;
+        lines.push(`  rollback  ${snapshot.rolledBackFrom} -> ${to}`);
+    }
+    // What `aragon update --rollback` would reinstall. This is the only place a
+    // user can find that out BEFORE running the command.
+    if (snapshot.lastGoodVersion)
+        lines.push(`  lastgood  ${snapshot.lastGoodVersion}`);
+    // The only place a user can learn their machine updates through the fallback.
+    if (snapshot.probe) {
+        lines.push(`  probe     ${snapshot.probe === 'npm' ? 'npm (proxy fallback)' : 'http'}`);
+    }
+    if (snapshot.consecutiveFailures > 0) {
+        lines.push(`  failures  ${snapshot.consecutiveFailures} in a row`);
+    }
+    const next = override ? port.nextCheckAt() : snapshot.nextCheckAt;
+    lines.push(`  next      ${next ? new Date(next).toLocaleTimeString() : 'not scheduled'}`);
+    return lines.join('\n');
+}
+function formatFastStatus(controller) {
+    const status = controller.getFastStatus();
+    const cfg = controller.getFastConfig();
+    const state = !status.registered
+        ? 'off for this session (not configured at launch)'
+        : status.enabled
+            ? 'on'
+            : 'off';
+    const lines = [];
+    if (status.tier.ok) {
+        const same = status.tier.sameAsMain ? '  (same as main)' : '';
+        lines.push(`Fast tier: ${state}. Model: ${status.tier.ref.providerId}:${status.tier.ref.modelId}${same}.`);
+    }
+    else {
+        lines.push(`Fast tier: ${state}. Model: ${cfg.model || '(not set)'}.`);
+    }
+    lines.push(`Review: ${cfg.review ? `every ${cfg.reviewEveryTurns} turns` : 'off'}. ` +
+        `Delegation: ${cfg.delegate ? 'on' : 'off'}.`);
+    const snapshot = status.snapshot;
+    const cost = snapshot.pricingUnknown
+        ? `unknown (no price table for ${snapshot.model})`
+        : formatCost(computeCost(snapshot.usage, status.tier.ok ? controller.getModelInfoFor(status.tier.ref).cost : undefined));
+    // `n/N`, NEVER A BARE `n` (fast-model-tier-hardening §4.3). A bare count
+    // answers "what have I spent" only for a reader who already knows the
+    // ceiling, which is precisely what the user does not know; `12/40` answers
+    // that and "how much is left" in the same three characters, and makes the
+    // budget discoverable to someone who never read the config schema. The
+    // exhausted form names the remedy inline, because a status line that reports
+    // a stop without its escape hatch just relocates the question.
+    //
+    // `budgetReached` is READ, not re-derived (RV-H10): with the tier off both
+    // numbers are `0` placeholders and `reviews >= reviewBudget` would be true.
+    const budget = snapshot.budgetReached ? ' (budget reached - raise with /fast budget <n>)' : '';
+    lines.push(`This session: ${snapshot.reviews}/${snapshot.reviewBudget} reviews${budget}, ` +
+        `${snapshot.delegated} delegated subagents, ` +
+        `in ${formatTokens(snapshot.usage.inputTokens)} / out ` +
+        `${formatTokens(snapshot.usage.outputTokens)}, cost ${cost}.`);
+    return lines.join('\n');
+}
 const COMMANDS = [
     {
         name: 'help',
@@ -223,6 +333,249 @@ const COMMANDS = [
             ctx.notify('warn', `Unknown argument "${verb}" - use /team [status|on|off|max <n>].`);
         },
     },
+    {
+        name: 'fast',
+        description: 'Fast model tier: status | on | off | model <id> | provider <id> | same | ' +
+            'review <n|off> | budget <n> | delegate on|off',
+        /**
+         * `/fast on` CANNOT turn the tier on in a session that started without it,
+         * for the reason `/team on` above records at length: the tool array is built
+         * ONCE and rebuilding it is forbidden (C-2), so a session that grew a schema
+         * field mid-flight would be a session whose request payloads change shape
+         * between turns.
+         *
+         * EVERY MUTATING BRANCH DOES THE TWO CALLS PLUS PERSIST that `/todo`
+         * documents: `controller.setFastConfig(patch)` updates the object `App`
+         * reads at render time AND re-resolves the tier AND rebuilds the prompt;
+         * `ctx.persistConfig({ fast: patch })` survives the session. Persist alone
+         * reports success and changes nothing until relaunch; the setter alone
+         * forgets by morning.
+         */
+        run: (ctx) => {
+            const arg = ctx.args.trim();
+            const [rawVerb, value] = arg.split(/\s+/, 2);
+            const verb = (rawVerb ?? '').toLowerCase();
+            const controller = ctx.controller;
+            // Refused mid-dispatch for the reason `/team` records: half a dispatch
+            // under one tier and half under another produces a report nothing can
+            // afterwards explain. THAT ARGUMENT IS ABOUT WRITES, so the two READS are
+            // grouped and answerable (RV-H3): `/fast status` always was, and a bare
+            // `/fast budget` reports the same numbers by another name. `/fast budget
+            // 80` is a write and is still refused.
+            const isRead = verb === 'status' || (verb === 'budget' && !value);
+            if (verb && !isRead && controller.isTeamBusy()) {
+                ctx.notify('warn', 'Cannot change fast-tier settings mid-dispatch.');
+                return;
+            }
+            const persist = (patch) => {
+                controller.setFastConfig(patch);
+                ctx.persistConfig({ fast: patch });
+            };
+            if (!verb || verb === 'status') {
+                ctx.notify('info', formatFastStatus(controller));
+                return;
+            }
+            if (verb === 'on' || verb === 'off') {
+                const enabled = verb === 'on';
+                persist({ enabled });
+                if (!controller.isFastRegistered()) {
+                    // The honest branch, and the whole point of splitting by what was
+                    // decided at construction (§3.3). It is one sentence, and it keeps
+                    // AC-2 / AC-3 intact: a session launched without the tier never grows
+                    // a schema field, whatever the user types afterwards.
+                    ctx.notify('info', enabled
+                        ? 'The fast tier is off for this session (not configured at launch). ' +
+                            'Saved for next launch.'
+                        : 'The fast tier is already off for this session. Saved for next launch.');
+                    return;
+                }
+                controller.setFastEnabled(enabled);
+                ctx.toast('success', `Fast tier ${enabled ? 'on' : 'off'}.`);
+                return;
+            }
+            if (verb === 'model') {
+                const raw = (value ?? '').trim();
+                if (!raw) {
+                    ctx.notify('warn', 'Usage: /fast model <id>  (or provider:model)');
+                    return;
+                }
+                // `provider:model` is accepted because that is how a user thinks about a
+                // tier on another vendor, and an unknown provider is rejected with THE
+                // MESSAGE `cli.tsx` ALREADY PRINTS rather than a second wording for the
+                // same fact (RV-16).
+                const colon = raw.indexOf(':');
+                if (colon > 0) {
+                    const provider = raw.slice(0, colon);
+                    const model = raw.slice(colon + 1);
+                    if (!isAdapterProvider(provider)) {
+                        ctx.notify('warn', `Unknown provider "${provider}". Choose: ${ADAPTER_PROVIDERS.join(', ')}.`);
+                        return;
+                    }
+                    persist({ provider, model });
+                    ctx.toast('success', `Fast model set to ${provider}:${model}.`);
+                    return;
+                }
+                persist({ model: raw });
+                ctx.toast('success', `Fast model set to ${raw}.`);
+                return;
+            }
+            if (verb === 'provider') {
+                const raw = (value ?? '').trim();
+                if (!raw) {
+                    ctx.notify('warn', 'Usage: /fast provider <id>');
+                    return;
+                }
+                if (!isAdapterProvider(raw)) {
+                    ctx.notify('warn', `Unknown provider "${raw}". Choose: ${ADAPTER_PROVIDERS.join(', ')}.`);
+                    return;
+                }
+                persist({ provider: raw });
+                ctx.toast('success', `Fast provider set to ${raw}.`);
+                return;
+            }
+            if (verb === 'same') {
+                // R-e IN ONE WORD. `sameAsMain` is display-only and no branch reads it
+                // (R-13): the user is allowed to run both tiers on one model, and the
+                // review still costs what it costs.
+                const cfg = controller.getConfig();
+                persist({
+                    provider: cfg.provider,
+                    model: cfg.model,
+                    baseUrl: cfg.baseUrl ?? '',
+                });
+                ctx.toast('success', `Fast tier set to ${cfg.provider}:${cfg.model} (same as main).`);
+                return;
+            }
+            if (verb === 'review') {
+                const raw = (value ?? '').trim().toLowerCase();
+                if (raw === 'off') {
+                    persist({ review: false });
+                    ctx.toast('success', 'Fast review off.');
+                    return;
+                }
+                const n = Number.parseInt(raw, 10);
+                if (!Number.isFinite(n) || n <= 0) {
+                    ctx.notify('warn', 'Usage: /fast review <n> | off');
+                    return;
+                }
+                // Clamped by `setFastConfig` and again on the persist path, so a value
+                // outside the range can reach neither the runtime nor the file.
+                const applied = controller.setFastConfig({ review: true, reviewEveryTurns: n });
+                ctx.persistConfig({
+                    fast: { review: true, reviewEveryTurns: applied.reviewEveryTurns },
+                });
+                ctx.toast('success', `Fast review every ${applied.reviewEveryTurns} turns.`);
+                return;
+            }
+            if (verb === 'budget') {
+                const snapshot = controller.getFastStatus().snapshot;
+                const raw = (value ?? '').trim();
+                if (!raw) {
+                    // The READ. Answerable mid-dispatch (see the guard above), and it
+                    // reports the same pair `/fast status` renders as `n/N`.
+                    ctx.notify('info', `Fast review budget: ${snapshot.reviews} of ${snapshot.reviewBudget} used ` +
+                        'this session. Use /fast budget <1-500> to raise it.');
+                    return;
+                }
+                const n = Number.parseInt(raw, 10);
+                if (!Number.isFinite(n) || n <= 0) {
+                    // Change NOTHING on a typo, the discipline `/max-tokens` sets: a
+                    // silent resolve to the default discards the number the user meant.
+                    ctx.notify('warn', 'Usage: /fast budget <1-500>');
+                    return;
+                }
+                // BOTH CALLS, IN THIS ORDER (RV-H4 / AC-H17). `setFastConfig` is what
+                // makes a raised budget take effect LIVE - the reviewer's `budgetLimit()`
+                // reads the controller's in-memory config, never disk - and it also
+                // re-emits `tier_changed`, which is how the new denominator reaches the
+                // status chip without a restart. See the comment on this command: a
+                // persist alone reports success and changes nothing until relaunch.
+                const applied = controller.setFastConfig({ reviewMaxPerSession: n });
+                ctx.persistConfig({
+                    fast: { reviewMaxPerSession: applied.reviewMaxPerSession },
+                });
+                // The APPLIED value, not the requested one, so a clamp is visible.
+                ctx.toast('success', `Fast review budget: ${applied.reviewMaxPerSession} per session. ` +
+                    `${snapshot.reviews} used.`);
+                return;
+            }
+            if (verb === 'delegate') {
+                const raw = (value ?? '').trim().toLowerCase();
+                if (raw !== 'on' && raw !== 'off') {
+                    ctx.notify('warn', 'Usage: /fast delegate <on|off>');
+                    return;
+                }
+                persist({ delegate: raw === 'on' });
+                ctx.toast('success', `Fast delegation ${raw}.`);
+                return;
+            }
+            ctx.notify('warn', `Unknown argument "${verb}" - use /fast ` +
+                '[status|on|off|model <id>|provider <id>|same|review <n|off>|budget <n>|' +
+                'delegate on|off].');
+        },
+    },
+    {
+        name: 'update',
+        description: 'Auto-update: status | now | skip | off',
+        /**
+         * THE GUARANTEED REPORTING SURFACE for the updater (C-12 / D-18).
+         *
+         * The bottom row can be preempted by a toast or by the activity line, and it
+         * is deliberately last in that precedence (D-2), so a user who is actually
+         * working may never see it. This command always answers "is it on, what did
+         * it find, and when does it look again".
+         *
+         * REACHES THE SERVICE THROUGH `ctx.update`, NOT THROUGH `ctx.controller`
+         * (C-14 / P0-2). `/fast`, `/team` and `/todo` ride on the controller because
+         * their subsystems live there; `update/` may not import `agent/` at all, so
+         * it carries its own optional port. `undefined` is a legitimate state - `off`,
+         * a non-TTY, or CI - and says so rather than pretending to have failed.
+         */
+        run: (ctx) => {
+            const arg = ctx.args.trim();
+            const [rawVerb] = arg.split(/\s+/, 1);
+            const verb = (rawVerb ?? '').toLowerCase();
+            const port = ctx.update;
+            // `/update off` is the one branch that works WITHOUT a service: turning
+            // something off must not require it to be running, or a user who launched
+            // with `--no-update` can never make that stick.
+            if (verb === 'off') {
+                ctx.persistConfig({ update: { mode: 'off' } });
+                ctx.toast('success', 'Auto-update off. Takes effect on the next launch.');
+                return;
+            }
+            if (!port) {
+                ctx.notify('info', 'Updates are disabled for this session (update.mode: off, a non-TTY, or CI). ' +
+                    'Enable with: aragon config set update.mode auto');
+                return;
+            }
+            if (!verb || verb === 'status') {
+                ctx.notify('info', formatUpdateStatus(port));
+                return;
+            }
+            if (verb === 'now') {
+                // `force: true` bypasses the machine-wide throttle - a human typing this
+                // is the one caller entitled to ignore `lastCheckAt`.
+                void port
+                    .checkNow({ force: true })
+                    .then((snapshot) => ctx.notify('info', formatUpdateStatus(port, snapshot)))
+                    .catch(() => ctx.notify('warn', 'Update check failed. See the log for details.'));
+                ctx.toast('info', 'Checking for updates...');
+                return;
+            }
+            if (verb === 'skip') {
+                const version = port.snapshot().latestVersion;
+                if (!version) {
+                    ctx.notify('info', 'No update is being offered, so there is nothing to skip.');
+                    return;
+                }
+                port.skip(version);
+                ctx.toast('success', `Skipped ${version}. You will hear about the next release.`);
+                return;
+            }
+            ctx.notify('warn', `Unknown argument "${verb}" - use /update [status|now|skip|off].`);
+        },
+    },
     {
         name: 'todo',
         description: 'Todo planning: status | on | off | panel on|off | follow <mode> | clear | continue',
@@ -377,6 +730,77 @@ const COMMANDS = [
                 '/todo [status|on|off|panel on|off|follow <mode>|clear|continue].');
         },
     },
+    {
+        name: 'retry',
+        description: 'API retry: show | on | off | max <n>',
+        /**
+         * TWO CALLS FOR EVERY MUTATION, IN THIS ORDER, and neither is optional
+         * (llm-api-retry-backoff §6.9 / §6.3):
+         *
+         *   `setRetryConfig`  replaces the policy on the live `ProviderRegistry`, so
+         *                     the change takes effect in THIS session — and, because
+         *                     `TeamRuntime` holds the same registry instance, for every
+         *                     child too. Without it `/retry off` reports success and
+         *                     changes nothing until the next launch.
+         *   `persistConfig`   is what survives the session.
+         *
+         * UNLIKE `/team on` AND `/todo on` there is no "off for this session" branch:
+         * retry is not a tool, nothing is registered at construction, and there is
+         * therefore no state a flag could have made unreachable. `--no-retry` is a
+         * starting value, not a permanent verdict.
+         */
+        run: (ctx) => {
+            const arg = ctx.args.trim().toLowerCase();
+            const [verb, value] = arg.split(/\s+/, 2);
+            const controller = ctx.controller;
+            if (!verb || verb === 'show' || verb === 'status') {
+                const cfg = controller.getRetryConfig();
+                if (!cfg.enabled || cfg.maxRetries <= 0) {
+                    ctx.notify('info', `API retry: off (maxRetries ${cfg.maxRetries}). Use /retry on or /retry max <n>.`);
+                    return;
+                }
+                ctx.notify('info', `API retry: on. Up to ${cfg.maxRetries} retries, ${cfg.initialDelayMs}ms doubling to ` +
+                    `${cfg.maxDelayMs}ms${cfg.jitter ? ' with jitter' : ''}, ` +
+                    `giving up after ${Math.round(cfg.maxElapsedMs / 1000)}s. ` +
+                    `Retry-After ${cfg.respectRetryAfter ? 'honoured' : 'ignored'}.`);
+                return;
+            }
+            if (verb === 'on' || verb === 'off') {
+                const enabled = verb === 'on';
+                const applied = controller.setRetryConfig({ enabled });
+                // A PARTIAL `retry` section, safe only because `updatePersistedConfig`
+                // deep-merges it — the same contract `/team on` relies on.
+                ctx.persistConfig({ retry: { enabled } });
+                if (enabled && applied.maxRetries <= 0) {
+                    // Honest rather than cheerful: `enabled` is on but the count is the
+                    // kill switch, so nothing will actually retry.
+                    ctx.notify('warn', 'API retry enabled, but maxRetries is 0 - use /retry max <n>.');
+                    return;
+                }
+                ctx.toast('success', `API retry ${enabled ? 'on' : 'off'}.`);
+                return;
+            }
+            if (verb === 'max') {
+                // `Number.isFinite` and `>= 0`, NOT `> 0`: `0` is this key's documented
+                // floor and its kill switch, and rejecting it here would make `/retry max 0`
+                // the one documented control that does not work (R-16).
+                const n = Number.parseInt(value ?? '', 10);
+                if (!Number.isFinite(n) || n < 0) {
+                    ctx.notify('warn', `Usage: /retry max <0-${HARD_MAX_RETRIES}>  (0 turns retry off)`);
+                    return;
+                }
+                const applied = controller.setRetryConfig({ maxRetries: n });
+                ctx.persistConfig({
+                    retry: { maxRetries: applied.maxRetries },
+                });
+                ctx.toast('success', applied.maxRetries === 0
+                    ? 'API retry off (maxRetries 0).'
+                    : `API retry: up to ${applied.maxRetries} retries.`);
+                return;
+            }
+            ctx.notify('warn', `Unknown argument "${verb}" - use /retry [show|on|off|max <n>].`);
+        },
+    },
     {
         name: 'expand',
         description: 'Expand / collapse a recent tool card (default: last)',

package/dist/commands/registry.d.ts

@@ -7,6 +7,7 @@ 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';
 import type { FollowThroughBudget } from '../todo/follow-through.js';
+import type { UpdateCommandPort } from '../update/types.js';
 export interface CommandContext {
     /** Raw argument string after the command word (may be empty). */
     args: string;
@@ -52,6 +53,22 @@ export interface CommandContext {
      * change; absent means the clause degrades to naming the ceiling alone.
      */
     followBudget?: FollowThroughBudget;
+    /**
+     * The updater, when this session has one (cli-auto-update §4.4 / C-14 / P0-2).
+     *
+     * `/fast`, `/team` and `/todo` reach their subsystems through `controller`,
+     * because those subsystems live on `AgentController`. This one does not, and
+     * by §3.1 it MUST NOT — `update/` may not import `agent/` — so it needs its
+     * own field, and this is the only seam a slash command has.
+     *
+     * OPTIONAL, for two independent reasons. The service is legitimately absent
+     * under `update.mode: 'off'`, on a non-TTY and in CI (§3.8), so `/update` has
+     * to have something honest to say when it is missing; and a REQUIRED field
+     * would break every existing `CommandContext` fixture in this package at
+     * compile time, for a feature none of them are about. `followBudget` above is
+     * the precedent for an optional, read-at-command-time member.
+     */
+    update?: UpdateCommandPort;
     /** Rebuild the system prompt and the dynamic command list after a skill change. */
     refreshSkills: () => void;
     /**

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

@@ -14,6 +14,9 @@
  *   ├── config.json.bak        `aragon config edit` pre-edit backup
  *   ├── prompt-history.jsonl   submitted prompts, append-only (0600 on POSIX)
  *   ├── state.json             UI bookkeeping scalars (0600 on POSIX)
+ *   ├── update-state.json      auto-update coordination (0600 on POSIX)
+ *   ├── update-install.lock    held by the running `npm i -g` child
+ *   ├── update-install.log     that child's stdout+stderr; unlinked on exit
  *   ├── logs/                  JSONL logs (0700 on POSIX)
  *   ├── sessions/              /save · /resume
  *   ├── skills/                `aragon skills install` target
@@ -79,6 +82,34 @@ export declare function getConfigBackupPath(): string;
 export declare function getPromptHistoryPath(): string;
 /** `<home>/state.json` — UI bookkeeping scalars only; see `ui-state.ts`. */
 export declare function getUiStatePath(): string;
+/**
+ * `<home>/update-state.json` — cross-process auto-update coordination
+ * (cli-auto-update §5.2).
+ *
+ * Deliberately NOT inside `state.json`: that file is documented as UI
+ * bookkeeping scalars only (C-6), and this is coordination state that a SECOND
+ * aragon process reads to decide whether anyone has already asked the registry.
+ * Different lifetime, different failure policy, different reader.
+ */
+export declare function getUpdateStatePath(): string;
+/**
+ * `<home>/update-install.lock` — the `wx` lock the running installer child holds
+ * (cli-auto-update §3.7).
+ *
+ * A FILE, and a direct child of the root, for the reason the two files above
+ * are: `logs/`, `sessions/` and `skills/` are all scan roots, and every extra
+ * file inside one is another thing each walk has to recognise and skip.
+ */
+export declare function getUpdateLockPath(): string;
+/**
+ * `<home>/update-install.log` — the installer child's stdout+stderr
+ * (cli-auto-update §3.5 / U-5).
+ *
+ * A REAL FILE and not a pipe: the child is detached and outlives the parent
+ * (D-10), and a pipe whose parent has exited takes EPIPE on the next write. The
+ * parent tails it on the child's exit, redacts, logs, and unlinks.
+ */
+export declare function getUpdateInstallLogPath(): string;
 export declare function getLogsDir(): string;
 export declare function getSessionsDir(): string;
 /** `<home>` — parent of `skills/`, and where sidecar state such as usage lives. */

package/dist/config/app-paths.js

@@ -14,6 +14,9 @@
  *   ├── config.json.bak        `aragon config edit` pre-edit backup
  *   ├── prompt-history.jsonl   submitted prompts, append-only (0600 on POSIX)
  *   ├── state.json             UI bookkeeping scalars (0600 on POSIX)
+ *   ├── update-state.json      auto-update coordination (0600 on POSIX)
+ *   ├── update-install.lock    held by the running `npm i -g` child
+ *   ├── update-install.log     that child's stdout+stderr; unlinked on exit
  *   ├── logs/                  JSONL logs (0700 on POSIX)
  *   ├── sessions/              /save · /resume
  *   ├── skills/                `aragon skills install` target
@@ -140,6 +143,40 @@ export function getPromptHistoryPath() {
 export function getUiStatePath() {
     return join(resolution.root, 'state.json');
 }
+/**
+ * `<home>/update-state.json` — cross-process auto-update coordination
+ * (cli-auto-update §5.2).
+ *
+ * Deliberately NOT inside `state.json`: that file is documented as UI
+ * bookkeeping scalars only (C-6), and this is coordination state that a SECOND
+ * aragon process reads to decide whether anyone has already asked the registry.
+ * Different lifetime, different failure policy, different reader.
+ */
+export function getUpdateStatePath() {
+    return join(resolution.root, 'update-state.json');
+}
+/**
+ * `<home>/update-install.lock` — the `wx` lock the running installer child holds
+ * (cli-auto-update §3.7).
+ *
+ * A FILE, and a direct child of the root, for the reason the two files above
+ * are: `logs/`, `sessions/` and `skills/` are all scan roots, and every extra
+ * file inside one is another thing each walk has to recognise and skip.
+ */
+export function getUpdateLockPath() {
+    return join(resolution.root, 'update-install.lock');
+}
+/**
+ * `<home>/update-install.log` — the installer child's stdout+stderr
+ * (cli-auto-update §3.5 / U-5).
+ *
+ * A REAL FILE and not a pipe: the child is detached and outlives the parent
+ * (D-10), and a pipe whose parent has exited takes EPIPE on the next write. The
+ * parent tails it on the child's exit, redacts, logs, and unlinks.
+ */
+export function getUpdateInstallLogPath() {
+    return join(resolution.root, 'update-install.log');
+}
 export function getLogsDir() {
     return join(resolution.root, 'logs');
 }