talos-code 0.0.1 → 0.2.0

package/dist/tui/session-controller.js

@@ -0,0 +1,791 @@
+import { randomUUID } from 'node:crypto';
+import { buildAgentTree } from "../runtime/agent-tree.js";
+import { createPermissionEngine } from "../security/permission-engine.js";
+import { createApprovalCoordinator, decisionFromChoice, decisionFromSource } from "./approval.js";
+import { createTuiEventAdapter, denialFromEngine, isolationOf } from "./event-adapter.js";
+import { createDescendantApprovals } from "./descendant-approvals.js";
+import { simulatePermission } from "../security/permission-explanation.js";
+import { KERNEL_RUN_TEXT } from "../i18n/kernel-map.js";
+import { permissionActionFromApproval } from "../security/from-approval.js";
+import { persistPermissionRule } from "../security/persist.js";
+import { EXECUTION_TEXT } from "../runtime/brokered-executor.js";
+import { secretValuesFromEnvironment } from "../diagnostics/redact.js";
+import { normalizeSessions } from "./overlays/session-picker.js";
+import { explainApproval } from "./overlays/approval-dialog.js";
+import { resolveProjectReferences } from "./project-references.js";
+import { createQueueStore } from "./queue-store.js";
+import { createCheckpointStore } from "../workspace/checkpoint-store.js";
+import { developmentLog, developmentLogError, developmentTextEvidence } from "../diagnostics/development-log.js";
+export class TuiNotReadyError extends Error {
+    code;
+    provider;
+    constructor(code, provider, message) { super(message); this.name = 'TuiNotReadyError'; this.code = code; this.provider = provider; }
+}
+const storedEntry = (entry) => entry.kind !== 'slash';
+export function createTuiSessionController({ runtime, projectRoot, model, mode, rules, paths, autoClassifier, readiness, onEvent, onApproval, onError = () => { }, onQueueChange, onQueueRestored, onQueuedDispatch, onQueuedSlash, onSteerState }) {
+    let currentMode = mode;
+    let currentModel = model;
+    const engine = createPermissionEngine({ projectRoot, rules, mode, ...(autoClassifier ? { classifier: autoClassifier } : {}), ...(paths ? { persistRule: async (effect, action) => persistPermissionRule({ paths, projectRoot, effect, action }) } : {}) });
+    /* R5a wiring (Q-R5-17, gate finding 15): the adapter learns who refused a tool BEFORE the kernel hears the "no" — the engine
+       alone (a deny rule, the policy, the mode: `denialFromEngine`) or the person (`resolveApproval`) — so the row never words
+       a refusal nobody asked for as the person's. */
+    const denialTargets = new Map();
+    const coordinator = createApprovalCoordinator({ engine, answer: (sid, rid, approved) => runtime.answerApproval(sid, rid, approved), interactive: true, mode: () => currentMode,
+        beforeDeny: (rid, decision) => { const target = denialTargets.get(rid); if (target)
+            adapter.noteDenial(target.toolCallId, denialFromEngine(decision, { rule: () => simulatePermission({ rules, action: target.action, projectRoot }).explanation.rule ?? null })); } });
+    const adapter = createTuiEventAdapter(secretValuesFromEnvironment(process.env));
+    /* P13: the approvals the current run's sub-agents ask for (descendant-approvals.ts), watched while that run is open. */
+    const descendants = createDescendantApprovals({ runtime, secretValues: secretValuesFromEnvironment(process.env),
+        onRequired: (origin, event) => requestApproval(origin.sessionId, event, origin),
+        onResolved: (_origin, requestId) => approvalResolved(requestId),
+        onError: error => developmentLogError('descendants.failure', error, { sessionId: current }, 'tui-controller') });
+    let unsubscribe = () => { };
+    let closed = false;
+    let current = null;
+    /*
+     * ⭐⭐⭐ DECISIONE OWNER 16/09/2026 — UN COMANDO DIGITATO MENTRE UN GIRO E' IN CORSO SI ACCODA.
+     *
+     * Misurato sui due concorrenti: Claude Code accoda SEMPRE mentre un turno e' attivo, Hermes
+     * esegue subito e lo documenta come regola. Sono opposti, quindi nessuna posizione di parita'
+     * esisteva e l'owner ha scelto la prima.
+     * ⇒ Conseguenza che TOGLIE lavoro: non serve nessun lucchetto sull'albero di lavoro, e un'intera
+     *   classe di difetti da scrittura concorrente non puo' verificarsi per costruzione.
+     */
+    const queuedEntries = [];
+    const queueStore = paths?.queueRoot ? createQueueStore({ rootDir: paths.queueRoot }) : null;
+    let queuePausedState = false, drainingQueue = false, boundaryWhileDraining = false, queueEpoch = 0;
+    let queueHydration = Promise.resolve();
+    let pendingSteer = null;
+    let steerInvocation = null;
+    let cancelling = false;
+    const checkpointStore = paths?.checkpointsRoot ? createCheckpointStore({ rootDir: paths.checkpointsRoot, projectRoot }) : null;
+    const shellAwaitingStart = [];
+    const shellByCommandId = new Map();
+    const shellCommandForCheckpoint = new Map();
+    /* R0 (2026-09-23): "this checkpoint received its ComandoUtenteIniziato". Unlike the map above it is NOT cleared by
+       ComandoUtenteFinito, so a command that finishes before `runtime.shell` returns is not misread as never correlated
+       (which raised CHECKPOINT_SHELL_CORRELATION_FAILED and blocked every later mutation). */
+    const shellCorrelated = new WeakSet();
+    let checkpointBlockedError = null;
+    function checkpointFailure(code, error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const blocked = Object.assign(new Error(`${code}: ${message}`), { code, cause: error });
+        checkpointBlockedError = blocked;
+        queuePausedState = true;
+        developmentLogError('checkpoint.failure', blocked, { code }, 'tui-controller');
+        if (!closed)
+            onError(blocked);
+        return blocked;
+    }
+    function assertCheckpointReady() { if (checkpointBlockedError)
+        throw checkpointBlockedError; }
+    async function runModelMutation(operation, sessionId, invoke) {
+        const invokeStarted = performance.now();
+        developmentLog('runtime.invoke.begin', { operation, sessionId }, 'debug', 'tui-controller');
+        try {
+            const id = await invoke();
+            developmentLog('runtime.invoke.accepted', { operation, sessionId: id, durationMs: performance.now() - invokeStarted }, 'info', 'tui-controller');
+            return id;
+        }
+        catch (error) {
+            developmentLogError('runtime.invoke.failure', error, { operation, sessionId, durationMs: performance.now() - invokeStarted }, 'tui-controller');
+            throw error;
+        }
+    }
+    async function runShellMutation(sessionId, command) {
+        assertCheckpointReady();
+        if (!checkpointStore) {
+            await runtime.shell(sessionId, command);
+            return;
+        }
+        const checkpoint = await checkpointStore.begin({ operation: 'shell', sessionId });
+        shellAwaitingStart.push(checkpoint);
+        try {
+            await runtime.shell(sessionId, command);
+            if (!shellCorrelated.has(checkpoint)) {
+                const index = shellAwaitingStart.indexOf(checkpoint);
+                if (index >= 0)
+                    shellAwaitingStart.splice(index, 1);
+                throw checkpointFailure('CHECKPOINT_SHELL_CORRELATION_FAILED', new Error('Direct shell returned without its synchronous ComandoUtenteIniziato correlation event.'));
+            }
+        }
+        catch (error) {
+            if (!shellCorrelated.has(checkpoint)) {
+                const index = shellAwaitingStart.indexOf(checkpoint);
+                if (index >= 0)
+                    shellAwaitingStart.splice(index, 1);
+                try {
+                    await checkpoint.finalize();
+                }
+                catch (finalization) {
+                    checkpointFailure('CHECKPOINT_FINALIZE_FAILED', finalization);
+                }
+            }
+            throw error;
+        }
+    }
+    function processRawEvent(id, raw, allowDrain = true) {
+        if (closed)
+            return;
+        developmentLog('runtime.raw_event', { sessionId: id, raw }, 'debug', 'tui-controller');
+        handleRawSteerEvent(raw);
+        const events = adapter.translateAll(raw);
+        const person = personCommandEvents(raw, events[0] ?? null);
+        if (!events.length) {
+            for (const extra of person)
+                onEvent(extra);
+            return;
+        }
+        for (const [index, translated] of events.entries()) {
+            processEvent(id, translated, allowDrain);
+            if (index === 0)
+                for (const extra of person)
+                    onEvent(extra);
+        }
+    }
+    function processEvent(id, translated, allowDrain) {
+        let event = personStopVerdict(id, translated);
+        if (event.type === 'run.started') {
+            openRun = event.runId ? { runId: event.runId } : {};
+            if (replayingHistory)
+                event = { ...event, history: true };
+            else
+                descendants.start(id);
+        }
+        else if (event.type === 'run.completed' || event.type === 'run.failed' || event.type === 'run.cancelled') {
+            openRun = null;
+            runEpoch++;
+            descendants.stop();
+        }
+        onEvent(event);
+        bypassWhy(event);
+        if ((event.type === 'run.completed' || event.type === 'run.failed' || event.type === 'run.cancelled') && interruptTerminalSession === id) {
+            const resolve = interruptTerminalResolve;
+            interruptTerminalResolve = null;
+            resolve?.();
+        }
+        if (event.type === 'approval.required') {
+            if (replayingHistory)
+                replayedApprovals.set(event.requestId, event);
+            else
+                requestApproval(id, event);
+        }
+        else if (event.type === 'approval.resolved')
+            approvalResolved(event.requestId);
+        else if (allowDrain && (event.type === 'run.completed' || event.type === 'run.failed') && !pendingSteer && !cancelling)
+            requestQueuedDrain(id);
+    }
+    /*
+     * R3 gate E12, owner decision Q-R3-15. The engine answers asynchronously, and a replay is synchronous: a replayed
+     * approval used to open its dialog AFTER the replayed answer had closed it (a stale dialog for a run long over). A
+     * replayed request is only remembered; once the replay is over it is asked only if its run is still waiting in the
+     * kernel (settleReplayedRun). A live request answered, or whose run ended, before the engine replied never opens.
+     */
+    let runEpoch = 0;
+    /*
+     * Q-R3-13 (owner, R3 follow-up): `Full access` is the why of every row that RAN in bypass mode, the tools the kernel ran
+     * without asking included. The mode is taken when the tool starts (live only: a replay does not know the old mode); at
+     * its result, a tool with no why yet that was not refused gets `full-access`. A row the person answered, and the
+     * person's own `!` command, keep their why; a why is sent once per tool.
+     */
+    const decidedTools = new Set();
+    const toolModes = new Map();
+    function emitDecision(toolCallId, decision) {
+        if (decision.kind === 'full-access' && decidedTools.has(toolCallId))
+            return;
+        decidedTools.add(toolCallId);
+        onEvent({ type: 'tool.decision', toolCallId, decision });
+    }
+    function bypassWhy(event) {
+        if (event.type === 'tool.started') {
+            if (!replayingHistory)
+                toolModes.set(event.toolCallId, currentMode);
+            return;
+        }
+        if (event.type === 'tool.completed') {
+            const mode = toolModes.get(event.toolCallId);
+            toolModes.delete(event.toolCallId);
+            if (mode === 'bypassPermissions' && !decidedTools.has(event.toolCallId) && event.outcome?.allowed !== false)
+                emitDecision(event.toolCallId, { kind: 'full-access' });
+            return;
+        }
+        if (event.type === 'run.completed' || event.type === 'run.failed' || event.type === 'run.cancelled') {
+            decidedTools.clear();
+            toolModes.clear();
+        }
+    }
+    const replayedApprovals = new Map();
+    const answeredApprovals = new Set();
+    const approvalTools = new Map();
+    function approvalResolved(requestId) {
+        replayedApprovals.delete(requestId);
+        approvalTools.delete(requestId);
+        answeredApprovals.add(requestId);
+        if (answeredApprovals.size > 256)
+            answeredApprovals.delete(answeredApprovals.values().next().value);
+        onApproval?.(null);
+    }
+    function requestApproval(id, event, origin) {
+        const action = permissionActionFromApproval(event.payload);
+        const epoch = runEpoch;
+        answeredApprovals.delete(event.requestId);
+        if (event.toolCallId)
+            denialTargets.set(event.requestId, { toolCallId: event.toolCallId, action });
+        void coordinator.request(id, event.requestId, action).finally(() => denialTargets.delete(event.requestId)).then(result => {
+            if (result.pending) {
+                if (answeredApprovals.has(event.requestId) || epoch !== runEpoch || (origin ? !descendants.watching().includes(id) : current !== id))
+                    return;
+                if (event.toolCallId)
+                    approvalTools.set(event.requestId, event.toolCallId);
+                const runtimeHint = event.payload.trifecta === true ? 'trifecta' : undefined;
+                onApproval?.({ requestId: event.requestId, sessionId: id, ...(origin ? { origin: { kind: 'agent', task: origin.task } } : {}), action: result.action, rawPayload: event.payload, reason: result.reason, ...(result.rule ? { rule: result.rule } : {}), ...(runtimeHint ? { runtimeHint } : {}), ...explainApproval({ rules, action: result.action, projectRoot, persists: Boolean(paths) }) });
+            }
+            else {
+                /* R3 gate E4 (Q-R3-3): why the engine let it run, on the tool's row. */
+                const decision = result.allowed ? decisionFromSource(result.source) : null;
+                if (decision && event.toolCallId)
+                    emitDecision(event.toolCallId, decision);
+                onApproval?.(null);
+            }
+        }).catch(onError);
+    }
+    /*
+     * R3 gate E4 (Q-R3-1/3). The person's `!` command: the kernel announces it as `ComandoUtenteIniziato{comandoId}`
+     * immediately followed by its `ToolCallStart{shell}` (agent-service.mjs:2124-2125) and ends it with
+     * `ComandoUtenteFinito{comandoId,codice,enforcement}` (:2168); the v2 bridge drops both. That tool call's row is the
+     * person's (`typed by you`), with the exit code and isolation of the finish event. Its duration is measured here, live
+     * only: a replay delivers every event at once, and a duration measured on the observer of a replay is not a duration
+     * (agui-events.mjs OSS-1), so a replayed command states none.
+     */
+    let personCommandNext = null;
+    const personCommands = new Map();
+    function personCommandEvents(raw, event) {
+        const row = raw && typeof raw === 'object' ? raw : null;
+        const announced = personCommandNext;
+        personCommandNext = null;
+        if (row?.type === 'ComandoUtenteIniziato') {
+            personCommandNext = typeof row.comandoId === 'string' && row.comandoId ? row.comandoId : null;
+            return [];
+        }
+        if (announced && event?.type === 'tool.started' && event.toolName === 'shell') {
+            personCommands.set(announced, { toolCallId: event.toolCallId, startedAt: replayingHistory ? null : performance.now() });
+            decidedTools.add(event.toolCallId);
+            return [{ type: 'tool.origin', toolCallId: event.toolCallId, origin: 'person' }, { type: 'tool.decision', toolCallId: event.toolCallId, decision: { kind: 'typed' } }];
+        }
+        if (row?.type === 'ComandoUtenteFinito' && typeof row.comandoId === 'string') {
+            const command = personCommands.get(row.comandoId);
+            if (!command)
+                return [];
+            personCommands.delete(row.comandoId);
+            const isolation = isolationOf(row.enforcement);
+            const facts = {
+                ...(typeof row.codice === 'number' && Number.isInteger(row.codice) ? { exitCode: row.codice } : {}),
+                ...(command.startedAt !== null && !replayingHistory ? { durationMs: Math.max(0, Math.round(performance.now() - command.startedAt)) } : {}),
+                ...(isolation ? { isolation } : {}),
+            };
+            return Object.keys(facts).length ? [{ type: 'tool.facts', toolCallId: command.toolCallId, facts }] : [];
+        }
+        return [];
+    }
+    function handleCheckpointRaw(id, raw) {
+        if (!raw || typeof raw !== 'object')
+            return false;
+        const row = raw;
+        if (row.type === 'ComandoUtenteIniziato') {
+            const checkpoint = shellAwaitingStart.shift();
+            if (checkpoint && typeof row.comandoId === 'string' && row.comandoId) {
+                checkpoint.bindCommand(row.comandoId);
+                shellByCommandId.set(row.comandoId, checkpoint);
+                shellCommandForCheckpoint.set(checkpoint, row.comandoId);
+                shellCorrelated.add(checkpoint);
+            }
+            return false;
+        }
+        if (row.type === 'ComandoUtenteFinito') {
+            let commandId = typeof row.comandoId === 'string' && row.comandoId ? row.comandoId : null;
+            let checkpoint = commandId ? shellByCommandId.get(commandId) ?? null : null;
+            if (!checkpoint && commandId === null && shellByCommandId.size === 1) {
+                const only = [...shellByCommandId.entries()][0];
+                commandId = only[0];
+                checkpoint = only[1];
+            }
+            if (checkpoint && commandId) {
+                shellByCommandId.delete(commandId);
+                shellCommandForCheckpoint.delete(checkpoint);
+                void checkpoint.finalize().catch(error => checkpointFailure('CHECKPOINT_FINALIZE_FAILED', error));
+            }
+            else if (commandId === null && shellByCommandId.size > 1)
+                checkpointFailure('CHECKPOINT_SHELL_CORRELATION_FAILED', new Error('Multiple direct shell checkpoints are active and the terminal event has no command id.'));
+            return false;
+        }
+        return false;
+    }
+    function steerState(state) { onSteerState?.(state); }
+    function pendingSteerNow() { return pendingSteer; }
+    function rejectSteer(code, message) { const outcome = { status: 'rejected', code, message }; steerState(outcome); return outcome; }
+    function handleRawSteerEvent(raw) {
+        if (!raw || typeof raw !== 'object')
+            return;
+        const row = raw;
+        const type = typeof row.type === 'string' ? row.type : '', redirectId = typeof row.redirectId === 'string' ? row.redirectId : '';
+        if (type === 'RunRedirectRequested') {
+            if (!steerInvocation || pendingSteer || !redirectId)
+                return;
+            pendingSteer = { redirectId, text: steerInvocation.text };
+            steerState({ status: 'requested', redirectId });
+            return;
+        }
+        if (!pendingSteer || pendingSteer.redirectId !== redirectId)
+            return;
+        if (type === 'RunRedirectApplied') {
+            steerState({ status: 'applied', redirectId });
+            pendingSteer = null;
+            return;
+        }
+        if (type === 'RunRedirectCancelled') {
+            steerState({ status: 'cancelled', redirectId });
+            pendingSteer = null;
+            return;
+        }
+        if (type === 'RunRedirectFailed') {
+            const code = typeof row.code === 'string' ? row.code : 'SESSION_STEER_FAILED', message = typeof row.message === 'string' ? row.message : 'Steering failed.';
+            steerState({ status: 'failed', redirectId, code, message });
+            pendingSteer = null;
+        }
+    }
+    function actionOf(entry) { return { kind: entry.kind, text: entry.text, ...(entry.attachments ? { attachments: entry.attachments.map(row => ({ ...row })) } : {}) }; }
+    function publicEntry(entry) { return { id: entry.id, kind: entry.kind, text: entry.text, status: entry.status === 'dispatching' ? 'uncertain' : 'pending', ...(entry.attachments ? { attachments: entry.attachments.map(row => ({ ...row })) } : {}) }; }
+    function queueSnapshot() { return queuedEntries.map(actionOf); }
+    function queueEntriesSnapshot() { return queuedEntries.map(publicEntry); }
+    function notifyQueue() { onQueueChange?.(queueSnapshot()); }
+    async function persistFor(sessionId, entries) { if (queueStore)
+        await queueStore.save(sessionId, entries.filter(storedEntry)); }
+    async function replaceQueue(entries, sessionId = current ?? '') {
+        if (!sessionId)
+            throw new Error('SESSION_NOT_FOUND');
+        await persistFor(sessionId, entries);
+        if (current !== sessionId)
+            throw new Error('QUEUE_SESSION_CHANGED');
+        queuedEntries.splice(0, queuedEntries.length, ...entries.map(entry => ({ ...entry, ...(entry.attachments ? { attachments: entry.attachments.map(row => ({ ...row })) } : {}) })));
+        notifyQueue();
+    }
+    async function hydrateQueue(id, epoch) {
+        queuedEntries.length = 0;
+        queuePausedState = false;
+        notifyQueue();
+        if (!queueStore)
+            return;
+        try {
+            const loaded = await queueStore.load(id);
+            if (current !== id || epoch !== queueEpoch)
+                return;
+            queuedEntries.splice(0, queuedEntries.length, ...loaded);
+            queuePausedState = loaded.length > 0;
+            notifyQueue();
+            if (loaded.length)
+                onQueueRestored?.(queueEntriesSnapshot());
+        }
+        catch (error) {
+            if (current !== id || epoch !== queueEpoch)
+                return;
+            queuePausedState = true;
+            onError(error);
+        }
+    }
+    async function enqueue(action) {
+        await queueHydration;
+        if (!current)
+            throw new Error('SESSION_NOT_FOUND');
+        const entry = { id: randomUUID(), kind: action.kind, text: action.text, status: 'pending', ...(action.attachments?.length ? { attachments: action.attachments.map(row => ({ ...row })) } : {}) };
+        await replaceQueue([...queuedEntries, entry], current);
+        return entry;
+    }
+    function queuePosition(entry) { const index = queuedEntries.findIndex(row => row.id === entry.id); return index < 0 ? 0 : index + 1; }
+    async function dispatchQueuedActions(id) {
+        await queueHydration;
+        if (current !== id || queuePausedState || drainingQueue)
+            return;
+        drainingQueue = true;
+        let followed = null;
+        try {
+            while (current === id && queuedEntries.length) {
+                const next = queuedEntries[0];
+                if (next.kind === 'prompt')
+                    await assertReady();
+                const marked = { ...next, status: 'dispatching', ...(next.attachments ? { attachments: next.attachments.map(row => ({ ...row })) } : {}) }, tail = queuedEntries.slice(1);
+                if (marked.kind === 'slash') {
+                    /* R5a Q-R5-8: out of the queue first, then run; a command that moved the session (/resume, /fork) takes what was
+                       typed after it along, since that was typed for the session it opens. */
+                    await replaceQueue(tail, id);
+                    try {
+                        await onQueuedSlash?.(marked.text);
+                    }
+                    catch (error) {
+                        onError(error);
+                    }
+                    if (current !== id) {
+                        const moved = tail.filter(entry => !queuedEntries.some(row => row.id === entry.id));
+                        if (current && moved.length) {
+                            await queueHydration;
+                            await persistFor(id, []);
+                            await replaceQueue([...queuedEntries, ...moved.map(entry => ({ ...entry, status: 'pending' }))], current);
+                            followed = current;
+                        }
+                        return;
+                    }
+                    continue;
+                }
+                await replaceQueue([marked, ...tail], id);
+                /* R5a S5 (E8, gate finding 8): a queued `!` command's own line is shown BEFORE it runs, so its row lands after it. */
+                if (marked.kind === 'command')
+                    onQueuedDispatch?.(actionOf(marked));
+                try {
+                    if (marked.kind === 'command')
+                        await runShellMutation(id, marked.text);
+                    else
+                        await runModelMutation('resume', id, () => runtime.resume(id, marked.text, marked.attachments));
+                }
+                catch (error) {
+                    if (current === id)
+                        await replaceQueue([{ ...marked, status: 'pending' }, ...tail], id).catch(onError);
+                    throw error;
+                }
+                await replaceQueue(tail, id);
+                if (marked.kind !== 'command')
+                    onQueuedDispatch?.(actionOf(marked));
+                if (marked.kind === 'prompt')
+                    return;
+            }
+        }
+        finally {
+            drainingQueue = false;
+            if (boundaryWhileDraining) {
+                boundaryWhileDraining = false;
+                requestQueuedDrain(id);
+            }
+            if (followed)
+                requestQueuedDrain(followed);
+        }
+    }
+    /* R5a Q-R5-8: a session-changing slash command typed during a turn waits in the queue (app.ts decides which ones). */
+    async function deferSlash(text, { running }) {
+        await queueHydration;
+        const value = String(text ?? '').trim();
+        if (!current)
+            throw new Error('SESSION_NOT_FOUND');
+        if (!value)
+            return 0;
+        const entry = await enqueue({ kind: 'slash', text: value });
+        if (!running && !queuePausedState)
+            await dispatchQueuedActions(current);
+        return queuePosition(entry);
+    }
+    function requestQueuedDrain(id) {
+        if (queuePausedState || pendingSteer || cancelling)
+            return;
+        if (drainingQueue) {
+            boundaryWhileDraining = true;
+            return;
+        }
+        void queueHydration.then(() => { if (current === id && !queuePausedState && !pendingSteer && !cancelling)
+            return dispatchQueuedActions(id); }).catch(onError);
+    }
+    async function assertReady() { if (!readiness)
+        return; const answer = await readiness(currentModel); if (!answer.ready)
+        throw new TuiNotReadyError(answer.code, answer.provider, answer.message); }
+    async function resolveId(id) { if (id !== 'last')
+        return id; const rows = await runtime.listSessions(); const row = rows.at(-1); if (!row?.sessionId)
+        throw new Error('SESSION_NOT_FOUND'); return String(row.sessionId); }
+    /*
+     * R1 lane R (D-04, D-08; gate E9). Re-attaching to an EXISTING session (resume, fork) replays its history synchronously inside
+     * `runtime.subscribe` (registry `iscriviti`, session-registry.mjs:5825-5831): those RunStarted events are marked `history`, so
+     * the transcript never lets an old message absorb a new send's echo. A session this controller has just started is not
+     * history — the prompt given on the command line is echoed by app.ts only after `initialize` returns.
+     * `openRun` follows the run lifecycle of the attached session; the kernel appends no terminal event to a run cut off by
+     * closing TALOS (measured: RunStarted, TextMessageStart, TextMessageContent, then nothing) but its session list says so.
+     */
+    let replayingHistory = false;
+    /*
+     * R3 gate E8, owner decision Q-R3-8. The kernel ends every stopped run with `RunError{code:'fermato'}`
+     * (harness-ui/src/agent-service.mjs:185); the CLI is the only one that knows the person asked for the stop, so it keeps
+     * that request until the run's terminal event and turns that event into the interrupted path the transcript already
+     * has (`run.cancelled{interrupted:true}`), with `reason:'person'` (a replayed cut-off run has no reason). A `fermato`
+     * nobody asked for (the model went silent), or any other code racing the stop, stays a failure. The request belongs to
+     * the run that was open when it was made: a new `run.started` drops it.
+     */
+    let stopRequested = null;
+    function personStopVerdict(id, event) {
+        if (event.type === 'run.started') {
+            stopRequested = null;
+            return event;
+        }
+        if (event.type !== 'run.failed' && event.type !== 'run.cancelled' && event.type !== 'run.completed')
+            return event;
+        const asked = stopRequested === id;
+        if (asked)
+            stopRequested = null;
+        /* A replayed `fermato` is the person's stop unless it is the kernel's exact "stopped without an answer" sentence. */
+        if (event.type !== 'run.failed' || event.error?.envelope?.code !== 'fermato')
+            return event;
+        const replayedStop = replayingHistory && (event.error.raw ?? event.error.message ?? '').trim() !== KERNEL_RUN_TEXT.stoppedWithoutAnswer;
+        if (!asked && !replayedStop)
+            return event;
+        return { type: 'run.cancelled', ...(event.runId ? { runId: event.runId } : {}), interrupted: true, reason: 'person', ...(event.eventId ? { eventId: event.eventId } : {}) };
+    }
+    let openRun = null;
+    function attach(id, from = 0, history = false) {
+        unsubscribe();
+        descendants.stop();
+        adapter.bindSession(id);
+        current = id;
+        openRun = null;
+        replayedApprovals.clear();
+        personCommandNext = null;
+        decidedTools.clear();
+        toolModes.clear();
+        const epoch = ++queueEpoch;
+        queueHydration = hydrateQueue(id, epoch);
+        replayingHistory = history;
+        try {
+            unsubscribe = runtime.subscribe(id, (raw) => { if (handleCheckpointRaw(id, raw))
+                return; processRawEvent(id, raw); }, from);
+        }
+        finally {
+            replayingHistory = false;
+        }
+        return id;
+    }
+    /* After a history replay, a run still open in the events but not running in the kernel was cut off: it is closed as
+       interrupted through one terminal event, so the transcript row and the status line (state.ts `run.cancelled`) agree with
+       the footer. Settled BEFORE any new prompt of the same resume is sent, and skipped if the session moved on meanwhile. */
+    async function settleReplayedRun(id) {
+        /* R3 E12 (Q-R3-15): the approvals the replay left unanswered are asked only when their run is still waiting. */
+        const waiting = [...replayedApprovals.values()];
+        replayedApprovals.clear();
+        const open = openRun;
+        if (!open || current !== id)
+            return;
+        let outcome = null;
+        try {
+            outcome = (await runtime.listSessions()).find((row) => row?.sessionId === id)?.outcome ?? null;
+        }
+        catch (error) {
+            developmentLogError('replay.settle.failure', error, { sessionId: id }, 'tui-controller');
+            return;
+        }
+        if (current === id && openRun === open && outcome === 'running') {
+            for (const event of waiting)
+                requestApproval(id, event);
+            descendants.start(id);
+            return;
+        }
+        if (current !== id || openRun !== open || typeof outcome !== 'string' || outcome === 'running' || outcome === 'unknown')
+            return;
+        openRun = null;
+        onEvent({ type: 'run.cancelled', ...(open.runId ? { runId: open.runId } : {}), interrupted: true });
+    }
+    async function listSessions() { return normalizeSessions(await runtime.listSessions()); }
+    async function agentTree() { if (!current)
+        return null; return buildAgentTree(await runtime.listSessions(), current); }
+    /* B1 slice 18, fix round: a prompt makes resume and fork a send, so readiness is asked FIRST — before the session list, the
+       subscription or the runtime call — and a not-ready answer reaches no runtime method. Without a prompt nothing is sent. */
+    async function referencesFor(text) { return resolveProjectReferences({ projectRoot, prompt: text }); }
+    function promptAction(text, attachments) { return attachments.length ? { kind: 'prompt', text, attachments } : { kind: 'prompt', text }; }
+    async function resumeSession(id, prompt) { const text = prompt?.trim(); if (text)
+        await assertReady(); const attachments = text ? await referencesFor(text) : []; const resolved = await resolveId(id); attach(resolved, 0, true); await queueHydration; await settleReplayedRun(resolved); if (text)
+        await runModelMutation('resume', resolved, () => runtime.resume(resolved, text, attachments)); return resolved; }
+    async function forkSession(id, prompt) { const text = prompt?.trim(); if (text)
+        await assertReady(); const attachments = text ? await referencesFor(text) : []; const resolved = await resolveId(id); const child = await runModelMutation('fork', null, () => runtime.fork(resolved, text, attachments)); attach(child, 0, true); await queueHydration; await settleReplayedRun(child); return child; }
+    async function initialize({ resume, fork, initialPrompt } = {}) { const text = initialPrompt?.trim(); if (text)
+        await assertReady(); const attachments = text ? await referencesFor(text) : []; if (resume || fork)
+        await runtime.restore(); if (resume) {
+        const id = await resolveId(resume);
+        attach(id, 0, true);
+        await queueHydration;
+        await settleReplayedRun(id);
+        if (text)
+            await runModelMutation('resume', id, () => runtime.resume(id, text, attachments));
+        return id;
+    } if (fork) {
+        const parent = await resolveId(fork);
+        const id = await runModelMutation('fork', null, () => runtime.fork(parent, text, attachments));
+        attach(id, 0, true);
+        await queueHydration;
+        await settleReplayedRun(id);
+        return id;
+    } if (text) {
+        const id = await runModelMutation('start', null, () => runtime.start({ projectRoot, prompt: text, model: currentModel, permissionMode: currentMode, ...(attachments.length ? { attachments } : {}) }));
+        attach(id, 0);
+        await queueHydration;
+        return id;
+    } return null; }
+    /*
+     * ⛔ IL PREFISSO `!` VA AL COMANDO, NON AL MODELLO. Nessun `start`/`resume` parte da questo ramo:
+     *   il testo non diventa mai un messaggio per il modello.
+     * ⛔ E senza sessione si RIFIUTA a voce alta: far sparire un comando digitato e' peggio che negarlo.
+     */
+    async function send(prompt, { running }) {
+        developmentLog('controller.send', { prompt: developmentTextEvidence(prompt), running, currentSessionId: current, model: currentModel, mode: currentMode, queueCount: queuedEntries.length }, 'debug', 'tui-controller');
+        await queueHydration;
+        const text = prompt.trim();
+        if (!text)
+            return { sessionId: current, kind: 'none', queued: false, position: 0 };
+        if (text.startsWith('!')) {
+            const command = text.slice(1).trim();
+            if (!command)
+                return { sessionId: current, kind: 'none', queued: false, position: 0 };
+            if (!current)
+                throw new Error(EXECUTION_TEXT.shellSessionRequired);
+            if (running || queuedEntries.length) {
+                const action = await enqueue({ kind: 'command', text: command });
+                if (!running && !queuePausedState)
+                    await dispatchQueuedActions(current);
+                const position = queuePosition(action);
+                return { sessionId: current, kind: 'command', queued: position > 0, position };
+            }
+            await runShellMutation(current, command);
+            return { sessionId: current, kind: 'command', queued: false, position: 0 };
+        }
+        await assertReady();
+        const attachments = await referencesFor(text);
+        if (running || queuedEntries.length) {
+            if (!current)
+                throw new Error('SESSION_NOT_FOUND');
+            const action = await enqueue(promptAction(text, attachments));
+            if (!running && !queuePausedState)
+                await dispatchQueuedActions(current);
+            const position = queuePosition(action);
+            return { sessionId: current, kind: 'prompt', queued: position > 0, position };
+        }
+        if (current) {
+            await runModelMutation('resume', current, () => runtime.resume(current, text, attachments));
+            return { sessionId: current, kind: 'prompt', queued: false, position: 0 };
+        }
+        const id = await runModelMutation('start', null, () => runtime.start({ projectRoot, prompt: text, model: currentModel, permissionMode: currentMode, ...(attachments.length ? { attachments } : {}) }));
+        attach(id, 0);
+        return { sessionId: id, kind: 'prompt', queued: false, position: 0 };
+    }
+    async function steer(prompt, { running }) {
+        await queueHydration;
+        const text = String(prompt ?? '').trim();
+        if (!text)
+            return rejectSteer('STEER_TEXT_REQUIRED', 'Steering text is required.');
+        if (text.startsWith('!'))
+            return rejectSteer('STEER_COMMAND_UNSUPPORTED', 'Shell commands cannot be used as steering input.');
+        if (!current)
+            return rejectSteer('SESSION_NOT_FOUND', 'There is no active session to steer.');
+        if (!running)
+            return rejectSteer('STEER_NOT_RUNNING', 'Steering requires an active run.');
+        if (pendingSteer || steerInvocation)
+            return rejectSteer('STEER_ALREADY_PENDING', 'A steering request is already waiting for a safe boundary.');
+        try {
+            await assertReady();
+            const attachments = await referencesFor(text);
+            steerInvocation = { text };
+            const accepted = await runtime.steer(current, text, attachments);
+            const correlated = pendingSteerNow();
+            if (correlated && correlated.redirectId !== accepted.redirectId) {
+                const stale = correlated;
+                pendingSteer = null;
+                steerState({ status: 'failed', redirectId: stale.redirectId, code: 'STEER_CORRELATION_FAILED', message: 'The runtime returned a different steering correlation id.' });
+                return rejectSteer('STEER_CORRELATION_FAILED', 'The runtime returned a different steering correlation id.');
+            }
+            if (!pendingSteerNow()) {
+                pendingSteer = { redirectId: accepted.redirectId, text };
+                steerState({ status: 'requested', redirectId: accepted.redirectId });
+            }
+            return { status: 'requested', redirectId: accepted.redirectId };
+        }
+        catch (error) {
+            pendingSteer = null;
+            const code = typeof error?.code === 'string' ? error.code : 'SESSION_STEER_REJECTED', message = error instanceof Error ? error.message : String(error);
+            return rejectSteer(code, message);
+        }
+        finally {
+            steerInvocation = null;
+        }
+    }
+    async function editQueue(id, text) { await queueHydration; if (!current)
+        throw new Error('SESSION_NOT_FOUND'); const index = queuedEntries.findIndex(row => row.id === id); if (index < 0)
+        throw new Error('QUEUE_ENTRY_NOT_FOUND'); const value = text.trim(); if (!value)
+        throw new Error('QUEUE_TEXT_REQUIRED'); const previous = queuedEntries[index], attachments = previous.kind === 'prompt' ? await referencesFor(value) : []; const edited = { id: previous.id, kind: previous.kind, text: value, status: 'pending', ...(attachments.length ? { attachments } : {}) }; const next = [...queuedEntries]; next[index] = edited; await replaceQueue(next, current); }
+    async function moveQueue(id, direction) { await queueHydration; if (!current)
+        throw new Error('SESSION_NOT_FOUND'); const index = queuedEntries.findIndex(row => row.id === id); if (index < 0)
+        throw new Error('QUEUE_ENTRY_NOT_FOUND'); const target = Math.max(0, Math.min(queuedEntries.length - 1, index + direction)); if (target === index)
+        return; const next = [...queuedEntries]; const [entry] = next.splice(index, 1); next.splice(target, 0, entry); await replaceQueue(next, current); }
+    async function deleteQueue(id) { await queueHydration; if (!current)
+        throw new Error('SESSION_NOT_FOUND'); const index = queuedEntries.findIndex(row => row.id === id); if (index < 0)
+        return null; const next = [...queuedEntries]; const [removed] = next.splice(index, 1); await replaceQueue(next, current); if (next.length === 0)
+        queuePausedState = false; return removed ? publicEntry(removed) : null; }
+    async function clearQueue() { await queueHydration; const dropped = queueSnapshot(); if (current)
+        await replaceQueue([], current);
+    else {
+        queuedEntries.length = 0;
+        notifyQueue();
+    } queuePausedState = false; return dropped; }
+    async function dispatchQueue() { await queueHydration; if (!current)
+        throw new Error('SESSION_NOT_FOUND'); if (!queuedEntries.length) {
+        queuePausedState = false;
+        return 0;
+    } const normalized = queuedEntries.map(row => row.status === 'dispatching' ? { ...row, status: 'pending' } : row); await replaceQueue(normalized, current); queuePausedState = false; await dispatchQueuedActions(current); return queuedEntries.length; }
+    let interruptPromise = null;
+    let interruptTerminalSession = null;
+    let interruptTerminalResolve = null;
+    async function interrupt() {
+        await queueHydration;
+        if (!current)
+            return queuedEntries.length;
+        if (interruptPromise)
+            return interruptPromise;
+        const sessionId = current;
+        cancelling = true;
+        interruptTerminalSession = sessionId;
+        if (openRun)
+            stopRequested = sessionId;
+        const terminal = new Promise(resolve => { interruptTerminalResolve = resolve; });
+        interruptPromise = (async () => {
+            try {
+                await runtime.cancel(sessionId);
+                await terminal;
+            }
+            catch (error) {
+                queuePausedState = true;
+                onError(error);
+                throw error;
+            }
+            finally {
+                cancelling = false;
+                interruptTerminalSession = null;
+                interruptTerminalResolve = null;
+            }
+            if (current !== sessionId || queuedEntries.length === 0)
+                return queuedEntries.length;
+            const normalized = queuedEntries.map(row => row.status === 'dispatching' ? { ...row, status: 'pending' } : row);
+            await replaceQueue(normalized, sessionId);
+            queuePausedState = false;
+            await dispatchQueuedActions(sessionId);
+            return queuedEntries.length;
+        })().finally(() => { interruptPromise = null; });
+        return interruptPromise;
+    }
+    return { initialize, attach, send, deferSlash, steer, listSessions, agentTree, resumeSession, forkSession, pendingCommands: () => queuedEntries.filter(action => action.kind === 'command').length, pendingPrompts: () => queuedEntries.filter(action => action.kind === 'prompt').length, queue: queueSnapshot, queueEntries: queueEntriesSnapshot, queuePaused: () => queuePausedState, queueReady: () => queueHydration, editQueue, moveQueue, deleteQueue, clearQueue, dispatchQueue, interrupt, current: () => current, mode: () => currentMode, setMode(next) { currentMode = next; }, model: () => currentModel, setModel(next) { if (typeof next !== 'string' || !next.trim())
+            throw new Error('MODEL_REQUIRED'); currentModel = next.trim(); }, async compact() { if (!current)
+            throw new Error('SESSION_NOT_FOUND'); return runtime.compact(current); }, async resolveApproval(requestId, choice) { /* R3 R3-ROW: the link is taken BEFORE the answer: the kernel's ApprovalResolved arrives during the await and drops it. */ const toolCallId = approvalTools.get(requestId); approvalTools.delete(requestId); if (toolCallId && !choice.startsWith('allow-'))
+            adapter.noteDenial(toolCallId, { by: 'person' }); await coordinator.resolve(requestId, choice); const decision = decisionFromChoice(choice); if (toolCallId && decision)
+            emitDecision(toolCallId, decision); onApproval?.(null); }, async cancel() { if (!current)
+            return []; const dropped = queueSnapshot(); if (openRun)
+            stopRequested = current; onEvent({ type: 'run.cancelled' }); cancelling = true; try {
+            await runtime.cancel(current);
+            await clearQueue();
+            return dropped;
+        }
+        catch (error) {
+            queuePausedState = true;
+            onError(error);
+            throw error;
+        }
+        finally {
+            cancelling = false;
+        } }, close() { if (closed)
+            return; closed = true; developmentLog('controller.close', { sessionId: current, queueCount: queuedEntries.length }, 'info', 'tui-controller'); descendants.stop(); unsubscribe(); } };
+}