@aragon-agent/cli 0.6.35 → 0.6.36

package/dist/prompts/types.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The quick-prompt library's data model (quick-prompt-library §6.1).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`. Chinese copy
+ * lives in `copy.ts` as `\uXXXX` escapes, never as literal text in this tree.
+ *
+ * THE DISK SHAPE IS THE ONLY TRUTH (D-3 / I-6). `App` holds a `PromptLibrary`
+ * snapshot for rendering, every mutation goes through `store.ts`, and the store
+ * hands the new snapshot back. No component computes an optimistic library of its
+ * own, because "the UI says it was added and the disk disagrees" is a failure
+ * mode with no error message.
+ */
+/**
+ * One entry.
+ *
+ * `useCount` / `createdAt` / `updatedAt` are ALWAYS present: a missing number
+ * would make every consumer write `?? 0` and one of them would eventually forget.
+ * `description` / `tags` / `favorite` / `lastUsedAt` are optional because "absent"
+ * is their honest state.
+ */
+export interface QuickPrompt {
+    /** `randomUUID()`. Never shown in full; the list uses an 8-character prefix. */
+    id: string;
+    /** 1..80 code points, trimmed, no control characters. Never empty (I-5). */
+    title: string;
+    /** 1..8000 code points. Original newlines preserved; `\r\n` normalised to `\n`. */
+    content: string;
+    /** 0..200 code points. */
+    description?: string;
+    /** 0..6 tags, each 0..24 code points. */
+    tags?: string[];
+    favorite?: boolean;
+    /** Monotonic per entry (I-4). */
+    useCount: number;
+    /** Epoch ms. */
+    createdAt: number;
+    updatedAt: number;
+    lastUsedAt?: number;
+}
+/**
+ * The whole library.
+ *
+ * `prompts` IS the manual order (I-1): index 0 is what the list shows first and
+ * what `Ctrl+Up/Down` rearranges. There is no `order` field, because a second
+ * ordering authority is a second thing that can disagree with the first.
+ */
+export interface PromptLibrary {
+    schema: 1;
+    prompts: QuickPrompt[];
+    /** Epoch ms of the last successful write; strictly increasing (I-3). */
+    updatedAt: number;
+}
+/**
+ * The persistent re-orderings `/prompts sort <key>` can name (D-9).
+ *
+ * A WRITE key, not a view: `PromptSortView` is what the picker renders and never
+ * persists, this is what the user may ask to have rewritten on disk. They overlap by two
+ * words and are deliberately separate types, because "sort by recent" and "show me the
+ * recent order for a moment" are different promises.
+ */
+export type PromptSortKey = 'name' | 'recent' | 'favorite';
+/** The picker's three presentations. A VIEW: never persisted (D-9). */
+export type PromptSortView = 'manual' | 'recent' | 'favorite';
+/**
+ * Why a write or a lookup failed. A stable code, never a sentence: the sentence
+ * comes from `copy.ts`, so the same failure has one wording on every surface.
+ */
+export type PromptWriteError = 'title_required' | 'content_required' | 'title_too_long' | 'content_too_long' | 'description_too_long' | 'tag_too_long' | 'too_many_tags' | 'too_many_prompts' | 'not_found' | 'ambiguous' | 'write_failed';
+/**
+ * The result of one mutation.
+ *
+ * THE LIBRARY TRAVELS WITH THE FAILURE TOO, and that is deliberate: a
+ * `write_failed` still applied in memory (D-4), so the caller has to be able to
+ * render what the user just created rather than pretending nothing happened.
+ */
+export type PromptMutationResult = {
+    ok: true;
+    library: PromptLibrary;
+    id?: string;
+} | {
+    ok: false;
+    code: PromptWriteError;
+    library: PromptLibrary;
+};
+/**
+ * A one-shot hand-off into the manager overlay (D-21).
+ *
+ * `App` never edits the overlay's state directly; it hands over an intent, and the
+ * overlay consumes it exactly once by nonce. That is what makes `/prompts edit 2`
+ * land in the editor with a prefilled draft instead of on row 0 of the list.
+ */
+export type PromptLibraryEntry = {
+    kind: 'list';
+    focusId?: string;
+} | {
+    kind: 'create';
+    seed?: {
+        title?: string;
+        content?: string;
+    };
+} | {
+    kind: 'edit';
+    id: string;
+} | {
+    kind: 'delete';
+    id: string;
+};
+/** `nonce` is monotonic; the same value is consumed at most once (I-8). */
+export interface PromptLibraryIntent {
+    nonce: number;
+    entry: PromptLibraryEntry;
+}
+/**
+ * `<n|title>` resolved to an entry (D-22).
+ *
+ * `ambiguous` CARRIES ITS CANDIDATES. Titles may repeat (I-2), and a lookup that
+ * failed without saying which entries matched would leave the user with nothing
+ * to type next - which is exactly how `/prompts rm <title>` deletes the wrong
+ * prompt, and there is no recycle bin (D-13).
+ */
+export type PromptRefResolution = {
+    ok: true;
+    prompt: QuickPrompt;
+} | {
+    ok: false;
+    code: 'not_found';
+} | {
+    ok: false;
+    code: 'ambiguous';
+    candidates: QuickPrompt[];
+};
+/**
+ * The editable form of one entry.
+ *
+ * `id: null` means "not saved yet". `tags` is the RAW field text: parsing it on
+ * every keystroke would rewrite what the user is typing as they type it.
+ */
+export interface PromptEditorDraft {
+    id: string | null;
+    title: string;
+    content: string;
+    description: string;
+    tags: string;
+    favorite: boolean;
+}
+/** The three things the manager overlay may ask the store to do (P2-1: idempotent). */
+export type PromptLibraryMutation = {
+    kind: 'create';
+    draft: PromptEditorDraft;
+} | {
+    kind: 'update';
+    id: string;
+    draft: PromptEditorDraft;
+} | {
+    kind: 'delete';
+    id: string;
+} | {
+    kind: 'move';
+    id: string;
+    delta: -1 | 1;
+} | {
+    kind: 'favorite';
+    id: string;
+    favorite: boolean;
+};
+/**
+ * What a command (or the picker) may ask the host to do (§6.3 / P1-3).
+ *
+ * THREE METHODS, and each one is something the command layer genuinely cannot do
+ * itself: open a surface, hand that surface a payload, or read the library through
+ * the same resolver the user's typing is interpreted with. Everything else
+ * (notifications, toasts, overlays in general) already exists on `CommandContext`
+ * and is not repeated here.
+ */
+export interface PromptCommandPort {
+    /** Open the picker (`overlay: 'prompt-pick'`). */
+    openPicker(): void;
+    /** Open the manager on a specific page, with an optional prefilled draft. */
+    openManager(entry: PromptLibraryEntry): void;
+    /** `<n|title>` -> entry, through `resolvePromptRef` (D-22). */
+    resolve(ref: string): PromptRefResolution;
+}
+/** A validated draft, ready for the store. Produced by `finishPromptEditor`. */
+export interface PromptDraftInput {
+    title: string;
+    content: string;
+    description?: string;
+    tags?: string[];
+    favorite?: boolean;
+}
+/**
+ * The verdict of validating a draft (§4.4 / D-12).
+ *
+ * `field` is the row that should own focus after a refusal, so the editor can jump
+ * there instead of leaving the user staring at a footer with an error code in it.
+ */
+export type PromptDraftVerdict = {
+    ok: true;
+    input: PromptDraftInput;
+} | {
+    ok: false;
+    code: PromptWriteError;
+    field: 'title' | 'content' | 'description' | 'tags';
+};

package/dist/prompts/types.js

@@ -0,0 +1,13 @@
+/**
+ * The quick-prompt library's data model (quick-prompt-library §6.1).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`. Chinese copy
+ * lives in `copy.ts` as `\uXXXX` escapes, never as literal text in this tree.
+ *
+ * THE DISK SHAPE IS THE ONLY TRUTH (D-3 / I-6). `App` holds a `PromptLibrary`
+ * snapshot for rendering, every mutation goes through `store.ts`, and the store
+ * hands the new snapshot back. No component computes an optimistic library of its
+ * own, because "the UI says it was added and the disk disagrees" is a failure
+ * mode with no error message.
+ */
+export {};

package/dist/session/checkpoint.d.ts

@@ -31,7 +31,7 @@
  */
 import { type Message, type ModelRef } from '@aragon-agent/core';
 import type { Entry, UsageTotal } from '../agent/reducer.js';
-import type { TodoItem } from '../todo/types.js';
+import type { AcceptanceItem, TodoItem } from '../todo/types.js';
 import type { CompactionIdentity } from '../compaction/memory-identity.js';
 import { type SessionLockHandle } from './store.js';
 /**
@@ -58,6 +58,13 @@ export interface CheckpointDeps {
         compactionIdentity?: CompactionIdentity;
     };
     readTodos(): TodoItem[];
+    /**
+     * The acceptance verdicts, for the same reason `readTodos` exists: a checkpoint
+     * must not lose the conclusions the user was just shown
+     * (todo-acceptance-criteria §6.12). OPTIONAL so a caller that has no table — and
+     * every existing test double — keeps compiling and writes no key.
+     */
+    readAcceptance?(): AcceptanceItem[];
     readModel(): ModelRef;
     /** `meta.cwd`; read at every write because `/cwd` can change it. */
     readCwd(): string;

package/dist/session/checkpoint.js

@@ -322,6 +322,9 @@ export class SessionCheckpointWriter {
             ...(input.compactionIdentity ? { compactionIdentity: input.compactionIdentity } : {}),
             entries: input.entries,
             todos: this.deps.readTodos(),
+            ...(this.deps.readAcceptance
+                ? { acceptance: this.deps.readAcceptance() }
+                : {}),
             meta: this.buildMeta(input),
         };
         try {
@@ -447,6 +450,9 @@ export class SessionCheckpointWriter {
             view.entries.length,
             lastEntry,
             this.deps.readTodos().length,
+            // A verdict landing must force a checkpoint even when the step list is
+            // unchanged: that is the one transition a `todos.length` key cannot see.
+            this.deps.readAcceptance?.().filter((item) => item.status !== 'pending').length ?? 0,
             this.pinned ? 'pin' : '-',
         ].join('|');
     }

package/dist/session/persist.d.ts

@@ -7,7 +7,7 @@
  */
 import type { Message, ModelRef } from '@aragon-agent/core';
 import type { Entry } from '../agent/reducer.js';
-import type { TodoItem } from '../todo/types.js';
+import type { AcceptanceItem, TodoItem } from '../todo/types.js';
 import { type CompactionIdentity } from '../compaction/memory-identity.js';
 /**
  * Bookkeeping `aragon exec` attaches to the sessions it owns
@@ -75,6 +75,19 @@ export interface SavedSession {
      * right answer for a session that predates the feature (D-20 / D-22).
      */
     todos?: TodoItem[];
+    /**
+     * The acceptance table's VERDICTS at save time (todo-acceptance-criteria §6.12).
+     *
+     * ADDITIVE AND OPTIONAL, exactly like `todos` above, so `SESSION_VERSION` stays 1
+     * and an older file simply yields `undefined` - which restores as "no criteria"
+     * and leaves the rail, the card and the chip exactly as they were (AC-30).
+     *
+     * `reopen` is consumed before anything is stored and `in_progress` is a derived
+     * state, so each entry on disk carries only `content` / `check` / `status`
+     * (three-valued here) / `evidence`; `restore` lets the store re-derive which
+     * criterion is being checked.
+     */
+    acceptance?: AcceptanceItem[];
     /**
      * Written by `aragon exec` (cli-integration-surface §5.2 / D-10) AND by the
      * TUI's session checkpoint (tui-session-id-resume §6.1).
@@ -109,6 +122,11 @@ export declare function saveSession(filePath: string, data: {
     compactionIdentity?: CompactionIdentity;
     entries: Entry[];
     todos: TodoItem[];
+    /**
+     * The acceptance verdicts. OPTIONAL HERE, unlike `todos`, only to keep the field
+     * additive for callers that predate it; every writer in this package passes it.
+     */
+    acceptance?: AcceptanceItem[];
     meta?: SessionMeta;
 }): void;
 /**

package/dist/session/persist.js

@@ -8,6 +8,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { getSessionsDir } from '../config/store.js';
+import { stripEphemeralRuns } from '../team/settled.js';
 import { validateSession } from './validate-session.js';
 import { validateCompactionIdentity, verifyCompactionIdentity, } from '../compaction/memory-identity.js';
 import { getLogger } from '../logging/logger.js';
@@ -109,8 +110,19 @@ export function saveSession(filePath, data) {
         model: data.model,
         messages: data.messages,
         ...(data.compactionIdentity ? { compactionIdentity: data.compactionIdentity } : {}),
-        entries: stripServiceTail(stripLiveToolOutput(data.entries)),
+        // THE EPHEMERAL-RUN GATE IS THE THIRD STRIP IN THIS CHAIN (tui-subagent-panel
+        // §4.5.4 / RV-P0-1), and it is the only one that protects EVERY write path:
+        // `/save`, the session checkpoint and the exit flush all arrive here. Without it a
+        // dispatch-time save would carry each child's 24-event timeline into the file, no
+        // matter how careful the dispatch exit is - the live `team` entry holds the LIVE
+        // runs while the dispatch is running (`agent/reducer.ts::teamUpdate`).
+        entries: stripEphemeralRuns(stripServiceTail(stripLiveToolOutput(data.entries))),
         todos: data.todos,
+        // ONE KEY, WRITTEN ONLY WHEN THERE IS SOMETHING TO WRITE, so a session with the
+        // capability off produces a file byte-identical to today's.
+        ...(data.acceptance && data.acceptance.length > 0
+            ? { acceptance: data.acceptance }
+            : {}),
         ...(data.meta ? { meta: data.meta } : {}),
     };
     writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');

package/dist/session/startup-session.d.ts

@@ -20,7 +20,7 @@
  */
 import type { Message } from '@aragon-agent/core';
 import type { Entry } from '../agent/reducer.js';
-import type { TodoItem } from '../todo/types.js';
+import type { AcceptanceItem, TodoItem } from '../todo/types.js';
 import type { CompactionIdentity } from '../compaction/memory-identity.js';
 import { type SavedSession } from './persist.js';
 /** Who this process is, as the rest of the CLI sees it. */
@@ -50,7 +50,12 @@ export interface StartupSessionInput {
  */
 export interface SessionRestorePort {
     replaceMessages(messages: Message[], identity?: CompactionIdentity): void;
-    restoreTodos(items: TodoItem[]): void;
+    /**
+     * The acceptance table is OPTIONAL on this port, so a test double or an `exec`
+     * caller that predates the feature keeps compiling and restores "no criteria" -
+     * the same additive shape as `SavedSession.acceptance`.
+     */
+    restoreTodos(items: TodoItem[], acceptance?: AcceptanceItem[]): void;
     setModel(providerId: string, modelId: string, baseUrl?: string): void;
 }
 export type StartupSessionResolution = {

package/dist/session/startup-session.js

@@ -39,8 +39,11 @@ import { basenameId, isValidSessionId, looksLikeSessionPath, resolveSessionRef,
  */
 export function applyRestoredSession(port, saved, opts = {}) {
     port.replaceMessages(saved.messages, saved.compactionIdentity);
-    // Absence clears the previous conversation's list, including old files.
-    port.restoreTodos(saved.todos ?? []);
+    // Absence clears the previous conversation's plan, including old files. The
+    // verdicts come back with it, for the reason `SavedSession.acceptance` records:
+    // restoring the steps and dropping the conclusions shows a plan as unstarted that
+    // the user already watched being verified.
+    port.restoreTodos(saved.todos ?? [], saved.acceptance ?? []);
     if (!opts.skipModel && saved.model?.providerId && saved.model?.modelId) {
         port.setModel(saved.model.providerId, saved.model.modelId, saved.model.baseUrl);
     }

package/dist/session/store.js

@@ -188,6 +188,9 @@ export function writeSession(input) {
             ? { compactionIdentity: input.session.compactionIdentity } : {}),
         entries: input.session.entries,
         todos: input.session.todos ?? [],
+        // Optional on the input, so an `exec` caller that has no acceptance table writes
+        // no key at all instead of an empty one.
+        ...(input.session.acceptance ? { acceptance: input.session.acceptance } : {}),
         meta: input.meta,
     });
     writePointer(input.meta.cwd, input.id, input.meta.updatedAt);

package/dist/session/validate-session.js

@@ -1,6 +1,7 @@
 import { isAdapterProvider } from '../config/schema.js';
 import { normalizeTodos } from '../todo/normalize.js';
 import { TODO_LIMITS } from '../todo/limits.js';
+import { acceptanceSummary, normalizeAcceptance } from '../todo/acceptance.js';
 import { validateCompactionIdentity } from '../compaction/memory-identity.js';
 import { MemoryError } from '../compaction/memory.js';
 function fail(path, expected) {
@@ -160,7 +161,26 @@ const ENTRY_FIELDS = {
     team: { dispatchId: string, requested: number, runs: array(subagent), aborted: boolean,
         durationMs: optional(number), active: boolean },
     todo: { items: array(todo), doneCount: number, total: number, live: boolean,
-        interrupted: optional(boolean) },
+        interrupted: optional(boolean),
+        // THE ACCEPTANCE BLOCK ON A TRANSCRIPT CARD (todo-acceptance-criteria §6.12).
+        // IT IS THE PROJECTION, NOT THE RAW TABLE: `Entry.acceptance` is an
+        // `AcceptanceSnapshot | null` (`agent/reducer.ts`), because the card reads
+        // `checkedCount` / `failedCount` without re-walking the rows - and `null` is a
+        // real value there, the one every card written while the capability is off
+        // holds. Demanding an items array here would make every session containing a todo
+        // card unloadable, and the CLI would tell the user to delete their conversation.
+        // OPTIONAL AND LOOSELY TYPED, then normalized per entry below: a card saved before
+        // this feature has no such key, and an item that is malformed must cost that one
+        // criterion rather than the whole session. "Strict at the boundary" means the
+        // SHAPE is enforced, not that a single bad row takes the file down.
+        acceptance: optional((value, path) => {
+            if (value === null)
+                return;
+            const snapshot = record(value, path);
+            if (!Array.isArray(snapshot.items))
+                fail(`${path}.items`, 'an array');
+            optional(number)(snapshot.updatedAt, `${path}.updatedAt`);
+        }) },
     retry: {
         attempt: number, maxRetries: number, errorType: string, message: string, delayMs: number,
         resumeAt: optional(number), startedAt: number, totalRetries: optional(number),
@@ -256,5 +276,48 @@ export function validateSession(value) {
     if (source.todos !== undefined) {
         prepared.todos = normalizeTodos(source.todos, TODO_LIMITS.maxItems).items;
     }
+    // THE SESSION FILE'S OWN TABLE, normalized exactly like a model payload: a
+    // user-editable file gets a model payload's treatment (`TodoStore.restore`'s
+    // standing argument). Absent stays absent, so an old file loads unchanged.
+    if (source.acceptance !== undefined) {
+        prepared.acceptance = normalizeAcceptance(source.acceptance, [], { enabled: true }).items;
+    }
+    prepared.entries = sanitizeEntryAcceptance(prepared.entries);
     return prepared;
 }
+/**
+ * Drop the acceptance rows a persisted card cannot use, keeping every usable one.
+ *
+ * ONE BAD ROW MUST NOT COST THE SESSION: the card is HISTORY, and a resume that
+ * refuses because one evidence string was a number would throw away the
+ * conversation to protect a footnote. Rows are repaired by the same normalizer the
+ * model's payloads go through, which is also what guarantees a card on screen and a
+ * card in the file agree about what a criterion is.
+ *
+ * THE PROJECTION IS REBUILT FROM ITS ROWS, never trusted: `total` / `checkedCount` /
+ * `failedCount` are derived quantities, and a file that edited them (or a build that
+ * later changed how they are counted) would otherwise draw a header that disagrees
+ * with the rows underneath it. `updatedAt` is carried over so a card does not claim
+ * to have changed when it was only reloaded; a row set that ends up empty becomes
+ * `null`, which is what the card means by "no acceptance block".
+ */
+function sanitizeEntryAcceptance(entries) {
+    if (!Array.isArray(entries))
+        return entries;
+    return entries.map((entry) => {
+        if (!entry || typeof entry !== 'object')
+            return entry;
+        const card = entry;
+        if (card.kind !== 'todo' || card.acceptance === undefined)
+            return entry;
+        if (card.acceptance === null)
+            return card;
+        const snapshot = card.acceptance;
+        const items = normalizeAcceptance(snapshot.items, [], { enabled: true }).items;
+        const updatedAt = typeof snapshot.updatedAt === 'number' ? snapshot.updatedAt : 0;
+        return {
+            ...card,
+            acceptance: items.length > 0 ? acceptanceSummary(items, () => updatedAt) : null,
+        };
+    });
+}

package/dist/team/limits.d.ts

@@ -96,6 +96,31 @@ export declare const TEAM_LIMITS: {
      *  command; below it, a basename or a program name. Mirrors `statusCompactCols`.
      *  This chooses WHICH FACT to show; `activityBudget` chooses how much of it. */
     readonly activityWideCols: 100;
+    /**
+     * Below this many columns the roster's activity cell gives way ENTIRELY
+     * (tui-subagent-panel §4.2.2).
+     *
+     * STRUCTURAL, like everything else in this block: twelve characters of prose in
+     * a 40-column terminal push the description column below its own twelve-column
+     * floor, and "who is doing what" outranks "what they are writing right now" when
+     * there is room for only one. That is why the cell returns 0 rather than
+     * `activityMinChars` below this width.
+     */
+    readonly activityDropCols: 56;
+    /**
+     * Events kept per child in `SubagentRun.timeline` (§4.5.3). Twenty-four covers
+     * a typical dispatch's complete tool sequence; ten children x 24 x 120 chars is
+     * about 29 KB at peak, and the ring is EPHEMERAL - it never reaches a file.
+     */
+    readonly timelineEntries: 24;
+    /** Display clamp on one timeline line; the same order as `activityArgChars`. */
+    readonly timelineTextChars: 120;
+    /**
+     * Row ceiling of the Agents board's projection. The overlay scrolls, so this is
+     * a memory bound rather than a fit: one row per fact and at most ten children
+     * plus one detail section, which no healthy dispatch can reach.
+     */
+    readonly boardMaxRows: 240;
     /** Retries of a child that produced NOTHING. One, and not configurable: a
      *  second retry doubles the worst-case latency of a failing dispatch and buys
      *  nothing a re-dispatch by the lead would not buy better. */

package/dist/team/limits.js

@@ -107,6 +107,32 @@ export const TEAM_LIMITS = {
      *  command; below it, a basename or a program name. Mirrors `statusCompactCols`.
      *  This chooses WHICH FACT to show; `activityBudget` chooses how much of it. */
     activityWideCols: 100,
+    /**
+     * Below this many columns the roster's activity cell gives way ENTIRELY
+     * (tui-subagent-panel §4.2.2).
+     *
+     * STRUCTURAL, like everything else in this block: twelve characters of prose in
+     * a 40-column terminal push the description column below its own twelve-column
+     * floor, and "who is doing what" outranks "what they are writing right now" when
+     * there is room for only one. That is why the cell returns 0 rather than
+     * `activityMinChars` below this width.
+     */
+    activityDropCols: 56,
+    // --- The Agents board (tui-subagent-panel §4.4 / §4.5) ---
+    /**
+     * Events kept per child in `SubagentRun.timeline` (§4.5.3). Twenty-four covers
+     * a typical dispatch's complete tool sequence; ten children x 24 x 120 chars is
+     * about 29 KB at peak, and the ring is EPHEMERAL - it never reaches a file.
+     */
+    timelineEntries: 24,
+    /** Display clamp on one timeline line; the same order as `activityArgChars`. */
+    timelineTextChars: 120,
+    /**
+     * Row ceiling of the Agents board's projection. The overlay scrolls, so this is
+     * a memory bound rather than a fit: one row per fact and at most ten children
+     * plus one detail section, which no healthy dispatch can reach.
+     */
+    boardMaxRows: 240,
     // --- Cold-start retry (team-live-activity F-4) ---
     /** Retries of a child that produced NOTHING. One, and not configurable: a
      *  second retry doubles the worst-case latency of a failing dispatch and buys

package/dist/team/runtime.js

@@ -28,6 +28,8 @@
  * pre-feature behaviour.
  */
 import { TeamBus } from './bus.js';
+import { settledRun } from './settled.js';
+import { appendTimeline, withSettleEntry } from './timeline.js';
 import { TEAM_AGGREGATE_LABEL, TEAM_LIMITS } from './limits.js';
 import { TeamOverseer, buildReplacementPrompt, nextOverseerLadderStepMs, resolveOverseerFirstCheckMs, } from './overseer.js';
 import { shouldRetryColdStart } from './retry.js';
@@ -581,7 +583,13 @@ export class TeamRuntime {
         }), { inputTokens: 0, outputTokens: 0 });
         const outcome = {
             dispatchId,
-            runs: handles.map((h) => ({ ...h.run, filesTouched: [...h.run.filesTouched] })),
+            // THE DISPATCH EXIT'S STRIP (tui-subagent-panel §4.5.4). `settledRun` drops the
+            // four fields with no reader on a settled run (`activity` / `activityArgs` /
+            // `retry` / `timeline`) and KEEPS `lastIntervention`, which the settled card's
+            // badge and the supervision report read. The save boundary strips the fifth one
+            // (`team/settled.ts` + `session/persist.ts`) - one gate is not enough, because
+            // the live entry's runs are written to disk during the dispatch.
+            runs: handles.map((h) => settledRun(h.run)),
             requested,
             startedAt,
             endedAt: Date.now(),
@@ -999,6 +1007,16 @@ export class TeamRuntime {
                 at,
                 reasonHead: decision.reason.slice(0, 60),
             };
+            // The board's timeline records the supervisor's ACTIONS only (tui-subagent-panel
+            // §4.5.2): a `wait` decision is an inspection, not an intervention, and one line
+            // per inspection would fill the ring with `nothing happened`.
+            if (decision.action !== 'wait') {
+                handle.run.timeline = appendTimeline(handle.run.timeline, {
+                    kind: 'overseer',
+                    at,
+                    text: decision.action + ': ' + decision.reason.slice(0, 60),
+                });
+            }
             this.publish(dispatchId, handle.run);
         }
     }
@@ -1199,7 +1217,14 @@ export class TeamRuntime {
     // Events
     // -------------------------------------------------------------------------
     publish(dispatchId, run) {
-        const copy = { ...run, filesTouched: [...run.filesTouched] };
+        const copy = {
+            // The attempt's terminal event rides the EMITTED snapshot only (see
+            // `timeline.ts::withSettleEntry`): `publish` is every state change's single exit,
+            // so this is the one place that also covers the two paths which set a terminal
+            // phase without going through `settlePhase` (§4.5.2 / RV-P1-3).
+            ...withSettleEntry(run, Date.now()),
+            filesTouched: [...run.filesTouched],
+        };
         if (this.snapshotState && this.snapshotState.dispatchId === dispatchId) {
             this.snapshotState = {
                 ...this.snapshotState,

package/dist/team/settled.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+import type { Entry } from '../agent/reducer.js';
+import type { SubagentRun } from './types.js';
+/** Fields with no reader on a settled run. Stripped at the dispatch exit. */
+export declare const SETTLE_STRIP_FIELDS: readonly ["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 declare const PERSIST_STRIP_FIELDS: readonly ["activity", "activityArgs", "retry", "timeline", "lastIntervention"];
+/**
+ * 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 declare function settledRun(run: SubagentRun): SubagentRun;
+/**
+ * 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 declare function stripEphemeralRuns(entries: Entry[]): Entry[];