@itookit/dsht 0.3.7 → 0.5.1

package/dist/controller/controller.js

@@ -1,30 +1,85 @@
 /** Application facade: composes the connection, session, catalog and cost domains. */
+import { join } from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
 import { Client } from "../transport/client.js";
-import { writeHeapSnapshot } from "../storage/index.js";
-import { errorText } from "../transport/wire.js";
+import { listEntries, readText, 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 { TraceLog } from "./trace-log.js";
+import { PromptStore } from "./prompts.js";
+import { latestAssistantText, parseLoopResult, ScoredLoop } from "./loop.js";
+import { findingsLines } from "./loop-contract.js";
+import { loopRecords as listLoopRecords } from "./loop-protocols.js";
+import { verificationId, verdictFile } from "./verifier.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, 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
+ * token in its query string. Commands therefore run with the operator's environment, not this
+ * client's session.
+ * @returns A copy of the environment safe to hand to a child process.
+ */
+function shellEnv() {
+    const env = { ...process.env };
+    delete env.DSH_TOKEN;
+    delete env.DSH_URL;
+    return env;
+}
+/** How many times a verifier outage is retried before the run reports verification unavailable. */
+const VERIFIER_RETRIES = 2;
+/** 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();
+}
+/** How long a finished turn may take to commit its final assistant message.
+ *
+ * The host reports the turn idle just before that message reaches the follow stream, so a single
+ * parse can miss the result block that decides the attempt. Waiting too long only delays a reply
+ * that never complies, while deciding too early spends an attempt the reviewer never got.
+ */
+const LOOP_SETTLE_GRACE_MS = 4000;
+/** 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;
@@ -36,20 +91,125 @@ 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;
+    /** Running agent loop, if any; the loop lives here, not in the UI. */
+    loop;
+    /** Prompt the loop still has to send, when it could not be sent immediately. */
+    loopPrompt;
+    /** 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();
+    /** When the in-flight attempt's turn ended, while its result block is still awaited. */
+    loopEndedAt;
+    /** Timer that settles an attempt whose reply never commits its result block. */
+    loopSettleTimer;
+    /** Whether an attempt is currently being judged by an independent verifier. */
+    loopVerifying = false;
+    /** A verdict is being consumed right now.
+     *
+     * Consuming one reads the artifact, so it is asynchronous; without this gate a replayed idle edge
+     * could start a second verification of an attempt whose verdict is already being applied.
+     */
+    loopSettling = false;
+    /** Cancels that verification when the loop is stopped or replaced. */
+    loopVerifyAbort;
+    /** Verdict of the previous attempt on the current step, for the retry and the next verifier. */
+    loopPrevious;
+    /** Identity of the run in flight, so its verdicts are isolated from every other run's. */
+    loopRunId;
+    /** Whether the run in flight already wrote its `loop end`; one end per begin (I9). */
+    loopEndTraced = false;
+    /** Sequence of the verification task in flight, so a retry never reuses the old task's identity. */
+    loopVerifySeq = 0;
+    /** Identity of the verification task whose result may still decide the attempt in flight. */
+    loopVerifyIdentity;
+    /** Timer that stops the whole run when its budget expires. */
+    loopDeadlineTimer;
+    /** Whole-run budget, when the operator set one. */
+    deadlineMs;
+    /** Consecutive verifier outages in this attempt, so a broken verifier is retried then reported. */
+    loopVerifierMisses = 0;
+    /** What the operator answered when a verifier abstained; consumed by the next judgment. */
+    loopAnswer;
+    /** Whether a reply block may stand in for a missing verdict; off unless asked for. */
+    allowSelfFallback;
+    /** Client-side directory verdict files are written under. */
+    verdictRoot;
+    /** 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;
+    /** Independent verifier for scored rounds, when one was supplied. */
+    verifier;
+    /** 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()) {
+    connectionSettled = false;
+    /** Counter behind `commandId`, so every executed line has one identifier in begin and end. */
+    commandSeq = 0;
+    /** The operation that owns the client right now, when one does; the single foreground slot. */
+    foreground;
+    /** Callers waiting for the slot, oldest first; woken one at a time so nobody barges in. */
+    foregroundWaiters = [];
+    /** True while a waiter has been promised the slot but has not taken it yet. */
+    foregroundGranted = false;
+    /** Set when the client stops, so a waiter never starts work on a closed connection. */
+    foregroundClosed = false;
+    foregroundSeq = 0;
+    /** Which operation the current async continuation belongs to, so a nested call never re-claims. */
+    foregroundOwner = new AsyncLocalStorage();
+    /** 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.verifier = options.verifier;
+        this.allowSelfFallback = options.allowSelfFallback === true;
+        this.verdictRoot = options.verdictRoot ?? this.localDirectory;
+        this.deadlineMs = options.deadlineMs;
+        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);
         if (costs)
             this.cost = new CostController(costs, {
@@ -62,8 +222,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) => {
@@ -73,7 +238,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. */
@@ -83,23 +248,226 @@ 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.foreground !== 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) : [];
+        // 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.loop?.sessionId !== next.sessionId) {
+            this.forgetLoop();
+            // 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();
+        // A prompt the loop could not send yet (offline, busy or answering) goes out as soon as it can.
+        if (this.loopPrompt !== undefined)
+            void this.flushLoop();
+        // A finished attempt whose reply is still committing gets another look on every publish.
+        if (this.loopEndedAt !== undefined)
+            this.trySettleLoop();
+    }
+    /** 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.claimForeground(kind, label, work, wait),
+            cancelForeground: () => this.cancelForeground(),
+            openPeek: id => this.openPeek(id),
+            closePeek: () => this.closePeek(),
+            switchWorkspace: id => this.runAction('navigation', 'Switching workspace…', () => this.switchWorkspace(id)),
+            switchSession: query => this.runAction('navigation', 'Switching session…', () => this.switchSession(query)),
+            selectSession: id => this.runAction('navigation', 'Loading session…', () => this.selectSession(id)),
+            createWorkspace: path => this.runAction('navigation', 'Registering workspace…', () => this.createWorkspace(path)),
+            createSession: () => this.runAction('navigation', 'Creating session…', () => this.createSession()),
+            createVerifierSession: title => this.runActionValue('verifier', 'Creating verifier session…', () => this.createVerifierSession(title)),
+            cancelVerifierSession: sessionId => this.runAction('verifier', 'Stopping verifier…', 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…', () => this.showPicker(screen)),
+            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)),
+            searchHistory: (query, signal) => this.runActionValue('search', 'Searching history…', () => this.searchHistory(query, signal)),
+            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.startLoop(protocol, limits)),
+            stopLoop: () => this.stopLoop(),
+            clearLoopResult: () => this.clearLoopResult(),
+            answerLoop: text => this.runAction('loop', 'Answering the verifier…', () => this.answerLoop(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…', () => this.older(signal, transcript)),
+            historyThrough: (target, signal) => this.runAction('history', 'Loading history…', () => this.historyThrough(target, signal)),
+            removeQueued: itemId => this.runAction('command', 'Removing queued input…', () => this.removeQueued(itemId)),
+            savePrompt: text => this.runAction('local', 'Saving prompt…', async () => {
+                await this.promptStore.save(text);
+                this.update({ lastFailure: '' });
+            }),
+            updatePrompt: (id, text) => this.runAction('local', 'Saving prompt…', async () => {
+                if (!await this.promptStore.update(id, text))
+                    throw new Error('That saved prompt no longer exists');
+                this.update({ lastFailure: '' });
+            }),
+            deletePrompt: id => this.runAction('local', 'Deleting prompt…', 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…', () => this.selectModel(provider, model, effort)),
+            modelCatalog: () => this.runActionValue('model', 'Loading models…', () => this.modelCatalog()),
+            refreshCosts: signal => this.runAction('cost', 'Refreshing costs…', () => this.refreshCosts(signal)),
+            loadPresetNames: () => this.loadPresetNames(),
+            clearFailure: () => this.clearFailure(),
+            enterPath: () => this.enterPath(),
+            pickWorkspace: id => this.pickWorkspace(id),
+            showChat: () => this.showChat(),
+            setViewWindow: window => this.setViewWindow(window),
+            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.verifier !== undefined; },
+            get selfScoring() { return controller.verifier === undefined || controller.allowSelfFallback; },
+            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; },
+            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.loop?.progress; },
+            get foreground() { return controller.foreground; },
+            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),
+            historyAt: (target, signal) => controller.historyAt(target, 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.foregroundClosed = true;
+        for (const wake of this.foregroundWaiters.splice(0))
+            wake();
+        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.
@@ -110,25 +478,133 @@ 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 runAction(kind, label, operation) {
+        if (!this.state.online)
+            return false;
+        if (!this.ownsForeground() && this.foreground !== undefined)
+            return false;
+        return await this.claimForeground(kind, label, async () => {
+            try {
+                await operation();
+                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)
+            return undefined;
+        if (!this.ownsForeground() && this.foreground !== undefined)
+            return undefined;
+        return await this.claimForeground(kind, label, async () => {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                this.update({ lastFailure: errorText(error) });
+                return undefined;
+            }
+        });
+    }
+    /** Whether the current async continuation is already inside the foreground operation.
+     *
+     * An action invoked *by* a running operation (a paging loop calling `older`, a command's policy
+     * calling an action) belongs to that operation: refusing it for being busy would deadlock the very
+     * work that owns the slot. An async-local owner answers that exactly, where a plain flag could not
+     * tell a nested call from a second, unrelated one.
+     * @returns True when this call runs inside the operation that owns the slot.
+     */
+    ownsForeground() { return this.foregroundOwner.getStore() !== undefined; }
+    /** Run one operation in the foreground slot, claiming it when the caller does not already own it.
+     *
+     * The slot serializes what the operator is doing — one thing at a time — which is a different
+     * question from the session write order (§6.3): a read takes this slot too. The controller owns the
+     * slot, the abort controller and the identity, so the front end only renders `queries.foreground`
+     * and cancels it in one call.
+     * @param kind - What the operation is.
+     * @param label - Human label shown while it runs.
+     * @param work - The work, handed the signal that `cancelForeground` aborts.
+     * @returns What the work returned, or undefined when the slot was taken or the work was cancelled.
+     */
+    async claimForeground(kind, label, work, wait = false) {
+        const owner = this.foreground;
+        // Nested: the operation that owns the slot supplies the signal and keeps the identity.
+        if (owner !== undefined && this.ownsForeground())
+            return await work(owner.abort.signal);
+        if (owner !== undefined || this.foregroundGranted) {
+            // A caller that does not want to wait is told no; one that does waits its turn in arrival order.
+            if (!wait)
+                return undefined;
+            this.traceEvent('foreground', { phase: 'queued', kind, label });
+            await new Promise(resolve => this.foregroundWaiters.push(resolve));
+            // The release handed this caller the slot; clearing the flag and taking it is one synchronous
+            // step, so a later arrival cannot slip in between.
+            this.foregroundGranted = false;
+            if (this.foregroundClosed)
+                return undefined;
+        }
+        const operation = { id: ++this.foregroundSeq, kind, label, startedAt: Date.now(), abort: new AbortController() };
+        this.foreground = operation;
+        this.update({ lastFailure: '' });
+        this.traceEvent('foreground', { phase: 'begin', id: operation.id, kind, label });
+        try {
+            return await this.foregroundOwner.run(operation.id, () => work(operation.abort.signal));
+        }
+        finally {
+            // Only the owner releases the slot; a nested claim never reaches this branch.
+            if (this.foreground === operation) {
+                this.foreground = undefined;
+                this.update({});
+                this.traceEvent('foreground', { phase: 'end', id: operation.id, kind, cancelled: operation.abort.signal.aborted });
+                // Hand the slot to the oldest waiter, if any: the occupant is gone before the next one takes
+                // it, and `foregroundGranted` keeps a fresh arrival from overtaking the promise already made.
+                const next = this.foregroundWaiters.shift();
+                if (next !== undefined) {
+                    this.foregroundGranted = true;
+                    next();
+                }
+            }
+        }
+    }
+    /** Cancel the operation that owns the foreground slot; false when none is running.
+     * @returns Whether an operation was there to cancel.
      */
-    async perform(operation) {
-        if (this.state.busy || !this.state.online)
+    cancelForeground() {
+        if (this.foreground === undefined)
             return false;
-        this.update({ busy: true, error: '' });
+        this.foreground.abort.abort();
+        return true;
+    }
+    /** Run one local operation that needs no connection, reporting failure the way `runAction` does.
+     *
+     * Shortcut prompts are the operator's own file, so they must keep working while the host is
+     * disconnected; only the failure line is shared with the remote operations.
+     * @param operation - Operation to run against local storage.
+     * @returns Whether it ran to completion.
+     */
+    async runLocalAction(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.
      *
@@ -186,49 +662,102 @@ 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.catalog.refresh();
-        this.update({ online: true, status: 'Connected', error: '', pending: [] });
+        this.update({ online: true, status: 'Connected', pending: [], lastFailure: '' });
         const screen = this.state.screen;
-        await this.session.showPicker(screen === 'sessions' ? 'sessions' : 'workspaces');
-        const sessionId = this.state.sessionId ?? this.initialSession;
-        if (sessionId && (screen === 'chat' || this.initialSession && !this.state.sessionId))
+        this.traceEvent('generation', { phase: 'ready', screen });
+        const picker = screen === 'sessions' ? 'sessions' : 'workspaces';
+        this.traceEvent('picker', { requested: picker });
+        await this.session.showPicker(picker);
+        // 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.
+        // The guard only excludes the `sessions` screen, so it also runs when the captured screen is
+        // `chat`: a reconnect mid-conversation then adopts the local workspace, `pickWorkspace` clears
+        // the selection, and the reader is returned to `/resume`. The trace records the `adopt` event
+        // and the `state` transition that follow, which is how that jump is told from a user action.
+        const mayAdopt = screen !== 'sessions' && !this.initialSession;
+        if (mayAdopt) {
+            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' });
+        }
+        // A loop outlives a reconnect, so it re-attaches to its own session even when the picker
+        // replaced the selection; without that the loop would keep settling against an empty transcript.
+        const looping = this.loop?.sessionId;
+        const sessionId = this.state.sessionId ?? looping ?? this.initialSession;
+        const reselect = Boolean(sessionId && (screen === 'chat' || looping !== undefined || this.initialSession && !this.state.sessionId));
+        this.traceEvent('resolve', { session: sessionId ?? 'none', looping: looping ?? 'none', reselect });
+        if (sessionId && reselect) {
             await this.session.selectSession(sessionId);
+        }
+        // `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.settleLoop(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. */
@@ -237,8 +766,159 @@ export class Controller {
     get sessionMode() { return this.session.sessionMode; }
     /** @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.loop?.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.verifier === undefined ? {} : { detail: `verifier ${this.verifier.name}` }),
+        });
+        // 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. */
@@ -257,16 +937,22 @@ export class Controller {
      * @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.stopLoop();
+        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.
+     */
+    setViewWindow(window) { this.session.setViewWindow(window); }
     /** 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.
@@ -289,45 +975,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.
      */
@@ -336,38 +994,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.
      */
@@ -375,7 +1001,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) {
+        this.traceEvent('action', { action: 'showPicker', screen });
+        await this.session.showPicker(screen);
+    }
     /** 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.
@@ -385,31 +1014,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) {
+        this.traceEvent('action', { action: 'switchWorkspace', query: query ?? 'picker' });
+        await this.session.switchWorkspace(query);
+    }
     /** 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) {
+        this.traceEvent('action', { action: 'switchSession', query: query ?? 'picker' });
+        await this.session.switchSession(query);
+    }
     /** 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) {
+        this.traceEvent('action', { action: 'createWorkspace', path });
+        await this.session.createWorkspace(path);
+    }
     /** Create a session in the selected workspace. */
-    async createSession() { await this.session.createSession(); }
+    async createSession() {
+        this.traceEvent('action', { action: 'createSession', workspace: this.state.workspaceId ?? 'none' });
+        await this.session.createSession();
+    }
     /** 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.
      */
@@ -457,11 +1118,587 @@ 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.stopLoop();
+        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);
+    }
+    /** Start a scored loop and send its opening step.
+     * @param protocol - Prompt text and step count the loop follows.
+     * @param limits - Resolved `--from/--to/--score/--tries`.
+     */
+    async startLoop(protocol, limits) {
+        const sessionId = this.state.sessionId;
+        // Every branch that can leave a start invisible is traced with its reason, so "it did nothing"
+        // is answerable from the trace instead of guessed at.
+        if (sessionId === undefined) {
+            this.traceEvent('loop', { phase: 'refused', kind: protocol.kind, reason: 'no-session' });
+            throw new Error('Select a session first');
+        }
+        // A new run replaces whatever was there; the old one is closed before the new identity exists.
+        this.forgetLoop('replaced');
+        const runId = randomUUID();
+        this.loopRunId = runId;
+        this.loopEndTraced = false;
+        this.traceEvent('loop', { phase: 'begin', runId, kind: protocol.kind, session: sessionId,
+            from: limits.from, to: limits.to, score: limits.score, tries: limits.tries, forked: this.verifier !== undefined });
+        const loop = new ScoredLoop(runId, sessionId, protocol, limits);
+        this.loop = loop;
+        // A protocol that reviews something already on disk verifies first: a round that passes costs no
+        // work turn at all, and only a failing verdict asks the agent to change anything.
+        if (this.startsByVerifying(loop)) {
+            this.update({});
+            this.armLoopDeadline();
+            this.traceEvent('loop', { phase: 'verify-first', runId, kind: protocol.kind, step: limits.from });
+            this.verifyStep(loop);
+            return;
+        }
+        const prompt = loop.start();
+        loop.sent();
+        this.update({});
+        this.armLoopDeadline();
+        try {
+            await this.session.promptInternal(prompt);
+            this.traceEvent('loop', { phase: 'sent', runId, kind: protocol.kind, step: limits.from, attempt: 1 });
+        }
+        catch (error) {
+            // The run never got its first turn. It ends needing a person rather than silently vanishing:
+            // the reason says the send was rejected, and the snapshot stays readable.
+            this.rejectLoopSend(loop, error);
+            throw error;
+        }
+    }
+    /** End a run whose next prompt could not be sent, keeping the reason visible.
+     *
+     * A rejected send is not a verdict and not an operator cancellation, so the phase is `needs-human`
+     * and `terminalReason` says why — this is what keeps `phase=cancelled` meaning "a person stopped it".
+     * @param loop - Run that could not send.
+     * @param error - What the host or the session layer rejected with.
+     */
+    rejectLoopSend(loop, error) {
+        const text = errorText(error).slice(0, 200);
+        this.forgetSettleTimer();
+        this.clearLoopDeadline();
+        this.abortVerification();
+        loop.human({ kind: 'send', text }, 'send-rejected');
+        this.traceLoopEnd(loop);
+        this.loopPrompt = undefined;
+        this.update({ lastFailure: text });
+    }
+    /** Record the end of one run once, with the phase it stopped in and why.
+     *
+     * I9 needs every `begin` to be paired inside the trace window; this is the only writer of `loop end`.
+     * @param loop - Run whose terminal phase was just published.
+     */
+    traceLoopEnd(loop) {
+        if (this.loopEndTraced)
+            return;
+        this.loopEndTraced = true;
+        const progress = loop.progress;
+        this.traceEvent('loop', { phase: 'end', runId: progress.runId, kind: loop.protocol.kind,
+            result: progress.phase, step: progress.step, attempt: progress.attempt,
+            reason: progress.terminalReason ?? 'unknown' });
+    }
+    /** Whether a step begins with verification rather than with a work prompt.
+     *
+     * Needs all three: the record asks for it, the record has a verifier prompt, and this client was
+     * given a verifier. Otherwise there is nobody to verify first, and the step asks for work.
+     * @param loop - Loop about to start a step.
+     * @returns True when the step starts by verifying.
+     */
+    startsByVerifying(loop) {
+        return loop.protocol.starts === 'verify' && loop.protocol.verify !== undefined && this.verifier !== undefined;
+    }
+    /** Verify the step in flight without a work turn before it.
+     *
+     * The activity is set inside `verifyRound`, so the first verification, a work-turn verdict and a
+     * retry all publish the same state without this caller having to remember it.
+     * @param loop - Loop whose step and attempt are already set.
+     */
+    verifyStep(loop) {
+        void this.verifySection(loop);
+    }
+    /** Check the round's own section before spending a verifier on it, then verify or ask for work.
+     *
+     * Verify-first exists so a round that already passes costs no work turn. When the section is not in
+     * the artifact at all the round *cannot* pass, and this client can read that itself — the same check
+     * it applies to a verdict before accepting one. Sending a verifier to discover "the file is missing"
+     * costs a session and, because a failed attempt consumes one, also the round's first attempt: a run
+     * over a document with no review yet would start working at attempt 2/10. An artifact this client
+     * cannot read stays a boundary: the verification runs and its verdict decides, as before.
+     * @param loop - Loop whose step and attempt are already set.
+     */
+    async verifySection(loop) {
+        const artifact = loop.protocol.artifact;
+        const marker = loop.protocol.artifactMarker?.(loop.progress.step);
+        if (artifact === undefined || marker === undefined) {
+            void this.verifyRound(loop);
+            return;
+        }
+        // `readText` answers undefined only for a file that is not there and throws for one that cannot be
+        // read, so the two cases are told apart here: a missing file has no section either, while an
+        // unreadable one is a boundary this client cannot decide.
+        let text;
+        try {
+            text = await readText(join(this.localDirectory, artifact));
+        }
+        catch {
+            void this.verifyRound(loop);
+            return;
+        }
+        // Reading the artifact is I/O, so the run may have moved on before it came back.
+        if (this.loop !== loop || !loop.active)
+            return;
+        if (text !== undefined && text.includes(marker)) {
+            void this.verifyRound(loop);
+            return;
+        }
+        // A missing file only proves the producer never wrote it when this client can see the workspace at
+        // all. A workspace this machine does not have is a boundary — the same boundary the artifact check
+        // after a verdict already respects — so the verifier's reading decides instead.
+        if (text === undefined && !await this.workspaceVisible()) {
+            void this.verifyRound(loop);
+            return;
+        }
+        this.traceEvent('loop', { phase: 'work-first', runId: this.loopRunId ?? '', kind: loop.protocol.kind,
+            step: loop.progress.step, artifact, reason: 'section-missing' });
+        loop.note(`⚠ artifact check · ${artifact} 还没有本轮小节，直接开始工作`);
+        // No verdict was consumed, so the attempt is untouched: the first work turn is attempt 1, exactly
+        // as it is for a record that asks for work first.
+        this.loopPrompt = loop.workPrompt();
+        this.update({});
+        void this.flushLoop();
+    }
+    /** Whether the directory this client runs in is readable here at all.
+     *
+     * `readText` answers undefined for a missing file and for a file inside a directory this machine does
+     * not have, and the two mean opposite things: the first is a producer that wrote nothing, the second
+     * is a workspace whose verdict cannot be checked from here.
+     * @returns True when the directory can be listed.
+     */
+    async workspaceVisible() {
+        try {
+            await listEntries(this.localDirectory);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Arm the whole-run budget, when the operator set one. */
+    armLoopDeadline() {
+        if (this.deadlineMs === undefined)
+            return;
+        this.loopDeadlineTimer = setTimeout(() => this.expireLoopDeadline(), this.deadlineMs);
+        this.loopDeadlineTimer.unref();
+    }
+    /** Answer a paused run, so the current artifact is judged again with what the operator supplied.
+     *
+     * The answer is not a work order: it only adds a condition to the judgment, so nothing is sent to the
+     * agent and no attempt is consumed. The verification that follows is a new task with a new identity,
+     * which is what keeps a late verdict from the paused one from deciding the attempt.
+     * @param text - What the operator added; never written to the trace.
+     */
+    async answerLoop(text) {
+        const loop = this.loop;
+        if (loop === undefined || !loop.active)
+            throw new Error('No loop is waiting for an answer');
+        this.loopAnswer = text;
+        const judged = this.verifier !== undefined && loop.protocol.verify !== undefined;
+        loop.resume(judged ? 'verify' : 'turn');
+        this.update({});
+        this.traceEvent('loop', { phase: 'answered', runId: loop.progress.runId, judged, chars: text.length });
+        if (judged) {
+            this.verifyStep(loop);
+            return;
+        }
+        // Without a forked verifier the answer is the next attempt's instruction: the agent is asked again
+        // with the addition, and the attempt budget still decides how many times that may happen.
+        this.loopPrompt = loop.answerPrompt(text);
+        void this.flushLoop();
+    }
+    /** Stop a running review; the terminal progress stays visible for the reader.
+     * @param reason - Why it stopped; the default is an operator action.
+     */
+    stopLoop(reason = 'user-cancelled') {
+        if (this.loop === undefined)
+            return;
+        this.forgetSettleTimer();
+        this.clearLoopDeadline();
+        this.abortVerification();
+        this.loopEndedAt = undefined;
+        this.loop.cancel(reason);
+        this.traceLoopEnd(this.loop);
+        this.loopPrompt = undefined;
+        this.update({});
+    }
+    /** Drop a finished run's progress line, keeping an active one.
+     *
+     * D3 keeps a terminal result on screen because it is what the reader most needs to see — but it is a
+     * result, not a status: the next line the operator runs means they have read it. An active run is
+     * left alone, so `/loop answer` and `/loop stop` keep the target they were typed for.
+     */
+    clearLoopResult() {
+        const loop = this.loop;
+        if (loop === undefined || loop.active)
+            return;
+        this.forgetLoop();
+        this.update({});
+    }
+    /** Drop the loop entirely, without publishing a cancelled phase.
+     * @param reason - Why it was dropped, recorded when it never reached a terminal phase itself.
+     */
+    forgetLoop(reason = 'replaced') {
+        // A run that is dropped while still active never published a terminal phase: close its trace span
+        // here so one begin still has one end, then let the snapshot go.
+        if (this.loop !== undefined && this.loop.active) {
+            this.loop.cancel(reason);
+            this.traceLoopEnd(this.loop);
+        }
+        this.forgetSettleTimer();
+        this.clearLoopDeadline();
+        this.abortVerification();
+        this.loopPrevious = undefined;
+        this.loopRunId = undefined;
+        this.loopEndTraced = false;
+        this.loopVerifySeq = 0;
+        this.loopVerifyIdentity = undefined;
+        this.loopVerifierMisses = 0;
+        this.loopAnswer = undefined;
+        this.loop = undefined;
+        this.loopPrompt = undefined;
+        this.loopEndedAt = undefined;
+    }
+    /** Note that an attempt's turn ended; its block may still be arriving.
+     * @param sessionId - Session the host reported idle.
+     */
+    settleLoop(sessionId) {
+        const loop = this.loop;
+        if (loop === undefined || !loop.active || !loop.settled || loop.sessionId !== sessionId)
+            return;
+        this.loopEndedAt ??= Date.now();
+        this.trySettleLoop();
+    }
+    /** Consume the attempt once its result block is committed, or the grace period expires.
+     *
+     * The final assistant message can land a moment after the idle event, so an empty parse is not yet
+     * a failed attempt: the next publish retries, and one timer covers a transcript that never grows.
+     */
+    trySettleLoop() {
+        const loop = this.loop;
+        if (loop === undefined || !loop.active || !loop.settled) {
+            this.forgetSettleTimer();
+            this.loopEndedAt = undefined;
+            return;
+        }
+        // Only a turn that actually ended may be consumed: a timer that fired just before the attempt
+        // settled must not decide the attempt that replaced it.
+        const endedAt = this.loopEndedAt;
+        if (endedAt === undefined) {
+            this.forgetSettleTimer();
+            return;
+        }
+        // An independent verifier decides the round; the reply block below stays as its fallback. Its
+        // branch keeps its own `verify` sub-state, so this must not announce settling over it.
+        if (loop.protocol.verify !== undefined && this.verifier !== undefined) {
+            if (!this.loopVerifying && !this.loopSettling)
+                void this.verifyRound(loop);
+            return;
+        }
+        // No forked verifier: reading the reply block, including the grace wait for it, is settling.
+        loop.settling();
+        const result = parseLoopResult(latestAssistantText(this.state.session.record.messages), loop.protocol);
+        if (result === undefined && Date.now() - endedAt < LOOP_SETTLE_GRACE_MS) {
+            if (this.loopSettleTimer === undefined) {
+                this.loopSettleTimer = setTimeout(() => { this.loopSettleTimer = undefined; this.trySettleLoop(); }, LOOP_SETTLE_GRACE_MS);
+                this.loopSettleTimer.unref();
+            }
+            return;
+        }
+        this.forgetSettleTimer();
+        this.loopEndedAt = undefined;
+        void this.settleChecked(loop, result);
+    }
+    /** Score one finished round out of band, in a process of its own.
+     *
+     * The child writes its verdict to a file, so a slow or failed verifier delays the attempt instead
+     * of corrupting it: with no verdict the reply block decides, and with neither the attempt fails.
+     * @param loop - The run whose attempt just finished.
+     */
+    async verifyRound(loop) {
+        const verifier = this.verifier;
+        if (verifier === undefined)
+            return;
+        const { step, attempt } = loop.progress;
+        const { kind } = loop.protocol;
+        const runId = this.loopRunId ?? (this.loopRunId = randomUUID());
+        // Every started verification is its own task: a failure retry or an operator answer must not
+        // reuse the identity or the file of the task it replaced, or a late verdict could decide it.
+        const seq = this.loopVerifySeq += 1;
+        const file = verdictFile(this.verdictRoot, runId, kind, step, attempt, seq);
+        const identity = verificationId(runId, kind, step, attempt, seq);
+        const prompt = loop.protocol.verify(loop.progress, step, attempt, { file, verificationId: identity }, this.loopPrevious);
+        // An answer the operator gave after an abstention only adds a condition: the same artifact is
+        // judged again, under a fresh identity, and no attempt is consumed for it.
+        const answered = this.loopAnswer === undefined ? prompt : `${prompt}\n\n## 操作者的补充判断\n${this.loopAnswer}`;
+        this.loopVerifying = true;
+        this.loopVerifyIdentity = identity;
+        // The sub-state is a fact on the loop, not a note: the progress line and the status bar both read
+        // it, and a retry's warning note stays beside it instead of being overwritten by a string.
+        loop.verifying();
+        this.update({});
+        this.traceEvent('verify', { runId, phase: 'begin', kind, step, attempt, seq, file });
+        const abort = new AbortController();
+        this.loopVerifyAbort = abort;
+        let outcome;
+        try {
+            // The reviewed workspace is declared here, where it is known, so the verifier's artifact check
+            // never has to infer it from whatever directory the process happens to run in.
+            outcome = await verifier.verify({ verificationId: identity, kind, step, attempt, prompt: answered, file,
+                workspace: this.localDirectory,
+                ...(loop.protocol.artifact === undefined ? {} : { artifact: loop.protocol.artifact }),
+                title: `[dsht-verify] ${loop.protocol.title} · ${step}/${attempt}` }, abort.signal);
+        }
+        catch (error) {
+            outcome = { type: 'unavailable', reason: `verifier failed: ${errorText(error)}` };
+        }
+        finally {
+            if (this.loopVerifyAbort === abort)
+                this.loopVerifyAbort = undefined;
+            this.loopVerifying = false;
+        }
+        // A newer verification task owns this attempt now: this task's verdict is stale by definition.
+        if (this.loopVerifyIdentity !== identity) {
+            this.traceEvent('verify', { runId, phase: 'stale', kind, step, attempt, seq });
+            return;
+        }
+        // Verification outlives nothing: a cancelled or replaced loop must not be settled by its result.
+        if (this.loop !== loop || !loop.active || !loop.settled) {
+            this.traceEvent('verify', { runId, phase: 'abandoned', kind, step, attempt, seq });
+            return;
+        }
+        this.forgetSettleTimer();
+        this.loopEndedAt = undefined;
+        // The review was cancelled: nothing to decide, and nothing to report as a verdict.
+        if (outcome.type === 'cancelled') {
+            this.traceEvent('verify', { runId, phase: 'cancelled', kind, step, attempt, seq });
+            return;
+        }
+        // The host is waiting for a human the verifier cannot answer: stop with the request attached.
+        // The verifier is blocked, not broken, so retrying would only hit the same wall three times.
+        if (outcome.type === 'needs-human') {
+            this.traceEvent('verify', { runId, phase: 'needs-human', kind, step, attempt, seq, request: outcome.request.kind });
+            this.clearLoopDeadline();
+            loop.human(outcome.request);
+            this.traceLoopEnd(loop);
+            this.update({});
+            return;
+        }
+        if (outcome.type === 'verified') {
+            this.traceEvent('verify', { runId, phase: 'verified', kind, step, attempt, seq,
+                score: outcome.result.score ?? -1, blocked: outcome.result.blocked === true, status: outcome.result.status ?? 'none' });
+            this.loopVerifierMisses = 0;
+            await this.settleChecked(loop, outcome.result);
+            return;
+        }
+        // Unavailable is not a verdict, so it never consumes the attempt: retry the verifier, and only
+        // then stop the run. Self-scoring is opt-in and is always visible in the progress line.
+        // A failure that says it is not retryable (an unconfirmed remote cancel, a bad configuration)
+        // would only repeat itself, so it is reported instead of spending the retry budget.
+        if (outcome.retryable === false) {
+            this.traceEvent('verify', { runId, phase: 'unavailable', kind, step, attempt, seq, retryable: false, reason: outcome.reason.slice(0, 200) });
+            loop.note(`⚠ verification unavailable · ${outcome.reason}`);
+            this.clearLoopDeadline();
+            loop.unavailable();
+            this.traceLoopEnd(loop);
+            this.update({});
+            return;
+        }
+        this.loopVerifierMisses += 1;
+        if (this.loopVerifierMisses <= VERIFIER_RETRIES) {
+            this.traceEvent('verify', { runId, phase: 'retry', kind, step, attempt, seq, misses: this.loopVerifierMisses, reason: outcome.reason.slice(0, 200) });
+            loop.note(`⚠ verification unavailable · retrying (${outcome.reason})`);
+            this.update({});
+            void this.verifyRound(loop);
+            return;
+        }
+        if (this.allowSelfFallback) {
+            const fallback = parseLoopResult(latestAssistantText(this.state.session.record.messages), loop.protocol);
+            this.traceEvent('verify', { runId, phase: 'fallback', kind, step, attempt, seq, block: fallback !== undefined });
+            await this.settleChecked(loop, fallback, fallback === undefined
+                ? `⚠ verification fallback · self-reported (and no reply block: ${outcome.reason})`
+                : '⚠ verification fallback · self-reported');
+            return;
+        }
+        this.traceEvent('verify', { runId, phase: 'unavailable', kind, step, attempt, seq, retryable: true, misses: this.loopVerifierMisses, reason: outcome.reason.slice(0, 200) });
+        loop.note(`⚠ verification unavailable · ${outcome.reason}`);
+        this.clearLoopDeadline();
+        loop.unavailable();
+        this.traceLoopEnd(loop);
+        this.update({});
+    }
+    /** Apply a protocol's own artifact requirement, then settle the attempt.
+     *
+     * The score is the verifier's judgement; whether the round's conclusion actually reached the
+     * artifact is a fact this client checks itself. A hard condition may not be overridden by a score:
+     * a round whose section is missing fails even at 10/10, and the missing line is fed back to the
+     * next attempt like any other finding. An artifact this client cannot read cannot be checked, so
+     * the verdict stands rather than being failed on a boundary.
+     * @param loop - The run whose attempt just finished.
+     * @param result - Verdict to consume.
+     * @param note - Note to show instead, when the check accepted the verdict unchanged.
+     */
+    async settleChecked(loop, result, note = '') {
+        if (this.loopSettling)
+            return;
+        this.loopSettling = true;
+        try {
+            const marker = result === undefined || result.blocked === true || result.abstained === true
+                ? undefined : loop.protocol.artifactMarker?.(loop.progress.step);
+            const artifact = loop.protocol.artifact;
+            if (marker === undefined || artifact === undefined || result === undefined) {
+                this.settleWith(loop, result, note);
+                return;
+            }
+            const text = await readText(join(this.localDirectory, artifact));
+            // Reading the artifact is I/O, so the run may have moved on before it came back.
+            if (this.loop !== loop || !loop.active || !loop.settled)
+                return;
+            if (text === undefined || text.includes(marker)) {
+                this.settleWith(loop, result, note);
+                return;
+            }
+            this.traceEvent('artifact', { phase: 'missing', artifact, step: loop.progress.step, score: result.score ?? -1 });
+            const reported = result.score === undefined ? '没有分数' : `${result.score} 分`;
+            this.settleWith(loop, { ...result, score: undefined,
+                findings: [...(result.findings ?? []), `工作区文件 ${artifact} 缺少本轮小节「${marker}」`] }, `⚠ artifact check · ${artifact} 缺少本轮小节「${marker}」（验证者给了 ${reported}，本轮不通过）`);
+        }
+        finally {
+            this.loopSettling = false;
+        }
+    }
+    /** Apply one attempt's verdict, and continue the run when it has a next step.
+     * @param loop - The run being settled.
+     * @param result - Verdict to consume, or undefined when the attempt produced none.
+     */
+    settleWith(loop, result, note = '') {
+        const before = loop.progress;
+        const step = loop.settle(result);
+        // The answer was the condition for this judgment, so it is spent once the verdict is in.
+        this.loopAnswer = undefined;
+        // A pause is not an end: the run keeps its span (and its deadline) until it is answered or ended.
+        if (step.kind !== 'continue' && !loop.active) {
+            this.clearLoopDeadline();
+            // A decision ended the run: close its trace span with the phase and reason it stopped in.
+            this.traceLoopEnd(loop);
+        }
+        // The note describes the attempt just decided, so it is applied after the state moved on.
+        loop.note(note);
+        if (step.kind === 'continue') {
+            // A retry on the same step carries the verdict that caused it; a new step starts clean.
+            this.loopPrevious = before.step === loop.progress.step && result !== undefined
+                ? { step: before.step, attempt: before.attempt, result } : undefined;
+            // A passing verdict advanced the step. When the record verifies first, the new round is
+            // verified against the artifact as it stands before anyone is asked to change it.
+            if (loop.progress.step !== before.step && this.startsByVerifying(loop)) {
+                this.update({});
+                this.verifyStep(loop);
+                return;
+            }
+            const findings = result === undefined ? [] : findingsLines(result);
+            // `step.prompt` is already brief-aware: a run that began by verifying has sent no prompt yet, so
+            // its first work message is the brief rather than a follow-up that describes nothing.
+            this.loopPrompt = [step.prompt, ...findings].join('\n');
+        }
+        this.update({});
+        if (step.kind === 'continue')
+            void this.flushLoop();
+    }
+    /** Stop an in-flight verification, if any; its result can no longer decide anything. */
+    abortVerification() {
+        this.loopVerifyAbort?.abort();
+        this.loopVerifyAbort = undefined;
+        this.loopVerifying = false;
+    }
+    /** Stop the run because the whole-run budget expired; a budget stop, not a verdict.
+     *
+     * Any verification in flight is cancelled (bounded, as everywhere else) and its late result can
+     * no longer decide anything, because the loop is no longer active.
+     */
+    expireLoopDeadline() {
+        this.loopDeadlineTimer = undefined;
+        const loop = this.loop;
+        if (loop === undefined || !loop.active)
+            return;
+        this.forgetSettleTimer();
+        this.abortVerification();
+        this.loopEndedAt = undefined;
+        loop.note('⚠ deadline reached');
+        loop.deadline();
+        this.traceLoopEnd(loop);
+        this.update({});
+    }
+    /** Drop the run deadline, if one is armed. */
+    clearLoopDeadline() {
+        if (this.loopDeadlineTimer === undefined)
+            return;
+        clearTimeout(this.loopDeadlineTimer);
+        this.loopDeadlineTimer = undefined;
+    }
+    /** Drop a pending settle timer, if any. */
+    forgetSettleTimer() {
+        if (this.loopSettleTimer === undefined)
+            return;
+        clearTimeout(this.loopSettleTimer);
+        this.loopSettleTimer = undefined;
+    }
+    /** Send the prompt the loop is holding, once the client can actually send it. */
+    async flushLoop() {
+        const loop = this.loop;
+        const prompt = this.loopPrompt;
+        if (loop === undefined || prompt === undefined || !loop.active)
+            return;
+        // Nothing of this loop writes while an independent verifier is judging it: the round under
+        // verification must be the round that was scored. A prompt that appears meanwhile is sent when
+        // the verdict lands (or dropped with the run), never interleaved with the verification.
+        if (this.loopVerifying)
+            return;
+        if (this.state.sessionId !== loop.sessionId)
+            return;
+        if (!this.state.online || this.foreground !== undefined || this.state.pending.length)
+            return;
+        // Consume before awaiting, so a re-entrant update cannot send the same prompt twice.
+        this.loopPrompt = undefined;
+        loop.sent();
+        this.update({});
+        try {
+            await this.session.promptInternal(prompt);
+        }
+        catch (error) {
+            // The next prompt was rejected (a waiting interaction, a lost snapshot, offline): the run ends
+            // with that reason recorded instead of vanishing without a trace.
+            this.rejectLoopSend(loop, error);
+        }
+    }
     /** Cancel the active turn; pending queue items remain host-owned. */
-    async cancelTurn() { await this.session.cancelTurn(); }
+    async cancelTurn() {
+        this.stopLoop();
+        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.
@@ -479,15 +1716,57 @@ export class Controller {
      * @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.
      */