@aragon-agent/cli 0.5.4 → 0.5.8

package/dist/todo/follow-through.js

@@ -0,0 +1,186 @@
+/**
+ * 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 { TODO_FOLLOW_LIMITS } from './limits.js';
+/** The zero budget. A fresh App, a fresh headless run, and every cleared list. */
+export function emptyBudget() {
+    return { used: 0, noProgressStreak: 0, anchorTotal: 0, doneAtRunStart: 0 };
+}
+/**
+ * Round 1's notice, preserved BYTE FOR BYTE (AC-1).
+ *
+ * This is what makes `followThrough: 'notify'` — the default — indistinguishable
+ * from `bf6aeb1a` on the path that matters. Its singular/plural treatment
+ * ("item is" / "items are") is round 1's; the strings added by this round use
+ * "steps", the noun `<todo_planning>` and the rail already use.
+ */
+function legacyUnfinishedNotice(left) {
+    return (`${left} todo ${left === 1 ? 'item is' : 'items are'} unfinished. ` +
+        'Use /todo continue to pick up where this run stopped, or /todo clear to drop it.');
+}
+/** `/todo continue ...` advice, which means nothing in `-p`. */
+function advise(interactive, text) {
+    return interactive ? ` ${text}` : '';
+}
+/**
+ * The decision. EVALUATED IN THIS ORDER, AND THE ORDER IS SEMANTICS, NOT STYLE —
+ * the same sentence `decideRenderMode` carries.
+ */
+export function decideFollowThrough(input) {
+    const { mode, snapshot, runEnd, budget, interactive } = input;
+    // 1. Nothing is unfinished. `beginUserTurn` already drops a fully-completed
+    //    list at the next turn, so this branch must not pre-empt that feedback.
+    if (!snapshot || snapshot.doneCount >= snapshot.total)
+        return { kind: 'none' };
+    const left = snapshot.total - snapshot.doneCount;
+    // 2. The user asked for silence and gets silence, INCLUDING no notice.
+    if (mode === 'off')
+        return { kind: 'none' };
+    // 3. A BUG FIX, NOT A POLICY (D-5). The user pressed Esc; restating what they
+    //    interrupted is the CLI answering a question nobody asked, and offering to
+    //    continue it is worse.
+    if (runEnd.aborted)
+        return { kind: 'none' };
+    // 4. NEVER `continue`, IN ANY MODE (D-6). Auto-continuing into a model that
+    //    just failed authentication or ran out of quota is the unbounded cost loop
+    //    with none of the upside.
+    if (runEnd.errored) {
+        return {
+            kind: 'notify',
+            level: 'warn',
+            text: `${left} ${left === 1 ? 'step' : 'steps'} left; the run ended with an error.` +
+                advise(interactive, '/todo continue to retry, /todo clear to drop it.'),
+        };
+    }
+    // 5. The default. Byte-identical to round 1 in the TUI (AC-1).
+    if (mode === 'notify') {
+        return {
+            kind: 'notify',
+            level: 'info',
+            text: interactive
+                ? legacyUnfinishedNotice(left)
+                : `${left} ${left === 1 ? 'step' : 'steps'} unfinished`,
+        };
+    }
+    // 6. The ceiling that holds when everything else is wrong.
+    if (budget.used >= TODO_FOLLOW_LIMITS.maxAutoContinuesPerList) {
+        return {
+            kind: 'notify',
+            level: 'warn',
+            text: `${left} ${left === 1 ? 'step' : 'steps'} left; auto-continue has run ` +
+                `${TODO_FOLLOW_LIMITS.maxAutoContinuesPerList} times for this plan.` +
+                advise(interactive, '/todo continue to keep going.'),
+        };
+    }
+    // 7. A model that has stopped engaging with its own plan hands back after one
+    //    nudge rather than after twenty-five.
+    if (budget.noProgressStreak >= TODO_FOLLOW_LIMITS.maxNoProgressContinues) {
+        return {
+            kind: 'notify',
+            level: 'warn',
+            text: `${left} ${left === 1 ? 'step' : 'steps'} left; the last ` +
+                `${TODO_FOLLOW_LIMITS.maxNoProgressContinues} attempts completed none of them.` +
+                advise(interactive, '/todo continue to retry, or take over.'),
+        };
+    }
+    const graceMs = interactive ? TODO_FOLLOW_LIMITS.graceMs : 0;
+    return {
+        kind: 'continue',
+        message: buildContinuationMessage(snapshot),
+        graceMs,
+        // The seconds figure is DERIVED from the constant, never spelled again: a
+        // notice that promises 3 s while the timer waits 5 is worse than no notice.
+        notice: interactive
+            ? `Continuing with ${left} remaining ${left === 1 ? 'step' : 'steps'} in ` +
+                `${Math.round(graceMs / 1000)}s - Esc to stop.`
+            : `continuing (${left} ${left === 1 ? 'step' : 'steps'} left)`,
+    };
+}
+/**
+ * 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 function advanceBudget(prev, snapshot, wasAutoContinuation) {
+    // THE ONLY PATH THAT CLEARS `used` (I-8). The list is gone; so is its economy.
+    // It is not reachable by a model on its own: `TodoStore.write` leaves the
+    // previous list untouched when a payload yields zero usable items, and the
+    // other three ways a list disappears are `/todo clear`, `/reset` and
+    // `beginUserTurn` dropping a list that is either finished (nothing to
+    // continue) or stale (which the streak rule beats to the punch, §3.5).
+    if (!snapshot)
+        return emptyBudget();
+    // A RE-PLAN BUYS FORGIVENESS, NOT A FRESH WALLET (D-16). Replanning is
+    // engagement rather than looping, which is why the streak is forgiven; zeroing
+    // `used` as well is what makes the hard ceiling unreachable, because a size
+    // change every turn would reset it every turn.
+    if (snapshot.total !== prev.anchorTotal) {
+        return {
+            used: prev.used,
+            noProgressStreak: 0,
+            anchorTotal: snapshot.total,
+            doneAtRunStart: snapshot.doneCount,
+        };
+    }
+    const progressed = snapshot.doneCount > prev.doneAtRunStart;
+    // NOTE THE GUARD: a run the USER started never charges the streak, because the
+    // user asking a question mid-plan is not the model failing to advance it.
+    const noProgressStreak = progressed
+        ? 0
+        : wasAutoContinuation
+            ? prev.noProgressStreak + 1
+            : prev.noProgressStreak;
+    return {
+        used: prev.used,
+        noProgressStreak,
+        anchorTotal: prev.anchorTotal,
+        // Assigned in EVERY branch, which is what makes the next call's comparison
+        // meaningful.
+        doneAtRunStart: snapshot.doneCount,
+    };
+}
+/**
+ * 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 function buildContinuationMessage(snapshot) {
+    const remaining = snapshot.items
+        .map((item, index) => ({ item, index }))
+        .filter(({ item }) => item.status !== 'completed')
+        .map(({ item, index }) => `${index + 1}. ${item.content}`);
+    return [
+        'Continue the plan. These steps are not done yet:',
+        ...remaining,
+        'Work the next one, then call todo_write to mark it completed and the following ' +
+            'one in_progress before you move on.',
+    ].join('\n');
+}

package/dist/todo/limits.d.ts

@@ -0,0 +1,114 @@
+/**
+ * TODO_LIMITS — the single authority on every structural bound this subsystem
+ * enforces (todo-plan-execution §4.2).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), whose `inScope` regex this feature extends. A NEW TREE IS
+ * INVISIBLE TO THAT SCAN UNTIL IT IS ADDED (C-4), which is a guard rail that
+ * silently stops guarding — the same hole the team feature had to close for
+ * `team/`.
+ *
+ * TWO KINDS OF NUMBER, AND THEY ARE NOT INTERCHANGEABLE — the distinction
+ * `TEAM_LIMITS` records at length:
+ *
+ *  - Everything below is STRUCTURAL: what the panel can physically carry, what
+ *    a plan can mean, what a payload may weigh. A user has no business tuning
+ *    them, so they are constants.
+ *  - The two `todo.*` config keys (`config/schema.ts`) are POLICY: register the
+ *    tool at all, render the rail at all. They are clamped, persisted and
+ *    user-facing.
+ */
+export declare const TODO_LIMITS: {
+    /** Items one list may hold. Extras are dropped with a repair note. */
+    readonly maxItems: 20;
+    /** `TodoItem.content`, clamped (never rejected). */
+    readonly contentChars: 80;
+    /** `TodoItem.activeForm`, clamped. */
+    readonly activeFormChars: 80;
+    /**
+     * Below this, a FRESH list is refused - the structural half of R-c ("simple
+     * tasks are done directly, not planned"). Gated on an EMPTY store: shrinking
+     * an existing list to one item is legitimate, so the guard must not fire
+     * there (§3.3 step 2).
+     */
+    readonly minFreshItems: 2;
+    /** Rows the in-progress row may wrap to. Every other row truncates. */
+    readonly activeWrapRows: 2;
+    /**
+     * Below this many AVAILABLE rail rows (`todoRailRows`, NOT `viewportBudget`)
+     * the rail is not mounted at all.
+     */
+    readonly panelMinRows: 6;
+    /** Below this many terminal columns the status-bar counter degrades to `[3/7]`. */
+    readonly statusCompactCols: 100;
+    /**
+     * Below this many columns the inline strip drops its `+N done` suffix
+     * (todo-plan-followthrough §3.7 / D-19).
+     *
+     * NAMED RATHER THAN INLINED, and the reason is that it sits between two other
+     * real bounds — `statusCompactCols` (100) above and `MIN_FULLSCREEN_COLS` (40)
+     * in `frame.ts` — with nothing to tell a reader whether a bare `80` in the
+     * component was a third policy or a typo for one of them.
+     */
+    readonly stripDoneCols: 80;
+    /**
+     * Rows `todoRailRows()` subtracts while a team dispatch is live (§3.9 / P1-3).
+     *
+     * `TEAM_LIMITS.panelMaxRows` (5) + header + `+N more` + the mail line = 8, and
+     * this is deliberately the FULL worst case rather than a measurement: an
+     * over-subtraction costs one item row, an under-subtraction eats the `+N
+     * below` marker - the one row whose absence is indistinguishable from "the
+     * list is short" - and those two mistakes are not equally bad.
+     */
+    readonly railReservedRows: 8;
+    /**
+     * Consecutive user turns an UNFINISHED list survives without a `todo_write`
+     * before `beginUserTurn()` drops it (§3.2 / P1-7). Three keeps the common
+     * interruption sequence ("wait, explain X" / "and Y?" / "ok, continue")
+     * intact and returns the column on the fourth unrelated turn.
+     */
+    readonly staleTurns: 3;
+};
+/**
+ * TODO_FOLLOW_LIMITS — the economy that makes auto-continue's worst case
+ * ARITHMETIC rather than trust (todo-plan-followthrough §8.1).
+ *
+ * STRUCTURAL, NOT POLICY, exactly like `TODO_LIMITS` above: `todo.followThrough`
+ * is the user-facing knob and it decides only WHETHER the loop runs. How far it
+ * may run is not something a user has any way to reason about, and a setting
+ * here would be a setting whose wrong value is a bill.
+ */
+export declare const TODO_FOLLOW_LIMITS: {
+    /**
+     * Auto-continuations for ONE LIST LINEAGE, however productive, and NOT reset
+     * by a re-plan (P0-1 / D-16). See `FollowThroughBudget.used`.
+     *
+     * DELIBERATELY GREATER THAN `TODO_LIMITS.maxItems` (20): a fully productive
+     * 20-step plan must never be cut off by the total cap, so the cap only ever
+     * binds on pathology. Lowering it below `maxItems` would make the ceiling fire
+     * on success, which is the one thing it must not do.
+     */
+    readonly maxAutoContinuesPerList: 25;
+    /**
+     * Consecutive auto-continuations that completed nothing before control goes
+     * back to the human. Two, so a model that merely forgot to tick an item gets
+     * exactly one free nudge and a model that has stopped engaging with its own
+     * plan does not get a third.
+     */
+    readonly maxNoProgressContinues: 2;
+    /**
+     * Interactive grace window before an armed continuation fires. The notice text
+     * derives its "in Ns" from THIS value rather than spelling 3 again, so the two
+     * cannot disagree.
+     */
+    readonly graceMs: 3000;
+};
+/**
+ * Bumped whenever the wording of the `<todo_planning>` block changes - INCLUDING
+ * either `{{VISIBILITY}}` variant, which is part of the block - so a behaviour
+ * report can be tied to a block revision with one grep.
+ *
+ * NOT BUMPED BY follow-through (D-3): the model is never told about the
+ * mechanism, so the block is byte-identical to `bf6aeb1a`.
+ */
+export declare const TODO_BLOCK_VERSION = "v1-2026-07";

package/dist/todo/limits.js

@@ -0,0 +1,114 @@
+/**
+ * TODO_LIMITS — the single authority on every structural bound this subsystem
+ * enforces (todo-plan-execution §4.2).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), whose `inScope` regex this feature extends. A NEW TREE IS
+ * INVISIBLE TO THAT SCAN UNTIL IT IS ADDED (C-4), which is a guard rail that
+ * silently stops guarding — the same hole the team feature had to close for
+ * `team/`.
+ *
+ * TWO KINDS OF NUMBER, AND THEY ARE NOT INTERCHANGEABLE — the distinction
+ * `TEAM_LIMITS` records at length:
+ *
+ *  - Everything below is STRUCTURAL: what the panel can physically carry, what
+ *    a plan can mean, what a payload may weigh. A user has no business tuning
+ *    them, so they are constants.
+ *  - The two `todo.*` config keys (`config/schema.ts`) are POLICY: register the
+ *    tool at all, render the rail at all. They are clamped, persisted and
+ *    user-facing.
+ */
+export const TODO_LIMITS = {
+    /** Items one list may hold. Extras are dropped with a repair note. */
+    maxItems: 20,
+    /** `TodoItem.content`, clamped (never rejected). */
+    contentChars: 80,
+    /** `TodoItem.activeForm`, clamped. */
+    activeFormChars: 80,
+    /**
+     * Below this, a FRESH list is refused - the structural half of R-c ("simple
+     * tasks are done directly, not planned"). Gated on an EMPTY store: shrinking
+     * an existing list to one item is legitimate, so the guard must not fire
+     * there (§3.3 step 2).
+     */
+    minFreshItems: 2,
+    /** Rows the in-progress row may wrap to. Every other row truncates. */
+    activeWrapRows: 2,
+    /**
+     * Below this many AVAILABLE rail rows (`todoRailRows`, NOT `viewportBudget`)
+     * the rail is not mounted at all.
+     */
+    panelMinRows: 6,
+    /** Below this many terminal columns the status-bar counter degrades to `[3/7]`. */
+    statusCompactCols: 100,
+    /**
+     * Below this many columns the inline strip drops its `+N done` suffix
+     * (todo-plan-followthrough §3.7 / D-19).
+     *
+     * NAMED RATHER THAN INLINED, and the reason is that it sits between two other
+     * real bounds — `statusCompactCols` (100) above and `MIN_FULLSCREEN_COLS` (40)
+     * in `frame.ts` — with nothing to tell a reader whether a bare `80` in the
+     * component was a third policy or a typo for one of them.
+     */
+    stripDoneCols: 80,
+    /**
+     * Rows `todoRailRows()` subtracts while a team dispatch is live (§3.9 / P1-3).
+     *
+     * `TEAM_LIMITS.panelMaxRows` (5) + header + `+N more` + the mail line = 8, and
+     * this is deliberately the FULL worst case rather than a measurement: an
+     * over-subtraction costs one item row, an under-subtraction eats the `+N
+     * below` marker - the one row whose absence is indistinguishable from "the
+     * list is short" - and those two mistakes are not equally bad.
+     */
+    railReservedRows: 8,
+    /**
+     * Consecutive user turns an UNFINISHED list survives without a `todo_write`
+     * before `beginUserTurn()` drops it (§3.2 / P1-7). Three keeps the common
+     * interruption sequence ("wait, explain X" / "and Y?" / "ok, continue")
+     * intact and returns the column on the fourth unrelated turn.
+     */
+    staleTurns: 3,
+};
+/**
+ * TODO_FOLLOW_LIMITS — the economy that makes auto-continue's worst case
+ * ARITHMETIC rather than trust (todo-plan-followthrough §8.1).
+ *
+ * STRUCTURAL, NOT POLICY, exactly like `TODO_LIMITS` above: `todo.followThrough`
+ * is the user-facing knob and it decides only WHETHER the loop runs. How far it
+ * may run is not something a user has any way to reason about, and a setting
+ * here would be a setting whose wrong value is a bill.
+ */
+export const TODO_FOLLOW_LIMITS = {
+    /**
+     * Auto-continuations for ONE LIST LINEAGE, however productive, and NOT reset
+     * by a re-plan (P0-1 / D-16). See `FollowThroughBudget.used`.
+     *
+     * DELIBERATELY GREATER THAN `TODO_LIMITS.maxItems` (20): a fully productive
+     * 20-step plan must never be cut off by the total cap, so the cap only ever
+     * binds on pathology. Lowering it below `maxItems` would make the ceiling fire
+     * on success, which is the one thing it must not do.
+     */
+    maxAutoContinuesPerList: 25,
+    /**
+     * Consecutive auto-continuations that completed nothing before control goes
+     * back to the human. Two, so a model that merely forgot to tick an item gets
+     * exactly one free nudge and a model that has stopped engaging with its own
+     * plan does not get a third.
+     */
+    maxNoProgressContinues: 2,
+    /**
+     * Interactive grace window before an armed continuation fires. The notice text
+     * derives its "in Ns" from THIS value rather than spelling 3 again, so the two
+     * cannot disagree.
+     */
+    graceMs: 3000,
+};
+/**
+ * Bumped whenever the wording of the `<todo_planning>` block changes - INCLUDING
+ * either `{{VISIBILITY}}` variant, which is part of the block - so a behaviour
+ * report can be tied to a block revision with one grep.
+ *
+ * NOT BUMPED BY follow-through (D-3): the model is never told about the
+ * mechanism, so the block is byte-identical to `bf6aeb1a`.
+ */
+export const TODO_BLOCK_VERSION = 'v1-2026-07';

package/dist/todo/normalize.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `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 type { TodoItem } from './types.js';
+export interface NormalizeResult {
+    items: TodoItem[];
+    /** How many entries the payload contained BEFORE dropping and capping. */
+    requested: number;
+    /** Human-readable repair notes, already bounded. Empty when nothing was wrong. */
+    repairs: string[];
+}
+export declare function normalizeTodos(raw: unknown, max: number): NormalizeResult;

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;