@aragon-agent/cli 0.5.3 → 0.5.6

package/dist/config/load.d.ts

@@ -52,6 +52,33 @@ export interface CliFlags {
     team?: boolean;
     /** `--team-max <n>` — override `team.maxSubagents` for this run (still clamped). */
     teamMax?: string | number;
+    /**
+     * `--todo` ⇒ true, `--no-todo` ⇒ false, absent ⇒ undefined
+     * (todo-plan-execution §4.3).
+     */
+    todo?: boolean;
+    /**
+     * `--todo-panel` ⇒ true, `--no-todo-panel` ⇒ false, absent ⇒ undefined.
+     *
+     * DECLARED AS A PAIR, like `--todo` above, and unlike `--no-skills` (P1-8).
+     * `panel` is a PERSISTED setting, so "not passed" has to stay distinguishable
+     * from `true` — otherwise commander's lone-`--no-x` default silently
+     * overwrites a config-file `panel: false` on every run that passes no flag at
+     * all. `--no-skills` escapes the rule only because nothing needs to
+     * distinguish `--skills` from silence.
+     */
+    todoPanel?: boolean;
+    /**
+     * `--todo-follow <mode>` — `notify` | `auto` | `off`
+     * (todo-plan-followthrough §4.2).
+     *
+     * A VALUE FLAG, NOT A PAIR, so commander materializes it only when passed and
+     * the `!== undefined` rule above applies to its presence rather than to a
+     * synthesized `true`. Typed `string` and not `FollowThroughMode`: an
+     * unrecognized value is CLAMPED to the default by `clampTodoConfig`, never
+     * rejected, which is what every other key in this file does.
+     */
+    todoFollow?: string;
     /** `--log-level <lv>` — this run only, never persisted. */
     logLevel?: string;
     /** `--log-file` ⇒ true, `--no-log-file` ⇒ false, absent ⇒ undefined. */

package/dist/config/load.js

@@ -6,7 +6,7 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTeamConfig, clampTheme, clampThinkingLevel, clampTranscriptWindow, coerceMaxTokens, coercePositiveInt, isSkillsToolPolicyMode, } from './schema.js';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile } from './store.js';
 import { getConfigPath } from './app-paths.js';
@@ -97,6 +97,29 @@ function resolveTeamConfig(flags, env, file) {
             : {}),
     });
 }
+/**
+ * Merge the `todo` section across all four layers (defaults › file › env ›
+ * flags), todo-plan-execution §4.3.
+ *
+ * `!== undefined` ON BOTH FLAGS, and that is the whole point (P1-8). `commander`
+ * materializes a lone `--no-x` as `opts.x = true` when the flag is absent, so a
+ * truthiness check cannot tell `--no-todo-panel` from "not passed" — and both
+ * keys here are persisted, so both need the distinction. This is the same rule
+ * `resolveTeamConfig` above states, one feature later.
+ */
+function resolveTodoConfig(flags, env, file) {
+    return clampTodoConfig({
+        ...DEFAULT_CONFIG.todo,
+        ...(file.todo ?? {}),
+        ...(env.todo ?? {}),
+        ...(flags.todo !== undefined ? { enabled: flags.todo } : {}),
+        ...(flags.todoPanel !== undefined ? { panel: flags.todoPanel } : {}),
+        // `!== undefined` for the third time, though for a value flag the risk is
+        // milder: commander leaves `opts.todoFollow` absent unless it was passed.
+        // Written this way anyway so the three lines read as one rule.
+        ...(flags.todoFollow !== undefined ? { followThrough: flags.todoFollow } : {}),
+    });
+}
 /** Merge the `log` section across all four layers (defaults › file › env › flags). */
 function resolveLogConfig(flags, env, file) {
     const merged = clampLogConfig({
@@ -118,6 +141,44 @@ function pick(...vals) {
     }
     return undefined;
 }
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+/**
+ * Resolve the output cap: flag › env › file › default, where an EXPLICIT `null`
+ * at any layer means AUTO (`undefined` — let the resolver pick per model).
+ *
+ * THIS CANNOT USE `pick()`, and that is the whole point. `pick` skips `null`, so
+ * a config file holding `"maxTokens": null` silently resolves to 64000 and AUTO
+ * is unreachable through every supported write path. Detecting it needs an
+ * own-property test, not a truthiness test — `null` is exactly the value we are
+ * looking for.
+ *
+ * An unparseable layer falls through to the next one rather than becoming AUTO:
+ * a typo in `ARAGON_MAX_TOKENS` must not silently discard the number in the
+ * config file underneath it.
+ */
+function resolveMaxTokens(flags, env, file) {
+    const layers = [
+        { name: '--max-tokens', value: flags.maxTokens },
+        { name: 'ARAGON_MAX_TOKENS', value: hasOwn(env, 'maxTokens') ? env.maxTokens : undefined },
+        { name: 'config.json maxTokens', value: hasOwn(file, 'maxTokens') ? file.maxTokens : undefined },
+    ];
+    for (const layer of layers) {
+        if (layer.value === undefined)
+            continue; // this layer said nothing
+        if (layer.value === null || isAutoToken(layer.value))
+            return undefined; // AUTO
+        const n = clampMaxTokens(layer.value);
+        if (n !== undefined)
+            return n;
+        getLogger().warn('config', 'max_tokens_unusable', {
+            source: layer.name,
+            value: String(layer.value),
+        });
+    }
+    return DEFAULT_CONFIG.maxTokens ?? undefined;
+}
 /**
  * Resolve the effective config by merging all layers, then derive the runtime
  * (non-persisted) fields and enforce the timeout invariant.
@@ -142,7 +203,7 @@ export function loadConfig(flags = {}) {
     const model = pick(flags.model, env.partial.model, file.model) ?? DEFAULT_CONFIG.model;
     const baseUrl = pick(flags.baseUrl, env.partial.baseUrl ?? undefined, file.baseUrl ?? undefined);
     const thinkingLevel = clampThinkingLevel(pick(flags.thinking, env.partial.thinkingLevel, file.thinkingLevel), DEFAULT_CONFIG.thinkingLevel);
-    const maxTokens = coerceMaxTokens(pick(flags.maxTokens, env.partial.maxTokens, file.maxTokens));
+    const maxTokens = resolveMaxTokens(flags, env.partial, file);
     // `clampTheme` is also where the v0.3.0 `dark` name is migrated to `cool`,
     // so reading a legacy config file needs no extra step here (§4.5 / R-4).
     const theme = clampTheme(pick(flags.theme, env.partial.theme, file.theme), DEFAULT_CONFIG.theme);
@@ -247,6 +308,7 @@ export function loadConfig(flags = {}) {
         },
         log: resolveLogConfig(flags, env.partial, file),
         team: resolveTeamConfig(flags, env.partial, file),
+        todo: resolveTodoConfig(flags, env.partial, file),
         cwd,
         color,
         colorLevel,
@@ -274,6 +336,9 @@ function recordResolvedConfig(config) {
         model: config.model,
         baseUrl: config.baseUrl,
         thinkingLevel: config.thinkingLevel,
+        // Four layers feed this one and none of them used to leave a trace, so
+        // "why is my output truncated" was unanswerable after the fact.
+        maxTokens: config.maxTokens ?? 'auto',
         theme: config.theme,
         fullscreen: config.fullscreen,
         toolTimeoutMs: config.toolTimeoutMs,

package/dist/config/schema.d.ts

@@ -5,8 +5,9 @@
  * See spec §3.5 (resolution pipeline), §6.1 (config file), and §3.8 (timeout
  * invariant).
  */
-import type { ThinkingLevel } from '@aragon-agent/core';
+import { type ThinkingLevel } from '@aragon-agent/core';
 import { type LogLevelName } from '../logging/levels.js';
+import type { FollowThroughMode } from '../todo/types.js';
 /**
  * `ModelRegistry` seeds builtin lists for five providers, but `initProviders()`
  * registers only three adapters. Running a model whose provider has no adapter
@@ -239,12 +240,58 @@ export declare const DEFAULT_TEAM_CONFIG: TeamConfig;
  * the two disagree would make the panel's `n/m` readout confusing for no gain.
  */
 export declare function clampTeamConfig(raw: unknown): TeamConfig;
+export interface TodoConfig {
+    /** Register `todo_write` at all. Default TRUE. */
+    enabled: boolean;
+    /**
+     * Render the right rail.
+     *
+     * INDEPENDENT OF `enabled` ON PURPOSE (D-16): a screen-reader user wants the
+     * planning discipline without the column, and the prompt block varies one
+     * sentence rather than disappearing (§3.7).
+     */
+    panel: boolean;
+    /**
+     * What happens when a run ends with unfinished steps
+     * (todo-plan-followthrough §4.1). Default `'notify'`, which reproduces round
+     * 1's behaviour byte for byte.
+     *
+     * THE THIRD SCALAR, and it stays a scalar for the reason the section header
+     * above gives: `store.ts` merges this section BY HAND, and both of its merges
+     * spread the whole object (`{ ...DEFAULT_CONFIG.todo, ...(partial.todo ?? {}) }`
+     * and `{ ...current.todo, ...(patch.todo ?? {}) }`), so a third scalar key is
+     * carried automatically and needs no change there. A NESTED field would not
+     * be, and would mean replacing both merges first.
+     */
+    followThrough: FollowThroughMode;
+}
+export declare const DEFAULT_TODO_CONFIG: TodoConfig;
+/**
+ * THE single gate for every todo-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` for the reason
+ * those record: hardening only the read path leaves a bad value on disk that
+ * reverts to the default on every launch, which presents to the user as "my
+ * setting won't stick".
+ */
+export declare function clampTodoConfig(raw: unknown): TodoConfig;
 export interface PersistedConfig {
     version: number;
     provider: string;
     model: string;
     baseUrl: string | null;
     thinkingLevel: ThinkingLevel;
+    /**
+     * Output token cap.
+     *
+     *   a number — an explicit cap, clamped to `[256, 200000]` on the way in AND
+     *              on the way out, then clamped again at request time down to the
+     *              target model's real ceiling when that ceiling is lower.
+     *   `null`   — AUTO: use each model's own ceiling, never above 64000.
+     *   absent   — the product default, 64000.
+     *
+     * `null` MEANS AUTO. It used to resolve to 64000 by accident (`pick()` skips
+     * `null`), which left the user no way to express "let the model decide".
+     */
     maxTokens: number | null;
     theme: ThemeName;
     /** Replace spinners with a static glyph for calmer, low-motion output. */
@@ -293,6 +340,8 @@ export interface PersistedConfig {
     log: LogConfig;
     /** Team mode. The FOURTH nested object; scalars only (see TeamConfig). */
     team: TeamConfig;
+    /** Todo planning. The FIFTH nested object; scalars only (see TodoConfig). */
+    todo: TodoConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -324,6 +373,7 @@ export interface CliConfig {
     model: string;
     baseUrl?: string;
     thinkingLevel: ThinkingLevel;
+    /** The resolved cap, or `undefined` for AUTO (per-model ceiling, ≤ 64000). */
     maxTokens?: number;
     theme: ThemeName;
     reducedMotion: boolean;
@@ -386,6 +436,16 @@ export interface CliConfig {
      * `/team` flips is a separate flag on the controller.
      */
     team: TeamConfig;
+    /**
+     * Resolved todo-planning settings (todo-plan-execution §4.2).
+     *
+     * `enabled` here decides whether `todo_write` is REGISTERED, which happens
+     * once at construction and can never be undone (C-1). The live on/off switch
+     * `/todo` flips is a separate flag on the controller; `panel` is read at
+     * RENDER time through `controller.getConfig()`, which is why `/todo panel`
+     * must call `setTodoConfig` as well as persisting (P1-2).
+     */
+    todo: TodoConfig;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *
@@ -406,8 +466,57 @@ export interface CliConfig {
     /** One-shot `--api-key` override; applies to the active provider only. */
     apiKeyOverride?: string;
 }
-/** Coerce an arbitrary value into a positive integer, or `undefined`. */
+/**
+ * Coerce an arbitrary value into a positive integer, or `undefined`.
+ *
+ * Kept because callers outside this feature still use it, and deliberately
+ * WITHOUT the range clamp so its behaviour for in-range values is byte-identical
+ * to what it always was. New code wants `clampMaxTokens`.
+ */
 export declare function coerceMaxTokens(v: unknown): number | undefined;
+/**
+ * The accepted range for an explicit output cap.
+ *
+ * The floor is the engine's: below it a turn cannot produce a usable tool call.
+ * The ceiling is a sanity bound on a hand-edited file, not a model limit — the
+ * real per-model ceiling is applied later, by `resolveOutputTokens`.
+ */
+export declare const MAX_TOKENS_RANGE: {
+    min: number;
+    max: number;
+};
+/** `auto`, an empty string and `0` all mean AUTO — "let the model decide". */
+export declare function isAutoToken(v: unknown): boolean;
+/**
+ * THE single gate for every `maxTokens` read AND write, in the shape
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` already use.
+ *
+ * Both directions on purpose: hardening only the read path leaves a bad value on
+ * disk that reverts to a default on every launch, which presents to the user as
+ * "my setting won't stick".
+ *
+ * Returns `undefined` for AUTO and for anything unusable — the caller decides
+ * which of the two it was, because they mean different things.
+ */
+export declare function clampMaxTokens(v: unknown): number | undefined;
+/**
+ * Parse text typed into the settings screen, a slash command, or `config set`.
+ *
+ * Distinguishes AUTO from "the user typed nonsense", which `clampMaxTokens`
+ * cannot: both come back as `undefined` there, and treating a typo as AUTO would
+ * silently discard the number the user meant to set.
+ */
+export declare function parseMaxTokensInput(raw: string): {
+    kind: 'auto';
+} | {
+    kind: 'value';
+    value: number;
+    clamped: boolean;
+} | {
+    kind: 'invalid';
+};
+/** The product default, re-exported so the CLI never spells the number itself. */
+export declare const DEFAULT_MAX_TOKENS = 64000;
 /** Coerce a value into a positive integer with a fallback (for timeouts). */
 export declare function coercePositiveInt(v: unknown, fallback: number): number;
 /**

package/dist/config/schema.js

@@ -6,6 +6,7 @@
  * invariant).
  */
 import { isAbsolute } from 'node:path';
+import { ABSOLUTE_MAX_OUTPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, } from '@aragon-agent/core';
 import { clampLogLevel } from '../logging/levels.js';
 import { TEAM_LIMITS } from '../team/limits.js';
 // ---------------------------------------------------------------------------
@@ -311,13 +312,49 @@ export function clampTeamConfig(raw) {
         maxTurnsPerSubagent: clampInt(src.maxTurnsPerSubagent, DEFAULT_TEAM_CONFIG.maxTurnsPerSubagent, TURNS_RANGE),
     };
 }
+export const DEFAULT_TODO_CONFIG = {
+    enabled: true,
+    panel: true,
+    followThrough: 'notify',
+};
+/**
+ * There is no enum helper in this file, so this follows the `isThinkingLevel`
+ * shape already here rather than inventing a second idiom.
+ */
+const FOLLOW_THROUGH_MODES = ['notify', 'auto', 'off'];
+function followMode(value, fallback) {
+    return typeof value === 'string' && FOLLOW_THROUGH_MODES.includes(value)
+        ? value
+        : fallback;
+}
+/**
+ * THE single gate for every todo-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` for the reason
+ * those record: hardening only the read path leaves a bad value on disk that
+ * reverts to the default on every launch, which presents to the user as "my
+ * setting won't stick".
+ */
+export function clampTodoConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    return {
+        enabled: bool(src.enabled, DEFAULT_TODO_CONFIG.enabled),
+        panel: bool(src.panel, DEFAULT_TODO_CONFIG.panel),
+        // CLAMPED TO THE DEFAULT, NEVER REJECTED — the discipline every other key in
+        // this file follows, and the trade round 1 already made for `--thinking`.
+        // `ARAGON_TODO_FOLLOW=garbage` therefore resolves to `'notify'` and throws
+        // nothing (AC-5).
+        followThrough: followMode(src.followThrough, DEFAULT_TODO_CONFIG.followThrough),
+    };
+}
 export const DEFAULT_CONFIG = {
     version: CONFIG_VERSION,
     provider: 'anthropic',
     model: DEFAULT_MODEL,
     baseUrl: null,
     thinkingLevel: 'off',
-    maxTokens: null,
+    // The engine owns this number; spelling it here again is how the CLI and the
+    // provider adapters end up disagreeing about what "the default" is.
+    maxTokens: DEFAULT_MAX_OUTPUT_TOKENS,
     theme: 'auto',
     reducedMotion: false,
     fullscreen: true,
@@ -337,6 +374,10 @@ export const DEFAULT_CONFIG = {
     skills: DEFAULT_SKILLS_CONFIG,
     log: DEFAULT_LOG_CONFIG,
     team: DEFAULT_TEAM_CONFIG,
+    // The load path's first spread is what supplies the section to a user with no
+    // `todo` key at all, so this line is as required as the two merges in
+    // `store.ts` (P0-1).
+    todo: DEFAULT_TODO_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake
@@ -376,7 +417,7 @@ export function stripLegacyStateKeys(raw) {
 // Coercion / validation helpers
 // ---------------------------------------------------------------------------
 /** Coerce an arbitrary value into a positive integer, or `undefined`. */
-export function coerceMaxTokens(v) {
+function coerceTokenCount(v) {
     if (v === null || v === undefined || v === '')
         return undefined;
     const n = typeof v === 'number' ? v : Number.parseInt(String(v), 10);
@@ -384,6 +425,74 @@ export function coerceMaxTokens(v) {
         return undefined;
     return Math.floor(n);
 }
+/**
+ * Coerce an arbitrary value into a positive integer, or `undefined`.
+ *
+ * Kept because callers outside this feature still use it, and deliberately
+ * WITHOUT the range clamp so its behaviour for in-range values is byte-identical
+ * to what it always was. New code wants `clampMaxTokens`.
+ */
+export function coerceMaxTokens(v) {
+    return coerceTokenCount(v);
+}
+/**
+ * The accepted range for an explicit output cap.
+ *
+ * The floor is the engine's: below it a turn cannot produce a usable tool call.
+ * The ceiling is a sanity bound on a hand-edited file, not a model limit — the
+ * real per-model ceiling is applied later, by `resolveOutputTokens`.
+ */
+export const MAX_TOKENS_RANGE = {
+    min: MIN_MAX_OUTPUT_TOKENS,
+    max: ABSOLUTE_MAX_OUTPUT_TOKENS,
+};
+/** `auto`, an empty string and `0` all mean AUTO — "let the model decide". */
+export function isAutoToken(v) {
+    if (v === 0)
+        return true;
+    if (typeof v !== 'string')
+        return false;
+    const trimmed = v.trim().toLowerCase();
+    return trimmed === '' || trimmed === 'auto' || trimmed === '0';
+}
+/**
+ * THE single gate for every `maxTokens` read AND write, in the shape
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` already use.
+ *
+ * Both directions on purpose: hardening only the read path leaves a bad value on
+ * disk that reverts to a default on every launch, which presents to the user as
+ * "my setting won't stick".
+ *
+ * Returns `undefined` for AUTO and for anything unusable — the caller decides
+ * which of the two it was, because they mean different things.
+ */
+export function clampMaxTokens(v) {
+    const n = coerceTokenCount(v);
+    if (n === undefined)
+        return undefined;
+    return Math.min(MAX_TOKENS_RANGE.max, Math.max(MAX_TOKENS_RANGE.min, n));
+}
+/**
+ * Parse text typed into the settings screen, a slash command, or `config set`.
+ *
+ * Distinguishes AUTO from "the user typed nonsense", which `clampMaxTokens`
+ * cannot: both come back as `undefined` there, and treating a typo as AUTO would
+ * silently discard the number the user meant to set.
+ */
+export function parseMaxTokensInput(raw) {
+    const trimmed = String(raw ?? '').trim();
+    if (isAutoToken(trimmed))
+        return { kind: 'auto' };
+    if (!/^\d+$/.test(trimmed))
+        return { kind: 'invalid' };
+    const parsed = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return { kind: 'invalid' };
+    const value = Math.min(MAX_TOKENS_RANGE.max, Math.max(MAX_TOKENS_RANGE.min, parsed));
+    return { kind: 'value', value, clamped: value !== parsed };
+}
+/** The product default, re-exported so the CLI never spells the number itself. */
+export const DEFAULT_MAX_TOKENS = DEFAULT_MAX_OUTPUT_TOKENS;
 /** Coerce a value into a positive integer with a fallback (for timeouts). */
 export function coercePositiveInt(v, fallback) {
     if (v === null || v === undefined || v === '')

package/dist/config/store.js

@@ -14,7 +14,23 @@ import { dirname } from 'node:path';
 import process from 'node:process';
 import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
-import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampSkillsConfig, clampTeamConfig, stripLegacyStateKeys, } from './schema.js';
+import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampMaxTokens, clampSkillsConfig, clampTeamConfig, clampTodoConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+/**
+ * Normalize `maxTokens` for both directions of the config file.
+ *
+ * `null` MEANS AUTO and must survive untouched; a number is clamped to the
+ * accepted range; anything else on a hand-edited file (a string, a float, a
+ * negative) becomes AUTO rather than a silent default. Same discipline as
+ * `clampSkillsConfig` — read AND write pass through one gate, or a bad value on
+ * disk reverts on every launch and presents as "my setting won't stick".
+ */
+function normalizeMaxTokens(v) {
+    if (v === undefined)
+        return DEFAULT_CONFIG.maxTokens;
+    if (v === null || isAutoToken(v))
+        return null;
+    return clampMaxTokens(v) ?? null;
+}
 // Re-exported so the many existing importers of `store.js` keep working; the
 // definitions live in `app-paths.ts` because they are pure path arithmetic.
 export { getConfigPath, getSessionsDir };
@@ -92,6 +108,12 @@ export function loadPersistedConfig() {
         ...DEFAULT_CONFIG,
         ...partial,
         version: CONFIG_VERSION,
+        // Own-property aware, because `null` is the value we need to preserve: a
+        // spread cannot tell "the key is absent" (⇒ the default) from "the key is
+        // null" (⇒ AUTO), and those are different settings.
+        maxTokens: Object.prototype.hasOwnProperty.call(partial, 'maxTokens')
+            ? normalizeMaxTokens(partial.maxTokens)
+            : DEFAULT_CONFIG.maxTokens,
         apiKeys: { ...DEFAULT_CONFIG.apiKeys, ...(partial.apiKeys ?? {}) },
         // `skills` is the second nested object in this file and needs the same
         // treatment `apiKeys` gets — see the note on updatePersistedConfig below.
@@ -100,6 +122,10 @@ export function loadPersistedConfig() {
         log: clampLogConfig({ ...DEFAULT_CONFIG.log, ...(partial.log ?? {}) }),
         // `team` is the fourth. Same one-level rule, same merge.
         team: clampTeamConfig({ ...DEFAULT_CONFIG.team, ...(partial.team ?? {}) }),
+        // `todo` is the fifth. Same one-level rule, same merge — and this line is
+        // the READ half of the pair that keeps `/todo panel off` from silently
+        // unregistering the tool on the next launch (P0-1 / AC-35).
+        todo: clampTodoConfig({ ...DEFAULT_CONFIG.todo, ...(partial.todo ?? {}) }),
     };
 }
 /**
@@ -131,6 +157,11 @@ export function updatePersistedConfig(patch) {
         ...current,
         ...patch,
         version: CONFIG_VERSION,
+        // The write half of the gate: without it `config set maxTokens 900000` puts
+        // a number on disk that the read path silently rewrites on every launch.
+        maxTokens: Object.prototype.hasOwnProperty.call(patch, 'maxTokens')
+            ? normalizeMaxTokens(patch.maxTokens)
+            : current.maxTokens,
         apiKeys: { ...current.apiKeys, ...(patch.apiKeys ?? {}) },
         skills: clampSkillsConfig({ ...current.skills, ...(patch.skills ?? {}) }),
         // Without this line, changing the log level from the settings screen would
@@ -141,6 +172,11 @@ export function updatePersistedConfig(patch) {
         // 4` sends `{ team: { maxSubagents: 4 } }`, which a shallow spread would
         // turn into "changing the fan-out width silently reverted every timeout".
         team: clampTeamConfig({ ...current.team, ...(patch.team ?? {}) }),
+        // The fifth section, and its omission is the worst of the five (P0-1):
+        // `/todo panel off` sends `{ todo: { panel: false } }`, which a shallow
+        // spread turns into "turning the panel off silently unregisters the tool",
+        // permanently, from the next launch onward, with nothing anywhere saying so.
+        todo: clampTodoConfig({ ...current.todo, ...(patch.todo ?? {}) }),
     };
     writeConfigFile(merged);
     return merged;

package/dist/session/persist.d.ts

@@ -7,22 +7,40 @@
  */
 import type { Message, ModelRef } from '@aragon-agent/core';
 import type { Entry } from '../agent/reducer.js';
+import type { TodoItem } from '../todo/types.js';
 export interface SavedSession {
     version: number;
     savedAt: number;
     model: ModelRef;
     messages: Message[];
     entries: Entry[];
+    /**
+     * The live todo list at save time (todo-plan-execution §3.13).
+     *
+     * `SESSION_VERSION` STAYS 1: the field is additive and optional, `loadSession`
+     * validates only that `messages` and `entries` are arrays, and an older file
+     * simply yields `undefined` — which `restoreTodos` treats as "clear", the
+     * right answer for a session that predates the feature (D-20 / D-22).
+     */
+    todos?: TodoItem[];
 }
 /** Resolve a `/save` target: absolute/relative path, or a name in the data dir. */
 export declare function resolveSessionPath(nameOrPath: string | undefined, cwd: string): string;
+/**
+ * `data` GAINS `todos`, AND WIDENING `SavedSession` ALONE IS NOT ENOUGH (P0-2):
+ * the writer below builds its payload from THIS parameter, not from the type, so
+ * a `todos?` field on the interface with no field here would ship a key nothing
+ * ever writes.
+ */
 export declare function saveSession(filePath: string, data: {
     model: ModelRef;
     messages: Message[];
     entries: Entry[];
+    todos: TodoItem[];
 }): void;
 /**
- * Settle any team entry that was saved mid-dispatch (team-subagents §5.3 / P1-5).
+ * Settle any team entry that was saved mid-dispatch (team-subagents §5.3 / P1-5),
+ * and any todo card that was saved mid-run (todo-plan-execution §3.8 / C-5).
  *
  * `saveSession` writes `entries` verbatim and `loadSession` validates only
  * array-ness, so a session saved while a dispatch was in flight resumes with a

package/dist/session/persist.js

@@ -28,6 +28,12 @@ function defaultStamp() {
     // Filesystem-safe timestamp without punctuation that breaks on Windows.
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
+/**
+ * `data` GAINS `todos`, AND WIDENING `SavedSession` ALONE IS NOT ENOUGH (P0-2):
+ * the writer below builds its payload from THIS parameter, not from the type, so
+ * a `todos?` field on the interface with no field here would ship a key nothing
+ * ever writes.
+ */
 export function saveSession(filePath, data) {
     const dir = dirname(filePath);
     if (!existsSync(dir))
@@ -38,11 +44,13 @@ export function saveSession(filePath, data) {
         model: data.model,
         messages: data.messages,
         entries: data.entries,
+        todos: data.todos,
     };
     writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
 }
 /**
- * Settle any team entry that was saved mid-dispatch (team-subagents §5.3 / P1-5).
+ * Settle any team entry that was saved mid-dispatch (team-subagents §5.3 / P1-5),
+ * and any todo card that was saved mid-run (todo-plan-execution §3.8 / C-5).
  *
  * `saveSession` writes `entries` verbatim and `loadSession` validates only
  * array-ness, so a session saved while a dispatch was in flight resumes with a
@@ -57,7 +65,18 @@ export function saveSession(filePath, data) {
  * never legitimately sees a stale-active entry — only the file does.
  */
 export function normalizeLoadedEntries(entries) {
-    return entries.map((entry) => entry.kind === 'team' && entry.active ? { ...entry, active: false, aborted: true } : entry);
+    return entries.map((entry) => {
+        if (entry.kind === 'team' && entry.active) {
+            return { ...entry, active: false, aborted: true };
+        }
+        // `interrupted: true` is the todo analogue of the team entry's `aborted`,
+        // and true for the same reason: the run behind the card died with the
+        // process (P2-6). Without it a resumed `2/7` reads as a run still in flight.
+        if (entry.kind === 'todo' && entry.live) {
+            return { ...entry, live: false, interrupted: true };
+        }
+        return entry;
+    });
 }
 export function loadSession(filePath) {
     const raw = readFileSync(filePath, 'utf-8');

package/dist/team/subagent.js

@@ -89,6 +89,17 @@ export function buildSubagentTools(spec, deps, getAgent) {
         // registering tools it could never use burns a turn — the same argument that
         // keeps them out of headless mode.
         planTools: [],
+        // NO `todo_write` FOR CHILDREN (todo-plan-execution §3.11 / D-14 / AC-34).
+        // Children run concurrently against ONE list under a full-replacement
+        // protocol: the last writer would win and the lead's plan would be destroyed
+        // by a subagent's private checklist. A list PER child would be a second
+        // panel and a second scroll model for work the lead already tracks as one
+        // item.
+        //
+        // EXPLICIT, WITH THIS COMMENT, even though the option's absence already
+        // yields an empty array: a silent default is not a decision anyone can find
+        // later.
+        todoTools: [],
         teamTools: commTools,
         // `spec.readOnly` forces the plan gate on for this child even in a BUILD
         // session. TIGHTENING ONLY (D-13): there is no field anywhere that gives a