@aragon-agent/cli 0.5.4 → 0.5.8

package/dist/config/schema.d.ts

@@ -7,6 +7,7 @@
  */
 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
@@ -63,15 +64,40 @@ export declare const DEFAULT_IDLE_TIMEOUT_MS: number;
  */
 export declare const PROMPT_HISTORY_CAP = 100;
 /**
- * How many trailing entries the full-screen viewport renders (invariant I-3).
- * Yoga lays out every child even when `overflow: hidden` clips it, so the cost
- * of a long session is linear in the entry count regardless of visibility. The
- * reducer and `/save` keep the full history — this is a render-layer bound only.
+ * The SCROLL HORIZON: entries older than this are not reachable inside the app
+ * and render as the "N earlier entries collapsed" line instead (invariant I-3).
+ *
+ * It used to be a rendering budget as well, because yoga laid out every child
+ * even when `overflow: hidden` clipped it. The viewport is virtualised now
+ * (tui-render-performance L3) — off-screen entries are not mounted at all — so
+ * the horizon costs O(entries) of arithmetic rather than O(characters) of layout
+ * and the default rises 300 -> 1000 with a 20000 ceiling. An existing persisted
+ * `300` is still valid and still clamps; no config migration is required.
  */
-export declare const DEFAULT_TRANSCRIPT_WINDOW = 300;
+export declare const DEFAULT_TRANSCRIPT_WINDOW = 1000;
 export declare const MIN_TRANSCRIPT_WINDOW = 50;
-export declare const MAX_TRANSCRIPT_WINDOW = 2000;
+export declare const MAX_TRANSCRIPT_WINDOW = 20000;
 export declare function clampTranscriptWindow(v: unknown, fallback: number): number;
+/**
+ * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
+ *
+ * A DIFFERENT BOUND FROM `transcriptWindow`, and the two must not be merged:
+ * the window is what the user can scroll to, this is what the process keeps in
+ * memory and what `/save` can export. Dropped entries are COUNTED and reported
+ * (`/perf`, and a leading line in the exported transcript) — never silent.
+ */
+export declare const DEFAULT_TRANSCRIPT_RETAIN = 1000;
+export declare const MIN_TRANSCRIPT_RETAIN = 200;
+export declare const MAX_TRANSCRIPT_RETAIN = 20000;
+export declare function clampTranscriptRetain(v: unknown, fallback: number): number;
+/** Adaptive coalescing under load. On by default; `--no-render-governor` kills it. */
+export declare const DEFAULT_RENDER_GOVERNOR = true;
+/**
+ * Ceiling of the governor ladder, in ms. `33` flattens the ladder to a single
+ * rung, which is the pre-feature behaviour without needing the kill switch.
+ */
+export declare const DEFAULT_MAX_RENDER_INTERVAL_MS = 320;
+export declare function clampMaxRenderInterval(v: unknown, fallback: number): number;
 /** `ask_user` calls allowed per user turn. */
 export declare const DEFAULT_PLAN_MAX_ASK_ROUNDS = 4;
 /**
@@ -239,6 +265,40 @@ 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;
@@ -265,8 +325,14 @@ export interface PersistedConfig {
     fullscreen: boolean;
     /** Replay a plain-text session summary after leaving the alternate screen. */
     exitTranscript: boolean;
-    /** Trailing entries the full-screen viewport renders (I-3). */
+    /** Entries reachable by scrolling; older ones show the "collapsed" line (I-3). */
     transcriptWindow: number;
+    /** Entries kept in `ViewState`; older ones are dropped and counted (L1). */
+    transcriptRetain: number;
+    /** Adaptive coalescing under load (L4). */
+    renderGovernor: boolean;
+    /** Ceiling of the governor ladder in ms; `33` flattens it (L4). */
+    maxRenderIntervalMs: number;
     confirmTools: boolean;
     toolTimeoutMs: number;
     idleTimeoutMs: number;
@@ -305,6 +371,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;
 /**
@@ -353,8 +421,30 @@ export interface CliConfig {
     fullscreen?: boolean;
     /** Replay a plain-text summary on exit (full-screen only — see §4.4). */
     exitTranscript: boolean;
-    /** Trailing entries the full-screen viewport renders (I-3). */
+    /** Entries reachable by scrolling; older ones show the "collapsed" line (I-3). */
     transcriptWindow: number;
+    /**
+     * Entries kept in `ViewState` (L1).
+     *
+     * Resolved to be `>= transcriptWindow`: retaining fewer entries than the
+     * window can scroll to would silently make part of the window unreachable.
+     */
+    transcriptRetain: number;
+    /**
+     * What the user actually asked `transcriptRetain` to be, present ONLY when
+     * that value had to be raised (§5.1).
+     *
+     * A setting ignored without a word is the one failure mode this feature is
+     * not allowed to add: the eco chip, `/perf` and the dropped-entry line all
+     * exist so that nothing it does happens unannounced, and a config key
+     * overwritten in silence would be the exception. `undefined` means nothing
+     * was overridden, which is every default session.
+     */
+    transcriptRetainRequested?: number;
+    /** Adaptive coalescing under load (L4). */
+    renderGovernor: boolean;
+    /** Ceiling of the governor ladder in ms; `33` flattens it (L4). */
+    maxRenderIntervalMs: number;
     confirmTools: boolean;
     toolTimeoutMs: number;
     idleTimeoutMs: number;
@@ -399,6 +489,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`).
      *

package/dist/config/schema.js

@@ -98,18 +98,52 @@ export const DEFAULT_IDLE_TIMEOUT_MS = DEFAULT_TOOL_TIMEOUT_MS + IDLE_TIMEOUT_MA
  */
 export const PROMPT_HISTORY_CAP = 100;
 /**
- * How many trailing entries the full-screen viewport renders (invariant I-3).
- * Yoga lays out every child even when `overflow: hidden` clips it, so the cost
- * of a long session is linear in the entry count regardless of visibility. The
- * reducer and `/save` keep the full history — this is a render-layer bound only.
+ * The SCROLL HORIZON: entries older than this are not reachable inside the app
+ * and render as the "N earlier entries collapsed" line instead (invariant I-3).
+ *
+ * It used to be a rendering budget as well, because yoga laid out every child
+ * even when `overflow: hidden` clipped it. The viewport is virtualised now
+ * (tui-render-performance L3) — off-screen entries are not mounted at all — so
+ * the horizon costs O(entries) of arithmetic rather than O(characters) of layout
+ * and the default rises 300 -> 1000 with a 20000 ceiling. An existing persisted
+ * `300` is still valid and still clamps; no config migration is required.
  */
-export const DEFAULT_TRANSCRIPT_WINDOW = 300;
+export const DEFAULT_TRANSCRIPT_WINDOW = 1000;
 export const MIN_TRANSCRIPT_WINDOW = 50;
-export const MAX_TRANSCRIPT_WINDOW = 2000;
+export const MAX_TRANSCRIPT_WINDOW = 20_000;
 export function clampTranscriptWindow(v, fallback) {
     const n = coercePositiveInt(v, fallback);
     return Math.min(MAX_TRANSCRIPT_WINDOW, Math.max(MIN_TRANSCRIPT_WINDOW, n));
 }
+/**
+ * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
+ *
+ * A DIFFERENT BOUND FROM `transcriptWindow`, and the two must not be merged:
+ * the window is what the user can scroll to, this is what the process keeps in
+ * memory and what `/save` can export. Dropped entries are COUNTED and reported
+ * (`/perf`, and a leading line in the exported transcript) — never silent.
+ */
+export const DEFAULT_TRANSCRIPT_RETAIN = 1000;
+export const MIN_TRANSCRIPT_RETAIN = 200;
+export const MAX_TRANSCRIPT_RETAIN = 20_000;
+export function clampTranscriptRetain(v, fallback) {
+    const n = coercePositiveInt(v, fallback);
+    return Math.min(MAX_TRANSCRIPT_RETAIN, Math.max(MIN_TRANSCRIPT_RETAIN, n));
+}
+// ---------------------------------------------------------------------------
+// Adaptive render governor (tui-render-performance L4 / R7)
+// ---------------------------------------------------------------------------
+/** Adaptive coalescing under load. On by default; `--no-render-governor` kills it. */
+export const DEFAULT_RENDER_GOVERNOR = true;
+/**
+ * Ceiling of the governor ladder, in ms. `33` flattens the ladder to a single
+ * rung, which is the pre-feature behaviour without needing the kill switch.
+ */
+export const DEFAULT_MAX_RENDER_INTERVAL_MS = 320;
+const RENDER_INTERVAL_RANGE = { min: 33, max: 1000 };
+export function clampMaxRenderInterval(v, fallback) {
+    return clampInt(v, fallback, RENDER_INTERVAL_RANGE);
+}
 // ---------------------------------------------------------------------------
 // Plan mode (plan-mode §4.4)
 //
@@ -312,6 +346,40 @@ 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',
@@ -326,6 +394,9 @@ export const DEFAULT_CONFIG = {
     fullscreen: true,
     exitTranscript: true,
     transcriptWindow: DEFAULT_TRANSCRIPT_WINDOW,
+    transcriptRetain: DEFAULT_TRANSCRIPT_RETAIN,
+    renderGovernor: DEFAULT_RENDER_GOVERNOR,
+    maxRenderIntervalMs: DEFAULT_MAX_RENDER_INTERVAL_MS,
     confirmTools: false,
     toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
     idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
@@ -340,6 +411,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

package/dist/config/store.js

@@ -14,7 +14,7 @@ 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, clampMaxTokens, clampSkillsConfig, clampTeamConfig, isAutoToken, 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.
  *
@@ -122,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 ?? {}) }),
     };
 }
 /**
@@ -168,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

package/dist/todo/follow-through.d.ts

@@ -0,0 +1,117 @@
+/**
+ * follow-through — what happens when a run ends with unfinished steps
+ * (todo-plan-followthrough §3.2 / §3.3).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), and every string this module builds is user-visible.
+ *
+ * PURE. No I/O, no timers, no React, no `Date.now()` — the discipline
+ * `TodoStore`'s injected clock already establishes. The TUI (`App.tsx`) and
+ * headless mode (`agent/headless.ts`) both call `decideFollowThrough`, which is
+ * the only reason the two cannot drift; a second copy of this table in either
+ * caller is the defect this file exists to prevent.
+ *
+ * IT NEVER WRITES TO `TodoStore` (I-1 / C-3). Follow-through reads snapshots and
+ * produces a MESSAGE; the plan changes only when the model calls `todo_write`,
+ * which keeps the list a projection of what the model believes.
+ */
+import type { TodoSnapshot } from './types.js';
+/**
+ * `notify` — say something true and stop (the default; round 1's behaviour).
+ * `auto`   — continue the plan, under the economy below.
+ * `off`    — say nothing at all.
+ */
+export type FollowThroughMode = 'notify' | 'auto' | 'off';
+/** Carried across runs by the caller. Serializable, comparable, inert. */
+export interface FollowThroughBudget {
+    /**
+     * Auto-continuations issued against this list LINEAGE.
+     *
+     * MONOTONIC UNTIL THE LIST IS GONE (P0-1 / D-16 / I-8). It is NOT reset by a
+     * re-plan: a model that emits a differently-sized list on every continuation
+     * would otherwise zero both counters every turn while `staleTurns` also never
+     * fires (it IS writing), which is an unbounded loop reachable by ordinary
+     * "re-plan as you learn" behaviour rather than by anything adversarial.
+     *
+     * A refactor that "simplifies" `advanceBudget` back to returning a zeroed
+     * budget on a `total` change re-opens that hole, and the symptom is a bill
+     * rather than a test failure. `advanceBudget`'s own test pins it.
+     */
+    used: number;
+    /** Consecutive auto-continuations after which `doneCount` did not increase. */
+    noProgressStreak: number;
+    /** `TodoSnapshot.total` the budget was opened against. Identity, not a count. */
+    anchorTotal: number;
+    /**
+     * `doneCount` as observed at the PREVIOUS `agent_end` — which is what
+     * `advanceBudget` assigns, in every branch, and therefore what the next call
+     * compares against. An implementer who captures it at `runStart` instead
+     * builds a different state machine that happens to agree in the normal case.
+     */
+    doneAtRunStart: number;
+}
+export interface FollowThroughInput {
+    mode: FollowThroughMode;
+    snapshot: TodoSnapshot | null;
+    /**
+     * Why the run ended. Derived by the caller, never carried by `AgentEndEvent`
+     * (C-2): core's event has `messages` and nothing else, and this round does not
+     * change core to make it otherwise.
+     */
+    runEnd: {
+        aborted: boolean;
+        errored: boolean;
+    };
+    budget: FollowThroughBudget;
+    /**
+     * `false` in headless: no grace window (there is nobody to use it), and a
+     * different notice verb, because `-p` writes `[todo] ...` lines rather than
+     * transcript notices.
+     */
+    interactive: boolean;
+}
+export type FollowThroughDecision = {
+    kind: 'none';
+} | {
+    kind: 'notify';
+    level: 'info' | 'warn';
+    text: string;
+} | {
+    kind: 'continue';
+    message: string;
+    graceMs: number;
+    notice: string;
+};
+/** The zero budget. A fresh App, a fresh headless run, and every cleared list. */
+export declare function emptyBudget(): FollowThroughBudget;
+/**
+ * The decision. EVALUATED IN THIS ORDER, AND THE ORDER IS SEMANTICS, NOT STYLE —
+ * the same sentence `decideRenderMode` carries.
+ */
+export declare function decideFollowThrough(input: FollowThroughInput): FollowThroughDecision;
+/**
+ * Fold a finished run into the budget. Called BEFORE `decideFollowThrough`, on
+ * every `agent_end` (and on every resolved `prompt()` in headless).
+ *
+ * `used` is NOT incremented here — a decision that is never acted on costs
+ * nothing. Both fire points charge it themselves (I-5): the TUI's grace timer
+ * and the headless loop, and BOTH are required. An uncharged counter in `-p` is
+ * an uncapped loop in the one environment with no human to press Esc (P1-2).
+ */
+export declare function advanceBudget(prev: FollowThroughBudget, snapshot: TodoSnapshot | null, wasAutoContinuation: boolean): FollowThroughBudget;
+/**
+ * The text an auto-continuation — or `/todo continue` — submits.
+ *
+ * IT ENUMERATES RATHER THAN REFERRING (D-11). Round 1 submitted the fixed string
+ * "Continue with the remaining todo items.", which is a reference to a
+ * `todo_write` call that in a long session may have scrolled far enough back
+ * that the model reconstructs it wrong — and reconstructing it wrong is SILENT,
+ * because whatever it writes next is a full replacement and becomes the new
+ * truth.
+ *
+ * `content` and never `activeForm`: the imperative is what an instruction wants.
+ * Numbers are the item's 1-based position in the WHOLE list, so "step 5" means
+ * the same thing here as it does in the rail. Completed items are omitted.
+ * `TODO_LIMITS.maxItems` bounds the whole message at roughly 1.8 kB.
+ */
+export declare function buildContinuationMessage(snapshot: TodoSnapshot): string;