@aragon-agent/cli 0.6.35 → 0.6.36

package/dist/team/settled.js

@@ -0,0 +1,87 @@
+/**
+ * The two stripping lists, and the two functions that apply them
+ * (tui-subagent-panel §4.5.4).
+ *
+ * WHY TWO LISTS AND NOT ONE. The fields fall into three groups, not two:
+ *
+ *  - `activity` / `activityArgs` / `retry` / `timeline` have NO reader on a settled run
+ *    (the card and the report read `summary` / `error` / the counters), so they are
+ *    removed at the dispatch exit as well;
+ *  - `lastIntervention` MUST survive onto the settled run -
+ *    `overseer-runtime-supervision.test.ts` asserts it and the supervision report reads
+ *    it - but `team/types.ts` marks it TRANSIENT / never persisted, and it is not part
+ *    of `session/validate-session.ts`'s persisted shape either. So it is stripped at
+ *    the SAVE boundary only;
+ *  - `retryable`, `truncated`, `compactions`, `lastTool`, `summary`, `error` are facts
+ *    that still mean something after the dispatch, and are in NEITHER list. Deleting
+ *    `retryable` in passing would be the kind of "cleanup" that loses a contract.
+ *
+ * WHY TWO PLACES AND NOT ONE (§4.5.4 / RV-P0-1). `dispatch()`'s exit only cleans the
+ * FINAL outcome. Everything written to disk goes through `saveSession`, and during a
+ * dispatch the live `team` entry holds the LIVE runs - `teamUpdate` writes them
+ * straight into `view.entries`. So a `/save`, a checkpoint or the exit flush issued
+ * mid-dispatch would carry the timeline into `<id>.json` even with the dispatch exit
+ * perfectly clean. The save boundary is therefore the second, independent gate, and it
+ * is the one that protects all three write paths (`R-12`).
+ *
+ * WHY THIS IS NOT IN `runtime.ts` (RV-P1-4): that file is already past the 1,000-line
+ * ceiling `CLAUDE.md` sets and has no dated exception in `.claude-index/config.md`, so
+ * new logic goes here and `runtime.ts` keeps one call.
+ *
+ * ASCII ONLY: `src/team/**` is inside `glyphs.test.ts`'s static scan.
+ */
+/** Fields with no reader on a settled run. Stripped at the dispatch exit. */
+export const SETTLE_STRIP_FIELDS = ['activity', 'activityArgs', 'retry', 'timeline'];
+/**
+ * Fields that may never reach a file. `lastIntervention` joins the four above because
+ * it must live on the settled run while staying out of every persisted one.
+ */
+export const PERSIST_STRIP_FIELDS = [...SETTLE_STRIP_FIELDS, 'lastIntervention'];
+/**
+ * Drop `fields` from one run, returning a NEW object - and the SAME object when there
+ * is nothing to drop, so a run's identity is preserved for reference equality where
+ * nothing changed (the `publish()` path compares nothing, but the reducer's
+ * `mapEntry` does dedupe on identity in some frames).
+ */
+function stripRun(run, fields) {
+    let changed = false;
+    for (const field of fields) {
+        if (run[field] !== undefined) {
+            changed = true;
+            break;
+        }
+    }
+    if (!changed)
+        return run;
+    const copy = { ...run };
+    for (const field of fields)
+        delete copy[field];
+    return copy;
+}
+/**
+ * The dispatch exit: one run, without `SETTLE_STRIP_FIELDS`.
+ *
+ * `lastIntervention` is deliberately KEPT (see this file's header) - the settled card's
+ * badge and the supervision report both read it.
+ */
+export function settledRun(run) {
+    return stripRun({ ...run, filesTouched: [...run.filesTouched] }, SETTLE_STRIP_FIELDS);
+}
+/**
+ * The save boundary: every `kind: 'team'` entry's runs, without
+ * `PERSIST_STRIP_FIELDS`.
+ *
+ * Entries that carry no team runs - or whose runs carry none of the fields - are
+ * returned UNTOUCHED, which is what keeps an ordinary session file byte-identical to
+ * the one this build produced before the feature.
+ */
+export function stripEphemeralRuns(entries) {
+    return entries.map((entry) => {
+        if (entry.kind !== 'team')
+            return entry;
+        const runs = entry.runs.map((run) => stripRun(run, PERSIST_STRIP_FIELDS));
+        return runs.some((run, index) => run !== entry.runs[index])
+            ? { ...entry, runs }
+            : entry;
+    });
+}

package/dist/team/subagent.js

@@ -15,8 +15,9 @@ import { formatStreamError } from '../agent/reducer.js';
 import { buildSystemPrompt } from '../agent/system-prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
 import { createBuiltinTools } from '../tools/index.js';
-import { pickActivityArgs, sanitizeActivity } from './activity.js';
+import { describeToolActivity, pickActivityArgs, sanitizeActivity } from './activity.js';
 import { TEAM_LIMITS, TEAM_SUBAGENT_TOOL_NAMES } from './limits.js';
+import { appendTimeline } from './timeline.js';
 import { isRetryableStreamError } from './retry.js';
 import { resolveSubagentKey, resolveSubagentModel } from './model.js';
 import { makeTeamSend, makeTeamWait, withMailboxTail } from './comm-tools.js';
@@ -306,6 +307,18 @@ export function createSubagent(spec, deps, hooks) {
     // append: a long turn would otherwise grow this without limit, and it is the
     // only per-token allocation this feature adds.
     let textTail = '';
+    /**
+     * The tool call in flight, for the timeline's duration (tui-subagent-panel §4.5.2).
+     *
+     * ONE field, not a stack: a child executes one tool at a time, and the ring records
+     * only the pair's difference. The `start` event deliberately writes NOTHING to the
+     * timeline - a line that appears and is then rewritten would push a real event out of
+     * the 24-slot ring for every call.
+     */
+    let pendingTool = null;
+    const noteTimeline = (entry) => {
+        run.timeline = appendTimeline(run.timeline, entry);
+    };
     const emit = () => {
         const now = Date.now();
         const retryKey = run.retry ? `${run.retry.attempt}/${run.retry.maxRetries}` : '';
@@ -399,6 +412,15 @@ export function createSubagent(spec, deps, hooks) {
                 break;
             }
             case 'compaction_end':
+                // The timeline records the APPLIED compactions only (§4.5.2): a refused one
+                // changed nothing, and the board already shows the phase.
+                if (event.applied) {
+                    noteTimeline({
+                        kind: 'compact',
+                        at: Date.now(),
+                        text: `compacted ${event.estimatedTokensBefore} -> ${event.estimatedTokensAfter} tokens`,
+                    });
+                }
                 contextManager?.onCompactionEnd({
                     applied: event.applied,
                     ...(event.reason !== undefined ? { reason: event.reason } : {}),
@@ -407,6 +429,9 @@ export function createSubagent(spec, deps, hooks) {
                 });
                 break;
             case 'tool_execution_start':
+                // Recorded for the DURATION only; the entry itself is appended on the end
+                // event, when `ok` and `ms` are both known (§4.5.2).
+                pendingTool = { name: event.toolName, at: Date.now() };
                 run.phase = event.toolName === 'team_wait' ? 'waiting' : 'tool';
                 run.lastTool = event.toolName;
                 run.toolCalls += 1;
@@ -415,7 +440,20 @@ export function createSubagent(spec, deps, hooks) {
                 run.activityArgs = pickActivityArgs(event.args); // PICKED, not raw (P1-4)
                 noteFile(event.toolName, event.args);
                 break;
-            case 'tool_execution_end':
+            case 'tool_execution_end': {
+                const endedAt = Date.now();
+                const startedAt = pendingTool?.at;
+                pendingTool = null;
+                // THE ARGUMENTS ARE GONE BY NOW, on purpose (P1-5): `activityArgs` is cleared a
+                // few lines below, and the timeline's text comes from `describeToolActivity` on
+                // the PICKED subset, so a `write_file` body can never reach the board.
+                noteTimeline({
+                    kind: 'tool',
+                    at: endedAt,
+                    ok: event.isError !== true,
+                    ...(startedAt !== undefined ? { ms: Math.max(0, endedAt - startedAt) } : {}),
+                    text: describeToolActivity(event.toolName, run.activityArgs, true),
+                });
                 run.phase = 'thinking';
                 textTail = '';
                 run.activity = undefined;
@@ -434,6 +472,7 @@ export function createSubagent(spec, deps, hooks) {
                     run.blockedWaits = deps.bus.blockedWaitCount(spec.label);
                 }
                 break;
+            }
             case 'message_update':
                 if (event.streamEvent.type === 'error') {
                     run.error = formatStreamError(event.streamEvent.error);
@@ -444,6 +483,13 @@ export function createSubagent(spec, deps, hooks) {
                     run.retry = undefined;
                 }
                 else if (event.streamEvent.type === 'retry_scheduled') {
+                    // The timeline keeps the retry's ARRIVAL only (§4.5.2): the countdown itself is
+                    // a live readout on the row, and a tick per attempt would eat the ring.
+                    noteTimeline({
+                        kind: 'retry',
+                        at: Date.now(),
+                        text: `retry ${event.streamEvent.attempt}/${event.streamEvent.maxRetries}`,
+                    });
                     // SET, and the phase is deliberately LEFT ALONE: the child is still
                     // `thinking` as far as the scheduler is concerned, and rewriting the
                     // phase would put a retry into `SubagentPhase` — a union the report, the

package/dist/team/timeline.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The per-child event ring behind the Agents board's `timeline` section
+ * (tui-subagent-panel §4.5).
+ *
+ * WHY A RING ON THE RUN rather than a second store: a `SubagentRun` already IS "one
+ * child's projection", and every UI surface reads it through `publish()`. A separate
+ * store would be a second authority for the same subject and would have to be
+ * subscribed to separately - and the four collection points below are all single
+ * funnels that already exist (§4.5.2).
+ *
+ * FIVE KINDS, NOT EVERY TURN (D-12). A turn marker per turn would fill twenty-four
+ * slots in a long task and push out the tool calls, which are the part a reader cannot
+ * reconstruct from the report. Phase changes are visible in the board's `state` field
+ * in real time, so they do not need history.
+ *
+ * BOUNDED AND PURE. `appendTimeline` returns a NEW array (never mutates the old one),
+ * drops the oldest entry past `TEAM_LIMITS.timelineEntries`, and clamps every line to
+ * `TEAM_LIMITS.timelineTextChars`. Purity is what lets `publish()`'s shallow copy hold
+ * a stable snapshot without knowing this module exists (AC-25).
+ *
+ * ASCII ONLY: `src/team/**` is inside `glyphs.test.ts`'s static scan.
+ *
+ * THE TEXT IS ALWAYS BUILT FROM `describeToolActivity` / `sanitizeActivity`, never
+ * from raw tool arguments (D-11 / P1-4). That is the boundary that keeps a
+ * `write_file` body, a `bash` transcript or a child's prompt out of a surface that is
+ * one `JSON.stringify` from a log.
+ */
+import type { SubagentPhase, SubagentRun } from './types.js';
+export type TimelineKind = 'tool' | 'retry' | 'compact' | 'overseer' | 'settle';
+export interface TimelineEntry {
+    kind: TimelineKind;
+    /** Absolute epoch ms, the same units as `startedAt` / `endedAt` / `lastIntervention.at`. */
+    at: number;
+    /** Already sanitized + clamped: at most `TEAM_LIMITS.timelineTextChars` characters. */
+    text: string;
+    /** Whether the tool call succeeded (`tool` only). */
+    ok?: boolean;
+    /** How long the tool call took in ms (`tool` only). */
+    ms?: number;
+}
+export declare function isTerminalPhase(phase: SubagentPhase): boolean;
+/**
+ * Append one event, returning a NEW array. The oldest entry is dropped once the ring
+ * is full, so the array's length is bounded by `max` for every possible input.
+ */
+export declare function appendTimeline(prev: readonly TimelineEntry[] | undefined, entry: TimelineEntry, max?: number): TimelineEntry[];
+/**
+ * The terminal event for one ATTEMPT, or `null` when there is nothing to record yet.
+ *
+ * WHY THIS IS CALLED FROM `publish()` AND NOT FROM `settlePhase` (§4.5.2 / RV-P1-3):
+ * `settlePhase` covers the retry loop's exit only, and two paths set a terminal phase
+ * directly - the worker's "never started" abort and the cold-start backoff abort. Those
+ * are exactly the children whose explanation a reader needs most, and hanging the
+ * settle entry on `settlePhase` alone would leave them with no last event.
+ *
+ * IDEMPOTENCE IS KEYED ON THE ATTEMPT, not on "the last entry is a settle" (I-14): a
+ * retry re-stamps `startedAt`, so a new attempt legitimately earns a second terminal
+ * entry, while a repeated `publish()` of the same attempt adds nothing.
+ */
+export declare function settleTimelineEntry(run: SubagentRun, at: number): TimelineEntry | null;
+/**
+ * The run as a reader should see it: unchanged, or with its attempt's terminal event
+ * appended once. Called from `publish()`, which is every state change's single exit
+ * (§4.5.2) and therefore covers the two paths that set a terminal phase directly.
+ *
+ * ADDED TO THE EMITTED SNAPSHOT, NEVER TO THE LIVE RUN (this is the part `publish()`
+ * makes subtle). `subagent.ts` calls `onUpdate` with a COPY of the run, so writing the
+ * entry onto the object `publish()` receives would be lost - and because
+ * `settleTimelineEntry` uses the live timeline as its idempotence key, a lost write
+ * means every later publish of the same settled child appends another `settle` row to
+ * the ring. Keeping the live run untouched makes the entry a property of the VIEW:
+ * exactly one terminal event per attempt, however many frames are published.
+ */
+export declare function withSettleEntry(run: SubagentRun, at: number): SubagentRun;

package/dist/team/timeline.js

@@ -0,0 +1,101 @@
+/**
+ * The per-child event ring behind the Agents board's `timeline` section
+ * (tui-subagent-panel §4.5).
+ *
+ * WHY A RING ON THE RUN rather than a second store: a `SubagentRun` already IS "one
+ * child's projection", and every UI surface reads it through `publish()`. A separate
+ * store would be a second authority for the same subject and would have to be
+ * subscribed to separately - and the four collection points below are all single
+ * funnels that already exist (§4.5.2).
+ *
+ * FIVE KINDS, NOT EVERY TURN (D-12). A turn marker per turn would fill twenty-four
+ * slots in a long task and push out the tool calls, which are the part a reader cannot
+ * reconstruct from the report. Phase changes are visible in the board's `state` field
+ * in real time, so they do not need history.
+ *
+ * BOUNDED AND PURE. `appendTimeline` returns a NEW array (never mutates the old one),
+ * drops the oldest entry past `TEAM_LIMITS.timelineEntries`, and clamps every line to
+ * `TEAM_LIMITS.timelineTextChars`. Purity is what lets `publish()`'s shallow copy hold
+ * a stable snapshot without knowing this module exists (AC-25).
+ *
+ * ASCII ONLY: `src/team/**` is inside `glyphs.test.ts`'s static scan.
+ *
+ * THE TEXT IS ALWAYS BUILT FROM `describeToolActivity` / `sanitizeActivity`, never
+ * from raw tool arguments (D-11 / P1-4). That is the boundary that keeps a
+ * `write_file` body, a `bash` transcript or a child's prompt out of a surface that is
+ * one `JSON.stringify` from a log.
+ */
+import { TEAM_LIMITS } from './limits.js';
+/** The phases that end an attempt. Used by the settle-idempotence rule below. */
+const TERMINAL_PHASES = new Set(['done', 'failed', 'aborted']);
+export function isTerminalPhase(phase) {
+    return TERMINAL_PHASES.has(phase);
+}
+/** Clamp one line to the display budget. Collapses whitespace for the same reason. */
+function clampText(text) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    if (flat.length <= TEAM_LIMITS.timelineTextChars)
+        return flat;
+    return `${flat.slice(0, TEAM_LIMITS.timelineTextChars - 3)}...`;
+}
+/**
+ * Append one event, returning a NEW array. The oldest entry is dropped once the ring
+ * is full, so the array's length is bounded by `max` for every possible input.
+ */
+export function appendTimeline(prev, entry, max = TEAM_LIMITS.timelineEntries) {
+    const limit = Number.isFinite(max) ? Math.max(1, Math.floor(max)) : TEAM_LIMITS.timelineEntries;
+    const next = [...(prev ?? []), { ...entry, text: clampText(entry.text) }];
+    return next.length > limit ? next.slice(next.length - limit) : next;
+}
+/** The first line of a multi-line answer, clamped - a timeline entry is one line. */
+function head(text) {
+    if (text === undefined || text.length === 0)
+        return '';
+    return clampText(text);
+}
+/**
+ * The terminal event for one ATTEMPT, or `null` when there is nothing to record yet.
+ *
+ * WHY THIS IS CALLED FROM `publish()` AND NOT FROM `settlePhase` (§4.5.2 / RV-P1-3):
+ * `settlePhase` covers the retry loop's exit only, and two paths set a terminal phase
+ * directly - the worker's "never started" abort and the cold-start backoff abort. Those
+ * are exactly the children whose explanation a reader needs most, and hanging the
+ * settle entry on `settlePhase` alone would leave them with no last event.
+ *
+ * IDEMPOTENCE IS KEYED ON THE ATTEMPT, not on "the last entry is a settle" (I-14): a
+ * retry re-stamps `startedAt`, so a new attempt legitimately earns a second terminal
+ * entry, while a repeated `publish()` of the same attempt adds nothing.
+ */
+export function settleTimelineEntry(run, at) {
+    if (!isTerminalPhase(run.phase))
+        return null;
+    const attemptStart = run.startedAt ?? 0;
+    const last = run.timeline?.[run.timeline.length - 1];
+    if (last?.kind === 'settle' && last.at >= attemptStart)
+        return null;
+    const text = run.phase === 'done'
+        ? `done: ${head(run.summary)}`.trim()
+        : run.phase === 'failed'
+            ? `failed: ${head(run.error)}`.trim()
+            : 'aborted';
+    return { kind: 'settle', at, text };
+}
+/**
+ * The run as a reader should see it: unchanged, or with its attempt's terminal event
+ * appended once. Called from `publish()`, which is every state change's single exit
+ * (§4.5.2) and therefore covers the two paths that set a terminal phase directly.
+ *
+ * ADDED TO THE EMITTED SNAPSHOT, NEVER TO THE LIVE RUN (this is the part `publish()`
+ * makes subtle). `subagent.ts` calls `onUpdate` with a COPY of the run, so writing the
+ * entry onto the object `publish()` receives would be lost - and because
+ * `settleTimelineEntry` uses the live timeline as its idempotence key, a lost write
+ * means every later publish of the same settled child appends another `settle` row to
+ * the ring. Keeping the live run untouched makes the entry a property of the VIEW:
+ * exactly one terminal event per attempt, however many frames are published.
+ */
+export function withSettleEntry(run, at) {
+    const settle = settleTimelineEntry(run, at);
+    if (settle === null)
+        return run;
+    return { ...run, timeline: appendTimeline(run.timeline, settle) };
+}

package/dist/team/types.d.ts

@@ -12,6 +12,7 @@
  */
 import type { TokenUsage } from '@aragon-agent/core';
 import type { ActivityArgs } from './activity.js';
+import type { TimelineEntry } from './timeline.js';
 /** One normalized delegation request. Produced only by `normalizeSubagentSpecs`. */
 export interface SubagentSpec {
     /** Slug, unique within the dispatch. Shown in the panel, the report and logs. */
@@ -163,7 +164,10 @@ export interface SubagentRun {
      * The most recent supervisor decision applied to this child
      * (subagent-overseer-v2 section 6). TRANSIENT, never persisted - the
      * same rule as `activity` / `activityArgs`; a resumed session has no
-     * live dispatch.
+     * live dispatch. The strip that enforces it is `PERSIST_STRIP_FIELDS` in
+     * `team/settled.ts` (tui-subagent-panel §4.5.4): it stays on the settled run,
+     * because the card's badge and the supervision report read it there, and the
+     * SAVE boundary is where it is removed.
      *
      * `at` is ABSOLUTE epoch ms, the same units as `startedAt` / `endedAt`
      * (R-P2-3), so the panel renders `nudged 2m` with one subtraction and
@@ -175,6 +179,25 @@ export interface SubagentRun {
         at: number;
         reasonHead: string;
     };
+    /**
+     * The last `TEAM_LIMITS.timelineEntries` (24) events of this child
+     * (tui-subagent-panel §4.5 / §7).
+     *
+     * EPHEMERAL, on exactly the same terms as `activity` / `activityArgs` / `retry`, and
+     * guaranteed by TWO independent strips (`team/settled.ts`): `settledRun()` at the
+     * dispatch exit and `stripEphemeralRuns()` in `saveSession`'s chain. One gate is not
+     * enough - the live entry's runs are written by `teamUpdate` during a dispatch, so a
+     * checkpoint or an exit flush would otherwise carry the ring to disk (§4.5.4).
+     *
+     * NEVER persisted, never in `aragon exec`'s stream either: `exec/runner.ts`'s
+     * `emitTeam` builds its events from an explicit field list, so a new run field cannot
+     * leak into `stream-json` (AC-22).
+     *
+     * `at` is ABSOLUTE epoch ms (the units of `startedAt` / `lastIntervention.at`), and
+     * each `text` is already sanitized and clamped, so appending is the only write and
+     * `appendTimeline` is the only appender.
+     */
+    timeline?: TimelineEntry[];
 }
 /** What the supervisor may do with one inspected child. */
 export type OverseerAction = 'wait' | 'nudge' | 'replace' | 'abandon';

package/dist/todo/acceptance.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The acceptance-criteria model (todo-acceptance-criteria §6.2 / §6.3 / §6.6.2).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
+ *
+ * PURE: no I/O, no timers, no `Date.now()`. The clock is injected where a
+ * timestamp is needed, exactly as `TodoStore`'s constructor does (P2-4).
+ *
+ * ONE PRINCIPLE RUNS THROUGH THE WHOLE FILE, and it is the reason this module
+ * exists: **a verdict is evidence, a plan is a belief**. A verdict is never
+ * destroyed by omission - not by re-sending the criterion as `pending`, and not
+ * by leaving it out of the list altogether - because a full replacement means the
+ * model re-sends the whole table on every turn and one lapse would silently erase
+ * a conclusion the user was shown. An unchecked criterion, by contrast, IS a
+ * plan, so a re-plan is free to drop it.
+ *
+ * NEVER THROWS, NEVER REJECTS, ONLY REPAIRS (I-9): the same discipline
+ * `normalize.ts` records for the todo list itself.
+ */
+import type { AcceptanceItem, AcceptanceSnapshot, PlanPhase, TodoItem, TodoSnapshot } from './types.js';
+export interface NormalizeAcceptanceResult {
+    items: AcceptanceItem[];
+    /** 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 interface NormalizeAcceptanceOptions {
+    /** `todo.acceptance`, read LIVE (D-11). False short-circuits everything below. */
+    enabled: boolean;
+    /**
+     * Per-lineage dedupe of the restoration note (§6.2.1 step 9 / P2-4).
+     *
+     * OWNED BY `TodoStore`, not by this module: the note would otherwise be
+     * re-printed on every turn, because the model has no way to know the server
+     * restored a verdict and would keep sending the same `pending` row. Passing the
+     * set in keeps this function pure and keeps the dedupe state in the one object
+     * that already owns the plan's lifetime.
+     */
+    restoredNotes?: Set<string>;
+}
+/**
+ * Repair whatever arrived in the `acceptance` field of a `todo_write` call.
+ *
+ * ORDER IS SEMANTICS, and one step of that order is load-bearing enough to be a
+ * review condition (C-2): `enabled` short-circuits FIRST, then `undefined`, then
+ * `Array.isArray`. `undefined` (the key is absent) and `[]` (the model sent an
+ * empty array) are NOT the same thing: absent means "I am only updating steps,
+ * keep the table", empty means "this plan needs no criteria". This is the one
+ * place in the feature where the two differ (§9).
+ */
+export declare function normalizeAcceptance(raw: unknown, previous: readonly AcceptanceItem[], options: NormalizeAcceptanceOptions): NormalizeAcceptanceResult;
+/**
+ * The immutable projection of one committed table (§6.2.2).
+ *
+ * CALLED FROM EXACTLY ONE PLACE PER COMMIT - `TodoStore`'s `write` / `restore` /
+ * `clear` / `reopenAll` - and stored, never recomputed on read. `snapshot()` runs
+ * on every event; recomputing here would stamp a new `now()` and a new object
+ * each frame, invalidating `TodoCard`'s `React.memo` and the transcript's height
+ * cache (P1-3).
+ */
+export declare function acceptanceSummary(items: readonly AcceptanceItem[], now: () => number): AcceptanceSnapshot;
+/**
+ * The ONE judge of "which phase is this plan in" (I-3 / D-5).
+ *
+ * Derived rather than stored, so the model, the rail, the transcript card and the
+ * machine event stream cannot disagree: a stored field would be a second writer
+ * of a fact that two lists already determine. Callers must not invoke this for a
+ * `null` plan.
+ */
+export declare function derivePlanPhase(items: readonly TodoItem[], acceptance: readonly AcceptanceItem[] | null): PlanPhase;
+/**
+ * "Is there nothing left to do in this plan" - THE single judge (G-4 / I-3).
+ *
+ * Referenced by follow-through, by `App`'s grace-window re-check and by
+ * `TodoStore.beginUserTurn`, because "every step is completed" stopped being the
+ * same claim as "the work is done" the moment acceptance criteria existed. Three
+ * copies of the old equation is exactly how a plan gets cleared while its last
+ * criterion is still unchecked.
+ */
+export declare function planIsResolved(items: readonly TodoItem[], acceptance: readonly AcceptanceItem[] | null): boolean;
+export declare function countUnfinishedSteps(items: readonly TodoItem[]): number;
+export declare function countUncheckedCriteria(acceptance: readonly AcceptanceItem[] | null): number;
+/** What is left in a plan, as the two numbers the notices are written from. */
+export interface Outstanding {
+    steps: number;
+    checks: number;
+}
+/**
+ * The six follow-through exits all need "how much is left", and after this
+ * feature that quantity has two halves (§6.6.1.1). One function decides it, so no
+ * exit can print `0 steps left` on a plan whose steps are all done but whose
+ * criteria are not - which is what `total - doneCount` would say on every verify
+ * turn.
+ */
+export declare function outstandingOf(snapshot: TodoSnapshot): Outstanding;
+/**
+ * Singular and plural decided in ONE place (§6.6.1.1): six call sites must not
+ * each spell their own.
+ */
+export declare function criteriaPhrase(count: number): string;
+/**
+ * A bounded enumeration of what a plan still owes, for the tool result text
+ * (§6.3). Ordered `todoFirst` because the tool result is read top-down and the
+ * step being worked on is the more urgent of the two when both exist.
+ *
+ * BOUNDED BY CONSTRUCTION at `VERIFY_MESSAGE_LIMITS.uncheckedItems` rows: this
+ * string is paid for on every call (I-11).
+ */
+export declare function planOutstanding(items: readonly TodoItem[], acceptance: readonly AcceptanceItem[] | null, todoFirst: boolean): string[];
+/**
+ * The continuation text for the verification phase (§6.6.2).
+ *
+ * CONSTRUCTIVELY BOUNDED, which is what AC-22 asserts: the unchecked list stops
+ * at 5 rows, the failed list at 2, `check` is clipped to 100 characters and
+ * `evidence` to 60. Both truncations are deliberate - the full text is already in
+ * the model's own previous payload, so re-sending it is paying twice for the same
+ * bytes; what the model needs is a reminder of WHICH rows are open.
+ */
+export declare function buildVerifyMessage(snapshot: TodoSnapshot): string;