@itookit/dsht 0.3.8 → 0.5.2

package/dist/controller/controller.js

@@ -1,19 +1,28 @@
 /** Application facade: composes the connection, session, catalog and cost domains. */
+import { join } from 'node:path';
 import { Client } from "../transport/client.js";
-import { writeHeapSnapshot } from "../storage/index.js";
-import { errorText } from "../transport/wire.js";
+import { removeFile, writeHeapSnapshot } from "../storage/index.js";
+import { errorText, string } from "../transport/wire.js";
 import { DEFAULT_HISTORY_LIMITS } from "../session/memory.js";
 import { layoutStats } from "../session/history.js";
 import { markdownCacheStats } from "../session/markdown.js";
 import { SessionController } from "../session/controller.js";
 import { CatalogController } from "../catalog/controller.js";
 import { CostController } from "../cost/controller.js";
-import { costText } from "../cost/ledger.js";
 import { ConnectionController } from "./connection.js";
 import { MemoryLog } from "./memory-log.js";
+import { ForegroundSlot } from "./foreground.js";
+import { TraceLog } from "./trace-log.js";
+import { PromptStore } from "./prompts.js";
+import { latestAssistantText } from "./loop.js";
+import { LoopCoordinator } from "./loop-coordinator.js";
+import { loopRecords as listLoopRecords } from "./loop-protocols.js";
+import { SessionPeek } from "../session/peek.js";
+import { costAddresses } from "../cost/scanner.js";
+import { sessionLabel } from "../session-title.js";
 import { clearReactMeasures, measureCount } from "./perf-measures.js";
 import { initialState } from "../state.js";
-import { ShellController } from "../shell/index.js";
+import { ShellController, localSourceId } from "../shell/index.js";
 /** Environment for a local `!` command: this client's variables without its credentials.
  *
  * `DSH_URL` is removed as well as the token, because the URL form the README documents can carry a
@@ -27,18 +36,39 @@ function shellEnv() {
     delete env.DSH_URL;
     return env;
 }
+/** Sources this client registers before it forgets the oldest; a session list can still find them. */
+const SOURCE_LIMIT = 50;
+/** The tag every verifier session title starts with, so a reader can tell it apart in a list. */
+const VERIFIER_TAG = '[dsht-verify] ';
+/** What the read-only view calls a verifier's session: its title without the marker prefix. */
+function verifierLabel(title) {
+    const stripped = title.startsWith(VERIFIER_TAG) ? title.slice(VERIFIER_TAG.length) : title;
+    return stripped.trim() === '' ? title : stripped.trim();
+}
+/** File `/handoff` clears on this machine before it asks the agent to write a handoff. */
+const HANDOFF_FILE = 'HANDOFF.md';
+/** Instruction `/handoff` sends once this client's own copy of the file is gone.
+ *
+ * The sections are explicit because a handoff is read by whoever continues the work: why the
+ * session exists, the goal, and the state of every task, including the ones that cannot be done.
+ */
+const HANDOFF_PROMPT = [
+    'Write a session handoff to HANDOFF.md in the workspace root, overwriting whatever is there,',
+    'in the language of this conversation. Cover, in this order:',
+    '(1) why this session exists and what triggered it;',
+    '(2) the goal it is working toward;',
+    '(3) every task and its state — completed, still open, or impossible, each with its reason;',
+    '(4) the decisions made and the files changed;',
+    '(5) how to verify the current state;',
+    '(6) the exact next steps for whoever continues this work.',
+    'Base it only on this session; never invent work that did not happen.',
+].join(' ');
 /** Application facade over the domain controllers; the UI owns only this object.
  *
  * State lives here, connection generations live in `connection`, the selected session and its
  * history live in `session`, model metadata lives in `catalog`, and billing lives in `cost`.
  */
 export class Controller {
-    base;
-    initialSession;
-    costs;
-    historyLimits;
-    memoryLogPath;
-    localDirectory;
     state = initialState();
     /** Physical connection, retry loop and projection store. */
     connection;
@@ -50,31 +80,92 @@ export class Controller {
     cost;
     /** Bounded runtime memory samples; present only when a log path was supplied. */
     memoryLog;
+    /** Bounded connection, screen and selection trace; present only when a path was supplied. */
+    trace;
+    /** Shortcut prompts the operator saved; in memory for this run when no path was supplied. */
+    promptStore;
+    /** Finished turns of the selected session, so a waiter never has to sample a cached flag. */
+    completedTurns = 0;
+    /** Sessions the host reported busy, so a lone idle frame cannot claim a finished turn. */
+    busySessions = new Set();
+    /** Loop execution owns all verifier, settling and deadline state. */
+    loops;
     /** Local `!` commands, run on this machine and shown inline in the transcript. */
     shell;
+    /** Mutating surface the UI drives. */
+    actions;
+    /** Read-only surface the UI drives. */
+    queries;
+    /** Host base URL this client talks to. */
+    base;
+    /** Billing ledger supplied at construction, when any. */
+    costs;
+    /** History retention budgets in force. */
+    historyLimits;
+    /** Runtime memory log path, when one was configured. */
+    memoryLogPath;
+    /** Directory this client runs in. */
+    localDirectory;
+    /** Session opened at startup, when one was named. */
+    initialSession;
     observers = new Set();
     selector = 0;
-    constructor(base, token, initialSession, makeClient = () => new Client(base), authenticate = client => client.authenticate(token ?? ''), costs, historyLimits = DEFAULT_HISTORY_LIMITS, memoryLogPath, 
-    /** Directory this client runs in, offered as a workspace when the host has not registered it. */
-    localDirectory = process.cwd(), 
-    /** Whether `!` may run local commands; the CLI disables it with `--no-shell`. */
-    shellEnabled = true) {
+    connectionSettled = false;
+    /** Startup defaults apply once; subsequent generations restore the operator's selection. */
+    initialized = false;
+    /** Counter behind `commandId`, so every executed line has one identifier in begin and end. */
+    commandSeq = 0;
+    /** Scheduling and cancellation are owned independently of domain operations. */
+    foregroundSlot = new ForegroundSlot({
+        changed: started => this.update(started ? { lastFailure: '' } : {}),
+        trace: event => this.traceEvent('foreground', event),
+    });
+    /** Read-only follower for the full-screen view; it borrows the connection and never selects. */
+    peek;
+    /** Sources this client created, keyed by session id; the host cannot record that lineage itself. */
+    createdSources = new Map();
+    /** The source the read-only view is showing, when one is open. */
+    peekId;
+    constructor(options) {
+        const { base, token, initialSession, costs } = options;
+        const makeClient = options.makeClient ?? (() => new Client(base));
+        const authenticate = options.authenticate ?? (client => client.authenticate(token ?? ''));
+        const historyLimits = options.historyLimits ?? DEFAULT_HISTORY_LIMITS;
+        const shellEnabled = options.shellEnabled ?? true;
         this.base = base;
-        this.initialSession = initialSession;
         this.costs = costs;
         this.historyLimits = historyLimits;
-        this.memoryLogPath = memoryLogPath;
-        this.localDirectory = localDirectory;
-        const options = { base, token, initialSession, makeClient, authenticate };
-        this.connection = new ConnectionController(this, options, this);
-        this.session = new SessionController(this, this.connection, this.connection, historyLimits);
+        this.memoryLogPath = options.memoryLogPath;
+        this.localDirectory = options.localDirectory ?? process.cwd();
+        this.initialSession = initialSession;
+        this.loops = new LoopCoordinator({
+            facts: () => ({ sessionId: this.state.sessionId, online: this.state.online,
+                ready: this.state.session.record.ready, busy: this.foregroundSlot.snapshot !== undefined, pending: this.state.pending.length > 0 }),
+            reply: () => latestAssistantText(this.state.session.record.messages),
+            send: prompt => this.session.promptInternal(prompt),
+            publish: failure => this.update(failure === undefined ? {} : { lastFailure: failure }),
+            trace: (event, detail) => this.traceEvent(event, detail),
+        }, { directory: this.localDirectory, verifier: options.verifier, verdictRoot: options.verdictRoot,
+            deadlineMs: options.deadlineMs, allowSelfFallback: options.allowSelfFallback });
+        const connectionOptions = { base, token, initialSession, makeClient, authenticate };
+        this.connection = new ConnectionController(this, connectionOptions, this);
+        // The view follows other sessions over the same connection; it never becomes a second writer.
+        this.peek = new SessionPeek(this.connection);
+        // Every session write is admitted in order; the trace records that order, which is what answers
+        // "who dispatched first" when two mutations of one session compete.
+        this.session = new SessionController(this, this.connection, this.connection, historyLimits, admission => this.traceEvent('mutation', { session: admission.sessionId, lane: admission.lane, waited: admission.waited }));
         this.shell = new ShellController({
             publish: () => this.update({}),
             cwd: () => this.localDirectory,
             env: () => shellEnv(),
             anchor: () => this.state.session.record.readThrough,
         }, shellEnabled);
-        this.catalog = new CatalogController(this, this.connection);
+        this.catalog = new CatalogController({
+            client: () => this.connection.client(), require: () => this.connection.require(),
+            online: () => this.state.online, signal: () => this.connection.signal(),
+            selection: () => ({ revision: this.selection(), sessionId: this.state.sessionId }),
+            publish: patch => this.update(patch),
+        });
         if (costs)
             this.cost = new CostController(costs, {
                 client: () => this.connection.client(),
@@ -86,8 +177,13 @@ export class Controller {
                 scanPage: (sessionId, records) => this.session.rememberScanPage(sessionId, records),
                 scanDone: sessionId => this.session.rememberScanDone(sessionId),
             });
-        if (memoryLogPath !== undefined)
-            this.memoryLog = new MemoryLog(memoryLogPath, () => this.memorySample());
+        if (this.memoryLogPath !== undefined)
+            this.memoryLog = new MemoryLog(this.memoryLogPath, () => this.memorySample());
+        if (options.tracePath !== undefined)
+            this.trace = new TraceLog(options.tracePath);
+        this.promptStore = new PromptStore(options.promptsPath);
+        this.actions = this.buildActions();
+        this.queries = this.buildQueries();
     }
     /** React-compatible state subscription. */
     subscribe = (listener) => {
@@ -97,7 +193,7 @@ export class Controller {
     /** Snapshot identity changes only when the controller publishes. */
     snapshot = () => this.state;
     /** Current projection store; replaced at each connection generation. */
-    get telemetry() { return this.connection.telemetry; }
+    get telemetry() { return this.session.telemetry; }
     /** Record of the selected session; the one strong owner lives in `State.session`. */
     get record() { return this.state.session.record; }
     /** @returns The current selector generation. */
@@ -107,24 +203,221 @@ export class Controller {
     /** Publish a state patch, re-deriving the visible pending interactions.
      * @param patch - Fields to replace on the current state.
      */
+    /** Whether an operation owns the client's foreground slot right now.
+     * @returns True while an operation is running.
+     */
+    busy() { return this.foregroundSlot.snapshot !== undefined; }
     update(patch) {
+        const previous = this.state;
         const next = { ...this.state, ...patch, version: this.state.version + 1 };
         next.pending = next.online && next.screen === 'chat' && this.session
-            ? this.session.pendingFor(next) : [];
+            ? this.session.pendingFor(next.sessionId) : [];
+        // The shell service owns its blocks; state carries only the plain snapshot the UI renders.
+        if (this.shell)
+            next.shell = this.shell.snapshot();
+        // A loop belongs to one session: selecting a different session ends it, but a reconnect — which
+        // transiently clears the selection — must not, or a long review could never finish.
+        if (next.sessionId !== undefined && next.sessionId !== this.state.sessionId && this.loops.sessionId !== next.sessionId) {
+            this.loops.forget();
+            // The read-only view belongs to the conversation that opened it; leaving that conversation
+            // closes it, and the session switch that follows is never left rendering someone else's rows.
+            this.dropPeek();
+        }
         this.state = next;
+        this.traceTransition(previous, next);
         for (const observer of this.observers)
             observer();
+        this.loops.changed();
+    }
+    /** Record one diagnostic event; a no-op when no trace path was configured. */
+    traceEvent(event, detail = {}) {
+        this.trace?.record({ event, ...detail });
+    }
+    /** Record one diagnostic event from outside the controller, such as a UI-only decision.
+     *
+     * The composition root knows things this class cannot see — which record the operator highlighted,
+     * that a form was refused a name — and a start that never reaches `startLoop` is otherwise invisible
+     * in every log. Same no-op contract as the internal call.
+     * @param event - Event name, e.g. `loop-ui`.
+     * @param detail - Identifiers only; never prompt or session text.
+     */
+    traceNote(event, detail = {}) {
+        this.traceEvent(event, detail);
+    }
+    /** Mint the identifier one executed line carries through its `begin` and `end` events.
+     *
+     * Short and process-local on purpose: it exists to pair two lines of one file, not to identify a
+     * line across runs, so a monotonic counter beats a random id a reader would have to match by eye.
+     * @returns The next command id, such as `C17`.
+     */
+    nextCommandId() {
+        this.commandSeq += 1;
+        return `C${this.commandSeq}`;
+    }
+    /** Record the state fields that decide which screen the reader is looking at.
+     *
+     * Every non-user transition is written here as well as at its cause, so a screen that moved
+     * without an expected reason is still visible in the trace rather than silently skipped.
+     * @param previous - State before the patch.
+     * @param next - State after the patch.
+     */
+    traceTransition(previous, next) {
+        if (this.trace === undefined)
+            return;
+        const changed = {};
+        if (previous.screen !== next.screen)
+            changed.screen = `${previous.screen} -> ${next.screen}`;
+        if (previous.sessionId !== next.sessionId)
+            changed.session = `${previous.sessionId ?? 'none'} -> ${next.sessionId ?? 'none'}`;
+        if (previous.workspaceId !== next.workspaceId)
+            changed.workspace = `${previous.workspaceId ?? 'none'} -> ${next.workspaceId ?? 'none'}`;
+        if (previous.online !== next.online)
+            changed.online = next.online;
+        if (Object.keys(changed).length > 0)
+            this.traceEvent('state', changed);
+    }
+    /** Bind every mutating entry point to its private implementation.
+     *
+     * Each one names the kind and label of the operation it performs, because that is now the single
+     * answer to "what owns the client right now" (§6.2): the front end renders it and cancels it, and
+     * nothing else has to know which layer started the work.
+     */
+    buildActions() {
+        return {
+            foreground: (kind, label, work, wait) => this.foregroundSlot.run(kind, label, work, wait),
+            cancelForeground: () => this.foregroundSlot.cancel(),
+            openPeek: id => this.openPeek(id),
+            closePeek: () => this.closePeek(),
+            switchWorkspace: id => this.runAction('navigation', 'Switching workspace…', signal => this.switchWorkspace(id, signal)),
+            switchSession: query => this.runAction('navigation', 'Switching session…', signal => this.switchSession(query, signal)),
+            selectSession: id => this.runAction('navigation', 'Loading session…', () => this.selectSession(id)),
+            createWorkspace: path => this.runAction('navigation', 'Registering workspace…', signal => this.createWorkspace(path, signal)),
+            createSession: () => this.runAction('navigation', 'Creating session…', signal => this.createSession(signal)),
+            createVerifierSession: title => this.runActionValue('verifier', 'Creating verifier session…', () => this.createVerifierSession(title)),
+            cancelVerifierSession: sessionId => this.runImmediateAction(async () => {
+                await this.session.cancelNamedSession(sessionId);
+                // The run is over even though its transcript stays readable; the list should say so.
+                this.endSource(sessionId, Date.now());
+            }),
+            showPicker: screen => this.runAction('picker', 'Listing…', signal => this.showPicker(screen, signal)),
+            removeTarget: target => this.runAction('removal', 'Removing…', () => this.removeTarget(target)),
+            removalTarget: (kind, query) => this.runActionValue('removal', 'Reading target…', () => this.removalTarget(kind, query)),
+            waitForHistory: signal => this.runAction('history', 'Loading history…', () => this.waitForHistory(signal)),
+            searchSessions: (query, workspaceOnly, signal) => this.runActionValue('search', 'Searching sessions…', () => this.searchSessions(query, workspaceOnly, signal)),
+            openHistory: (target, signal) => this.runAction('history', 'Opening history…', operation => this.session.openHistory(target, AbortSignal.any([signal, operation]))),
+            searchHistory: (query, signal) => this.runActionValue('search', 'Searching history…', operation => this.searchHistory(query, AbortSignal.any([signal, operation]))),
+            prompt: text => this.runAction('prompt', 'Sending…', () => this.prompt(text)),
+            handoff: () => this.runAction('handoff', 'Requesting handoff…', () => this.handoff()),
+            startLoop: (protocol, limits) => this.runAction('loop', 'Starting loop…', () => this.loops.start(protocol, limits)),
+            stopLoop: () => this.loops.stop(),
+            clearLoopResult: () => this.loops.clearResult(),
+            answerLoop: text => this.runAction('loop', 'Answering the verifier…', () => this.loops.answer(text)),
+            cancelTurn: () => this.runAction('interaction', 'Cancelling…', () => this.cancelTurn()),
+            answer: value => this.runAction('interaction', 'Answering…', () => this.answer(value)),
+            answerQuestion: input => this.runAction('interaction', 'Answering…', async () => {
+                if (!await this.answerQuestion(input))
+                    throw new Error('The answer could not be sent');
+            }),
+            approve: allowed => this.runAction('interaction', 'Answering…', () => this.approve(allowed)),
+            dismissQuestion: () => this.runAction('interaction', 'Dismissing…', () => this.dismissQuestion()),
+            interrupt: force => this.interrupt(force),
+            older: (signal, transcript) => this.runAction('history', 'Loading history…', operation => this.older(signal === undefined ? operation : AbortSignal.any([signal, operation]), transcript)),
+            historyThrough: (target, signal) => this.runAction('history', 'Loading history…', operation => this.historyThrough(target, AbortSignal.any([signal, operation]))),
+            removeQueued: itemId => this.runAction('command', 'Removing queued input…', () => this.removeQueued(itemId)),
+            savePrompt: text => this.runImmediateAction(async () => {
+                await this.promptStore.save(text);
+                this.update({ lastFailure: '' });
+            }),
+            updatePrompt: (id, text) => this.runImmediateAction(async () => {
+                if (!await this.promptStore.update(id, text))
+                    throw new Error('That saved prompt no longer exists');
+                this.update({ lastFailure: '' });
+            }),
+            deletePrompt: id => this.runImmediateAction(async () => {
+                if (!await this.promptStore.remove(id))
+                    throw new Error('That saved prompt no longer exists');
+                this.update({ lastFailure: '' });
+            }),
+            command: (line, signal) => this.runActionValue('command', 'Running command…', () => this.command(line, signal)),
+            exportLog: (path, signal) => this.runActionValue('export', 'Exporting session log…', () => this.exportLog(path, signal)),
+            exportHtml: (path, signal) => this.runActionValue('export', 'Exporting conversation…', () => this.exportHtml(path, signal)),
+            selectModel: (provider, model, effort) => this.runAction('model', 'Selecting model…', signal => this.catalog.selectModel(provider, model, effort, signal)),
+            modelCatalog: () => this.runActionValue('model', 'Loading models…', signal => this.catalog.modelCatalog(signal)),
+            refreshCosts: signal => this.runAction('cost', 'Refreshing costs…', operation => this.refreshCosts(signal === undefined ? operation : AbortSignal.any([signal, operation]))),
+            loadPresetNames: () => this.loadPresetNames(),
+            clearFailure: () => this.clearFailure(),
+            enterPath: () => this.enterPath(),
+            pickWorkspace: id => this.pickWorkspace(id),
+            showChat: () => this.showChat(),
+            showLatest: () => this.session.setViewWindow(undefined),
+            pinHistory: pinned => this.pinHistory(pinned),
+            setAnswers: answers => this.setAnswers(answers),
+            setOption: option => this.setOption(option),
+            setApproval: approval => this.setApproval(approval),
+            recordRecall: value => this.recordRecall(value),
+            resetRecall: () => this.resetRecall(),
+            refillRecall: () => this.refillRecall(),
+            heapSnapshot: tag => this.heapSnapshot(tag),
+        };
+    }
+    /** Bind every read-only entry point; getters stay live because the values move between renders. */
+    buildQueries() {
+        const controller = this;
+        return {
+            get running() { return controller.running; },
+            get turnsCompleted() { return controller.completedTurns; },
+            get forkedVerification() { return controller.loops.forkedVerification; },
+            get selfScoring() { return controller.loops.selfScoring; },
+            get connectionSettled() { return controller.connectionSettled; },
+            get sessionName() { return controller.sessionName; },
+            get sessionMode() { return controller.sessionMode; },
+            get workingSince() { return controller.workingSince; },
+            get visibleSessions() { return controller.visibleSessions; },
+            get record() { return controller.record; },
+            get window() { return controller.window; },
+            get interaction() { return controller.interaction; },
+            get telemetry() { return controller.telemetry.reader; },
+            get recallAtOldest() { return controller.recallAtOldest; },
+            get recallLength() { return controller.recallLength; },
+            get recallHasOlder() { return controller.recallHasOlder; },
+            get prompts() { return controller.promptStore.list; },
+            get promptsError() { return controller.promptStore.error; },
+            get loop() { return controller.loops.progress; },
+            get foreground() { return controller.foregroundSlot.snapshot; },
+            get sources() { return controller.outputSources(); },
+            get peek() { return controller.peekSnapshot(); },
+            get activity() { return controller.activity; },
+            get loopRecords() { return listLoopRecords(); },
+            pendingCounts: () => controller.pendingCounts(),
+            recall: (direction, current) => controller.recall(direction, current),
+            references: (query, signal) => controller.references(query, signal),
+            render: input => controller.render(input),
+        };
     }
     /** Start one retry loop, with a fresh snapshot generation after every disconnect. */
-    start() { this.connection.start(); this.memoryLog?.start(); }
+    start() {
+        this.connection.start();
+        this.memoryLog?.start();
+        // Reading the shortcuts file is local and may finish after the first paint. Nothing is
+        // republished for an empty list: the picker reads the live list when it opens, so a load that
+        // found nothing must not add a render to an unrelated interaction.
+        void this.promptStore.load().then(changed => { if (changed)
+            this.update({}); });
+    }
     /** Cancel retries and HTTP, close the socket, and release session and catalog work. */
     async stop() {
+        // Nobody waits forever for a slot that will never be handed out again.
+        this.foregroundSlot.close();
+        this.catalog.close();
+        await this.loops.close();
+        this.dropPeek();
         await this.shell.stop();
         await this.connection.stop();
         await this.session.settle();
         await this.catalog.settle();
         await this.cost?.stop();
         await this.memoryLog?.stop();
+        await this.trace?.settle();
         this.session.release();
     }
     /** Stop the selected turn and then close, so quitting does not leave host work running.
@@ -135,25 +428,61 @@ export class Controller {
             await this.session.interrupt(true);
         await this.stop();
     }
-    /** Run a UI operation and expose errors without destroying the current input.
+    /** Run one mutating operation inside the client's single foreground slot.
+     *
+     * Private on purpose: the application owns the slot, so a caller never hands the controller a
+     * closure to orchestrate. Every entry of `actions` uses it, and `actions.foreground` is the one
+     * door left open for work the front end orchestrates itself.
+     * @param kind - What the operation is, for the label and the trace.
+     * @param label - Human label shown while it runs.
      * @param operation - Operation to run while the client is busy.
-     * @returns Whether the operation completed.
+     * @returns Whether the operation ran to completion.
      */
-    async perform(operation) {
-        if (this.state.busy || !this.state.online)
+    async runAction(kind, label, operation) {
+        if (!this.state.online) {
+            this.update({ lastFailure: 'Not connected. Try again after reconnecting.' });
             return false;
-        this.update({ busy: true, error: '' });
+        }
+        return await this.foregroundSlot.run(kind, label, async (signal) => {
+            try {
+                await operation(signal);
+                return true;
+            }
+            catch (error) {
+                this.update({ lastFailure: errorText(error) });
+                return false;
+            }
+        }) === true;
+    }
+    /** Same slot, for an operation that produces a value the caller needs. */
+    async runActionValue(kind, label, operation) {
+        if (!this.state.online) {
+            this.update({ lastFailure: 'Not connected. Try again after reconnecting.' });
+            return undefined;
+        }
+        return await this.foregroundSlot.run(kind, label, async (signal) => {
+            try {
+                return await operation(signal);
+            }
+            catch (error) {
+                this.update({ lastFailure: errorText(error) });
+                return undefined;
+            }
+        });
+    }
+    /** Run outside the foreground slot, with the same application failure reporting.
+     * Local prompt edits need no connection; verifier cancellation uses the session control lane and
+     * must reach the host even while the foreground is busy or closed for shutdown.
+     */
+    async runImmediateAction(operation) {
         try {
             await operation();
             return true;
         }
         catch (error) {
-            this.update({ error: errorText(error) });
+            this.update({ lastFailure: errorText(error) });
             return false;
         }
-        finally {
-            this.update({ busy: false });
-        }
     }
     /** Read the counters one memory sample records; content never leaves as text.
      *
@@ -211,92 +540,279 @@ export class Controller {
     }
     /** A new generation starts; drop generation-scoped domain state. */
     begin() {
+        this.traceEvent('generation', { phase: 'begin', screen: this.state.screen, session: this.state.sessionId ?? 'none' });
         this.session.beginGeneration();
         this.catalog.reset();
+        this.connectionSettled = false;
+        // A busy state does not survive the connection it was observed on.
+        this.busySessions.clear();
         this.update({ controlError: undefined });
     }
     /** The event stream is ready and the control baseline is applied. */
     async ready() {
+        this.update({ online: true, status: 'Connected', pending: [], lastFailure: '' });
         this.catalog.refresh();
-        this.update({ online: true, status: 'Connected', error: '', pending: [] });
         const screen = this.state.screen;
-        await this.session.showPicker(screen === 'sessions' ? 'sessions' : 'workspaces');
-        // Starting inside a registered workspace's directory already answers the first question, so the
-        // reader lands on that workspace's sessions instead of a list they would pick from by hand.
-        if (screen !== 'sessions' && !this.initialSession && this.session.adoptLocalWorkspace(this.localDirectory) !== undefined) {
-            this.update({ status: 'Workspace from this directory · ← to switch' });
+        this.traceEvent('generation', { phase: 'ready', screen });
+        this.traceEvent('navigation-refresh', { screen });
+        await this.session.refreshLists();
+        // Startup may choose the local workspace. Reconnect only refreshes data: it must not reinterpret
+        // the reader's current screen as a request to navigate or discard a selected conversation.
+        if (!this.initialized && this.state.screen === 'workspaces' && !this.state.sessionId && !this.initialSession) {
+            const adopted = this.session.adoptLocalWorkspace(this.localDirectory);
+            this.traceEvent('adopt', { directory: this.localDirectory, workspace: adopted ?? 'none' });
+            if (adopted !== undefined)
+                this.update({ status: 'Workspace from this directory · ← to switch' });
         }
-        const sessionId = this.state.sessionId ?? this.initialSession;
-        if (sessionId && (screen === 'chat' || this.initialSession && !this.state.sessionId))
+        const selected = this.state.sessionId;
+        const sessionId = selected ?? this.loops.sessionId ?? (!this.initialized ? this.initialSession : undefined);
+        this.traceEvent('resolve', { session: sessionId ?? 'none', looping: this.loops.sessionId ?? 'none', reselect: sessionId !== undefined });
+        if (selected !== undefined)
+            this.session.restoreSelectedSession();
+        else if (sessionId !== undefined)
             await this.session.selectSession(sessionId);
+        this.initialized = true;
+        // `online` means the socket works; `connectionSettled` means the picker and the selection are
+        // done, which is what an automation caller must wait for or it races `showPicker`.
+        this.connectionSettled = true;
+        this.update({});
+        this.traceEvent('generation', { phase: 'settled', screen: this.state.screen, session: this.state.sessionId ?? 'none' });
         this.cost?.start();
     }
-    /** The generation ended; invalidate session work and stop the scan. */
+    /** The generation ended; invalidate session work and stop the scan.
+     *
+     * A running loop is deliberately left alone: the host keeps running the review, and the client
+     * re-selects the same session after reconnecting, so only a switch to another session ends it.
+     */
     async ended() {
+        this.traceEvent('generation', { phase: 'ended', screen: this.state.screen, session: this.state.sessionId ?? 'none' });
         this.session.endGeneration();
         await this.cost?.stop();
     }
-    /** Deliver a host waterfall to the session domain.
-     * @param frame - One decoded waterfall frame.
-     * @returns Whether the session domain retained it.
-     */
-    waterfall(frame) { return this.session.waterfall(frame); }
-    /** Drop a waterfall the host cancelled.
-     * @param eventId - Correlation id previously retained.
-     */
-    cancelled(eventId) { this.session.cancelled(eventId); }
-    /** Apply one host running-state notification.
-     * @param sessionId - Session whose state changed.
-     * @param running - Whether the host still runs that session.
-     */
-    status(sessionId, running) { this.session.status(sessionId, running); }
-    /** Surface a host-reported session error.
-     * @param sessionId - Session the host reported on.
-     * @param error - Error payload as delivered by the host.
-     */
-    error(sessionId, error) { this.session.reportError(sessionId, error); }
-    /** Reload the model catalog after a host settings, credential or adapter change. */
-    invalidated() { this.catalog.refresh(); }
-    /** Refresh billing after a turn finished. */
-    idle() { this.cost?.onTurnIdle(); }
+    /** Route one normalized host event to the domain that owns it.
+     *
+     * This is the composition point: the connection knows only that an event arrived, so a feature
+     * never has to hold another feature. `false` means the host's waterfall is still unsettled.
+     * @param event - Normalized host event.
+     * @returns Whether a retained waterfall was consumed.
+     */
+    event(event) {
+        switch (event.kind) {
+            case 'approval-request':
+            case 'question-request': return this.session.accept(event);
+            case 'waterfall-delegate': return false;
+            case 'cancel':
+                this.session.cancelled(event.eventId);
+                return true;
+            case 'agent-status':
+                this.session.status(event.sessionId, event.running);
+                if (event.running)
+                    this.busySessions.add(event.sessionId);
+                else {
+                    // Only a turn this client watched start counts as finished. A replayed or duplicated idle
+                    // frame would otherwise look like a prompt completing, which `--wait` would trust.
+                    const started = this.busySessions.delete(event.sessionId);
+                    if (started && event.sessionId === this.state.sessionId)
+                        this.completedTurns += 1;
+                    this.cost?.onTurnIdle();
+                    this.loops.idle(event.sessionId);
+                }
+                return true;
+            case 'catalog-invalidated':
+                this.catalog.refresh();
+                return true;
+            case 'session-error':
+                this.session.reportError(event.sessionId, event.error);
+                return true;
+            case 'control':
+                this.session.acceptControl(event.frame);
+                return true;
+        }
+    }
     /** @returns Host running state of the selected session. */
     get running() { return this.session.running; }
     /** @returns Current session title, falling back to the list title and then the ID. */
     get sessionName() { return this.session.sessionName; }
     /** @returns Current agent-preset label. */
-    get sessionMode() { return this.session.sessionMode; }
+    get sessionMode() { return this.session.sessionMode(this.state.presets); }
     /** @returns Epoch start of the active turn, when known. */
     get workingSince() { return this.session.workingSince; }
+    /** What the client is doing right now, merged across the host turn and any running loop.
+     *
+     * This is the controller's answer, not a view's guess: a turn speaks for the session while it runs,
+     * otherwise a live loop speaks for itself with its own sub-state and clock, and neither means idle.
+     * @returns The activity, or undefined when nothing is in flight.
+     */
+    get activity() {
+        if (this.running) {
+            return { kind: 'turn', ...(this.workingSince === undefined ? {} : { since: this.workingSince }) };
+        }
+        const progress = this.loops.progress;
+        if (progress === undefined || !progress.active)
+            return undefined;
+        // A paused run is still the client's work, but nothing is running: the bar must ask for the reader
+        // rather than claim a clock.
+        if (progress.phase === 'needs-human') {
+            return { kind: 'paused', title: progress.title, step: progress.step, total: progress.total };
+        }
+        if (progress.activity === undefined)
+            return undefined;
+        return { kind: 'loop', activity: progress.activity, title: progress.title,
+            step: progress.step, total: progress.total, startedAt: progress.startedAt };
+    }
     /** @returns Sessions accounted to the selected workspace, minus archived identities. */
     get visibleSessions() { return this.session.visibleSessions; }
+    /** Every readable output source, newest activity first.
+     *
+     * Three origins feed one list, because a reader asking "what is that session" does not care which
+     * layer knows about it: sessions this client created (the host cannot record that link), local `!`
+     * runs it already holds, and host-created subagent children, whose only lineage is their list row.
+     * A client-created source wins over the list row for the same session, since it says more.
+     * @returns Sources to offer, running ones first.
+     */
+    outputSources() {
+        const sources = [];
+        const seen = new Set();
+        for (const [id, source] of this.createdSources) {
+            sources.push(source);
+            seen.add(id);
+        }
+        for (const block of this.state.shell.blocks) {
+            // A note runs nothing: it is a bar pointing at another source, which is listed on its own.
+            if (block.kind !== 'shell')
+                continue;
+            const id = localSourceId(block.id);
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            sources.push({
+                id, kind: 'local', label: `! ${block.command}`,
+                state: block.status === 'running' ? 'running' : 'ended',
+                startedAt: block.startedAt,
+                ...(block.endedAt === undefined ? {} : { endedAt: block.endedAt }),
+                createdBy: 'shell',
+                ...(this.state.sessionId === undefined ? {} : { parentSessionId: this.state.sessionId }),
+            });
+        }
+        for (const row of this.visibleSessions) {
+            const sessionId = string(row.sessionId);
+            const parent = typeof row.parentSessionId === 'string' ? row.parentSessionId : '';
+            if (sessionId === '' || parent === '' || row.origin !== 'subagent' || seen.has(sessionId))
+                continue;
+            seen.add(sessionId);
+            sources.push({
+                id: sessionId, kind: 'session', label: sessionLabel(row), state: 'ended',
+                ...(typeof row.updatedAt === 'number' ? { startedAt: row.updatedAt } : {}),
+                createdBy: 'agent', parentSessionId: parent,
+            });
+        }
+        return sources.sort((a, b) => a.state === b.state
+            ? (b.startedAt ?? 0) - (a.startedAt ?? 0)
+            : a.state === 'running' ? -1 : 1);
+    }
+    /** Register a session this client created for a verifier, so the list can explain it. */
+    async createVerifierSession(title) {
+        const sessionId = await this.session.createNamedSession(title);
+        if (sessionId === undefined)
+            return undefined;
+        const parent = this.state.sessionId;
+        this.createdSources.set(sessionId, {
+            id: sessionId, kind: 'session', label: verifierLabel(title), state: 'running', startedAt: Date.now(),
+            createdBy: 'verifier',
+            ...(parent === undefined ? {} : { parentSessionId: parent }),
+            ...(this.loops.verifierName === undefined ? {} : { detail: `verifier ${this.loops.verifierName}` }),
+        });
+        // The bar the run echoed into the transcript now opens this session, which is the newest check.
+        this.shell.link(sessionId);
+        // A long-lived client runs many reviews; the registry is a convenience list, not a ledger, and a
+        // dropped session is still reachable by selecting it. Insertion order is the age order.
+        while (this.createdSources.size > SOURCE_LIMIT) {
+            const oldest = this.createdSources.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.createdSources.delete(oldest);
+        }
+        this.update({});
+        return sessionId;
+    }
+    /** Mark a source this client created as finished, keeping it readable. */
+    endSource(id, at) {
+        const source = this.createdSources.get(id);
+        if (source === undefined || source.state === 'ended')
+            return;
+        this.createdSources.set(id, { ...source, state: 'ended', endedAt: at });
+        this.update({});
+    }
+    /** Open one source read-only at full screen; a session source starts following it. */
+    openPeek(id) {
+        const source = this.outputSources().find(candidate => candidate.id === id);
+        if (source === undefined || this.peekId === id)
+            return;
+        this.peekId = id;
+        this.traceEvent('peek begin', { source: id, kind: source.kind });
+        if (source.kind === 'session') {
+            const row = this.visibleSessions.find(candidate => string(candidate.sessionId) === id);
+            // The list row is the only place that knows a child needs its parent in the address.
+            this.peek.open(row === undefined ? [{ kind: 'session', sessionId: id }] : costAddresses(row), () => this.update({}));
+        }
+        this.update({});
+    }
+    /** Close the read-only view and release whatever it followed. */
+    closePeek() {
+        if (this.peekId === undefined)
+            return;
+        this.traceEvent('peek end', { source: this.peekId });
+        this.peek.close();
+        this.peekId = undefined;
+        this.update({});
+    }
+    /** Release the view without publishing; the caller is already inside an update. */
+    dropPeek() {
+        if (this.peekId === undefined)
+            return;
+        this.traceEvent('peek end', { source: this.peekId });
+        this.peek.close();
+        this.peekId = undefined;
+    }
+    /** What the read-only view renders, or undefined while it is closed. */
+    peekSnapshot() {
+        if (this.peekId === undefined)
+            return undefined;
+        const source = this.outputSources().find(candidate => candidate.id === this.peekId);
+        if (source === undefined)
+            return undefined;
+        if (source.kind === 'local') {
+            const block = this.state.shell.blocks.find(candidate => `shell:${candidate.id}` === source.id);
+            return { source, lines: block?.lines ?? [] };
+        }
+        const followed = this.peek.snapshot;
+        if (followed === undefined)
+            return { source };
+        return { source, transcript: followed.transcript, ...(followed.error === undefined ? {} : { error: followed.error }) };
+    }
     /** @returns Unanswered interactions by session, for the state each list row reports. */
     pendingCounts() { return this.session.pendingCounts(); }
     /** Load the optional preset roster once per connection. */
     loadPresetNames() { this.catalog.loadPresetNames(); }
-    /** @returns Host model routes and adapter-owned reasoning choices. */
-    async modelCatalog() { return this.catalog.modelCatalog(); }
-    /** Select the next request's model.
-     * @param provider - Host provider route ID.
-     * @param model - Exact model ID.
-     * @param reasoningEffort - Optional adapter-owned effort ID.
-     */
-    async selectModel(provider, model, reasoningEffort) {
-        await this.catalog.selectModel(provider, model, reasoningEffort);
-    }
     /** Stop the selected turn, or allow exit only while idle.
      * @param force - Send an explicit cancellation even when the cached running flag is idle.
      * @returns True when the caller may exit.
      */
-    interrupt(force = false) { return this.session.interrupt(force); }
-    /** One-line estimate of the selected session's cost, or `?` while the ledger has no entry for it. */
-    get sessionCostText() {
-        const sessionId = this.state.sessionId;
-        return this.costs?.hasSession(sessionId) ? costText(this.costs.total(sessionId)) : '?';
+    interrupt(force = false) {
+        // Esc and Ctrl+C stop the automated loop as well as the turn; otherwise it would keep sending.
+        this.loops.stop();
+        return this.session.interrupt(force);
     }
+    /** One-line estimate of the selected session's cost, or `?` while the ledger has no entry for it. */
     /** Keep history stable while the user reads, searches, or expands it.
      * @param pinned - Whether the main transcript is being read away from its tail.
      */
     pinHistory(pinned) { this.session.pinHistory(pinned); }
+    /** @returns The detached history window the reader opened, if any. */
+    get window() { return this.session.window; }
+    /** Show a detached history window, releasing the one it replaces.
+     * @param window - Record to display, or undefined to return to the live transcript.
+     */
     /** Recall one step through the selected session's prompt index; never touches the network.
      * @param direction - Negative for older input, positive for newer input.
      * @param current - Composer content before recall began, restored at the newest position.
@@ -319,45 +835,17 @@ export class Controller {
      * @returns Whether any older prompt was recovered.
      */
     refillRecall() { return this.session.refillRecall(); }
-    /** Composer draft, caret and parked draft of the selected session. */
-    get composer() { return this.session.composer; }
-    /** Replace the composer text and caret.
-     * @param draft - New text.
-     * @param cursor - Caret column; defaults to the end of the text.
-     */
-    setComposer(draft, cursor) { this.session.setComposer(draft, cursor); }
-    /** Move the caret without changing the text.
-     * @param cursor - Caret column.
-     */
-    setComposerCursor(cursor) { this.session.setComposerCursor(cursor); }
-    /** Move a non-empty draft aside while a dialog owns the keyboard. */
-    parkComposer() { this.session.parkComposer(); }
-    /** Give a parked draft back once no dialog needs the keyboard. */
-    restoreComposer() { this.session.restoreComposer(); }
-    /** How the selected session's record is being read right now. */
-    get view() { return this.session.view; }
-    /** Show a detached history window, releasing the one it replaces.
-     * @param window - Record to display, or undefined to return to the live transcript.
-     */
-    setViewWindow(window) { this.session.setViewWindow(window); }
-    /** Move the reader's position inside the displayed record.
-     * @param scroll - Rows scrolled back from the live end.
-     */
-    setScroll(scroll) { this.session.setScroll(scroll); }
-    /** Replace the set of expanded reasoning blocks.
-     * @param folds - Sequences to expand beyond the default fold.
-     */
-    setFolds(folds) { this.session.setFolds(folds); }
-    /** Set the fold mode of the live attempt's completed reasoning.
-     * @param reasoning - `row` to fold, `full` to keep the streamed text.
-     */
-    setLiveReasoning(reasoning) { this.session.setLiveReasoning(reasoning); }
     /** Local answer state for the selected session's pending waterfalls. */
     get interaction() { return this.session.interaction; }
     /** Replace the partly collected answers, keyed by waterfall event id.
      * @param answers - Answers collected so far, by event id.
      */
     setAnswers(answers) { this.session.setAnswers(answers); }
+    /** Clear the internal last failure; a no-op when there is none. */
+    clearFailure() {
+        if (this.state.lastFailure !== '')
+            this.update({ lastFailure: '' });
+    }
     /** Replace the pending question's option keyboard state.
      * @param option - Highlighted option, toggled labels and free-text mode; undefined clears it.
      */
@@ -366,38 +854,6 @@ export class Controller {
      * @param approval - Selected approval row; undefined clears the highlight.
      */
     setApproval(approval) { this.session.setApproval(approval); }
-    /** Composer-adjacent `@` reference menu state. */
-    get reference() { return this.session.reference; }
-    /** Highlight one row of the open reference menu.
-     * @param index - Row index into the current matches.
-     */
-    setReferenceIndex(index) { this.session.setReferenceIndex(index); }
-    /** Remember the draft that dismissed the reference menu.
-     * @param draft - Composer text at dismissal, or undefined to allow the menu again.
-     */
-    setReferenceDismissed(draft) { this.session.setReferenceDismissed(draft); }
-    /** Panels the selected session has open. */
-    get panels() { return this.session.panels; }
-    /** Show or hide the reasoning panel.
-     * @param open - Whether `/think` is open.
-     */
-    openThoughts(open) { this.session.openThoughts(open); }
-    /** Show or hide the pending-input panel.
-     * @param open - Whether `/queue` is open.
-     */
-    openQueue(open) { this.session.openQueue(open); }
-    /** Show the model dialog at one step, or close it.
-     * @param model - Catalog plus the provider or model being inspected; undefined closes the dialog.
-     */
-    setModelPanel(model) { this.session.setModelPanel(model); }
-    /** Show the history or content-search dialog, or close it.
-     * @param history - Query, content-search mode and matches; undefined closes the dialog.
-     */
-    setHistoryPanel(history) { this.session.setHistoryPanel(history); }
-    /** Show the host session-search results, or close them.
-     * @param search - Query, results and truncation flag; undefined closes the dialog.
-     */
-    setSearchPanel(search) { this.session.setSearchPanel(search); }
     /** Refresh all HTTP-visible sessions without changing the selected conversation.
      * @param signal - Optional cancellation for an explicit /cost refresh.
      */
@@ -405,7 +861,10 @@ export class Controller {
     /** Refresh both lists from the host, then show the requested picker.
      * @param screen - Picker to display after the refresh.
      */
-    async showPicker(screen) { await this.session.showPicker(screen); }
+    async showPicker(screen, signal) {
+        this.traceEvent('action', { action: 'showPicker', screen });
+        await this.session.showPicker(screen, signal);
+    }
     /** Resolve a removal command to one reviewable object.
      * @param kind - Workspace registration removal or session archival.
      * @param query - Exact name, ID, or unambiguous ID prefix.
@@ -415,31 +874,63 @@ export class Controller {
     /** Apply a confirmed removal or verified empty-session archival.
      * @param target - Exact workspace or session identity reviewed by the user.
      */
-    async removeTarget(target) { await this.session.removeTarget(target); }
+    async removeTarget(target) {
+        this.traceEvent('action', { action: 'removeTarget', kind: target.kind, id: target.id });
+        await this.session.removeTarget(target);
+    }
     /** Pick a workspace, or use all sessions when the identity is omitted.
      * @param workspaceId - Workspace to select, if any.
      */
-    pickWorkspace(workspaceId) { this.session.pickWorkspace(workspaceId); }
+    pickWorkspace(workspaceId) {
+        this.traceEvent('action', { action: 'pickWorkspace', workspace: workspaceId ?? 'none' });
+        this.session.pickWorkspace(workspaceId);
+    }
+    /** Leave a picker and return to the selected conversation, without reloading it.
+     * @returns Whether there was a selected conversation to return to.
+     */
+    showChat() {
+        const shown = this.session.showChat();
+        this.traceEvent('action', { action: 'showChat', shown });
+        return shown;
+    }
     /** Open a workspace picker, or resolve a workspace target.
      * @param query - Workspace target, if any.
      */
-    async switchWorkspace(query) { await this.session.switchWorkspace(query); }
+    async switchWorkspace(query, signal) {
+        this.traceEvent('action', { action: 'switchWorkspace', query: query ?? 'picker' });
+        await this.session.switchWorkspace(query, signal);
+    }
     /** Guide session selection, list all sessions with `all`, or resolve a target.
      * @param query - Session target, `all`, or nothing for the guided picker.
      */
-    async switchSession(query) { await this.session.switchSession(query); }
+    async switchSession(query, signal) {
+        this.traceEvent('action', { action: 'switchSession', query: query ?? 'picker' });
+        await this.session.switchSession(query, signal);
+    }
     /** Prompt for a host path without starting a local agent. */
-    enterPath() { this.session.enterPath(); }
+    enterPath() {
+        this.traceEvent('action', { action: 'enterPath' });
+        this.session.enterPath();
+    }
     /** Register a host directory and move to its session picker.
      * @param path - Absolute directory path on the host.
      */
-    async createWorkspace(path) { await this.session.createWorkspace(path); }
+    async createWorkspace(path, signal) {
+        this.traceEvent('action', { action: 'createWorkspace', path });
+        await this.session.createWorkspace(path, signal);
+    }
     /** Create a session in the selected workspace. */
-    async createSession() { await this.session.createSession(); }
+    async createSession(signal) {
+        this.traceEvent('action', { action: 'createSession', workspace: this.state.workspaceId ?? 'none' });
+        await this.session.createSession(signal);
+    }
     /** Replace the selected transcript and follow the session.
      * @param sessionId - Session to follow.
      */
-    async selectSession(sessionId) { await this.session.selectSession(sessionId); }
+    async selectSession(sessionId) {
+        this.traceEvent('action', { action: 'selectSession', session: sessionId });
+        await this.session.selectSession(sessionId);
+    }
     /** Wait for the selected follow snapshot.
      * @param signal - Cancels waiting without closing the session.
      */
@@ -487,11 +978,30 @@ export class Controller {
      */
     heapSnapshot(tag) { return writeHeapSnapshot(process.cwd(), tag); }
     /** Admit text once as steering while running, or a new turn while idle.
+     *
+     * Text the operator typed ends an automated review: the loop must not race a human for the turn,
+     * and the reply it would parse is no longer the reply to its own prompt.
      * @param text - Composed prompt text.
      */
-    async prompt(text) { await this.session.prompt(text); }
+    async prompt(text) {
+        this.loops.stop();
+        await this.session.prompt(text);
+    }
+    /** Clear this client's stale handoff file, then ask the agent to write a new one.
+     *
+     * The deletion happens first and on this machine, so a handoff that never gets written cannot be
+     * mistaken for the previous one. The request itself is an ordinary turn: it steers a running
+     * agent and starts an idle one, exactly like submitted text.
+     */
+    async handoff() {
+        await removeFile(join(this.localDirectory, HANDOFF_FILE));
+        await this.session.promptInternal(HANDOFF_PROMPT);
+    }
     /** Cancel the active turn; pending queue items remain host-owned. */
-    async cancelTurn() { await this.session.cancelTurn(); }
+    async cancelTurn() {
+        this.loops.stop();
+        await this.session.cancelTurn();
+    }
     /** Add a page before the retained window.
      * @param signal - Cancels local paging without interrupting the remote agent.
      * @param transcript - Transcript to extend; defaults to the live one.
@@ -503,21 +1013,57 @@ export class Controller {
      * @returns Newest-first bounded summaries and an explicit truncation flag.
      */
     async searchHistory(query, signal) { return this.session.searchHistory(query, signal); }
-    /** Load a separate small window ending at a search target.
-     * @param target - Durable message sequence to display.
-     * @param signal - Cancels the target-page request.
-     * @returns A caller-owned historical window that must be disposed when closed.
-     */
-    async historyAt(target, signal) { return this.session.historyAt(target, signal); }
+    /** Plain rows and offsets for one laid-out record; the projection stays in the session domain. */
+    render(input) {
+        return this.session.render(input);
+    }
     /** Load the prefix required for an explicit history jump.
      * @param target - Visible record sequence, or first for the oldest available history.
      * @param signal - Cancels local paging without interrupting the remote agent.
      */
     async historyThrough(target, signal) { await this.session.historyThrough(target, signal); }
     /** Answer the oldest selected-session interaction, after explicit user action.
-     * @param value - Structured answer value or approval outcome.
+     * @param value - Structured answer collected by the UI.
      */
     async answer(value) { await this.session.answer(value); }
+    /** Answer the current sub-question of the pending set, advancing the waterfall or sending it.
+     *
+     * The waterfall is interaction state of the session — which sub-question is current follows from the
+     * answers collected so far, and the ticked labels live in the option state — so it belongs here
+     * rather than in a front end. Both entry points then complete a question the same way: a line the
+     * operator typed as an answer, and the option keys.
+     * @param input - Labels chosen for this sub-question, or free text the operator typed.
+     * @returns True once the answer was recorded or sent; a host refusal throws, leaving the collected
+     *   answers in place so the same submission can be retried.
+     */
+    async answerQuestion(input = {}) {
+        const pending = this.state.pending[0];
+        if (pending?.kind !== 'question')
+            throw new Error('No pending question');
+        const interaction = this.state.session.interaction;
+        const answers = interaction.answers[pending.eventId] ?? [];
+        const question = pending.questions[answers.length];
+        if (question === undefined)
+            throw new Error('The pending question has changed');
+        // A typed answer keeps whatever is ticked for a multi-select question; a picked option is explicit.
+        const selected = input.selected ?? (question.multiSelect === true ? interaction.option?.selected ?? [] : []);
+        const answer = { id: question.id, selected: [...selected], ...(input.custom ? { custom: input.custom } : {}) };
+        const next = [...answers, answer];
+        if (next.length < pending.questions.length) {
+            this.setAnswers({ ...interaction.answers, [pending.eventId]: next });
+            this.setOption(undefined);
+            return true;
+        }
+        // A rejected submission keeps the collected answers and the keyboard state, so the reader can
+        // retry the same answer instead of rebuilding it: a refusal throws out of here before the
+        // collected answers are dropped.
+        await this.answer({ answers: next });
+        const rest = { ...interaction.answers };
+        delete rest[pending.eventId];
+        this.setAnswers(rest);
+        this.setOption(undefined);
+        return true;
+    }
     /** Approve or reject the pending approval request.
      * @param allowed - Whether the request is approved once.
      */