@aragon-agent/cli 0.5.4 → 0.5.8

package/dist/agent/controller.d.ts

@@ -9,9 +9,10 @@
  * from the event stream by the reducer (TUI) and the headless writer.
  */
 import { ModelRegistry, type AgentEvent, type AgentTool, type Message, type ModelInfo, type ProviderRegistry, type ThinkingLevel } from '@aragon-agent/core';
-import type { CliConfig, TeamConfig, ThemeName } from '../config/schema.js';
+import type { CliConfig, TeamConfig, ThemeName, TodoConfig } from '../config/schema.js';
 import { type ConfirmRequest } from '../tools/index.js';
 import type { TeamEvent, TeamSnapshot } from '../team/types.js';
+import type { TodoEventListener, TodoSnapshot } from '../todo/types.js';
 import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
 import type { AgentMode } from './agent-mode.js';
@@ -48,6 +49,23 @@ export interface ControllerDeps {
      * wizard or a plan card.
      */
     humanInput?: HumanInputGate;
+    /**
+     * Whether this session could EVER render the todo rail (todo-plan-execution
+     * §3.7 / P1-6). Full-screen and interactive; `-p` and inline mode are false.
+     *
+     * It varies ONE SENTENCE of the `<todo_planning>` block, and nothing else.
+     * Telling the model "the user sees this list in a panel beside the
+     * conversation" under `-p` is the same error `composeSystemPrompt` already
+     * guards against for team mode with its two flags. Defaults to `false` so a
+     * caller that forgets it gets the honest sentence rather than a false claim
+     * about the user's screen.
+     *
+     * Deliberately STATIC (D-25). The two dynamic causes — a resize below
+     * `TODO_RAIL_MIN_TOTAL_COLS` and an open overlay — do NOT re-compose the
+     * prompt: rebuilding it on every resize would rewrite the system prompt
+     * mid-run, and the sentence is guidance rather than a contract.
+     */
+    todoPanelCapable?: boolean;
 }
 /** What `setAgentMode` actually adopted — see `AgentController.setAgentMode`. */
 export interface AgentModeState {
@@ -84,6 +102,11 @@ export declare class AgentController {
     private readonly teamRegistered;
     private teamEnabled;
     private readonly teamRuntime;
+    private readonly todoRegistered;
+    private todoEnabled;
+    private readonly todos;
+    /** Static: whether this session could ever render the rail. See the dep. */
+    private readonly todoPanelCapable;
     constructor(config: CliConfig, deps?: ControllerDeps);
     private resolveKey;
     /**
@@ -229,6 +252,53 @@ export declare class AgentController {
     subscribeTeam(listener: (event: TeamEvent) => void): () => void;
     /** Abort every child and clear timers. Idempotent; safe to call twice. */
     dispose(): void;
+    /** Whether `todo_write` is in `this.tools`. Fixed at construction (C-1). */
+    isTodoRegistered(): boolean;
+    /** Whether `todo_write` will actually write. Flipped live by `/todo on|off`. */
+    isTodoEnabled(): boolean;
+    /**
+     * Flip the live switch and RE-RENDER THE PROMPT.
+     *
+     * THE REBUILD IS NOT OPTIONAL (P1-1 / AC-37). `composeSystemPrompt()` gates
+     * `todoBlock` on `todoRegistered && todoEnabled`; without the rebuild
+     * `<todo_planning>` survives `/todo off`, every call comes back with
+     * `TODO_OFF_REFUSAL`, and the instructions telling the model to keep calling
+     * are still in its own context — a refusal loop it cannot diagnose.
+     *
+     * Turning it ON in a session that started with `--no-todo` deliberately does
+     * NOT register the tool: the array is immutable (C-1), and advertising an
+     * unregistered tool is the dead end `/team on` already documents. `/todo`
+     * reports that honestly by checking `isTodoRegistered()` first.
+     */
+    setTodoEnabled(enabled: boolean): void;
+    getTodoConfig(): TodoConfig;
+    /**
+     * Adopt a new todo config for this session.
+     *
+     * THIS EXISTS BECAUSE `persistConfig` DOES NOT TOUCH THE RUNTIME (P1-2 /
+     * AC-38). `App` reads `controller.getConfig()` on every render, and that
+     * returns THIS object; the App's `persistConfig` only writes the file. So
+     * `/todo panel off` must call both, exactly as `/team max` does — with only
+     * the persist call the command reports success and changes nothing until the
+     * next launch.
+     *
+     * Clamped here as well as on the persist path, so a bad value can reach
+     * neither the runtime nor the file. The prompt rebuild carries §3.7's
+     * `panelVisible` sentence, which is part of the block.
+     */
+    setTodoConfig(patch: Partial<TodoConfig>): TodoConfig;
+    getTodoSnapshot(): TodoSnapshot | null;
+    /**
+     * Subscribe to the CLI-local todo event stream.
+     *
+     * Returns a no-op unsubscribe when todo planning was off at construction, so
+     * every caller can subscribe unconditionally.
+     */
+    subscribeTodos(listener: TodoEventListener): () => void;
+    /** `/resume`. An absent or empty list CLEARS — see `TodoStore.restore` (P0-2). */
+    restoreTodos(items: unknown): void;
+    /** `/todo clear`. A user override of a projection; refused mid-run by `/todo`. */
+    clearTodos(): void;
     setModel(provider: string, model: string, baseUrl?: string): void;
     setThinkingLevel(level: ThinkingLevel): void;
     setMaxTokens(value: number | undefined): void;

package/dist/agent/controller.js

@@ -9,7 +9,7 @@
  * from the event stream by the reducer (TUI) and the headless writer.
  */
 import { Agent, initProviders, ModelRegistry, } from '@aragon-agent/core';
-import { clampTeamConfig, isAdapterProvider } from '../config/schema.js';
+import { clampTeamConfig, clampTodoConfig, isAdapterProvider } from '../config/schema.js';
 import { makeGetApiKey } from '../config/load.js';
 import { updatePersistedConfig } from '../config/store.js';
 import { createBuiltinTools } from '../tools/index.js';
@@ -17,6 +17,9 @@ import { TeamRuntime } from '../team/runtime.js';
 import { TeamHumanQueue } from '../team/human-queue.js';
 import { createTaskTool } from '../team/task-tool.js';
 import { buildTeamBlock } from '../team/prompt.js';
+import { TodoStore } from '../todo/store.js';
+import { createTodoTool } from '../todo/todo-tool.js';
+import { buildTodoBlock } from '../todo/prompt.js';
 import { createPlanTools } from '../tools/plan-tools.js';
 import { DENY_ALL_HUMAN_INPUT } from '../tools/human-input.js';
 import { createNodeSkillHost } from '../skills/node-host.js';
@@ -71,6 +74,26 @@ export class AgentController {
     teamRegistered;
     teamEnabled;
     teamRuntime;
+    // -----------------------------------------------------------------------
+    // Todo planning (todo-plan-execution §3.6a) — THE SAME TWO FLAGS, FOR THE
+    // SAME REASON.
+    //
+    // `todoRegistered` is decided ONCE, at construction: whether `todo_write` is
+    // in `this.tools` at all. The array is immutable for the life of the session
+    // (C-1), so `/todo on` in a session started with `--no-todo` CANNOT add it.
+    //
+    // `todoEnabled` is live. `/todo off` flips it, which makes `todo_write` refuse
+    // through its own closure AND drops `<todo_planning>` from the next prompt
+    // rebuild — and BOTH halves are required (P1-1). Flip the flag without the
+    // rebuild and the block survives `/todo off`: every call comes back with the
+    // refusal while the instructions telling the model to keep calling are still
+    // in its own context, so it cannot diagnose the loop.
+    // -----------------------------------------------------------------------
+    todoRegistered;
+    todoEnabled;
+    todos;
+    /** Static: whether this session could ever render the rail. See the dep. */
+    todoPanelCapable;
     constructor(config, deps = {}) {
         this.config = config;
         this.cwd = config.cwd;
@@ -104,6 +127,11 @@ export class AgentController {
             this.skills.reportUnknownForcedSkills();
         }
         const confirm = deps.confirm;
+        // --- Todo planning -----------------------------------------------------
+        this.todoRegistered = config.todo.enabled;
+        this.todoEnabled = config.todo.enabled;
+        this.todoPanelCapable = deps.todoPanelCapable === true;
+        this.todos = this.todoRegistered ? new TodoStore() : null;
         // --- Team mode ---------------------------------------------------------
         this.teamRegistered = config.team.enabled;
         this.teamEnabled = config.team.enabled;
@@ -167,6 +195,18 @@ export class AgentController {
                 withHumanWait: (fn) => this.withHumanWait(fn),
                 onPlanApproved: () => this.setAgentMode('build', { force: true }),
             }),
+            // THROUGH THE FACTORY for the reason `teamTools` records below (C-2), and
+            // empty when todo planning was off at construction — which leaves the
+            // array byte-identical to the pre-todo build (AC-30).
+            todoTools: this.todos
+                ? [
+                    createTodoTool({
+                        store: this.todos,
+                        // Read LIVE: `/todo off` flips the flag, it cannot unregister.
+                        isEnabled: () => this.todoEnabled,
+                    }),
+                ]
+                : [],
             // THROUGH THE FACTORY, NEVER APPENDED AFTERWARDS (D-15 / P0-1).
             // `tools.test.ts::C7` asserts `HOST_TOOL_NAMES` equals what
             // `createBuiltinTools` produces, so appending `task` here would turn that
@@ -286,6 +326,16 @@ export class AgentController {
                     maxConcurrent: this.config.team.maxConcurrent,
                 })
                 : '',
+            // BOTH FLAGS, exactly as team mode uses both, and for the identical
+            // reason: `todoRegistered` false means there is no `todo_write` to
+            // advertise, `todoEnabled` false means the user turned it off for this
+            // session, and advertising in either case would describe a capability the
+            // model does not have.
+            todoBlock: this.todoRegistered && this.todoEnabled
+                ? buildTodoBlock({
+                    panelVisible: this.todoPanelCapable && this.config.todo.panel,
+                })
+                : '',
         });
     }
     rebuildSystemPrompt() {
@@ -382,6 +432,11 @@ export class AgentController {
         // steering "actually, use Postgres" into a running plan is answering the
         // questions, not buying four more rounds of them.
         this.askRounds = 0;
+        // Same asymmetry, same reason (§3.5): a completed plan is dropped HERE
+        // rather than at `agent_end`, so the user gets their `7/7 done` moment, and
+        // an unfinished one survives "continue" / "now do the rest" but not four
+        // unrelated turns.
+        this.todos?.beginUserTurn();
         return this.agent.prompt(text);
     }
     abort() {
@@ -579,6 +634,80 @@ export class AgentController {
         this.teamRuntime?.dispose();
     }
     // -----------------------------------------------------------------------
+    // Todo planning (todo-plan-execution §3.6a)
+    // -----------------------------------------------------------------------
+    /** Whether `todo_write` is in `this.tools`. Fixed at construction (C-1). */
+    isTodoRegistered() {
+        return this.todoRegistered;
+    }
+    /** Whether `todo_write` will actually write. Flipped live by `/todo on|off`. */
+    isTodoEnabled() {
+        return this.todoEnabled;
+    }
+    /**
+     * Flip the live switch and RE-RENDER THE PROMPT.
+     *
+     * THE REBUILD IS NOT OPTIONAL (P1-1 / AC-37). `composeSystemPrompt()` gates
+     * `todoBlock` on `todoRegistered && todoEnabled`; without the rebuild
+     * `<todo_planning>` survives `/todo off`, every call comes back with
+     * `TODO_OFF_REFUSAL`, and the instructions telling the model to keep calling
+     * are still in its own context — a refusal loop it cannot diagnose.
+     *
+     * Turning it ON in a session that started with `--no-todo` deliberately does
+     * NOT register the tool: the array is immutable (C-1), and advertising an
+     * unregistered tool is the dead end `/team on` already documents. `/todo`
+     * reports that honestly by checking `isTodoRegistered()` first.
+     */
+    setTodoEnabled(enabled) {
+        this.todoEnabled = enabled;
+        this.rebuildSystemPrompt();
+    }
+    getTodoConfig() {
+        return this.config.todo;
+    }
+    /**
+     * Adopt a new todo config for this session.
+     *
+     * THIS EXISTS BECAUSE `persistConfig` DOES NOT TOUCH THE RUNTIME (P1-2 /
+     * AC-38). `App` reads `controller.getConfig()` on every render, and that
+     * returns THIS object; the App's `persistConfig` only writes the file. So
+     * `/todo panel off` must call both, exactly as `/team max` does — with only
+     * the persist call the command reports success and changes nothing until the
+     * next launch.
+     *
+     * Clamped here as well as on the persist path, so a bad value can reach
+     * neither the runtime nor the file. The prompt rebuild carries §3.7's
+     * `panelVisible` sentence, which is part of the block.
+     */
+    setTodoConfig(patch) {
+        const todo = clampTodoConfig({ ...this.config.todo, ...patch });
+        this.config = { ...this.config, todo };
+        this.rebuildSystemPrompt();
+        return todo;
+    }
+    getTodoSnapshot() {
+        return this.todos?.snapshot() ?? null;
+    }
+    /**
+     * Subscribe to the CLI-local todo event stream.
+     *
+     * Returns a no-op unsubscribe when todo planning was off at construction, so
+     * every caller can subscribe unconditionally.
+     */
+    subscribeTodos(listener) {
+        if (!this.todos)
+            return () => { };
+        return this.todos.subscribe(listener);
+    }
+    /** `/resume`. An absent or empty list CLEARS — see `TodoStore.restore` (P0-2). */
+    restoreTodos(items) {
+        this.todos?.restore(items);
+    }
+    /** `/todo clear`. A user override of a projection; refused mid-run by `/todo`. */
+    clearTodos() {
+        this.todos?.clear('user');
+    }
+    // -----------------------------------------------------------------------
     // Mutators
     // -----------------------------------------------------------------------
     setModel(provider, model, baseUrl) {
@@ -620,6 +749,11 @@ export class AgentController {
         // A new conversation has no loaded skills, so the "already loaded earlier
         // in this conversation" hint would otherwise start lying (P2-9).
         this.skills.getRegistry().clearActive();
+        // `/reset` clears `messages`, so the belief that justifies the panel is gone
+        // with them and the list must go too (I-2). `/clear` reaches the transcript
+        // and NOT this method, which is the whole distinction: it tells the model
+        // nothing, so it may not change the list.
+        this.todos?.clear('reset');
     }
     /** Read-only view of the live system prompt (regression tests, /debug). */
     getSystemPrompt() {

package/dist/agent/entry-limits.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Bounded view state (tui-render-performance L1 / R5).
+ *
+ * `ViewState.entries` used to grow without any ceiling: `argsRaw`, assistant
+ * `text` and `thinking` all concatenated forever, and the entry array was never
+ * trimmed. That makes the per-frame cost of the renderer proportional to the
+ * total number of characters the session has ever produced, because Ink's
+ * `renderNodeToOutput` walks and measures every mounted text node whether or not
+ * `overflow: hidden` clips it.
+ *
+ * Two bounds live here, both pure and React-free:
+ *   - `appendBounded` caps one field by eliding its MIDDLE, and
+ *   - `trimEntries` ring-trims the entry array itself.
+ *
+ * ASCII ONLY. This module is produced outside `src/ui/**`, where no terminal
+ * capabilities are available, so the elision marker has to be safe on a legacy
+ * `cmd.exe` -- the same rule `PREVIEW_TRUNCATION_MARK` in `reducer.ts` records.
+ */
+import type { Entry } from './reducer.js';
+export interface EntryLimits {
+    /** Assistant answer text ceiling, in characters. */
+    text: number;
+    /** Assistant thinking ceiling. */
+    thinking: number;
+    /** Streamed tool-argument JSON ceiling. */
+    argsRaw: number;
+}
+/**
+ * The per-field ceilings.
+ *
+ * `text` is the generous one on purpose: a 256 KiB answer is already far past
+ * anything a terminal can usefully show, and the middle is what gets elided, so
+ * both the opening and the live cursor survive. `argsRaw` is the tight one --
+ * it is a streamed JSON fragment rendered as a 60-character card summary, so
+ * anything past a few KiB is invisible by construction.
+ */
+export declare const ENTRY_LIMITS: EntryLimits;
+/** Marker inserted at the elision point. ASCII -- produced outside `src/ui/**`. */
+export declare const ELISION_MARK_PREFIX = "\n[... ";
+export declare const ELISION_MARK_SUFFIX = " characters elided ...]\n";
+/**
+ * Append `delta` to `prev`, keeping the result at or below `cap` by eliding the
+ * MIDDLE. Head and tail are both preserved: the head is the answer's opening,
+ * the tail is where the cursor is. Idempotent -- re-eliding an already elided
+ * string collapses the two markers into one.
+ *
+ * The returned string is NEVER longer than `cap` (AC-7). The marker's own digit
+ * count is bounded before the tail budget is computed, so the arithmetic cannot
+ * overshoot by a digit the way a naive `cap - marker.length` would.
+ */
+export declare function appendBounded(prev: string, delta: string, cap: number): string;
+export interface TrimResult {
+    entries: Entry[];
+    dropped: number;
+}
+/**
+ * Ring-trim to `retain` entries; returns the SAME array reference when no-op.
+ *
+ * The identity return is load-bearing: the reducer spreads this result into a
+ * new `ViewState` on every append, and a fresh array on every action would
+ * defeat the `React.memo` boundaries L2 installs on the transcript.
+ */
+export declare function trimEntries(entries: Entry[], retain: number): TrimResult;
+export declare function setEntryRetain(value: number): void;
+export declare function entryRetain(): number;

package/dist/agent/entry-limits.js

@@ -0,0 +1,133 @@
+/**
+ * Bounded view state (tui-render-performance L1 / R5).
+ *
+ * `ViewState.entries` used to grow without any ceiling: `argsRaw`, assistant
+ * `text` and `thinking` all concatenated forever, and the entry array was never
+ * trimmed. That makes the per-frame cost of the renderer proportional to the
+ * total number of characters the session has ever produced, because Ink's
+ * `renderNodeToOutput` walks and measures every mounted text node whether or not
+ * `overflow: hidden` clips it.
+ *
+ * Two bounds live here, both pure and React-free:
+ *   - `appendBounded` caps one field by eliding its MIDDLE, and
+ *   - `trimEntries` ring-trims the entry array itself.
+ *
+ * ASCII ONLY. This module is produced outside `src/ui/**`, where no terminal
+ * capabilities are available, so the elision marker has to be safe on a legacy
+ * `cmd.exe` -- the same rule `PREVIEW_TRUNCATION_MARK` in `reducer.ts` records.
+ */
+import { DEFAULT_TRANSCRIPT_RETAIN } from '../config/schema.js';
+/**
+ * The per-field ceilings.
+ *
+ * `text` is the generous one on purpose: a 256 KiB answer is already far past
+ * anything a terminal can usefully show, and the middle is what gets elided, so
+ * both the opening and the live cursor survive. `argsRaw` is the tight one --
+ * it is a streamed JSON fragment rendered as a 60-character card summary, so
+ * anything past a few KiB is invisible by construction.
+ */
+export const ENTRY_LIMITS = {
+    text: 262_144,
+    thinking: 65_536,
+    argsRaw: 16_384,
+};
+/** Marker inserted at the elision point. ASCII -- produced outside `src/ui/**`. */
+export const ELISION_MARK_PREFIX = '\n[... ';
+export const ELISION_MARK_SUFFIX = ' characters elided ...]\n';
+/** Matches a marker this module wrote, so re-elision collapses rather than nests. */
+const ELISION_RE = /\n\[\.\.\. (\d+) characters elided \.\.\.\]\n/;
+/** Fixed cost of the marker, before the digits of the count. */
+const MARKER_FIXED = ELISION_MARK_PREFIX.length + ELISION_MARK_SUFFIX.length;
+/**
+ * Fraction of the cap reserved for the HEAD. The tail gets the rest because that
+ * is where the cursor is; the head exists so the answer still starts where the
+ * model started it.
+ */
+const HEAD_FRACTION = 4;
+/** Undo one elision, so a second one merges into it rather than nesting. */
+function splitElided(prev) {
+    const m = ELISION_RE.exec(prev);
+    if (!m)
+        return { head: '', elided: 0, tail: prev };
+    const index = m.index;
+    return {
+        head: prev.slice(0, index),
+        elided: Number.parseInt(m[1], 10) || 0,
+        tail: prev.slice(index + m[0].length),
+    };
+}
+/**
+ * Append `delta` to `prev`, keeping the result at or below `cap` by eliding the
+ * MIDDLE. Head and tail are both preserved: the head is the answer's opening,
+ * the tail is where the cursor is. Idempotent -- re-eliding an already elided
+ * string collapses the two markers into one.
+ *
+ * The returned string is NEVER longer than `cap` (AC-7). The marker's own digit
+ * count is bounded before the tail budget is computed, so the arithmetic cannot
+ * overshoot by a digit the way a naive `cap - marker.length` would.
+ */
+export function appendBounded(prev, delta, cap) {
+    if (!Number.isFinite(cap) || cap <= 0)
+        return '';
+    const split = splitElided(prev);
+    let head = split.head;
+    let tail = split.tail + delta;
+    let elided = split.elided;
+    // Fast path: nothing has ever been elided and it still fits. This is the path
+    // every ordinary answer takes, so it must allocate nothing beyond the concat.
+    if (elided === 0 && tail.length <= cap)
+        return tail;
+    const headBudget = Math.max(0, Math.min(Math.floor(cap / HEAD_FRACTION), cap - MARKER_FIXED - 1));
+    if (elided === 0) {
+        // First elision: the head has to be carved out of the accumulated text.
+        head = tail.slice(0, headBudget);
+        tail = tail.slice(headBudget);
+    }
+    else if (head.length > headBudget) {
+        // A later `cap` reduction can leave the stored head oversized; charge the
+        // difference to the elision count rather than silently keeping it.
+        elided += head.length - headBudget;
+        head = head.slice(0, headBudget);
+    }
+    if (head.length + MARKER_FIXED >= cap) {
+        // Degenerate cap (only reachable from a hand-written test): keep the tail.
+        return tail.slice(Math.max(0, tail.length - cap));
+    }
+    // `elided + tail.length` is an UPPER BOUND on the final count, so its digit
+    // count is an upper bound on the marker's width. Budgeting against the bound
+    // is what makes the `<= cap` guarantee hold without a second pass.
+    const digitBound = String(elided + tail.length).length;
+    const markerBound = MARKER_FIXED + digitBound;
+    const tailKeep = Math.max(0, Math.min(tail.length, cap - head.length - markerBound));
+    const total = elided + (tail.length - tailKeep);
+    return `${head}${ELISION_MARK_PREFIX}${total}${ELISION_MARK_SUFFIX}${tail.slice(tail.length - tailKeep)}`;
+}
+/**
+ * Ring-trim to `retain` entries; returns the SAME array reference when no-op.
+ *
+ * The identity return is load-bearing: the reducer spreads this result into a
+ * new `ViewState` on every append, and a fresh array on every action would
+ * defeat the `React.memo` boundaries L2 installs on the transcript.
+ */
+export function trimEntries(entries, retain) {
+    const keep = Math.max(1, Math.floor(retain));
+    if (entries.length <= keep)
+        return { entries, dropped: 0 };
+    return { entries: entries.slice(entries.length - keep), dropped: entries.length - keep };
+}
+// ---------------------------------------------------------------------------
+// The resolved retain ceiling
+// ---------------------------------------------------------------------------
+/**
+ * `viewReducer` is pure and takes no config, so the resolved `transcriptRetain`
+ * reaches it through a module-level singleton -- the shape `prompt-history.ts`
+ * already uses for `setHistoryEnabled`. `load.ts` is the ONLY writer.
+ */
+let resolvedRetain = DEFAULT_TRANSCRIPT_RETAIN;
+export function setEntryRetain(value) {
+    if (Number.isFinite(value) && value > 0)
+        resolvedRetain = Math.floor(value);
+}
+export function entryRetain() {
+    return resolvedRetain;
+}

package/dist/agent/headless.d.ts

@@ -7,6 +7,8 @@
 import type { AgentEvent, ModelInfo } from '@aragon-agent/core';
 import type { PreflightResult } from './controller.js';
 import type { TeamEvent } from '../team/types.js';
+import type { TodoEvent, TodoSnapshot } from '../todo/types.js';
+import { type FollowThroughMode } from '../todo/follow-through.js';
 /** The minimal controller surface headless mode needs (real or stubbed). */
 export interface HeadlessController {
     preflight(): PreflightResult;
@@ -24,11 +26,38 @@ export interface HeadlessController {
      * the `--no-team` headless path byte-identical to today's.
      */
     subscribeTeam?(listener: (event: TeamEvent) => void): () => void;
+    /**
+     * The CLI-local todo stream — OPTIONAL, for the identical reason
+     * `subscribeTeam` is (todo-plan-execution §3.12). This interface is minimal so
+     * tests can satisfy it with an object literal; making the member REQUIRED
+     * would break every existing stub for no benefit, and a controller with no
+     * store genuinely has no todo events. `runHeadless` calls it with `?.`, which
+     * keeps a `--no-todo` headless run byte-identical to today's.
+     */
+    subscribeTodos?(listener: (event: TodoEvent) => void): () => void;
+    /**
+     * The current plan — OPTIONAL, for the identical reason the two subscriptions
+     * above are (todo-plan-followthrough §3.6 rule 2). ABSENT MEANS THE
+     * CONTINUATION LOOP NEVER RUNS, which is what keeps a stubbed controller's
+     * stdout, stderr and exit code byte-identical to today's (AC-23).
+     */
+    getTodoSnapshot?(): TodoSnapshot | null;
 }
 export interface HeadlessOptions {
     quiet?: boolean;
     stdout?: NodeJS.WritableStream;
     stderr?: NodeJS.WritableStream;
+    /**
+     * Follow-through mode for `-p` (todo-plan-followthrough §3.6). Defaults to
+     * `'notify'`, so an omitted option behaves exactly as the resolved default
+     * config does.
+     *
+     * PASSED IN RATHER THAN READ OFF THE CONTROLLER, because `HeadlessController`
+     * is deliberately the minimal surface a test can satisfy with an object
+     * literal; `runOneShot` holds the real `AgentController` and reads
+     * `getTodoConfig().followThrough` there.
+     */
+    followThrough?: FollowThroughMode;
 }
 /** Run a single prompt headlessly and resolve with the process exit code. */
 export declare function runHeadless(controller: HeadlessController, prompt: string, options?: HeadlessOptions): Promise<number>;

package/dist/agent/headless.js

@@ -6,6 +6,7 @@
  */
 import { formatCost, formatTokens, formatDuration, computeCost } from './usage.js';
 import { formatStreamError } from './reducer.js';
+import { advanceBudget, decideFollowThrough, emptyBudget, } from '../todo/follow-through.js';
 /** Run a single prompt headlessly and resolve with the process exit code. */
 export async function runHeadless(controller, prompt, options = {}) {
     const out = options.stdout ?? process.stdout;
@@ -96,12 +97,96 @@ export async function runHeadless(controller, prompt, options = {}) {
                 `${event.outcome.aborted ? ' (aborted)' : ''}\n`);
         }
     });
+    // ONE LINE PER TRANSITION OF THE ACTIVE ITEM, not one per call: a model that
+    // rewrites the list without moving the cursor produces no output at all.
+    //
+    // These lines are interleaved with the generic `> todo_write (1ms)` pairs
+    // above, because that loop keys on the EVENT and not on the tool name (P2-2).
+    // `SELF_RENDERING_TOOLS` is a TRANSCRIPT concept and teaching this writer
+    // about it would put the same name in two places for a cosmetic gain on a
+    // stream that is already `--quiet`-able in full.
+    let announcedTotal = 0;
+    let lastActive = -1;
+    const unsubscribeTodos = controller.subscribeTodos?.((event) => {
+        if (quiet || event.type !== 'updated')
+            return;
+        const { total, doneCount, activeIndex, items } = event.snapshot;
+        if (total !== announcedTotal) {
+            announcedTotal = total;
+            err.write(`\n[todo] ${total} ${total === 1 ? 'step' : 'steps'} planned\n`);
+            lastActive = -1;
+        }
+        if (activeIndex < 0) {
+            if (lastActive !== -2) {
+                lastActive = -2;
+                err.write(`[todo] ${doneCount}/${total} done\n`);
+            }
+            return;
+        }
+        if (activeIndex === lastActive)
+            return;
+        lastActive = activeIndex;
+        err.write(`[todo] ${activeIndex + 1}/${total} ${items[activeIndex]?.content ?? ''}\n`);
+    });
+    // --- The bounded continuation loop (todo-plan-followthrough §3.6). --------
+    //
+    // THE THREE `unsubscribe` CALLS STAY OUTSIDE IT (rule 4). The loop wraps the
+    // whole `try/finally` rather than sitting inside it, because unsubscribing per
+    // iteration would silently cost iteration 2 onwards its `[todo]` progress
+    // lines, its team usage accounting and — worst — the `agent_end` handler that
+    // computes `errored`, so a failing second iteration would exit 0.
+    //
+    // Deciding the moment `prompt()` resolves is safe: `agent.prompt()` awaits
+    // `runLoopWithLifecycle()`, whose `finally` emits `agent_end` BEFORE resolving,
+    // and `emit` is synchronous — so `errored` and `sawTurnEnd` are already final.
+    const followThrough = options.followThrough ?? 'notify';
+    let budget = emptyBudget();
+    let wasAutoContinuation = false;
     try {
-        await controller.prompt(prompt);
+        let message = prompt;
+        for (;;) {
+            // PER-ITERATION RESET (rule 1). `sawTurnEnd` is the silent-failure
+            // detector; left sticky, a swallowed throw on iteration 2 is invisible
+            // because iteration 1 set the flag. `errored` is deliberately NOT reset —
+            // once a run has errored the exit code is 1 and the loop must stop.
+            sawTurnEnd = false;
+            await controller.prompt(message);
+            const snapshot = controller.getTodoSnapshot?.() ?? null;
+            budget = advanceBudget(budget, snapshot, wasAutoContinuation);
+            wasAutoContinuation = false;
+            const decision = decideFollowThrough({
+                mode: followThrough,
+                snapshot,
+                // `aborted` is STRUCTURALLY false here (C-2): `-p` has no Esc and
+                // installs no signal handler that marks one, so there is nothing to
+                // derive and nothing to plumb. An errored run takes the `notify` branch
+                // below and ends the loop, which is what keeps exit code 1 reachable.
+                runEnd: { aborted: false, errored },
+                budget,
+                interactive: false,
+            });
+            if (decision.kind === 'none')
+                break;
+            if (decision.kind === 'notify') {
+                if (!quiet)
+                    err.write(`\n[todo] ${decision.text}\n`);
+                break;
+            }
+            // CHARGED BEFORE THE RE-PROMPT, and this line is the whole of the headless
+            // cap (P1-2 / I-5 / AC-37). The TUI charges `used` in its grace-timer
+            // callback; headless has no timer, so without this `maxAutoContinuesPerList`
+            // would never bind in the one environment with no human to press Esc.
+            budget = { ...budget, used: budget.used + 1 };
+            wasAutoContinuation = true;
+            if (!quiet)
+                err.write(`\n[todo] ${decision.notice}\n`);
+            message = decision.message;
+        }
     }
     finally {
         unsubscribe();
         unsubscribeTeam?.();
+        unsubscribeTodos?.();
     }
     // Ensure a trailing newline so piped output is well-formed.
     if (wroteText)