@aragon-agent/cli 0.5.4 → 0.5.6

package/dist/todo/normalize.js

@@ -0,0 +1,117 @@
+/**
+ * `normalizeTodos` — pure repair of whatever arrived in a `todo_write` call, or
+ * of whatever a session file happened to contain (todo-plan-execution §3.4).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
+ *
+ * MODELLED ON `team/normalize.ts`, INCLUDING THE REASON IT EXISTS. The JSON
+ * Schema declares SHAPE, not POLICY (C-8): `ajv` is an OPTIONAL dependency of
+ * `@aragon-agent/core`, so a schema-level `maxItems` / `enum` would REJECT a
+ * payload where it is installed and let the identical payload through to here
+ * where it is not. One design, two behaviours, selected by whether an optional
+ * install step succeeded. Every bound therefore lives in the tool's
+ * `description` (which is what the model reads) and is enforced here (which is
+ * deterministic and unit-tested).
+ *
+ * REPAIR, NEVER REJECT. Zero survivors is the caller's single hard failure.
+ * NEVER THROWS.
+ *
+ * THE LAST TWO RULES ARE THE FEATURE, not defensive tidying. "Exactly one item
+ * at a time" (R-b) is made a property of the STORED STATE rather than a request
+ * in a prompt, which is what lets the panel render an unconditional "current
+ * step" with no null branch and lets a unit test prove the property instead of
+ * an operator inferring it from a transcript.
+ */
+import { TODO_LIMITS } from './limits.js';
+const STATUSES = new Set([
+    'pending',
+    'in_progress',
+    'completed',
+]);
+/**
+ * Collapse whitespace and clamp.
+ *
+ * SANITIZED AT STORE RATHER THAN AT RENDER, which is the argument
+ * `sanitizeActivity` records one subsystem over: a newline inside a rail row
+ * would break the layout, and doing it here means the transcript card, the
+ * headless writer and `/todo status` all inherit the guarantee for free.
+ */
+function clean(value, maxChars) {
+    if (typeof value !== 'string')
+        return '';
+    const collapsed = value.replace(/\s+/g, ' ').trim();
+    return collapsed.length > maxChars ? collapsed.slice(0, maxChars) : collapsed;
+}
+export function normalizeTodos(raw, max) {
+    if (!Array.isArray(raw))
+        return { items: [], requested: 0, repairs: [] };
+    const requested = raw.length;
+    const repairs = [];
+    const kept = [];
+    let dropped = 0;
+    for (const entry of raw) {
+        if (!entry || typeof entry !== 'object') {
+            dropped += 1;
+            continue;
+        }
+        const src = entry;
+        const content = clean(src.content, TODO_LIMITS.contentChars);
+        // The one field with no repair: an item with nothing to say is not an item.
+        if (content.length === 0) {
+            dropped += 1;
+            continue;
+        }
+        const activeForm = clean(src.activeForm, TODO_LIMITS.activeFormChars) || content;
+        const status = (typeof src.status === 'string' && STATUSES.has(src.status) ? src.status : 'pending');
+        kept.push({ content, activeForm, status });
+    }
+    if (dropped > 0) {
+        repairs.push(`${dropped} ${dropped === 1 ? 'item was' : 'items were'} dropped: each needs a non-empty content string.`);
+    }
+    // DROP FIRST, CAP SECOND — the ordering `normalizeSubagentSpecs` records:
+    // capping first would let a blank entry consume a slot the model meant for
+    // real work, and nothing would say so.
+    const ceiling = Math.max(1, Math.min(Math.floor(max) || 1, TODO_LIMITS.maxItems));
+    const items = kept.slice(0, ceiling);
+    if (kept.length > ceiling) {
+        // COUNTED OFF `kept`, NOT `requested`, because the two differ exactly when
+        // the payload ALSO had unusable entries — and those were already reported
+        // by the note above. `requested - ceiling` would charge the cap for them a
+        // second time and, worse, name a number that is not true of any suffix:
+        // "the last 5 were dropped" when the cap took 3 from the end and two blanks
+        // came from the middle. The model reads these notes to correct itself, so
+        // the arithmetic has to describe what actually happened.
+        repairs.push(`${requested} items were sent; the last ${kept.length - ceiling} were dropped (maximum ${ceiling}).`);
+    }
+    repairExactlyOneActive(items, repairs);
+    return { items, requested, repairs };
+}
+/**
+ * Enforce invariant I-3: exactly one item is `in_progress` whenever at least one
+ * item is not `completed`.
+ *
+ * The promotion half deliberately fires on the INITIAL all-pending write. A
+ * model that writes its plan and then starts step 1 is doing the right thing,
+ * and the panel should say so on the first frame rather than one tool call
+ * later.
+ */
+function repairExactlyOneActive(items, repairs) {
+    const active = [];
+    for (let i = 0; i < items.length; i += 1) {
+        if (items[i].status === 'in_progress')
+            active.push(i);
+    }
+    if (active.length > 1) {
+        for (const index of active.slice(1)) {
+            items[index] = { ...items[index], status: 'pending' };
+        }
+        repairs.push(`${active.length} items were marked in_progress; only the first was kept.`);
+        return;
+    }
+    if (active.length === 1)
+        return;
+    const firstUnfinished = items.findIndex((item) => item.status !== 'completed');
+    if (firstUnfinished >= 0) {
+        items[firstUnfinished] = { ...items[firstUnfinished], status: 'in_progress' };
+    }
+}

package/dist/todo/panel-rows.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `selectTodoRows` — which items the rail shows (todo-plan-execution §3.10).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
+ *
+ * PURE WINDOWING, NO OFFSET STATE ANYWHERE (non-goal 2 / R-10). Ink has no
+ * absolute positioning and this codebase already owns one hand-rolled viewport
+ * (`ScrollViewport`) whose invariants took a whole spec to pin down; a second
+ * scrollable region with its own offset, its own intent nonce and its own wheel
+ * band would be the largest source of new bugs in this feature by a wide margin.
+ * The rail therefore never scrolls - it windows around the item being worked on
+ * and reports what is off each end.
+ *
+ * THE DIRECT DESCENDANT OF `selectPanelRows`'s F-2 LESSON: the team panel
+ * originally took the first five children by ARRAY INDEX, which showed the five
+ * that finished FIRST and hid everything still working. Here the equivalent
+ * mistake is `slice(0, maxRows)`, which on a 20-item plan shows steps 1-8 - all
+ * completed - and hides the one the user is actually watching.
+ */
+import type { TodoItem } from './types.js';
+export interface TodoRowSelection {
+    visible: {
+        item: TodoItem;
+        index: number;
+    }[];
+    hiddenAbove: number;
+    hiddenBelow: number;
+}
+/**
+ * The row the window is built around: the item in progress, or the first
+ * unfinished one, or the last item when everything is done.
+ *
+ * `normalizeTodos` guarantees an `in_progress` item whenever one is not
+ * completed (I-3), so the second branch is a belt-and-braces path for a list
+ * this module was handed without going through the store.
+ */
+export declare function todoAnchorIndex(items: TodoItem[]): number;
+/**
+ * @param maxRows Rows available for the item rows AND the two overflow markers
+ *                together. `todoRailRows()` upstream is what makes this number
+ *                honest while a team dispatch is live (I-10 / P1-3).
+ *
+ * THE ANCHOR IS ALWAYS VISIBLE, and that beats the row bound when the two
+ * conflict. They can only conflict below `maxRows` 3 with overflow on BOTH
+ * sides — one item plus two markers is three rows — where this returns the
+ * anchor and lets the caller's `overflow="hidden"` clip a marker. Hiding the
+ * one row the user is watching in order to keep a `+N above` would be the wrong
+ * trade. `TODO_LIMITS.panelMinRows` (6) gates the mount and leaves `TodoPanel`
+ * at least 4 item rows, so the case is unreachable from the rail; a future
+ * caller with a smaller budget should read this paragraph before assuming
+ * otherwise.
+ */
+export declare function selectTodoRows(items: TodoItem[], maxRows: number): TodoRowSelection;

package/dist/todo/panel-rows.js

@@ -0,0 +1,103 @@
+/**
+ * `selectTodoRows` — which items the rail shows (todo-plan-execution §3.10).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
+ *
+ * PURE WINDOWING, NO OFFSET STATE ANYWHERE (non-goal 2 / R-10). Ink has no
+ * absolute positioning and this codebase already owns one hand-rolled viewport
+ * (`ScrollViewport`) whose invariants took a whole spec to pin down; a second
+ * scrollable region with its own offset, its own intent nonce and its own wheel
+ * band would be the largest source of new bugs in this feature by a wide margin.
+ * The rail therefore never scrolls - it windows around the item being worked on
+ * and reports what is off each end.
+ *
+ * THE DIRECT DESCENDANT OF `selectPanelRows`'s F-2 LESSON: the team panel
+ * originally took the first five children by ARRAY INDEX, which showed the five
+ * that finished FIRST and hid everything still working. Here the equivalent
+ * mistake is `slice(0, maxRows)`, which on a 20-item plan shows steps 1-8 - all
+ * completed - and hides the one the user is actually watching.
+ */
+/**
+ * The row the window is built around: the item in progress, or the first
+ * unfinished one, or the last item when everything is done.
+ *
+ * `normalizeTodos` guarantees an `in_progress` item whenever one is not
+ * completed (I-3), so the second branch is a belt-and-braces path for a list
+ * this module was handed without going through the store.
+ */
+export function todoAnchorIndex(items) {
+    if (items.length === 0)
+        return 0;
+    const active = items.findIndex((item) => item.status === 'in_progress');
+    if (active >= 0)
+        return active;
+    const unfinished = items.findIndex((item) => item.status !== 'completed');
+    if (unfinished >= 0)
+        return unfinished;
+    return items.length - 1;
+}
+/**
+ * How much of the window sits ABOVE the anchor.
+ *
+ * A QUARTER, and the asymmetry is the point: completed context above the anchor
+ * is sacrificed before upcoming work below it, because the user's question is
+ * "what is next", not "what is behind me".
+ */
+const ABOVE_SHARE = 0.25;
+function windowFor(count, anchor, slots) {
+    if (slots >= count)
+        return { start: 0, end: count };
+    const above = Math.min(anchor, Math.max(0, Math.floor((slots - 1) * ABOVE_SHARE)));
+    let start = anchor - above;
+    let end = start + slots;
+    if (end > count) {
+        end = count;
+        start = Math.max(0, end - slots);
+    }
+    return { start, end };
+}
+/**
+ * @param maxRows Rows available for the item rows AND the two overflow markers
+ *                together. `todoRailRows()` upstream is what makes this number
+ *                honest while a team dispatch is live (I-10 / P1-3).
+ *
+ * THE ANCHOR IS ALWAYS VISIBLE, and that beats the row bound when the two
+ * conflict. They can only conflict below `maxRows` 3 with overflow on BOTH
+ * sides — one item plus two markers is three rows — where this returns the
+ * anchor and lets the caller's `overflow="hidden"` clip a marker. Hiding the
+ * one row the user is watching in order to keep a `+N above` would be the wrong
+ * trade. `TODO_LIMITS.panelMinRows` (6) gates the mount and leaves `TodoPanel`
+ * at least 4 item rows, so the case is unreachable from the rail; a future
+ * caller with a smaller budget should read this paragraph before assuming
+ * otherwise.
+ */
+export function selectTodoRows(items, maxRows) {
+    const count = items.length;
+    const anchor = todoAnchorIndex(items);
+    if (count === 0)
+        return { visible: [], hiddenAbove: 0, hiddenBelow: 0 };
+    if (maxRows <= 0) {
+        return { visible: [], hiddenAbove: anchor, hiddenBelow: count - 1 - anchor };
+    }
+    // The marker rows and the window depend on each other: a `+N above` row costs
+    // a slot, which can shrink the window, which can create a `+N below`. Two
+    // passes reach the fixpoint for every input this can be handed; the loop bound
+    // is a backstop, not a live case.
+    let reserved = 0;
+    let start = 0;
+    let end = count;
+    for (let pass = 0; pass < 3; pass += 1) {
+        const slots = Math.max(1, maxRows - reserved);
+        const win = windowFor(count, anchor, slots);
+        start = win.start;
+        end = win.end;
+        const need = (start > 0 ? 1 : 0) + (end < count ? 1 : 0);
+        if (need === reserved)
+            break;
+        reserved = need;
+    }
+    const visible = [];
+    for (let i = start; i < end; i += 1)
+        visible.push({ item: items[i], index: i });
+    return { visible, hiddenAbove: start, hiddenBelow: count - end };
+}

package/dist/todo/prompt.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The `<todo_planning>` system-prompt block (todo-plan-execution §3.7).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope, and this string
+ * also reaches a model that may be running in a `cmd.exe` terminal.
+ *
+ * SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what preserves C-10:
+ * with `todo.enabled: false` the prompt is BYTE-IDENTICAL to the pre-todo output
+ * for a fixed tool array. An unconditional guidance line anywhere here would
+ * quietly break `--no-todo`, `--no-team`, `--no-skills` and the plan-mode
+ * snapshot all at once.
+ *
+ * THE BLOCK'S THRESHOLD (3+ steps) IS STRICTER THAN THE STRUCTURAL GUARD
+ * (`minFreshItems`, 2). A backstop looser than the guidance never argues with a
+ * judgement call the model made on purpose: a 2-step list for two genuinely
+ * separate deliverables is fine, and the prompt simply does not encourage it.
+ *
+ * `TODO_BLOCK_VERSION` exists so a change to this wording is greppable from a
+ * behaviour report - INCLUDING a change to either `{{VISIBILITY}}` variant,
+ * which is part of the block.
+ */
+import { TODO_BLOCK_VERSION } from './limits.js';
+export { TODO_BLOCK_VERSION };
+export interface TodoBlockParams {
+    /**
+     * Whether this session can actually render the rail.
+     *
+     * FOUR SUPPORTED PATHS HAVE THE TOOL AND NO PANEL — `-p` (§3.12), inline mode
+     * (non-goal 4), `--no-todo-panel` (§4.3), and a terminal under 80 columns or 6
+     * viewport rows (§6.4) — and in the first three the answer is fixed for the
+     * whole session, before the prompt is composed. Telling the model about a
+     * panel the user does not have is the same error `composeSystemPrompt` already
+     * guards against for team mode with its TWO flags (P1-6 / D-24).
+     *
+     * Dropping the block instead would be wrong: the planning discipline is worth
+     * having without the column, which is precisely why `enabled` and `panel` are
+     * separate config keys, and a screen-reader user is the case that argument was
+     * written for.
+     */
+    panelVisible: boolean;
+}
+/**
+ * BOUNDED AT 1600 CHARACTERS, and the number is asserted in `todo-tool.test.ts`.
+ *
+ * The block is paid for on EVERY turn of every todo-enabled session, so anything
+ * that does not change a planning decision does not belong in it (the discipline
+ * `buildTeamBlock` records at 1200 for a shorter block). This one lands at ~1430
+ * as designed — three bullet lists plus the `{{VISIBILITY}}` sentence — and was
+ * NOT trimmed to reach a borrowed budget, because every line in it changes a
+ * planning decision, which is the test that actually applies. The bound exists
+ * so that adding a paragraph stays a decision someone makes on purpose. See
+ * spec §15 IF-3.
+ */
+export declare function buildTodoBlock(params: TodoBlockParams): string;

package/dist/todo/prompt.js

@@ -0,0 +1,76 @@
+/**
+ * The `<todo_planning>` system-prompt block (todo-plan-execution §3.7).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope, and this string
+ * also reaches a model that may be running in a `cmd.exe` terminal.
+ *
+ * SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what preserves C-10:
+ * with `todo.enabled: false` the prompt is BYTE-IDENTICAL to the pre-todo output
+ * for a fixed tool array. An unconditional guidance line anywhere here would
+ * quietly break `--no-todo`, `--no-team`, `--no-skills` and the plan-mode
+ * snapshot all at once.
+ *
+ * THE BLOCK'S THRESHOLD (3+ steps) IS STRICTER THAN THE STRUCTURAL GUARD
+ * (`minFreshItems`, 2). A backstop looser than the guidance never argues with a
+ * judgement call the model made on purpose: a 2-step list for two genuinely
+ * separate deliverables is fine, and the prompt simply does not encourage it.
+ *
+ * `TODO_BLOCK_VERSION` exists so a change to this wording is greppable from a
+ * behaviour report - INCLUDING a change to either `{{VISIBILITY}}` variant,
+ * which is part of the block.
+ */
+import { TODO_BLOCK_VERSION } from './limits.js';
+export { TODO_BLOCK_VERSION };
+/**
+ * The ONLY sentence in the block that mentions a display at all. Everything else
+ * talks about "the list", which is what makes "the two variants differ in
+ * exactly one sentence" checkable rather than approximate (AC-42).
+ */
+const VISIBLE = 'The user sees this list in a panel beside the conversation, so it is the only place ' +
+    'they can watch a long task progress.';
+const NOT_VISIBLE = 'The user cannot see this list in this session, but keeping it is still how you stay ' +
+    'on one step at a time and report what is left.';
+/**
+ * BOUNDED AT 1600 CHARACTERS, and the number is asserted in `todo-tool.test.ts`.
+ *
+ * The block is paid for on EVERY turn of every todo-enabled session, so anything
+ * that does not change a planning decision does not belong in it (the discipline
+ * `buildTeamBlock` records at 1200 for a shorter block). This one lands at ~1430
+ * as designed — three bullet lists plus the `{{VISIBILITY}}` sentence — and was
+ * NOT trimmed to reach a borrowed budget, because every line in it changes a
+ * planning decision, which is the test that actually applies. The bound exists
+ * so that adding a paragraph stays a decision someone makes on purpose. See
+ * spec §15 IF-3.
+ */
+export function buildTodoBlock(params) {
+    return [
+        '<todo_planning>',
+        'For work that takes three or more distinct steps, keep a visible plan with the',
+        'todo_write tool.',
+        params.panelVisible ? VISIBLE : NOT_VISIBLE,
+        '',
+        'Use it when:',
+        '- the request has three or more steps that must happen in order;',
+        '- the user gave you several things to do in one message;',
+        '- you are part-way through a long task and the user asks what is left.',
+        '',
+        'Do NOT use it for:',
+        '- anything you can finish in one or two steps - just do it and say what you did;',
+        '- a question, an explanation, or a search with no work attached;',
+        '- restating a step you are already in the middle of.',
+        '',
+        'How to use it:',
+        '- Send the COMPLETE list every time. The tool replaces the whole list; it has no',
+        '  add or update operation.',
+        '- Exactly one item is in_progress at a time. Mark an item completed the moment',
+        '  it is done and mark the next one in_progress in the SAME call.',
+        '- Do not batch. Finishing three steps and reporting them together hides where you',
+        '  are RIGHT NOW, which is the whole point of keeping the list.',
+        '- Give each item a content ("Add the rail to AppShell") and an activeForm',
+        '  ("Adding the rail to AppShell"). The list shows activeForm for the step in',
+        '  progress and content for the rest.',
+        '- Only mark an item completed when it is really finished. If you hit a blocker,',
+        '  leave it in_progress, add an item describing what is blocking, and say so.',
+        '</todo_planning>',
+    ].join('\n');
+}

package/dist/todo/store.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `TodoStore` — the session's todo list plus its CLI-local event stream
+ * (todo-plan-execution §3.5).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
+ *
+ * ZERO I/O OF ANY KIND, and no timers. That is what lets `todo_write` be the one
+ * tool in the array with no error path beyond a malformed payload (R-h), and it
+ * is why `AgentController` can own this object as unconditionally as it owns
+ * `TeamRuntime`.
+ *
+ * INVARIANT I-2 — the list is a PROJECTION OF WHAT THE MODEL BELIEVES, and
+ * nothing that does not tell the model may change it. `/clear` wipes the
+ * transcript but not the conversation, so it must NOT reach this class;
+ * `/reset` clears `messages`, so it must. Every write is a FULL REPLACEMENT and
+ * every clear is a FULL REMOVAL - there is no partial update anywhere, which is
+ * what makes I-9 ("the panel is never a contradiction of the model") provable
+ * rather than argued.
+ */
+import { type NormalizeResult } from './normalize.js';
+import type { TodoClearReason, TodoEventListener, TodoSnapshot } from './types.js';
+export declare class TodoStore {
+    private readonly now;
+    private items;
+    private updatedAt;
+    /** Consecutive `beginUserTurn()` calls since the last `write()`. */
+    private turnsSinceWrite;
+    private readonly listeners;
+    /**
+     * @param now Injected clock. Defaults to `Date.now`; a test passes a counter
+     *            so `TodoSnapshot.updatedAt` is not wall time (P2-4).
+     */
+    constructor(now?: () => number);
+    /** `null` means no list, which is what leaves the rail unmounted entirely. */
+    snapshot(): TodoSnapshot | null;
+    isEmpty(): boolean;
+    /**
+     * Commit a model payload.
+     *
+     * ZERO SURVIVORS LEAVES THE PREVIOUS LIST UNTOUCHED (AC-9). A model sending
+     * nothing usable is a BUG, and destroying a working plan because of one
+     * malformed call is the worst available reaction; the caller turns the empty
+     * result into an error the model can act on. Contrast `restore()`, where an
+     * empty list is a FACT about a file and therefore means "clear".
+     */
+    write(raw: unknown): NormalizeResult;
+    /**
+     * `/resume`. Runs through `normalizeTodos` — a session file is user-editable
+     * input and gets a model payload's treatment.
+     *
+     * AN EMPTY (OR ALL-DROPPED) ARRAY CLEARS; IT DOES NOT NO-OP (P0-2 / D-22).
+     * `/resume` has just called `replaceMessages`, so the conversation the current
+     * list belonged to is gone; leaving it on screen is I-2 INVERTED — a panel
+     * that disagrees with the model, which §1.2 ranks below having no panel at
+     * all. The two entry points share normalization and differ only here, which is
+     * exactly the difference between "the model sent nothing" (a bug) and "the
+     * file has nothing" (a fact).
+     */
+    restore(items: unknown): void;
+    clear(reason: TodoClearReason): void;
+    /**
+     * The turn boundary (§3.2).
+     *
+     * Called from `AgentController.prompt()` and NOT from `steer()` — the same
+     * asymmetry, for the same reason, that `askRounds = 0` already has: a steer is
+     * a mid-turn interjection, not a new task. The stale counter inherits that
+     * asymmetry for free, which is the behaviour you want: a steer must not age
+     * out the plan it is steering.
+     *
+     * A FULLY-COMPLETED LIST IS DROPPED HERE rather than at `agent_end`. Ending
+     * the run is exactly when the user wants to see `7/7 done`; wiping it there
+     * would replace a moment of feedback with a blank column (D-6).
+     */
+    beginUserTurn(): void;
+    /**
+     * Report a refusal that never reached `write()` (§3.3 steps 1 and 2).
+     *
+     * THE COMPENSATING PATH FOR SUPPRESSING THE TOOL CARD (§3.8): `todo_write`
+     * renders its own transcript entry, so without this the one case that produces
+     * nothing visible would be the case that most needs to be visible.
+     */
+    reject(reason: string): void;
+    subscribe(listener: TodoEventListener): () => void;
+    /** Per-listener isolation: one bad subscriber cannot fail a tool call. */
+    private emit;
+}

package/dist/todo/store.js

@@ -0,0 +1,183 @@
+/**
+ * `TodoStore` — the session's todo list plus its CLI-local event stream
+ * (todo-plan-execution §3.5).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
+ *
+ * ZERO I/O OF ANY KIND, and no timers. That is what lets `todo_write` be the one
+ * tool in the array with no error path beyond a malformed payload (R-h), and it
+ * is why `AgentController` can own this object as unconditionally as it owns
+ * `TeamRuntime`.
+ *
+ * INVARIANT I-2 — the list is a PROJECTION OF WHAT THE MODEL BELIEVES, and
+ * nothing that does not tell the model may change it. `/clear` wipes the
+ * transcript but not the conversation, so it must NOT reach this class;
+ * `/reset` clears `messages`, so it must. Every write is a FULL REPLACEMENT and
+ * every clear is a FULL REMOVAL - there is no partial update anywhere, which is
+ * what makes I-9 ("the panel is never a contradiction of the model") provable
+ * rather than argued.
+ */
+import { getLogger } from '../logging/logger.js';
+import { TODO_LIMITS } from './limits.js';
+import { normalizeTodos } from './normalize.js';
+export class TodoStore {
+    now;
+    items = [];
+    updatedAt = 0;
+    /** Consecutive `beginUserTurn()` calls since the last `write()`. */
+    turnsSinceWrite = 0;
+    listeners = new Set();
+    /**
+     * @param now Injected clock. Defaults to `Date.now`; a test passes a counter
+     *            so `TodoSnapshot.updatedAt` is not wall time (P2-4).
+     */
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** `null` means no list, which is what leaves the rail unmounted entirely. */
+    snapshot() {
+        if (this.items.length === 0)
+            return null;
+        return {
+            items: this.items,
+            total: this.items.length,
+            doneCount: this.items.filter((item) => item.status === 'completed').length,
+            activeIndex: this.items.findIndex((item) => item.status === 'in_progress'),
+            updatedAt: this.updatedAt,
+        };
+    }
+    isEmpty() {
+        return this.items.length === 0;
+    }
+    /**
+     * Commit a model payload.
+     *
+     * ZERO SURVIVORS LEAVES THE PREVIOUS LIST UNTOUCHED (AC-9). A model sending
+     * nothing usable is a BUG, and destroying a working plan because of one
+     * malformed call is the worst available reaction; the caller turns the empty
+     * result into an error the model can act on. Contrast `restore()`, where an
+     * empty list is a FACT about a file and therefore means "clear".
+     */
+    write(raw) {
+        const result = normalizeTodos(raw, TODO_LIMITS.maxItems);
+        if (result.items.length === 0) {
+            this.emit({
+                type: 'rejected',
+                reason: 'No usable todo items: each needs a non-empty content string.',
+            });
+            return result;
+        }
+        this.items = result.items;
+        this.updatedAt = this.now();
+        this.turnsSinceWrite = 0;
+        const snapshot = this.snapshot();
+        // COUNTS ONLY, NEVER ITEM TEXT (D-19 / §3.14). It is user-task content, it
+        // is unbounded in aggregate, and the counts answer every question a log can
+        // answer here: did the list move, and was the payload repaired?
+        //
+        // SCOPE `'agent'`, NOT `'todo'`. §3.14 writes `'todo'`, but `LogScope` is a
+        // CLOSED UNION in `logging/logger.ts` and that file is not in the change
+        // plan; team mode faced the identical choice and files its CLI-local events
+        // under `'agent'` (`install.ts::attachTeamEvents`). Following that precedent
+        // keeps the diff focused and keeps a support reader filtering on one scope
+        // for everything a turn did. See spec §15 IF-1.
+        getLogger().debug('agent', 'todo_write', {
+            total: snapshot?.total ?? 0,
+            done: snapshot?.doneCount ?? 0,
+            active: snapshot?.activeIndex ?? -1,
+            repairs: result.repairs.length,
+        });
+        if (snapshot)
+            this.emit({ type: 'updated', snapshot });
+        return result;
+    }
+    /**
+     * `/resume`. Runs through `normalizeTodos` — a session file is user-editable
+     * input and gets a model payload's treatment.
+     *
+     * AN EMPTY (OR ALL-DROPPED) ARRAY CLEARS; IT DOES NOT NO-OP (P0-2 / D-22).
+     * `/resume` has just called `replaceMessages`, so the conversation the current
+     * list belonged to is gone; leaving it on screen is I-2 INVERTED — a panel
+     * that disagrees with the model, which §1.2 ranks below having no panel at
+     * all. The two entry points share normalization and differ only here, which is
+     * exactly the difference between "the model sent nothing" (a bug) and "the
+     * file has nothing" (a fact).
+     */
+    restore(items) {
+        const result = normalizeTodos(items, TODO_LIMITS.maxItems);
+        if (result.items.length === 0) {
+            this.clear('reset');
+            return;
+        }
+        this.items = result.items;
+        this.updatedAt = this.now();
+        this.turnsSinceWrite = 0;
+        const snapshot = this.snapshot();
+        if (snapshot)
+            this.emit({ type: 'updated', snapshot });
+    }
+    clear(reason) {
+        this.items = [];
+        this.updatedAt = this.now();
+        this.turnsSinceWrite = 0;
+        this.emit({ type: 'cleared', reason });
+    }
+    /**
+     * The turn boundary (§3.2).
+     *
+     * Called from `AgentController.prompt()` and NOT from `steer()` — the same
+     * asymmetry, for the same reason, that `askRounds = 0` already has: a steer is
+     * a mid-turn interjection, not a new task. The stale counter inherits that
+     * asymmetry for free, which is the behaviour you want: a steer must not age
+     * out the plan it is steering.
+     *
+     * A FULLY-COMPLETED LIST IS DROPPED HERE rather than at `agent_end`. Ending
+     * the run is exactly when the user wants to see `7/7 done`; wiping it there
+     * would replace a moment of feedback with a blank column (D-6).
+     */
+    beginUserTurn() {
+        if (this.items.length === 0)
+            return;
+        if (this.items.every((item) => item.status === 'completed')) {
+            this.clear('turn');
+            return;
+        }
+        // ...but a partial list is not immortal (P1-7 / D-21). Without a bound, a
+        // plan abandoned mid-way holds a fifth of the terminal for the rest of the
+        // session, showing work nobody is doing - the "furniture when idle" R-g
+        // rules out. Self-healing, because the model's next write is a full
+        // replacement: the panel is ABSENT while the model still knows the plan,
+        // which is the safe direction (I-9).
+        this.turnsSinceWrite += 1;
+        if (this.turnsSinceWrite > TODO_LIMITS.staleTurns)
+            this.clear('stale');
+    }
+    /**
+     * Report a refusal that never reached `write()` (§3.3 steps 1 and 2).
+     *
+     * THE COMPENSATING PATH FOR SUPPRESSING THE TOOL CARD (§3.8): `todo_write`
+     * renders its own transcript entry, so without this the one case that produces
+     * nothing visible would be the case that most needs to be visible.
+     */
+    reject(reason) {
+        this.emit({ type: 'rejected', reason });
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Per-listener isolation: one bad subscriber cannot fail a tool call. */
+    emit(event) {
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Swallowed on purpose. A UI subscriber that throws is a UI bug, and
+                // failing the model's tool call over it would be a worse one.
+            }
+        }
+    }
+}