@adhdev/daemon-core 0.9.82-rc.18 → 0.9.82-rc.180

package/src/cli-adapters/provider-cli-adapter.ts

@@ -16,6 +16,7 @@
 
 import * as os from 'os';
 import type { CliAdapter } from '../cli-adapter-types.js';
+import type { InteractivePromptResponse } from '../providers/types/interactive-prompt.js';
 import { LOG } from '../logging/logger.js';
 import { getDebugRuntimeConfig } from '../logging/debug-config.js';
 import { TerminalScreen } from './terminal-screen.js';
@@ -44,6 +45,13 @@ import {
     type CliTraceEntry,
     type ParsedSession,
 } from './provider-cli-shared.js';
+import { CliScriptRunner } from './cli-script-runner.js';
+import {
+    CliStateEngine,
+    type CliBufferSnapshot,
+    type CliTransportAccess,
+    type CliStateEngineCallbacks,
+} from './cli-state-engine.js';
 import {
     buildCliParseInput,
     buildCliTraceParseSnapshot,
@@ -78,24 +86,6 @@ export {
 } from './provider-cli-shared.js';
 
 
-interface IdleFinishCandidate {
-    armedAt: number;
-    lastOutputAt: number;
-    lastScreenChangeAt: number;
-    responseEpoch: number;
-    assistantLength: number;
-}
-
-interface SettledEvalContext {
-    now: number;
-    modal: any;
-    status: string;
-    parsedMessages: CliChatMessage[];
-    lastParsedAssistant: CliChatMessage | undefined;
-    parsedStatus: string | null;
-    prevStatus: string;
-}
-
 interface SendMessageState {
     text: string;
     normalizedPromptSnippet: string;
@@ -110,6 +100,14 @@ interface SendMessageCompletion {
     rejectOnce: (error: unknown) => void;
 }
 
+interface PendingOutboundMessage {
+    id: string;
+    role: 'user';
+    content: string;
+    queuedAt: number;
+    source: 'sendMessage';
+}
+
 export function appendBoundedText(current: string, chunk: string, maxChars: number): string {
     if (!chunk) return current.length <= maxChars ? current : current.slice(-maxChars);
     if (maxChars <= 0) return '';
@@ -122,23 +120,23 @@ export function appendBoundedText(current: string, chunk: string, maxChars: numb
 // ─── Adapter ────────────────────────────────────────
 
 export class ProviderCliAdapter implements CliAdapter {
-    readonly cliType: string;
+    cliType: string;
     readonly cliName: string;
     public workingDir: string;
 
     private provider: CliProviderModule;
     private ptyProcess: PtyRuntimeTransport | null = null;
     private transportFactory: PtyTransportFactory;
-    private currentStatus: CliSessionStatus['status'] = 'starting';
     private onStatusChange: (() => void) | null = null;
 
+    // ─── State machine engine ─────────────────────────
+    readonly engine: CliStateEngine;
+
     private responseBuffer = '';
     private recentOutputBuffer = '';
-    private isWaitingForResponse = false;
-    private activeModal: { message: string; buttons: string[] } | null = null;
-    private parseErrorMessage: string | null = null;
+    private get parseErrorMessage(): string | null { return this.runner.parseErrorMessage; }
+    private providerSessionId: string | null = null;
     private responseTimeout: NodeJS.Timeout | null = null;
-    private idleTimeout: NodeJS.Timeout | null = null;
     private ready = false;
     private startupBuffer = '';
     private startupParseGate = false;
@@ -164,39 +162,48 @@ export class ProviderCliAdapter implements CliAdapter {
     private serverConn: any = null;
     private logBuffer: { message: string; level: string }[] = [];
 
- // Approval cooldown
-    private lastApprovalResolvedAt: number = 0;
-
- // Approval state machine
-    private approvalTransitionBuffer: string = '';
-    private approvalExitTimeout: NodeJS.Timeout | null = null;
-    private pendingScriptStatus: 'generating' | 'waiting_approval' | null = null;
-    private pendingScriptStatusSince = 0;
-    private pendingScriptStatusTimer: NodeJS.Timeout | null = null;
-
- // Output settle debounce — fires after PTY output goes quiet
-    private settleTimer: NodeJS.Timeout | null = null;
-    private settledBuffer: string = '';
-    private submitPendingUntil = 0;
-    private responseSettleIgnoreUntil = 0;
-    private responseEpoch = 0;
+    private pendingOutboundQueue: PendingOutboundMessage[] = [];
+    private pendingOutboundFlushTimer: NodeJS.Timeout | null = null;
+    private pendingOutboundFlushInFlight = false;
+    // Submit retry timer — PTY-level, not state machine
     private submitRetryTimer: NodeJS.Timeout | null = null;
-    private submitRetryUsed = false;
-    private submitRetryPromptSnippet = '';
-    private idleFinishCandidate: IdleFinishCandidate | null = null;
-    private finishRetryTimer: NodeJS.Timeout | null = null;
-    private finishRetryCount = 0;
 
  // Resize redraw suppression
     private resizeSuppressUntil: number = 0;
 
- // Debug: status transition history
-    private statusHistory: { status: string; at: number; trigger?: string }[] = [];
+    // (A2.2) Native transcript anchor moved to CHAT_SOURCE_REGISTRY.
+    // ChatSourceMachine holds the lock by state, not by a mutable field on
+    // the adapter. Removed entirely; no callers remain after the readChat
+    // ladder was replaced.
+
+    // ─── Script runner (parsing isolated here, adapter stays as transport) ───
+    private readonly runner: CliScriptRunner;
+    /** @deprecated use runner.cliScripts for direct script access */
+    get cliScripts(): CliScripts { return this.runner.cliScripts; }
 
-    // ─── CLI Scripts (script-based parsing) ───
-    private cliScripts: CliScripts;
-    /** Per-session opaque state object created by cliScripts.createState(), reset on stop. */
-    private scriptState: unknown = null;
+    /**
+     * Recent script invocations (oldest → newest). Exposed via the
+     * `get_chat_debug_bundle` daemon command so anyone debugging a
+     * stuck-status regression can read what each detectStatus /
+     * parseSession call actually saw and returned, instead of having
+     * to instrument the daemon.
+     */
+    getScriptInvocationTrace() {
+        return this.runner.getInvocationTrace();
+    }
+
+    /**
+     * Returns the full raw PTY byte stream captured since adapter start.
+     * Used by the `record_provider_pty` IPC command to produce fixtures.
+     * Bounded by MAX_ACCUMULATED_BUFFER; older bytes may have been dropped.
+     */
+    getAccumulatedRawBuffer(): { text: string; droppedChars: number } {
+        return {
+            text: this.accumulatedRawBuffer,
+            droppedChars: this.accumulatedRawBufferDroppedChars,
+        };
+    }
+    set cliScripts(scripts: CliScripts) { this.setCliScripts(scripts); }
     private runtimeSettings: Record<string, any> = {};
     /** Full accumulated rendered PTY transcript for parser/readback use */
     private accumulatedBuffer: string = '';
@@ -216,10 +223,6 @@ export class ProviderCliAdapter implements CliAdapter {
      *  Hermes turn (tool calls + reasoning + final bubble) without the
      *  rolling window pushing the turn's ╭─ opening line out of view. */
     private static readonly MAX_ACCUMULATED_BUFFER = 262144;
-    private currentTurnScope: TurnParseScope | null = null;
-    private traceEntries: CliTraceEntry[] = [];
-    private traceSeq = 0;
-    private traceSessionId = '';
     private parsedStatusCache: {
         responseBuffer: string;
         currentTurnScope: TurnParseScope | null;
@@ -233,11 +236,8 @@ export class ProviderCliAdapter implements CliAdapter {
         result: any;
     } | null = null;
     private static readonly SCREEN_SNAPSHOT_MIN_INTERVAL_MS = 250;
-    private static readonly MAX_TRACE_ENTRIES = 250;
 
     private readonly providerResolutionMeta: ProviderResolutionMeta;
-    private static readonly FINISH_RETRY_DELAY_MS = 300;
-    private static readonly MAX_FINISH_RETRIES = 2;
 
     private getBufferState(): NonNullable<CliSessionStatus['bufferState']> | undefined {
         const build = (droppedChars: number, maxChars: number) => droppedChars > 0
@@ -313,13 +313,13 @@ export class ProviderCliAdapter implements CliAdapter {
         if (
             cached
             && cached.responseBuffer === this.responseBuffer
-            && cached.currentTurnScope === this.currentTurnScope
+            && cached.currentTurnScope === this.engine.currentTurnScope
             && cached.recentOutputBuffer === this.recentOutputBuffer
             && cached.accumulatedBuffer === this.accumulatedBuffer
             && cached.accumulatedRawBufferKey === accumulatedRawBufferKey
             && cached.screenText === this.lastScreenText
-            && cached.currentStatus === this.currentStatus
-            && cached.activeModal === this.activeModal
+            && cached.currentStatus === this.engine.currentStatus
+            && cached.activeModal === this.engine.activeModal
             && cached.cliName === this.cliName
         ) {
             return cached.result;
@@ -343,86 +343,6 @@ export class ProviderCliAdapter implements CliAdapter {
         return this.timeouts.statusActivityHold;
     }
 
-    private setStatus(status: CliSessionStatus['status'], trigger?: string): void {
-        const prev = this.currentStatus;
-        if (prev === status) return;
-        this.currentStatus = status;
-        this.statusHistory.push({ status, at: Date.now(), trigger });
-        if (this.statusHistory.length > 50) this.statusHistory.shift();
-        this.recordTrace('status', {
-            previousStatus: prev,
-            trigger: trigger || null,
-        });
-        LOG.info('CLI', `[${this.cliType}] status: ${prev} → ${status}${trigger ? ` (${trigger})` : ''}`);
-    }
-
-    private clearIdleFinishCandidate(reason: string): void {
-        if (!this.idleFinishCandidate) return;
-        this.recordTrace('idle_candidate_reset', {
-            reason,
-            candidate: this.idleFinishCandidate,
-        });
-        this.idleFinishCandidate = null;
-    }
-
-    private armIdleFinishCandidate(assistantLength: number): void {
-        const now = Date.now();
-        const idleFinishConfirmMs = this.getIdleFinishConfirmMs();
-        this.idleFinishCandidate = {
-            armedAt: now,
-            lastOutputAt: this.lastOutputAt,
-            lastScreenChangeAt: this.lastScreenChangeAt,
-            responseEpoch: this.responseEpoch,
-            assistantLength,
-        };
-        this.recordTrace('idle_candidate_armed', {
-            confirmMs: idleFinishConfirmMs,
-            candidate: this.idleFinishCandidate,
-            ...buildCliTraceParseSnapshot({
-                accumulatedBuffer: this.accumulatedBuffer,
-                accumulatedRawBuffer: this.accumulatedRawBuffer,
-                responseBuffer: this.responseBuffer,
-                partialResponse: this.responseBuffer,
-                scope: this.currentTurnScope,
-            }),
-        });
-        if (this.settleTimer) clearTimeout(this.settleTimer);
-        this.settleTimer = setTimeout(() => {
-            this.settleTimer = null;
-            this.settledBuffer = this.recentOutputBuffer;
-            this.evaluateSettled();
-        }, idleFinishConfirmMs);
-    }
-
-
-    private recordTrace(type: string, payload: Record<string, any> = {}): void {
-        const entry: CliTraceEntry = {
-            id: ++this.traceSeq,
-            at: Date.now(),
-            type,
-            status: this.currentStatus,
-            isWaitingForResponse: this.isWaitingForResponse,
-            activeModal: this.activeModal
-                ? { message: this.activeModal.message, buttons: [...this.activeModal.buttons] }
-                : null,
-            payload,
-        };
-        this.traceEntries.push(entry);
-        if (this.traceEntries.length > ProviderCliAdapter.MAX_TRACE_ENTRIES) {
-            this.traceEntries.splice(0, this.traceEntries.length - ProviderCliAdapter.MAX_TRACE_ENTRIES);
-        }
-    }
-
-    private resetTraceSession(): void {
-        this.traceEntries = [];
-        this.traceSeq = 0;
-        this.traceSessionId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-        this.recordTrace('session_start', {
-            providerType: this.cliType,
-            workingDir: this.workingDir,
-        });
-    }
-
  // Resolved timeouts
     private readonly timeouts: Required<NonNullable<CliProviderModule['timeouts']>>;
 
@@ -432,7 +352,6 @@ export class ProviderCliAdapter implements CliAdapter {
     private readonly sendKey: string;
     private readonly submitStrategy: 'wait_for_echo' | 'immediate';
     private readonly requirePromptEchoBeforeSubmit: boolean;
-    private static readonly SCRIPT_STATUS_DEBOUNCE_MS = 3000;
 
     constructor(
         provider: CliProviderModule,
@@ -441,6 +360,7 @@ export class ProviderCliAdapter implements CliAdapter {
         private extraEnv: Record<string, string> = {},
         transportFactory: PtyTransportFactory = new NodePtyTransportFactory(),
     ) {
+        this.runner = new CliScriptRunner(provider.type);
         this.provider = provider;
         this.transportFactory = transportFactory;
         this.cliType = provider.type;
@@ -458,10 +378,33 @@ export class ProviderCliAdapter implements CliAdapter {
         this.requirePromptEchoBeforeSubmit = resolvedConfig.requirePromptEchoBeforeSubmit;
         this.providerResolutionMeta = resolvedConfig.providerResolutionMeta;
 
-        // Scripts are required — loaded by ProviderLoader via compatibility array
-        this.cliScripts = provider.scripts || {};
-        this.scriptState = typeof this.cliScripts.createState === 'function' ? (this.cliScripts.createState() ?? null) : null;
-        const scriptNames = listCliScriptNames(this.cliScripts);
+        // State machine engine — owns all status transitions
+        this.engine = new CliStateEngine(
+            provider,
+            this.runner,
+            this as unknown as CliTransportAccess,
+            {
+                onStatusChange: () => { this.onStatusChange?.(); },
+                onApplyParsedSession: (session) => { this.applyParsedSessionMetadata(session); },
+                onTurnCompleted: () => { this.responseBuffer = ''; },
+            } satisfies CliStateEngineCallbacks,
+            resolvedConfig.timeouts,
+        );
+
+        // Scripts delegated to CliScriptRunner — adapter stays as transport.
+        // Pass the manifest tui block so the runner can build the
+        // declarativeDetectStatus / declarativeParseApproval SDK functions
+        // that v1 extended-tier overrides depend on (without these, scripts
+        // like codex-cli's detect_status v1 fail-closed with return 'idle'
+        // and the session sticks in `generating` forever).
+        this.runner.setScripts(provider.scripts || {}, provider.tui);
+        // Per-invocation wall-clock budget for provider scripts. Manifests may
+        // raise this for genuinely slow parsers, but the default (50ms) is the
+        // settle-loop safety net — any script that exceeds it gets flagged in
+        // the invocation trace and surfaced via the debug bundle so we can
+        // identify the offender instead of guessing why the settle loop hangs.
+        this.runner.setScriptCallBudget(provider.scriptCallBudgetMs ?? 50);
+        const scriptNames = this.runner.getScriptNames();
         if (scriptNames.length > 0) {
             LOG.info('CLI', `[${this.cliType}] CLI scripts: [${scriptNames.join(', ')}]`);
             LOG.info(
@@ -487,14 +430,9 @@ export class ProviderCliAdapter implements CliAdapter {
 
     /** Inject CLI scripts after construction (e.g. when resolved by ProviderLoader) */
     setCliScripts(scripts: CliScripts): void {
-        this.cliScripts = scripts;
+        this.runner.setScripts(scripts);
         this.parsedStatusCache = null;
-        this.parseErrorMessage = null;
-        // Initialize per-session state: createState() is called once here and on script reload.
-        // The returned object lives until the PTY exits (scriptState = null on exit).
-        this.scriptState = typeof scripts.createState === 'function' ? (scripts.createState() ?? null) : null;
-        const scriptNames = listCliScriptNames(scripts);
-        LOG.info('CLI', `[${this.cliType}] CLI scripts injected: [${scriptNames.join(', ')}]`);
+        LOG.info('CLI', `[${this.cliType}] CLI scripts injected: [${this.runner.getScriptNames().join(', ')}]`);
     }
 
     /** Refresh provider scripts/config used by this adapter without restarting the PTY runtime. */
@@ -548,15 +486,6 @@ export class ProviderCliAdapter implements CliAdapter {
         });
 
         LOG.info('CLI', `[${this.cliType}] Spawning in ${this.workingDir}`);
-        this.resetTraceSession();
-        this.recordTrace('spawn', {
-            shellCommand: spawnPlan.shellCmd,
-            shellArgs: spawnPlan.shellArgs,
-            cwd: spawnPlan.ptyOptions.cwd,
-            cols: spawnPlan.ptyOptions.cols,
-            rows: spawnPlan.ptyOptions.rows,
-            providerResolution: this.providerResolutionMeta,
-        });
 
         try {
             this.ptyProcess = this.transportFactory.spawn(
@@ -620,13 +549,12 @@ export class ProviderCliAdapter implements CliAdapter {
         this.ptyProcess.onExit(({ exitCode }: { exitCode: number }) => {
             LOG.info('CLI', `[${this.cliType}] Exit code ${exitCode}`);
             this.flushPendingOutputParse();
-            this.recordTrace('exit', { exitCode });
             this.ptyProcess = null;
-            this.setStatus('stopped', 'pty_exit');
+            this.engine.onPtyExit();
             this.ready = false;
             this.startupParseGate = false;
             this.spawnAt = 0;
-            this.scriptState = null;
+            this.runner.resetSessionState();
             this.onStatusChange?.();
         });
 
@@ -637,15 +565,9 @@ export class ProviderCliAdapter implements CliAdapter {
         if (this.startupSettleTimer) { clearTimeout(this.startupSettleTimer); this.startupSettleTimer = null; }
         this.resetTerminalScreen(24, 80);
         this.pendingTerminalQueryTail = '';
-        this.currentTurnScope = null;
-        this.finishRetryCount = 0;
-        if (this.finishRetryTimer) { clearTimeout(this.finishRetryTimer); this.finishRetryTimer = null; }
         this.ready = false;
         await this.ptyProcess.ready;
-        this.recordTrace('ready', {
-            runtimeMeta: this.getRuntimeMetadata(),
-        });
-        this.setStatus('starting', 'pty_ready');
+        this.engine.onSpawnReady();
         this.scheduleStartupSettleCheck();
         this.onStatusChange?.();
     }
@@ -671,11 +593,11 @@ export class ProviderCliAdapter implements CliAdapter {
         if (this.startupParseGate && !this.startupFirstOutputAt && (cleanData.trim() || normalizedScreenSnapshot.trim())) {
             this.startupFirstOutputAt = now;
         }
-        if (this.idleFinishCandidate && (rawData.length > 0 || cleanData.length > 0)) {
-            this.clearIdleFinishCandidate('new_output');
+        if (rawData.length > 0 || cleanData.length > 0) {
+            this.engine.clearIdleFinishCandidate('new_output');
         }
         if (getDebugRuntimeConfig().collectDebugTrace) {
-            this.recordTrace('output', {
+            this.engine.recordExternalTrace('output', {
                 rawLength: rawData.length,
                 cleanLength: cleanData.length,
                 rawPreview: summarizeCliTraceText(rawData, 300),
@@ -687,7 +609,7 @@ export class ProviderCliAdapter implements CliAdapter {
             this.scheduleStartupSettleCheck();
         }
 
-        if (this.isWaitingForResponse && cleanData) {
+        if (this.engine.isWaitingForResponse && cleanData) {
             const previousResponseLen = this.responseBuffer.length;
             this.responseBuffer = appendBoundedText(this.responseBuffer, cleanData, ProviderCliAdapter.MAX_RESPONSE_BUFFER);
             this.responseBufferDroppedChars += this.recordBoundedAppendDrop(previousResponseLen, cleanData.length, this.responseBuffer.length);
@@ -726,19 +648,19 @@ export class ProviderCliAdapter implements CliAdapter {
         // Keep turn-scope offsets aligned with the truncated buffer so scoped
         // parses don't lose the beginning of a long turn (e.g. the Hermes
         // ╭─ opening line) when the rolling window sheds bytes.
-        if (this.currentTurnScope) {
+        if (this.engine.currentTurnScope) {
             if (droppedClean > 0) {
-                this.currentTurnScope.bufferStart = Math.max(0, this.currentTurnScope.bufferStart - droppedClean);
+                this.engine.currentTurnScope.bufferStart = Math.max(0, this.engine.currentTurnScope.bufferStart - droppedClean);
             }
             if (droppedRaw > 0) {
-                this.currentTurnScope.rawBufferStart = Math.max(0, this.currentTurnScope.rawBufferStart - droppedRaw);
+                this.engine.currentTurnScope.rawBufferStart = Math.max(0, this.engine.currentTurnScope.rawBufferStart - droppedRaw);
             }
         }
 
         this.resolveStartupState('output', screenText, normalizedScreenSnapshot, now);
 
         // ─── Script-based status detection
-        this.scheduleSettle();
+        this.engine.scheduleSettle();
     }
 
     private resolveStartupState(
@@ -761,6 +683,11 @@ export class ProviderCliAdapter implements CliAdapter {
         if (stableMs < 2000) return;
 
         const startupModal = this.runParseApproval(this.recentOutputBuffer);
+        const startupStatus = this.runDetectStatus(screenText || this.recentOutputBuffer);
+        if (!startupModal && startupStatus !== 'idle') {
+            this.scheduleStartupSettleCheck();
+            return;
+        }
         this.startupParseGate = false;
         if (this.startupSettleTimer) {
             clearTimeout(this.startupSettleTimer);
@@ -768,14 +695,22 @@ export class ProviderCliAdapter implements CliAdapter {
         }
         this.ready = true;
         if (startupModal) {
-            this.activeModal = startupModal;
-            this.setStatus('waiting_approval', `startup_ready:${trigger}`);
+            this.engine.activeModal = startupModal;
+            this.engine.setStatus('waiting_approval', `startup_ready:${trigger}`);
         } else {
-            if (this.currentStatus === 'waiting_approval' || this.activeModal) {
-                this.lastApprovalResolvedAt = Date.now();
+            if (this.engine.currentStatus === 'waiting_approval' || this.engine.activeModal) {
+                this.engine.lastApprovalResolvedAt = Date.now();
             }
-            this.activeModal = null;
-            this.setStatus('idle', `startup_ready:${trigger}`);
+            this.engine.activeModal = null;
+            // Clear the in-flight turn flag at the same time we declare
+            // startup-idle. Otherwise the next settled evaluation sees
+            // isWaitingForResponse=true + recent CLI welcome-screen paints
+            // and flips us right back to generating via the hold path
+            // (the "startup → generating → idle → generating → idle"
+            // flicker the user observed on claude-cli launch).
+            this.engine.isWaitingForResponse = false;
+            this.engine.currentTurnScope = null;
+            this.engine.setStatus('idle', `startup_ready:${trigger}`);
         }
         LOG.info(
             'CLI',
@@ -801,88 +736,6 @@ export class ProviderCliAdapter implements CliAdapter {
         }, delayMs);
     }
 
-    private scheduleSettle(): void {
-        if (this.settleTimer) clearTimeout(this.settleTimer);
-        const settleEpoch = this.responseEpoch;
-        const delay = Math.max(
-            this.timeouts.outputSettle,
-            this.submitPendingUntil > Date.now()
-                ? (this.submitPendingUntil - Date.now()) + this.timeouts.outputSettle
-                : 0,
-        );
-        this.settleTimer = setTimeout(() => {
-            this.settleTimer = null;
-            if (settleEpoch !== this.responseEpoch) return;
-            this.settledBuffer = this.recentOutputBuffer;
-            this.evaluateSettled();
-        }, delay);
-    }
-
-    private armApprovalExitTimeout(): void {
-        if (this.approvalExitTimeout) clearTimeout(this.approvalExitTimeout);
-        this.approvalExitTimeout = setTimeout(() => {
-            if (!this.hasActionableApproval()) return;
-            const tail = this.recentOutputBuffer;
-            const screenText = this.terminalScreen.getText() || '';
-            const modal = this.runParseApproval(tail);
-            const stillWaiting = this.runDetectStatus(tail) === 'waiting_approval' || !!modal;
-            if (stillWaiting) {
-                if (!modal) {
-                    LOG.warn('CLI', `[${this.cliType}] approval timeout check found no actionable modal; keeping approval state fail-closed`);
-                    this.activeModal = null;
-                    this.onStatusChange?.();
-                    this.armApprovalExitTimeout();
-                    return;
-                }
-                this.activeModal = modal;
-                this.onStatusChange?.();
-                this.armApprovalExitTimeout();
-                return;
-            }
-            LOG.warn('CLI', `[${this.cliType}] Approval timeout — auto-clearing`);
-            this.activeModal = null;
-            this.lastApprovalResolvedAt = Date.now();
-            this.setStatus('idle', 'approval_timeout');
-            this.onStatusChange?.();
-        }, 60000);
-    }
-
-    private shouldRetryFinishResponse(commitResult: { hasAssistant: boolean; assistantContent: string }): boolean {
-        if (!this.currentTurnScope) return false;
-        if (this.hasActionableApproval()) return false;
-        if (this.finishRetryCount >= ProviderCliAdapter.MAX_FINISH_RETRIES) return false;
-        if (commitResult.hasAssistant && commitResult.assistantContent.trim()) return false;
-
-        if (this.runDetectStatus(this.recentOutputBuffer) !== 'idle') return false;
-
-        const now = Date.now();
-        const quietForMs = this.lastNonEmptyOutputAt ? (now - this.lastNonEmptyOutputAt) : Number.MAX_SAFE_INTEGER;
-        const screenStableMs = this.lastScreenChangeAt ? (now - this.lastScreenChangeAt) : 0;
-        return quietForMs < 1200 || screenStableMs < 1200 || !commitResult.hasAssistant;
-    }
-
-    private hasRecentInteractiveActivity(now: number): boolean {
-        const quietForMs = this.lastNonEmptyOutputAt ? (now - this.lastNonEmptyOutputAt) : Number.MAX_SAFE_INTEGER;
-        const screenStableMs = this.lastScreenChangeAt ? (now - this.lastScreenChangeAt) : Number.MAX_SAFE_INTEGER;
-        const holdMs = this.getStatusActivityHoldMs();
-        return quietForMs < holdMs
-            || screenStableMs < holdMs;
-    }
-
-    private shouldDeferIdleTimeoutFinish(): boolean {
-        if (!this.isWaitingForResponse || this.hasActionableApproval()) {
-            return false;
-        }
-        const latestStatus = this.runDetectStatus(this.recentOutputBuffer) || this.currentStatus;
-        if (latestStatus === 'generating') {
-            this.settledBuffer = this.recentOutputBuffer;
-            this.evaluateSettled();
-            return true;
-        }
-        return false;
-    }
-
-
     private async waitForInteractivePrompt(maxWaitMs = 5000): Promise<void> {
         const startedAt = Date.now();
         let loggedWait = false;
@@ -892,7 +745,7 @@ export class ProviderCliAdapter implements CliAdapter {
             const screenText = this.terminalScreen.getText() || '';
             const stableMs = this.lastScreenChangeAt ? (Date.now() - this.lastScreenChangeAt) : 0;
             const recentlyOutput = this.lastNonEmptyOutputAt ? (Date.now() - this.lastNonEmptyOutputAt) : Number.MAX_SAFE_INTEGER;
-            const status = this.runDetectStatus(this.recentOutputBuffer) || this.currentStatus;
+            const status = this.runDetectStatus(this.recentOutputBuffer) || this.engine.currentStatus;
             const interactiveReady = status === 'idle'
                 && stableMs >= 700
                 && recentlyOutput >= 350;
@@ -926,637 +779,84 @@ export class ProviderCliAdapter implements CliAdapter {
 
     private clearAllTimers(): void {
         if (this.responseTimeout) { clearTimeout(this.responseTimeout); this.responseTimeout = null; }
-        if (this.idleTimeout) { clearTimeout(this.idleTimeout); this.idleTimeout = null; }
-        if (this.approvalExitTimeout) { clearTimeout(this.approvalExitTimeout); this.approvalExitTimeout = null; }
         if (this.submitRetryTimer) { clearTimeout(this.submitRetryTimer); this.submitRetryTimer = null; }
-        if (this.finishRetryTimer) { clearTimeout(this.finishRetryTimer); this.finishRetryTimer = null; }
-        if (this.settleTimer) { clearTimeout(this.settleTimer); this.settleTimer = null; }
-        if (this.pendingScriptStatusTimer) { clearTimeout(this.pendingScriptStatusTimer); this.pendingScriptStatusTimer = null; }
         if (this.pendingOutputParseTimer) { clearTimeout(this.pendingOutputParseTimer); this.pendingOutputParseTimer = null; }
         if (this.ptyOutputFlushTimer) { clearTimeout(this.ptyOutputFlushTimer); this.ptyOutputFlushTimer = null; }
+        this.engine.clearAllTimers();
     }
 
-    private clearStaleIdleResponseGuard(reason: string): boolean {
-        const blockingModal = this.activeModal || this.runParseApproval(this.recentOutputBuffer);
-        const isIdle = this.runDetectStatus(this.recentOutputBuffer) === 'idle';
-        if (!this.isWaitingForResponse || this.currentStatus !== 'idle' || !isIdle || !!blockingModal) {
-            return false;
-        }
-        this.clearAllTimers();
-        this.clearIdleFinishCandidate(reason);
-        this.responseBuffer = '';
-        this.isWaitingForResponse = false;
-        this.responseSettleIgnoreUntil = 0;
-        this.submitRetryUsed = false;
-        this.submitRetryPromptSnippet = '';
-        this.finishRetryCount = 0;
-        this.currentTurnScope = null;
-        this.activeModal = null;
-        this.recordTrace('stale_idle_response_cleared', { reason });
-        return true;
-    }
-
-    private hasMeaningfulResponseBuffer(promptSnippet: string): boolean {
-        const raw = String(this.responseBuffer || '').trim();
-        if (!raw) return false;
-        const normalizedPrompt = compactPromptText(promptSnippet);
-        if (!normalizedPrompt) return true;
-        const normalizedBuffer = compactPromptText(raw);
-        if (!normalizedBuffer) return false;
-        if (normalizedBuffer === normalizedPrompt) return false;
-        if (normalizedBuffer.startsWith(normalizedPrompt)) {
-            const remainder = normalizedBuffer
-                .slice(normalizedPrompt.length)
-                .replace(/[─═\-]+/g, '')
-                .replace(/⏵⏵accepteditson\([^)]*\)/gi, '')
-                .replace(/accepteditson\([^)]*\)/gi, '')
-                .replace(/(?:◐|◑|◒|◓|◔|◕|◉|●|·)?(?:x?high|medium|low|max)·?\/effort/gi, '')
-                .replace(/updateavailable!run:[a-z0-9:._\-/]+/gi, '')
-                .replace(/esctointerrupt/gi, '')
-                .replace(/❯/g, '')
-                .replace(/^[\s\-–—:;,.!/?]+/, '')
-                .trim();
-            return remainder.length > 0;
-        }
-        return true;
-    }
-
-    private evaluateSettled(): void {
-        const now = Date.now();
-        if (this.submitPendingUntil > now || this.responseSettleIgnoreUntil > now) {
-            const delayTime = Math.max(this.submitPendingUntil - now, this.responseSettleIgnoreUntil - now) + 50;
-            if (this.settleTimer) clearTimeout(this.settleTimer);
-            this.settleTimer = setTimeout(() => {
-                this.settleTimer = null;
-                this.settledBuffer = this.recentOutputBuffer;
-                this.evaluateSettled();
-            }, delayTime);
-            return;
-        }
-
-        this.resolveStartupState('settled');
-        if (this.startupParseGate) return;
-
-        if (!this.isWaitingForResponse && !this.currentTurnScope && !this.activeModal && !this.parseErrorMessage) {
-            const tail = this.settledBuffer || this.recentOutputBuffer;
-            const modal = this.runParseApproval(tail);
-            const lightweightStatus = this.cliScripts?.detectStatus
-                ? this.runDetectStatus(tail)
-                : null;
-            if (!modal && lightweightStatus === 'idle' && this.currentStatus === 'idle') {
-                return;
-            }
-        }
-
-        const session = this.runParseSession();
-        if (!session) return;
-
-        const { status, messages, parsedStatus } = session;
-        const modal = (session as any).activeModal ?? session.modal ?? null;
-        const parsedMessages = normalizeCliParsedMessages(messages, {
-            scope: null,
-            lastOutputAt: this.lastOutputAt,
-        });
-
-        if (this.maybeCommitVisibleIdleTranscript(session, parsedMessages)) return;
-
-        const lastParsedAssistant = [...parsedMessages].reverse().find((m) => m.role === 'assistant');
-        const normalizedPromptSnippet = normalizePromptText(this.submitRetryPromptSnippet || this.currentTurnScope?.prompt || '');
-        const screenText = this.terminalScreen.getText() || '';
+ // ─── Script dispatch — builds inputs for CliScriptRunner ──────────────────
 
-        this.recordTrace('settled', {
-            tail: summarizeCliTraceText(this.settledBuffer, 500),
-            screenText: summarizeCliTraceText(screenText, 1200),
-            detectStatus: status,
-            parsedStatus: parsedStatus || null,
-            parsedMessageCount: parsedMessages.length,
-            parsedLastAssistant: lastParsedAssistant ? summarizeCliTraceText(lastParsedAssistant.content, 280) : '',
-            parsedActiveModal: modal,
-            approval: modal,
-            ...buildCliTraceParseSnapshot({
-                accumulatedBuffer: this.accumulatedBuffer,
-                accumulatedRawBuffer: this.accumulatedRawBuffer,
-                responseBuffer: this.responseBuffer,
-                partialResponse: this.responseBuffer,
-                scope: this.currentTurnScope,
-            }),
+    runParseSession(): ParsedSession | null {
+        const screenText = this.terminalScreen.getText();
+        const parseScreenText = this.getParseScreenText(screenText);
+        const tail = this.recentOutputBuffer.slice(-500);
+        const input = buildCliParseInput({
+            accumulatedBuffer: this.accumulatedBuffer,
+            accumulatedRawBuffer: this.accumulatedRawBuffer,
+            recentOutputBuffer: this.recentOutputBuffer,
+            terminalScreenText: parseScreenText,
+            workingDir: this.workingDir,
+            providerSessionId: this.providerSessionId || undefined,
+            historySessionId: this.providerSessionId || undefined,
+            baseMessages: [],
+            partialResponse: this.responseBuffer,
+            isWaitingForResponse: this.engine.isWaitingForResponse,
+            scope: this.engine.currentTurnScope,
+            runtimeSettings: this.runtimeSettings,
+            spawnAt: this.spawnAt,
         });
-
-        if (
-            this.currentTurnScope
-            && !lastParsedAssistant
-            && !this.submitRetryUsed
-            && this.ptyProcess
-            && !this.hasActionableApproval()
-            && promptLikelyVisible(screenText, normalizedPromptSnippet)
-            && !this.hasMeaningfulResponseBuffer(normalizedPromptSnippet)
-        ) {
-            this.submitRetryUsed = true;
-            this.responseSettleIgnoreUntil = Date.now() + this.timeouts.outputSettle + 400;
-            LOG.info('CLI', `[${this.cliType}] Retrying submit key from settled parser (no assistant yet)`);
-            this.recordTrace('submit_write', {
-                mode: 'settled_retry',
-                sendKey: this.sendKey,
-                screenText: summarizeCliTraceText(screenText, 500),
-            });
-            this.ptyProcess.write(this.sendKey);
-            if (this.settleTimer) clearTimeout(this.settleTimer);
-            this.settleTimer = setTimeout(() => {
-                this.settleTimer = null;
-                this.settledBuffer = this.recentOutputBuffer;
-                this.evaluateSettled();
-            }, this.timeouts.outputSettle + 150);
-            return;
-        }
-
-        if (this.currentTurnScope && !lastParsedAssistant) {
-            LOG.debug(
-                'CLI',
-                `[${this.cliType}] Settled without assistant: prompt=${JSON.stringify(this.currentTurnScope.prompt).slice(0, 140)} responseBuffer=${JSON.stringify(summarizeCliTraceText(this.responseBuffer, 220)).slice(0, 260)} screen=${JSON.stringify(summarizeCliTraceText(screenText, 220)).slice(0, 260)} providerDir=${this.providerResolutionMeta.providerDir || '-'} scriptDir=${this.providerResolutionMeta.scriptDir || '-'}`
-            );
-        }
-
-        if (!status) return;
-
-        const prevStatus = this.currentStatus;
-        const ctx: SettledEvalContext = { now, modal, status, parsedMessages, lastParsedAssistant, parsedStatus: parsedStatus || null, prevStatus };
-
-        if (!this.applyPendingScriptStatusDebounce(ctx)) return;
-
-        const recentInteractiveActivity = this.hasRecentInteractiveActivity(now);
-        LOG.debug(
-            'CLI',
-            `[${this.cliType}] settled diagnostics prompt=${JSON.stringify(this.currentTurnScope?.prompt || '').slice(0, 140)} status=${String(status || '')} parsedStatus=${String(parsedStatus || '')} parsedMsgCount=${parsedMessages.length} lastParsedAssistant=${JSON.stringify(summarizeCliTraceText(lastParsedAssistant?.content || '', 120)).slice(0, 160)} responseBuffer=${JSON.stringify(summarizeCliTraceText(this.responseBuffer, 160)).slice(0, 220)} screen=${JSON.stringify(summarizeCliTraceText(screenText, 160)).slice(0, 220)}`
-        );
-
-        const shouldHoldGenerating =
-            status === 'idle'
-            && this.isWaitingForResponse
-            && !modal
-            && recentInteractiveActivity
-            && !(parsedStatus === 'idle' && !!lastParsedAssistant);
-
-        if (shouldHoldGenerating) { this.applyHoldGenerating(ctx, recentInteractiveActivity); return; }
-        if (status === 'waiting_approval') { this.applyWaitingApproval(ctx); return; }
-        if (status === 'generating') { this.applyGenerating(ctx); return; }
-        if (status === 'idle') { this.applyIdle(ctx, now); }
-    }
-
-    // Returns false if the caller should bail out (debounce pending).
-    private applyPendingScriptStatusDebounce(ctx: SettledEvalContext): boolean {
-        const { now, status, prevStatus } = ctx;
-        const shouldDebounce =
-            prevStatus === 'idle'
-            && !this.isWaitingForResponse
-            && !this.currentTurnScope
-            && (status === 'generating' || status === 'waiting_approval');
-
-        if (!shouldDebounce) {
-            this.pendingScriptStatus = null;
-            this.pendingScriptStatusSince = 0;
-            if (this.pendingScriptStatusTimer) { clearTimeout(this.pendingScriptStatusTimer); this.pendingScriptStatusTimer = null; }
-            return true;
-        }
-
-        const armPending = (delayMs: number) => {
-            if (this.pendingScriptStatusTimer) clearTimeout(this.pendingScriptStatusTimer);
-            this.pendingScriptStatusTimer = setTimeout(() => {
-                this.pendingScriptStatusTimer = null;
-                this.settledBuffer = this.recentOutputBuffer;
-                this.evaluateSettled();
-            }, delayMs);
-        };
-
-        if (this.pendingScriptStatus !== status) {
-            this.pendingScriptStatus = status as 'generating' | 'waiting_approval';
-            this.pendingScriptStatusSince = now;
-            armPending(ProviderCliAdapter.SCRIPT_STATUS_DEBOUNCE_MS);
-            return false;
-        }
-        const elapsed = now - this.pendingScriptStatusSince;
-        if (elapsed < ProviderCliAdapter.SCRIPT_STATUS_DEBOUNCE_MS) {
-            armPending(ProviderCliAdapter.SCRIPT_STATUS_DEBOUNCE_MS - elapsed);
-            return false;
-        }
-        return true;
-    }
-
-    private applyHoldGenerating(ctx: SettledEvalContext, recentInteractiveActivity: boolean): void {
-        const { status } = ctx;
-        this.clearIdleFinishCandidate('hold_generating_recent_activity');
-        this.setStatus('generating', 'recent_activity_hold');
-        if (this.idleTimeout) clearTimeout(this.idleTimeout);
-        this.idleTimeout = setTimeout(() => {
-            if (this.isWaitingForResponse && !this.hasActionableApproval()) {
-                if (this.shouldDeferIdleTimeoutFinish()) return;
-                this.finishResponse();
-            }
-        }, this.timeouts.generatingIdle);
-        this.recordTrace('hold_generating_recent_activity', {
-            scriptStatus: status,
-            recentInteractiveActivity,
-            lastNonEmptyOutputAt: this.lastNonEmptyOutputAt,
-            lastScreenChangeAt: this.lastScreenChangeAt,
-            holdMs: this.getStatusActivityHoldMs(),
-            ...buildCliTraceParseSnapshot({
-                accumulatedBuffer: this.accumulatedBuffer,
-                accumulatedRawBuffer: this.accumulatedRawBuffer,
-                responseBuffer: this.responseBuffer,
-                partialResponse: this.responseBuffer,
-                scope: this.currentTurnScope,
-            }),
+        const session = this.runner.parseSession({
+            ...input,
+            tail,
+            tailScreen: buildCliScreenSnapshot(tail),
         });
-        this.onStatusChange?.();
-    }
-
-    private applyWaitingApproval(ctx: SettledEvalContext): void {
-        const { modal } = ctx;
-        this.clearIdleFinishCandidate('waiting_approval');
-        const inCooldown = this.lastApprovalResolvedAt && (Date.now() - this.lastApprovalResolvedAt) < this.timeouts.approvalCooldown;
-        if (inCooldown && !modal) {
-            if (this.approvalExitTimeout) { clearTimeout(this.approvalExitTimeout); this.approvalExitTimeout = null; }
-            this.activeModal = null;
-            if (this.isWaitingForResponse) {
-                this.setStatus('idle', inCooldown ? 'approval_cooldown_non_actionable' : 'approval_prompt_gone_non_actionable');
-                if (this.idleTimeout) clearTimeout(this.idleTimeout);
-                this.idleTimeout = setTimeout(() => {
-                    if (this.isWaitingForResponse && !this.hasActionableApproval()) {
-                        if (this.shouldDeferIdleTimeoutFinish()) return;
-                        this.finishResponse();
-                    }
-                }, this.timeouts.generatingIdle);
-            } else {
-                this.setStatus('idle', inCooldown ? 'approval_cooldown_non_actionable' : 'approval_prompt_gone_non_actionable');
-            }
-            this.onStatusChange?.();
-            return;
-        }
-        if (!inCooldown) {
-            if (!modal) {
-                LOG.warn('CLI', `[${this.cliType}] detectStatus reported waiting_approval without parseApproval modal; ignoring non-actionable approval state`);
-                return;
-            }
-            this.isWaitingForResponse = true;
-            this.setStatus('waiting_approval', 'script_detect');
-            this.activeModal = modal;
-            if (this.idleTimeout) clearTimeout(this.idleTimeout);
-            this.armApprovalExitTimeout();
-            this.onStatusChange?.();
-        }
-    }
-
-    private applyGenerating(ctx: SettledEvalContext): void {
-        const { modal, parsedMessages, lastParsedAssistant, parsedStatus, prevStatus } = ctx;
-        this.clearIdleFinishCandidate('generating');
-        const screenText = this.terminalScreen.getText() || '';
-        const effectiveScreenText = screenText || this.accumulatedBuffer;
-        const noActiveTurn = !this.currentTurnScope;
-        const looksIdleChrome = /(^|\n)\s*[❯›>]\s*(?:\n|$)/m.test(effectiveScreenText);
-        const parsedShowsLiveAssistantProgress = parsedStatus === 'generating'
-            && !!lastParsedAssistant
-;
-        if (prevStatus === 'idle' && !this.isWaitingForResponse && noActiveTurn && !modal && looksIdleChrome && !parsedShowsLiveAssistantProgress) {
-            return;
-        }
-        if (prevStatus === 'waiting_approval') {
-            // Transitioned out of approval → generating
-            if (this.approvalExitTimeout) { clearTimeout(this.approvalExitTimeout); this.approvalExitTimeout = null; }
-            this.activeModal = null;
-            this.lastApprovalResolvedAt = Date.now();
-        }
-        if (!this.isWaitingForResponse) {
-            this.isWaitingForResponse = true;
-            this.responseBuffer = '';
-        }
-        this.setStatus('generating', 'script_detect');
-        // Reset idle timeout
-        if (this.idleTimeout) clearTimeout(this.idleTimeout);
-        this.idleTimeout = setTimeout(() => {
-            if (this.isWaitingForResponse) {
-                if (this.shouldDeferIdleTimeoutFinish()) return;
-                this.finishResponse();
-            }
-        }, this.timeouts.generatingIdle);
-        this.onStatusChange?.();
+        if (session && typeof session === 'object') this.applyParsedSessionMetadata(session);
+        return session;
     }
 
-    private applyIdle(ctx: SettledEvalContext, now: number): void {
-        const { modal, lastParsedAssistant, prevStatus } = ctx;
-        if (prevStatus === 'waiting_approval') {
-            if (this.approvalExitTimeout) { clearTimeout(this.approvalExitTimeout); this.approvalExitTimeout = null; }
-            this.activeModal = null;
-            this.lastApprovalResolvedAt = Date.now();
-            this.setStatus('idle', 'approval_prompt_gone_script_idle');
-        }
-        if (!this.isWaitingForResponse) {
-            if (prevStatus !== 'idle') {
-                this.clearIdleFinishCandidate('idle_without_response');
-                this.setStatus('idle', 'script_detect');
-                this.onStatusChange?.();
-            }
-            return;
-        }
-        const quietForMs = this.lastNonEmptyOutputAt ? (now - this.lastNonEmptyOutputAt) : Number.MAX_SAFE_INTEGER;
-        const screenStableMs = this.lastScreenChangeAt ? (now - this.lastScreenChangeAt) : 0;
-        const hasAssistantTurn = !!lastParsedAssistant;
-        const assistantLength = lastParsedAssistant?.content?.length || 0;
-        const idleFinishConfirmMs = this.getIdleFinishConfirmMs();
-        const idleQuietThresholdMs = Math.max(idleFinishConfirmMs, this.timeouts.outputSettle);
-        const idleReady = !modal
-            && hasAssistantTurn
-            && quietForMs >= idleQuietThresholdMs
-            && screenStableMs >= idleFinishConfirmMs;
-        const candidate = this.idleFinishCandidate;
-        const candidateQuiet = !!candidate
-            && candidate.responseEpoch === this.responseEpoch
-            && candidate.lastOutputAt === this.lastOutputAt
-            && candidate.lastScreenChangeAt === this.lastScreenChangeAt
-            && assistantLength >= candidate.assistantLength
-            && (now - candidate.armedAt) >= idleFinishConfirmMs;
-
-        this.recordTrace('idle_decision', {
-            quietForMs,
-            screenStableMs,
-            hasAssistantTurn,
-            assistantLength,
-            hasModal: !!modal,
-            idleQuietThresholdMs,
-            idleStableThresholdMs: idleFinishConfirmMs,
-            idleReady,
-            idleFinishConfirmMs,
-            idleFinishCandidate: candidate,
-            candidateQuiet,
-            canFinishImmediately: idleReady && candidateQuiet,
-            submitPendingUntil: this.submitPendingUntil,
-            responseSettleIgnoreUntil: this.responseSettleIgnoreUntil,
-            ...buildCliTraceParseSnapshot({
-                accumulatedBuffer: this.accumulatedBuffer,
-                accumulatedRawBuffer: this.accumulatedRawBuffer,
-                responseBuffer: this.responseBuffer,
-                partialResponse: this.responseBuffer,
-                scope: this.currentTurnScope,
-            }),
-        });
-
-        if (idleReady && candidateQuiet) {
-            this.clearIdleFinishCandidate('finish_response');
-            if (this.idleTimeout) clearTimeout(this.idleTimeout);
-            this.finishResponse();
-            return;
-        }
-
-        if (idleReady) {
-            if (!candidate) {
-                this.armIdleFinishCandidate(assistantLength);
-                return;
-            }
-        } else {
-            this.clearIdleFinishCandidate('idle_not_ready');
-        }
-
-        if (this.idleTimeout) clearTimeout(this.idleTimeout);
-        this.idleTimeout = setTimeout(() => {
-            if (this.isWaitingForResponse && !this.hasActionableApproval()) {
-                if (this.shouldDeferIdleTimeoutFinish()) return;
-                this.clearIdleFinishCandidate('idle_timeout_finish');
-                this.finishResponse();
-            }
-        }, this.timeouts.idleFinish);
-    }
-
-    private finishResponse(): void {
-        if (this.submitPendingUntil > Date.now()) return;
-        if (this.responseSettleIgnoreUntil > Date.now()) return;
-        this.clearIdleFinishCandidate('finish_response_enter');
-        this.recordTrace('finish_response', {
-            ...buildCliTraceParseSnapshot({
-                accumulatedBuffer: this.accumulatedBuffer,
-                accumulatedRawBuffer: this.accumulatedRawBuffer,
-                responseBuffer: this.responseBuffer,
-                partialResponse: this.responseBuffer,
-                scope: this.currentTurnScope,
-            }),
+    runDetectStatus(text: string): string | null {
+        const screenText = this.terminalScreen.getText();
+        const tail = text.slice(-500);
+        return this.runner.detectStatus({
+            tail,
+            screenText,
+            rawBuffer: this.accumulatedRawBuffer,
+            isWaitingForResponse: this.engine.isWaitingForResponse,
+            screen: buildCliScreenSnapshot(screenText),
+            tailScreen: buildCliScreenSnapshot(tail),
         });
-        const commitResult = this.commitCurrentTranscript();
-        if (this.shouldRetryFinishResponse(commitResult)) {
-            this.finishRetryCount += 1;
-            this.recordTrace('finish_response_retry', {
-                retryCount: this.finishRetryCount,
-                retryDelayMs: ProviderCliAdapter.FINISH_RETRY_DELAY_MS,
-                assistantContent: summarizeCliTraceText(commitResult.assistantContent, 220),
-                ...buildCliTraceParseSnapshot({
-                    accumulatedBuffer: this.accumulatedBuffer,
-                    accumulatedRawBuffer: this.accumulatedRawBuffer,
-                    responseBuffer: this.responseBuffer,
-                    partialResponse: this.responseBuffer,
-                    scope: this.currentTurnScope,
-                }),
-            });
-            if (this.finishRetryTimer) clearTimeout(this.finishRetryTimer);
-            this.finishRetryTimer = setTimeout(() => {
-                this.finishRetryTimer = null;
-                if (this.isWaitingForResponse && !this.hasActionableApproval()) {
-                    this.finishResponse();
-                }
-            }, ProviderCliAdapter.FINISH_RETRY_DELAY_MS);
-            return;
-        }
-        this.clearAllTimers();
-        this.responseBuffer = '';
-        this.isWaitingForResponse = false;
-        this.responseSettleIgnoreUntil = 0;
-        this.submitRetryUsed = false;
-        this.submitRetryPromptSnippet = '';
-        this.finishRetryCount = 0;
-        this.currentTurnScope = null;
-        this.activeModal = null;
-        this.setStatus('idle', 'response_finished');
-        this.onStatusChange?.();
     }
 
-    private maybeCommitVisibleIdleTranscript(session: ParsedSession, parsedMessages: CliChatMessage[]): boolean {
-        const allowImmediateScriptIdleCommit = this.provider.allowInputDuringGeneration === true;
-        if (!allowImmediateScriptIdleCommit) return false;
-        if (
-            !session
-            || session.status !== 'idle'
-            || !this.isWaitingForResponse
-            || !this.currentTurnScope
-            || this.activeModal
-            || session.modal
-        ) {
-            return false;
-        }
-
-        const visibleAssistant = [...parsedMessages].reverse().find((m) => m.role === 'assistant' && m.content.trim());
-        if (!visibleAssistant) return false;
-
-        this.clearAllTimers();
-        this.responseBuffer = '';
-        this.isWaitingForResponse = false;
-        this.responseSettleIgnoreUntil = 0;
-        this.submitRetryUsed = false;
-        this.submitRetryPromptSnippet = '';
-        this.finishRetryCount = 0;
-        this.currentTurnScope = null;
-        this.activeModal = null;
-        this.setStatus('idle', 'script_idle_commit');
-        this.onStatusChange?.();
-        this.recordTrace('script_idle_commit', {
-            messageCount: parsedMessages.length,
-            lastAssistant: summarizeCliTraceText(visibleAssistant.content, 320),
+    runParseApproval(tail: string): { message: string; buttons: string[] } | null {
+        const screenText = this.terminalScreen.getText();
+        const buffer = screenText || this.accumulatedBuffer;
+        return this.runner.parseApproval({
+            buffer,
+            screenText,
+            rawBuffer: this.accumulatedRawBuffer,
+            tail,
+            screen: buildCliScreenSnapshot(screenText),
+            bufferScreen: buildCliScreenSnapshot(buffer),
+            tailScreen: buildCliScreenSnapshot(tail),
         });
-        return true;
-    }
-
-    private commitCurrentTranscript(): { hasAssistant: boolean; assistantContent: string } {
-        const parsed = this.parseCurrentTranscript(
-            [],
-            this.responseBuffer,
-            this.currentTurnScope,
-        );
-        if (parsed && Array.isArray(parsed.messages)) {
-            const parsedMessages = normalizeCliParsedMessages(parsed.messages, {
-                    scope: null,
-                lastOutputAt: this.lastOutputAt,
-            });
-            const lastAssistant = [...parsedMessages].reverse().find((message) => message.role === 'assistant');
-            if (this.currentTurnScope) {
-                LOG.info(
-                    'CLI',
-                    `[${this.cliType}] commitCurrentTranscript parserMessages=${parsedMessages.length} finalLastAssistant=${JSON.stringify(summarizeCliTraceText(lastAssistant?.content || '', 220)).slice(0, 260)}`
-                );
-            }
-            this.recordTrace('commit_transcript', {
-                parsedStatus: parsed.status || null,
-                messageCount: parsedMessages.length,
-                lastAssistant: lastAssistant ? summarizeCliTraceText(lastAssistant.content, 320) : '',
-                messages: summarizeCliTraceMessages(parsedMessages),
-                ...buildCliTraceParseSnapshot({
-                    accumulatedBuffer: this.accumulatedBuffer,
-                    accumulatedRawBuffer: this.accumulatedRawBuffer,
-                    responseBuffer: this.responseBuffer,
-                    partialResponse: this.responseBuffer,
-                    scope: this.currentTurnScope,
-                }),
-            });
-            if (!lastAssistant && this.currentTurnScope) {
-                LOG.warn(
-                    'CLI',
-                    `[${this.cliType}] Commit without assistant turn: prompt=${JSON.stringify(this.currentTurnScope.prompt).slice(0, 140)} responseBuffer=${JSON.stringify(summarizeCliTraceText(this.responseBuffer, 220)).slice(0, 260)} providerDir=${this.providerResolutionMeta.providerDir || '-'} scriptDir=${this.providerResolutionMeta.scriptDir || '-'} scriptsPath=${this.providerResolutionMeta.scriptsPath || '-'}`
-                );
-            }
-            const hasAssistant = !!lastAssistant;
-            return {
-                hasAssistant,
-                assistantContent: lastAssistant?.content || '',
-            };
-        }
-        if (this.currentTurnScope) {
-            LOG.info(
-                'CLI',
-                `[${this.cliType}] commitCurrentTranscript parsed.messages=none responseBufferLen=${this.responseBuffer.length} accumulatedBufferLen=${this.accumulatedBuffer.length} parsedStatus=${parsed?.status || '-'} providerDir=${this.providerResolutionMeta.providerDir || '-'} scriptDir=${this.providerResolutionMeta.scriptDir || '-'}`
-            );
-        }
-        return {
-            hasAssistant: false,
-            assistantContent: '',
-        };
-    }
-
-
- // ─── Script Execution ──────────────────────────
-
-    private invokeCliScript<T>(script: Function, input: any): T {
-        const hasStateFactory = typeof this.cliScripts?.createState === 'function';
-        const expectsStateArgument = hasStateFactory || this.scriptState !== null || script.length >= 2;
-        return expectsStateArgument
-            ? script(this.scriptState, input)
-            : script(input);
-    }
-
-    private runParseSession(): ParsedSession | null {
-        if (typeof this.cliScripts?.parseSession !== 'function') {
-            this.parseErrorMessage = `${this.cliType} parseSession unavailable`;
-            return null;
-        }
-        try {
-            const screenText = this.terminalScreen.getText();
-            const parseScreenText = this.getParseScreenText(screenText);
-            const tail = this.recentOutputBuffer.slice(-500);
-            const input = buildCliParseInput({
-                accumulatedBuffer: this.accumulatedBuffer,
-                accumulatedRawBuffer: this.accumulatedRawBuffer,
-                recentOutputBuffer: this.recentOutputBuffer,
-                terminalScreenText: parseScreenText,
-                baseMessages: [],
-                partialResponse: this.responseBuffer,
-                isWaitingForResponse: this.isWaitingForResponse,
-                scope: this.currentTurnScope,
-                runtimeSettings: this.runtimeSettings,
-            });
-            const session = this.invokeCliScript<ParsedSession | null>(
-                this.cliScripts.parseSession,
-                { ...input, tail, tailScreen: buildCliScreenSnapshot(tail) },
-            );
-            this.parseErrorMessage = null;
-            return session && typeof session === 'object' ? session : null;
-        } catch (e: any) {
-            const message = e?.message || String(e);
-            this.parseErrorMessage = message;
-            LOG.warn('CLI', `[${this.cliType}] parseSession error: ${message}`);
-            return null;
-        }
-    }
-
-    private runDetectStatus(text: string): string | null {
-        if (!this.cliScripts?.detectStatus) return null;
-        try {
-            const screenText = this.terminalScreen.getText();
-            const status = this.invokeCliScript<string | null>(this.cliScripts.detectStatus, {
-                tail: text.slice(-500),
-                screenText,
-                rawBuffer: this.accumulatedRawBuffer,
-                isWaitingForResponse: this.isWaitingForResponse,
-                screen: buildCliScreenSnapshot(screenText),
-                tailScreen: buildCliScreenSnapshot(text.slice(-500)),
-            });
-            return status;
-        } catch (e: any) {
-            LOG.warn('CLI', `[${this.cliType}] detectStatus error: ${e.message}`);
-            return null;
-        }
     }
 
-    private runParseApproval(tail: string): { message: string; buttons: string[] } | null {
-        if (!this.cliScripts?.parseApproval) return null;
-        try {
-            const screenText = this.terminalScreen.getText();
-            const buffer = screenText || this.accumulatedBuffer;
-            return this.invokeCliScript<{ message: string; buttons: string[] } | null>(this.cliScripts.parseApproval, {
-                buffer,
-                screenText,
-                rawBuffer: this.accumulatedRawBuffer,
-                tail,
-                screen: buildCliScreenSnapshot(screenText),
-                bufferScreen: buildCliScreenSnapshot(buffer),
-                tailScreen: buildCliScreenSnapshot(tail),
-            });
-        } catch (e: any) {
-            LOG.warn('CLI', `[${this.cliType}] parseApproval error: ${e.message}`);
-            return null;
+    private applyParsedSessionMetadata(parsed: any): void {
+        const providerSessionId = typeof parsed?.providerSessionId === 'string' && parsed.providerSessionId.trim()
+            ? parsed.providerSessionId.trim()
+            : '';
+        if (providerSessionId && providerSessionId !== this.providerSessionId) {
+            this.providerSessionId = providerSessionId;
+            this.updateRuntimeMeta({ providerSessionId });
         }
     }
 
-    private hasActionableApproval(startupModal: { message: string; buttons: string[] } | null = null): boolean {
-        return !!(startupModal || this.activeModal);
-    }
-
     private projectEffectiveStatus(startupModal: { message: string; buttons: string[] } | null = null): CliSessionStatus['status'] {
         if (this.parseErrorMessage) return 'error';
-        if (this.hasActionableApproval(startupModal)) return 'waiting_approval';
-        if (this.isWaitingForResponse && this.currentTurnScope && this.currentStatus !== 'stopped') return 'generating';
-        return this.currentStatus;
+        if (!!(startupModal || this.engine.activeModal)) return 'waiting_approval';
+        if (this.engine.isWaitingForResponse && this.engine.currentTurnScope && this.engine.currentStatus !== 'stopped') return 'generating';
+        return this.engine.currentStatus;
     }
 
  // ─── Public API (CliAdapter) ───────────────────
@@ -1564,17 +864,73 @@ export class ProviderCliAdapter implements CliAdapter {
     getStatus(options: { allowParse?: boolean } = {}): CliSessionStatus {
         const allowParse = options.allowParse !== false;
         const startupModal = allowParse && this.startupParseGate ? this.runParseApproval(this.recentOutputBuffer) : null;
+        const startupDetectedStatus = allowParse && this.startupParseGate && !startupModal
+            ? this.runDetectStatus(this.recentOutputBuffer || this.terminalScreen.getText())
+            : null;
         let effectiveStatus = this.projectEffectiveStatus(startupModal);
-        let effectiveModal = startupModal || this.activeModal;
+        let effectiveModal = startupModal || this.engine.activeModal;
+        // (fix) When we have no captured modal yet, take one more live attempt
+        // with the current screen text — the engine's settle pass can miss
+        // the modal when it happens to fire exactly between writes, and
+        // without a modal here the dashboard could never show the buttons.
+        // We deliberately do NOT overwrite an existing engine.activeModal so
+        // a stable matched modal wins. This runs even outside the startup
+        // gate because Claude's approval frames can appear long after launch.
+        if (allowParse && !effectiveModal && this.engine.isWaitingForResponse) {
+            const liveDetect = this.runDetectStatus(this.recentOutputBuffer || this.terminalScreen.getText());
+            if (liveDetect === 'waiting_approval') {
+                const liveModal = this.runParseApproval(this.terminalScreen.getText())
+                    || this.runParseApproval(this.recentOutputBuffer);
+                // (fix) Only surface modals that have at least one non-empty
+                // button. Half-rendered approval frames produced
+                // { message, buttons: [] } briefly — auto-approve would then
+                // pick buttonIndex=-1 and resolveModal would write the
+                // provider's index-0 key into the prompt. Skip those frames
+                // and let a later evaluate find the complete modal.
+                const buttonsOk = liveModal && Array.isArray(liveModal.buttons)
+                    && liveModal.buttons.some((b: any) => typeof b === 'string' && b.trim());
+                if (liveModal && buttonsOk) {
+                    effectiveModal = liveModal;
+                    if (!this.engine.activeModal) this.engine.activeModal = liveModal;
+                }
+            }
+        }
+        // Only surface waiting_approval when we ALSO have a concrete modal
+        // (message + buttons). detectStatus alone can fire while parseApproval
+        // is still null — the engine logs "detectStatus=waiting_approval but
+        // parseApproval returned null; ignoring". Without this guard getStatus
+        // was shipping a bare waiting_approval with activeModal=null and the
+        // user perceived the flow as broken.
+        if (startupDetectedStatus === 'waiting_approval' && effectiveModal) {
+            effectiveStatus = 'waiting_approval';
+        } else if (startupDetectedStatus === 'idle' && !startupModal && !effectiveModal) {
+            effectiveStatus = 'idle';
+        }
         if (allowParse && !startupModal && !effectiveModal) {
             const parsed = this.getFreshParsedStatusCache();
             const parsedModal = parsed?.activeModal && Array.isArray(parsed.activeModal.buttons)
                 && parsed.activeModal.buttons.some((button: any) => typeof button === 'string' && button.trim())
                 ? parsed.activeModal
                 : null;
+            const hasFinalAssistant = (p: any) => {
+                const msgs = Array.isArray(p?.messages) ? p.messages : [];
+                return msgs.some((m: any) => m?.role === 'assistant' && typeof m.content === 'string' && m.content.trim());
+            };
             if (parsed?.status === 'waiting_approval' && parsedModal) {
                 effectiveStatus = 'waiting_approval';
                 effectiveModal = parsedModal;
+            } else if (
+                effectiveStatus === 'idle'
+                && parsed?.status === 'generating'
+                && !hasFinalAssistant(parsed)
+            ) {
+                effectiveStatus = 'generating';
+            } else if (
+                effectiveStatus === 'generating'
+                && parsed?.status === 'idle'
+                && hasFinalAssistant(parsed)
+            ) {
+                effectiveStatus = 'idle';
             }
         }
         const bufferState = this.getBufferState();
@@ -1583,8 +939,17 @@ export class ProviderCliAdapter implements CliAdapter {
             messages: [],
             workingDir: this.workingDir,
             activeModal: effectiveModal,
-            errorMessage: this.parseErrorMessage || undefined,
-            errorReason: this.parseErrorMessage ? 'parse_error' : undefined,
+            pendingOutboundCount: this.pendingOutboundQueue.length,
+            pendingOutboundMessages: this.pendingOutboundQueue.map((message) => ({
+                id: message.id,
+                role: message.role,
+                content: message.content,
+                queuedAt: message.queuedAt,
+                source: message.source,
+            })),
+            errorMessage: this.parseErrorMessage || this.engine.providerErrorMessage || undefined,
+            errorReason: this.parseErrorMessage ? 'parse_error' : (this.engine.providerErrorReason || undefined),
+            providerSessionId: this.providerSessionId || undefined,
             ...(bufferState ? { bufferState } : {}),
         };
     }
@@ -1600,15 +965,16 @@ export class ProviderCliAdapter implements CliAdapter {
         const cached = this.parsedStatusCache;
         const accumulatedRawBufferKey = this.getAccumulatedRawBufferCacheKey();
         if (
-            cached
+            !this.providerOwnsTranscript()
+            && cached
             && cached.responseBuffer === this.responseBuffer
-            && cached.currentTurnScope === this.currentTurnScope
+            && cached.currentTurnScope === this.engine.currentTurnScope
             && cached.recentOutputBuffer === this.recentOutputBuffer
             && cached.accumulatedBuffer === this.accumulatedBuffer
             && cached.accumulatedRawBufferKey === accumulatedRawBufferKey
             && cached.screenText === parseScreenText
-            && cached.currentStatus === this.currentStatus
-            && cached.activeModal === this.activeModal
+            && cached.currentStatus === this.engine.currentStatus
+            && cached.activeModal === this.engine.activeModal
             && cached.cliName === this.cliName
         ) {
             return cached.result;
@@ -1623,14 +989,20 @@ export class ProviderCliAdapter implements CliAdapter {
         const bufferState = this.getBufferState();
         const result = {
             id: (parsed as any).id || 'cli_session',
-            status: parsed.status || this.currentStatus,
+            status: parsed.status || this.engine.currentStatus,
             title: (parsed as any).title || this.cliName,
             messages: normalizeCliParsedMessages(parsed.messages, {
                     scope: null,
                 lastOutputAt: this.lastOutputAt,
             }),
             activeModal,
-            providerSessionId: typeof (parsed as any).providerSessionId === 'string' ? (parsed as any).providerSessionId : undefined,
+            providerSessionId: this.providerSessionId || (typeof (parsed as any).providerSessionId === 'string' ? (parsed as any).providerSessionId : undefined),
+            errorMessage: typeof (parsed as any).errorMessage === 'string' && (parsed as any).errorMessage.trim()
+                ? (parsed as any).errorMessage.trim()
+                : undefined,
+            errorReason: typeof (parsed as any).errorReason === 'string' && (parsed as any).errorReason.trim()
+                ? (parsed as any).errorReason.trim()
+                : undefined,
             ...(bufferState ? { bufferState } : {}),
             ...((parsed as any).transcriptAuthority === 'provider' || (parsed as any).transcriptAuthority === 'daemon'
                 ? { transcriptAuthority: (parsed as any).transcriptAuthority }
@@ -1642,13 +1014,13 @@ export class ProviderCliAdapter implements CliAdapter {
 
         this.parsedStatusCache = {
             responseBuffer: this.responseBuffer,
-            currentTurnScope: this.currentTurnScope,
+            currentTurnScope: this.engine.currentTurnScope,
             recentOutputBuffer: this.recentOutputBuffer,
             accumulatedBuffer: this.accumulatedBuffer,
             accumulatedRawBufferKey,
             screenText: parseScreenText,
-            currentStatus: this.currentStatus,
-            activeModal: this.activeModal,
+            currentStatus: this.engine.currentStatus,
+            activeModal: this.engine.activeModal,
             cliName: this.cliName,
             result,
         };
@@ -1656,22 +1028,22 @@ export class ProviderCliAdapter implements CliAdapter {
     }
 
     async invokeScript(scriptName: string, args?: Record<string, any>): Promise<any> {
-        const fn = this.cliScripts?.[scriptName];
-        if (typeof fn !== 'function') {
-            throw new Error(`CLI script '${scriptName}' not available`);
-        }
         const input = buildCliParseInput({
             accumulatedBuffer: this.accumulatedBuffer,
             accumulatedRawBuffer: this.accumulatedRawBuffer,
             recentOutputBuffer: this.recentOutputBuffer,
             terminalScreenText: this.getParseScreenText(this.terminalScreen.getText()),
+            workingDir: this.workingDir,
+            providerSessionId: this.providerSessionId || undefined,
+            historySessionId: this.providerSessionId || undefined,
             baseMessages: [],
             partialResponse: this.responseBuffer,
-            isWaitingForResponse: this.isWaitingForResponse,
-            scope: this.currentTurnScope,
+            isWaitingForResponse: this.engine.isWaitingForResponse,
+            scope: this.engine.currentTurnScope,
             runtimeSettings: this.runtimeSettings,
+            spawnAt: this.spawnAt,
         });
-        return await Promise.resolve(this.invokeCliScript(fn, {
+        return await Promise.resolve(this.runner.invokeByName(scriptName, {
             ...input,
             args: args && typeof args === 'object' ? { ...args } : {},
         }));
@@ -1683,7 +1055,7 @@ export class ProviderCliAdapter implements CliAdapter {
 
     /** Whether this adapter has CLI scripts loaded */
     hasCliScripts(): boolean {
-        return typeof this.cliScripts?.detectStatus === 'function';
+        return this.runner.hasDetectStatus();
     }
 
     /**
@@ -1692,24 +1064,29 @@ export class ProviderCliAdapter implements CliAdapter {
      */
     async resolveAction(data: any): Promise<void> {
         let promptText = '';
-        if (this.cliScripts && typeof this.cliScripts.resolveAction === 'function') {
-            try {
-                promptText = this.cliScripts.resolveAction(data);
-            } catch (e: any) {
-                LOG.warn('CLI', `[${this.cliType}] resolveAction error: ${e.message}`);
-            }
+        try {
+            promptText = this.runner.invokeByName('resolveAction', data);
+        } catch {
+            LOG.warn('CLI', `[${this.cliType}] resolveAction skipped: provider script not available`);
+            return;
         }
         if (!promptText) {
-            LOG.warn('CLI', `[${this.cliType}] resolveAction skipped: provider script did not supply a prompt`);
+            LOG.warn('CLI', `[${this.cliType}] resolveAction skipped: provider script did not return a prompt`);
             return;
         }
         await this.sendMessage(promptText);
     }
 
+    async setInteractivePromptResponse(_response: InteractivePromptResponse): Promise<void> {
+        // Legacy TUI providers do not currently expose an interactive prompt
+        // protocol. Spec-backed claude-cli implements the first real wiring.
+    }
+
     private isSubmitStuck(normalizedPromptSnippet: string): boolean {
-        if (!this.ptyProcess || !this.isWaitingForResponse || this.submitRetryUsed) return false;
-        if (this.hasActionableApproval()) return false;
-        if (this.hasMeaningfulResponseBuffer(normalizedPromptSnippet)) return false;
+        if (!this.ptyProcess || !this.engine.isWaitingForResponse || this.engine.submitRetryUsed) return false;
+        if (this.engine.hasActionableApproval()) return false;
+        // If there's already meaningful response content beyond the echoed prompt, not stuck
+        if (this.hasMeaningfulResponseBufferLocal(normalizedPromptSnippet)) return false;
         const screenText = this.terminalScreen.getText();
         if (!promptLikelyVisible(screenText, normalizedPromptSnippet)) return false;
         const liveApproval = this.runParseApproval(screenText) || this.runParseApproval(this.recentOutputBuffer);
@@ -1718,20 +1095,41 @@ export class ProviderCliAdapter implements CliAdapter {
         return liveStatus !== 'generating' && liveStatus !== 'waiting_approval';
     }
 
+    private hasMeaningfulResponseBufferLocal(promptSnippet: string): boolean {
+        const raw = String(this.responseBuffer || '').trim();
+        if (!raw) return false;
+        const normalizedPrompt = compactPromptText(promptSnippet);
+        if (!normalizedPrompt) return true;
+        const normalizedBuffer = compactPromptText(raw);
+        if (!normalizedBuffer) return false;
+        if (normalizedBuffer === normalizedPrompt) return false;
+        if (normalizedBuffer.startsWith(normalizedPrompt)) {
+            const remainder = normalizedBuffer
+                .slice(normalizedPrompt.length)
+                .replace(/[─═\-]+/g, '')
+                .replace(/⏵⏵accepteditson\([^)]*\)/gi, '')
+                .replace(/accepteditson\([^)]*\)/gi, '')
+                .replace(/(?:◐|◑|◒|◓|◔|◕|◉|●|·)?(?:x?high|medium|low|max)·?\/effort/gi, '')
+                .replace(/updateavailable!run:[a-z0-9:._\-/]+/gi, '')
+                .replace(/esctointerrupt/gi, '')
+                .replace(/❯/g, '')
+                .replace(/^[\s\-–—:;,.!/?]+/, '')
+                .trim();
+            return remainder.length > 0;
+        }
+        return true;
+    }
+
     private async writeToPty(data: string): Promise<void> {
         if (!this.ptyProcess) throw new Error(`${this.cliName} is not running`);
         await this.ptyProcess.write(data);
     }
 
     private resetPendingSendState(reason: string): void {
-        this.isWaitingForResponse = false;
         this.responseBuffer = '';
-        this.currentTurnScope = null;
-        this.submitPendingUntil = 0;
-        this.clearIdleFinishCandidate(reason);
         if (this.responseTimeout) { clearTimeout(this.responseTimeout); this.responseTimeout = null; }
-        if (this.submitRetryTimer) { clearTimeout(this.submitRetryTimer); this.submitRetryTimer = null; }
-        if (this.finishRetryTimer) { clearTimeout(this.finishRetryTimer); this.finishRetryTimer = null; }
+        this.engine.resetActiveTurnState();
+        this.engine.clearIdleFinishCandidate(reason);
     }
 
     private commitSendUserTurn(state: SendMessageState): void {
@@ -1748,42 +1146,14 @@ export class ProviderCliAdapter implements CliAdapter {
         }
         this.responseTimeout = setTimeout(() => {
             this.responseTimeout = null;
-            if (!this.isWaitingForResponse) return;
-
-            const detectedStatusBeforeEval = this.runDetectStatus(this.recentOutputBuffer);
-            this.recordTrace('response_timeout_check', {
-                timeoutMs,
-                detectedStatus: detectedStatusBeforeEval,
-                currentStatus: this.currentStatus,
-                isWaitingForResponse: this.isWaitingForResponse,
-                hasActionableApproval: this.hasActionableApproval(),
-                ...buildCliTraceParseSnapshot({
-                    accumulatedBuffer: this.accumulatedBuffer,
-                    accumulatedRawBuffer: this.accumulatedRawBuffer,
-                    responseBuffer: this.responseBuffer,
-                    partialResponse: this.responseBuffer,
-                    scope: this.currentTurnScope,
-                }),
-            });
+            if (!this.engine.isWaitingForResponse) return;
 
-            // maxResponse is a watchdog/checkpoint, not a completion signal. The old
-            // behavior called finishResponse() unconditionally at the default 300s,
-            // which fabricated idle transitions and downstream generating_completed
-            // notifications while long-running CLIs were still generating. Re-run the
+            // maxResponse is a watchdog/checkpoint, not a completion signal. Re-run the
             // normal settled parser instead and keep the turn open unless the provider
             // actually reports an idle, commit-ready state.
-            this.settledBuffer = this.recentOutputBuffer;
-            this.evaluateSettled();
-
-            if (this.isWaitingForResponse && !this.hasActionableApproval()) {
-                const detectedStatusAfterEval = this.runDetectStatus(this.recentOutputBuffer);
-                this.recordTrace('response_timeout_kept_open', {
-                    timeoutMs,
-                    detectedStatusBeforeEval,
-                    detectedStatusAfterEval,
-                    currentStatus: this.currentStatus,
-                    isWaitingForResponse: this.isWaitingForResponse,
-                });
+            this.engine.evaluateSettled(this.getSnapshot());
+
+            if (this.engine.isWaitingForResponse && !this.engine.hasActionableApproval()) {
                 this.armResponseTimeout();
             }
         }, timeoutMs);
@@ -1798,34 +1168,20 @@ export class ProviderCliAdapter implements CliAdapter {
     private retrySubmitIfStuck(state: SendMessageState, attempt: number): void {
         this.submitRetryTimer = null;
         if (!this.isSubmitStuck(state.normalizedPromptSnippet)) return;
-        const screenText = this.terminalScreen.getText();
-        this.responseSettleIgnoreUntil = Date.now() + this.timeouts.outputSettle + 400;
+        this.engine.responseSettleIgnoreUntil = Date.now() + this.timeouts.outputSettle + 400;
         LOG.info('CLI', `[${this.cliType}] Retrying submit key for stuck prompt (attempt ${attempt})`);
-        this.recordTrace('submit_write', {
-            mode: 'submit_retry',
-            attempt,
-            sendKey: this.sendKey,
-            screenText: summarizeCliTraceText(screenText, 500),
-        });
         this.writeSubmitKeyForRetry('submit_retry');
-        if (attempt >= 3) { this.submitRetryUsed = true; return; }
+        if (attempt >= 3) { this.engine.submitRetryUsed = true; return; }
         this.submitRetryTimer = setTimeout(() => this.retrySubmitIfStuck(state, attempt + 1), state.retryDelayMs);
     }
 
     private retryImmediateSubmitIfStuck(state: SendMessageState): void {
         this.submitRetryTimer = null;
         if (!this.isSubmitStuck(state.normalizedPromptSnippet)) return;
-        const screenText = this.terminalScreen.getText();
-        this.responseSettleIgnoreUntil = Date.now() + this.timeouts.outputSettle + 400;
+        this.engine.responseSettleIgnoreUntil = Date.now() + this.timeouts.outputSettle + 400;
         LOG.info('CLI', `[${this.cliType}] Retrying submit key for stuck prompt (attempt 1)`);
-        this.recordTrace('submit_write', {
-            mode: 'immediate_retry',
-            attempt: 1,
-            sendKey: this.sendKey,
-            screenText: summarizeCliTraceText(screenText, 500),
-        });
         this.writeSubmitKeyForRetry('immediate_retry');
-        this.submitRetryUsed = true;
+        this.engine.submitRetryUsed = true;
     }
 
     private submitSendKey(state: SendMessageState, completion: SendMessageCompletion): void {
@@ -1833,13 +1189,7 @@ export class ProviderCliAdapter implements CliAdapter {
             completion.resolveOnce();
             return;
         }
-        this.submitPendingUntil = 0;
-        const screenText = this.terminalScreen.getText();
-        this.recordTrace('submit_write', {
-            mode: 'submit_key',
-            sendKey: this.sendKey,
-            screenText: summarizeCliTraceText(screenText, 500),
-        });
+        this.engine.submitPendingUntil = 0;
         void this.writeToPty(this.sendKey).then(() => {
             this.commitSendUserTurn(state);
             this.submitRetryTimer = setTimeout(() => this.retrySubmitIfStuck(state, 1), state.retryDelayMs);
@@ -1849,13 +1199,7 @@ export class ProviderCliAdapter implements CliAdapter {
     }
 
     private submitImmediatePrompt(state: SendMessageState, completion: SendMessageCompletion): void {
-        this.submitPendingUntil = 0;
-        this.recordTrace('submit_write', {
-            mode: 'immediate',
-            text: summarizeCliTraceText(state.text, 500),
-            sendKey: this.sendKey,
-            screenText: summarizeCliTraceText(this.terminalScreen.getText(), 500),
-        });
+        this.engine.submitPendingUntil = 0;
         void this.writeToPty(state.text + this.sendKey).then(() => {
             this.commitSendUserTurn(state);
             this.submitRetryTimer = setTimeout(() => this.retryImmediateSubmitIfStuck(state), state.retryDelayMs);
@@ -1899,7 +1243,8 @@ export class ProviderCliAdapter implements CliAdapter {
                 requirePromptEchoBeforeSubmit: this.requirePromptEchoBeforeSubmit,
                 screenText: summarizeCliTraceText(screenText, 1000),
             };
-            this.recordTrace('submit_echo_missing', diagnostic);
+            LOG.warn('CLI', `[${this.cliType}] submit_echo_missing: ${JSON.stringify(diagnostic)}`);
+
             if (this.requirePromptEchoBeforeSubmit) {
                 // At this point the prompt text write already completed. Rejecting without
                 // a submit key can leave the delegated CLI with an unsent prompt sitting at
@@ -1924,12 +1269,110 @@ export class ProviderCliAdapter implements CliAdapter {
         ), 50);
     }
 
-    async sendMessage(text: string): Promise<void> {
+    async sendMessage(text: string, options: { force?: boolean } = {}): Promise<void> {
+        if (options.force === true) {
+            await this.forceSendMessage(text);
+            return;
+        }
+        await this.sendMessageNow(text, true);
+    }
+
+    async forceSendMessage(text: string): Promise<void> {
+        if (!this.ptyProcess) throw new Error(`${this.cliName} is not running`);
+        const content = String(text || '');
+        if (!content.trim()) return;
+        LOG.info('CLI', `[${this.cliType}] force-sending prompt while status=${this.engine.currentStatus}`);
+        await this.writeToPty(content + this.sendKey);
+        this.onStatusChange?.();
+    }
+
+    private enqueuePendingOutboundMessage(text: string, reason: string): void {
+        const content = String(text || '');
+        const duplicate = this.pendingOutboundQueue.some((message) => message.content === content);
+        if (duplicate) {
+            return;
+        }
+        const queuedAt = Date.now();
+        const message: PendingOutboundMessage = {
+            id: `${queuedAt}:${this.pendingOutboundQueue.length}:${Math.random().toString(36).slice(2, 10)}`,
+            role: 'user',
+            content,
+            queuedAt,
+            source: 'sendMessage',
+        };
+        this.pendingOutboundQueue.push(message);
+        LOG.info('CLI', `[${this.cliType}] queued outbound message while busy (${reason}); queue=${this.pendingOutboundQueue.length}`);
+        this.onStatusChange?.();
+    }
+
+    private shouldQueuePendingOutboundMessage(parsedStatusBeforeSend: any | null = null): string | null {
+        if (this.provider.allowInputDuringGeneration === true) return null;
+        if (this.engine.hasActionableApproval()) return null;
+        const parsedSessionStatus = typeof parsedStatusBeforeSend?.status === 'string'
+            ? String(parsedStatusBeforeSend.status)
+            : '';
+        const hasFinalAssistant = (p: any) => {
+            const msgs = Array.isArray(p?.messages) ? p.messages : [];
+            return msgs.some((m: any) => m?.role === 'assistant' && typeof m.content === 'string' && m.content.trim());
+        };
+        if (parsedSessionStatus === 'idle' && hasFinalAssistant(parsedStatusBeforeSend)) return null;
+        if (this.engine.currentStatus === 'generating') return 'current_status_generating';
+        if (parsedSessionStatus === 'generating' || parsedSessionStatus === 'long_generating') {
+            const parsedModal = parsedStatusBeforeSend?.activeModal ?? parsedStatusBeforeSend?.modal ?? null;
+            const parsedHasActionableModal = Boolean(
+                parsedModal
+                && Array.isArray(parsedModal.buttons)
+                && parsedModal.buttons.some((candidate: unknown) => typeof candidate === 'string' && candidate.trim()),
+            );
+            const terminalLooksIdle = this.engine.currentStatus === 'idle'
+                && this.runDetectStatus(this.recentOutputBuffer) === 'idle'
+                && !this.engine.isWaitingForResponse
+                && !this.engine.currentTurnScope
+                && !this.engine.hasActionableApproval()
+                && !parsedHasActionableModal;
+            return terminalLooksIdle ? null : `parsed_status_${parsedSessionStatus}`;
+        }
+        if (this.engine.isWaitingForResponse && this.engine.currentTurnScope) return 'active_turn_in_progress';
+        return null;
+    }
+
+    private schedulePendingOutboundFlush(delayMs = 0): void {
+        if (this.pendingOutboundFlushTimer) clearTimeout(this.pendingOutboundFlushTimer);
+        this.pendingOutboundFlushTimer = setTimeout(() => {
+            this.pendingOutboundFlushTimer = null;
+            void this.flushPendingOutboundQueue();
+        }, Math.max(0, delayMs));
+    }
+
+    private async flushPendingOutboundQueue(): Promise<void> {
+        if (this.pendingOutboundFlushInFlight || this.pendingOutboundQueue.length === 0) return;
+        if (this.engine.currentStatus !== 'idle' || this.engine.isWaitingForResponse || this.engine.hasActionableApproval()) return;
+        this.pendingOutboundFlushInFlight = true;
+        try {
+            while (this.pendingOutboundQueue.length > 0) {
+                if (this.engine.currentStatus !== 'idle' || this.engine.isWaitingForResponse || this.engine.hasActionableApproval()) break;
+                const next = this.pendingOutboundQueue[0];
+                try {
+                    await this.sendMessageNow(next.content, false);
+                    this.pendingOutboundQueue.shift();
+                    this.onStatusChange?.();
+                } catch (error: any) {
+                    LOG.warn('CLI', `[${this.cliType}] queued outbound flush failed: ${error?.message || error}`);
+                    this.schedulePendingOutboundFlush(1000);
+                    break;
+                }
+            }
+        } finally {
+            this.pendingOutboundFlushInFlight = false;
+        }
+    }
+
+    private async sendMessageNow(text: string, allowQueue: boolean): Promise<void> {
         if (!this.ptyProcess) throw new Error(`${this.cliName} is not running`);
         const allowInputDuringGeneration = this.provider.allowInputDuringGeneration === true;
         const allowInterventionPrompt = allowInputDuringGeneration
-            && this.isWaitingForResponse
-            && !this.hasActionableApproval();
+            && this.engine.isWaitingForResponse
+            && !this.engine.hasActionableApproval();
         if (this.startupParseGate) {
             const deadline = Date.now() + 10000;
             while (this.startupParseGate && Date.now() < deadline) {
@@ -1937,27 +1380,33 @@ export class ProviderCliAdapter implements CliAdapter {
                 await new Promise(resolve => setTimeout(resolve, 50));
             }
         }
+        const parsedStatusBeforeSend = !allowInputDuringGeneration
+            ? (() => {
+                try {
+                    return this.getScriptParsedStatus?.() || null;
+                } catch {
+                    return null;
+                }
+            })()
+            : null;
+        const queueReason = this.shouldQueuePendingOutboundMessage(parsedStatusBeforeSend);
+        if (allowQueue && queueReason) {
+            this.enqueuePendingOutboundMessage(text, queueReason);
+            return;
+        }
         if (!allowInterventionPrompt) {
             await this.waitForInteractivePrompt();
         }
         if (!this.ready) {
             this.resolveStartupState('send_precheck');
-            if (this.runDetectStatus(this.recentOutputBuffer) === 'idle' && this.currentStatus === 'idle') {
+            if (this.runDetectStatus(this.recentOutputBuffer) === 'idle') {
                 this.ready = true;
                 this.startupParseGate = false;
+                this.engine.setStatus('idle', 'send_message_idle_prompt_recovery');
                 LOG.info('CLI', `[${this.cliType}] sendMessage recovered idle prompt readiness`);
             }
         }
-        if (!this.ready) throw new Error(`${this.cliName} not ready (status: ${this.currentStatus})`);
-        const parsedStatusBeforeSend = !allowInputDuringGeneration
-            ? (() => {
-                try {
-                    return this.getScriptParsedStatus?.() || null;
-                } catch {
-                    return null;
-                }
-            })()
-            : null;
+        if (!this.ready) throw new Error(`${this.cliName} not ready (status: ${this.engine.currentStatus})`);
         const parsedSessionStatus = typeof parsedStatusBeforeSend?.status === 'string'
             ? String(parsedStatusBeforeSend.status)
             : '';
@@ -1968,45 +1417,48 @@ export class ProviderCliAdapter implements CliAdapter {
                 && Array.isArray(parsedModal.buttons)
                 && parsedModal.buttons.some((candidate: unknown) => typeof candidate === 'string' && candidate.trim()),
             );
-            const terminalLooksIdle = this.currentStatus === 'idle'
+            const terminalLooksIdle = this.engine.currentStatus === 'idle'
                 && this.runDetectStatus(this.recentOutputBuffer) === 'idle'
-                && !this.isWaitingForResponse
-                && !this.currentTurnScope
-                && !this.hasActionableApproval()
+                && !this.engine.isWaitingForResponse
+                && !this.engine.currentTurnScope
+                && !this.engine.hasActionableApproval()
                 && !parsedHasActionableModal;
             if (!terminalLooksIdle) {
+                if (allowQueue) {
+                    this.enqueuePendingOutboundMessage(text, `parsed_status_${parsedSessionStatus}`);
+                    return;
+                }
                 throw new Error(`${this.cliName} is still processing the previous prompt`);
             }
         }
-        if (this.isWaitingForResponse && !allowInputDuringGeneration) {
-            if (!this.clearStaleIdleResponseGuard('send_message_guard')) {
+        if (this.engine.isWaitingForResponse && !allowInputDuringGeneration) {
+            const snap = this.getSnapshot();
+            if (
+                !this.engine.clearStaleIdleResponseGuard('send_message_guard', snap)
+                && !this.engine.clearParsedIdleResponseGuard('send_message_parsed_idle_guard', parsedStatusBeforeSend, snap)
+            ) {
+                if (allowQueue) {
+                    this.enqueuePendingOutboundMessage(text, 'waiting_for_response');
+                    return;
+                }
                 throw new Error(`${this.cliName} is still processing the previous prompt`);
             }
         }
-        this.isWaitingForResponse = true;
         this.responseBuffer = '';
-        this.finishRetryCount = 0;
-        if (this.finishRetryTimer) { clearTimeout(this.finishRetryTimer); this.finishRetryTimer = null; }
-        this.clearIdleFinishCandidate('send_message');
-        this.currentTurnScope = {
+        const turnScope: TurnParseScope = {
             prompt: text,
             startedAt: Date.now(),
             bufferStart: this.accumulatedBuffer.length,
             rawBufferStart: this.accumulatedRawBuffer.length,
         };
-        this.recordTrace('send_message', {
-            text: summarizeCliTraceText(text, 500),
-            estimatedLines: estimatePromptDisplayLines(text),
-            turnScope: this.currentTurnScope,
-        });
-        LOG.info('CLI', `[${this.cliType}] sendMessage turn scope buffer=${this.currentTurnScope.bufferStart} raw=${this.currentTurnScope.rawBufferStart} prompt=${JSON.stringify(text).slice(0, 120)}`);
-        this.submitRetryUsed = false;
-        this.submitRetryPromptSnippet = extractPromptRetrySnippet(text);
-        const normalizedPromptSnippet = normalizePromptText(this.submitRetryPromptSnippet);
+        LOG.info('CLI', `[${this.cliType}] sendMessage turn scope buffer=${turnScope.bufferStart} raw=${turnScope.rawBufferStart} prompt=${JSON.stringify(text).slice(0, 120)}`);
         if (this.submitRetryTimer) {
             clearTimeout(this.submitRetryTimer);
             this.submitRetryTimer = null;
         }
+        this.engine.onTurnStarted(turnScope);
+        this.engine.submitRetryPromptSnippet = extractPromptRetrySnippet(text);
+        const normalizedPromptSnippet = normalizePromptText(this.engine.submitRetryPromptSnippet);
         const estimatedLines = estimatePromptDisplayLines(text);
         const submitDelayMs = this.sendDelayMs + Math.min(2000, Math.max(0, estimatedLines - 1) * 350);
         const maxEchoWaitMs = submitDelayMs + Math.max(1500, Math.min(5000, estimatedLines * 500));
@@ -2019,12 +1471,7 @@ export class ProviderCliAdapter implements CliAdapter {
             retryDelayMs,
             didCommitUserTurn: false,
         };
-        if (this.settleTimer) {
-            clearTimeout(this.settleTimer);
-            this.settleTimer = null;
-        }
-        this.responseEpoch += 1;
-        this.responseSettleIgnoreUntil = Date.now() + submitDelayMs + this.timeouts.outputSettle + 250;
+        this.engine.responseSettleIgnoreUntil = Date.now() + submitDelayMs + this.timeouts.outputSettle + 250;
         await new Promise<void>((resolve, reject) => {
             let resolved = false;
             const completion: SendMessageCompletion = {
@@ -2047,24 +1494,20 @@ export class ProviderCliAdapter implements CliAdapter {
             }
 
             if (submitDelayMs > 0) {
-                this.submitPendingUntil = Date.now() + submitDelayMs;
+                this.engine.submitPendingUntil = Date.now() + submitDelayMs;
             }
-            this.recordTrace('submit_write', {
-                mode: 'type_then_submit',
-                text: summarizeCliTraceText(text, 500),
-                sendKey: this.sendKey,
-                screenText: summarizeCliTraceText(this.terminalScreen.getText(), 500),
-            });
             const submitStartedAt = Date.now();
             void this.writeToPty(text).then(
                 () => this.waitForEchoAndSubmit(sendState, completion, submitStartedAt),
                 completion.rejectOnce,
             );
         });
+        // Schedule settle after successful send
+        this.engine.scheduleSettle();
     }
 
     getPartialResponse(): string {
-        if (!this.isWaitingForResponse) return '';
+        if (!this.engine.isWaitingForResponse) return '';
         return this.responseBuffer;
     }
 
@@ -2077,10 +1520,10 @@ export class ProviderCliAdapter implements CliAdapter {
             cliType: this.cliType,
             cliName: this.cliName,
             workingDir: this.workingDir,
-            currentStatus: this.currentStatus,
+            currentStatus: this.engine.currentStatus,
             ready: this.ready,
-            isWaitingForResponse: this.isWaitingForResponse,
-            activeModal: this.activeModal,
+            isWaitingForResponse: this.engine.isWaitingForResponse,
+            activeModal: this.engine.activeModal,
             parseErrorMessage: this.parseErrorMessage,
             messageCounts: {
                 parsedCache: Array.isArray(parsedResult?.messages) ? parsedResult.messages.length : undefined,
@@ -2106,10 +1549,10 @@ export class ProviderCliAdapter implements CliAdapter {
                 lastScreenSnapshotReadAt: this.lastScreenSnapshotReadAt,
             },
             parser: {
-                scriptNames: listCliScriptNames(this.cliScripts),
-                traceSessionId: this.traceSessionId,
-                traceSeq: this.traceSeq,
-                currentTurnScope: this.currentTurnScope,
+                scriptNames: this.runner.getScriptNames(),
+                traceSessionId: this.engine.getTraceSessionId(),
+                traceSeq: this.engine.getTraceEntries().length,
+                currentTurnScope: this.engine.currentTurnScope,
                 parsedStatusCache: parsedResult
                     ? {
                         id: parsedResult.id,
@@ -2122,26 +1565,25 @@ export class ProviderCliAdapter implements CliAdapter {
                         activeModal: parsedResult.activeModal,
                     }
                     : null,
-                pendingScriptStatus: this.pendingScriptStatus,
-                pendingScriptStatusSince: this.pendingScriptStatusSince,
+                pendingScriptStatus: this.engine.pendingScriptStatus,
+                pendingScriptStatusSince: this.engine.pendingScriptStatusSince,
             },
             runtimeMetadata: this.getRuntimeMetadata(),
-            statusHistory: this.statusHistory.slice(-80),
-            traceEntries: this.traceEntries.slice(-120),
+            statusHistory: this.engine.getStatusHistory().slice(-80),
+            traceEntries: this.engine.getTraceEntries().slice(-120),
             timing: {
                 spawnAt: this.spawnAt,
                 startupFirstOutputAt: this.startupFirstOutputAt,
-                submitPendingUntil: this.submitPendingUntil,
-                responseSettleIgnoreUntil: this.responseSettleIgnoreUntil,
-                responseEpoch: this.responseEpoch,
+                submitPendingUntil: this.engine.submitPendingUntil,
+                responseSettleIgnoreUntil: this.engine.responseSettleIgnoreUntil,
+                responseEpoch: this.engine.responseEpoch,
                 resizeSuppressUntil: this.resizeSuppressUntil,
-                lastApprovalResolvedAt: this.lastApprovalResolvedAt,
+                lastApprovalResolvedAt: this.engine.lastApprovalResolvedAt,
             },
             finish: {
-                idleFinishCandidate: this.idleFinishCandidate,
-                finishRetryCount: this.finishRetryCount,
-                submitRetryUsed: this.submitRetryUsed,
-                submitRetryPromptSnippet: this.submitRetryPromptSnippet,
+                finishRetryCount: this.engine.finishRetryCount,
+                submitRetryUsed: this.engine.submitRetryUsed,
+                submitRetryPromptSnippet: this.engine.submitRetryPromptSnippet,
             },
         };
     }
@@ -2152,6 +1594,12 @@ export class ProviderCliAdapter implements CliAdapter {
     }
 
     updateRuntimeMeta(meta: Record<string, unknown>, replace = false): void {
+        const nextProviderSessionId = typeof meta?.providerSessionId === 'string'
+            ? meta.providerSessionId.trim()
+            : '';
+        if (nextProviderSessionId) {
+            this.providerSessionId = nextProviderSessionId;
+        }
         if (!this.ptyProcess || typeof this.ptyProcess.updateMeta !== 'function') return;
         this.ptyProcess.updateMeta(meta, replace);
     }
@@ -2172,7 +1620,7 @@ export class ProviderCliAdapter implements CliAdapter {
             this.timeouts.shutdownGrace,
             typeof resume.shutdownGraceMs === 'number' ? resume.shutdownGraceMs : 3000,
         );
-        const wasProcessing = this.currentStatus === 'generating' || this.currentStatus === 'waiting_approval';
+        const wasProcessing = this.engine.currentStatus === 'generating' || this.engine.currentStatus === 'waiting_approval';
 
         try {
             if (wasProcessing) {
@@ -2210,7 +1658,7 @@ export class ProviderCliAdapter implements CliAdapter {
         return new Promise((resolve) => {
             const startedAt = Date.now();
             const timer = setInterval(() => {
-                if (!this.ptyProcess || this.currentStatus === 'stopped') {
+                if (!this.ptyProcess || this.engine.currentStatus === 'stopped') {
                     clearInterval(timer);
                     resolve(true);
                     return;
@@ -2224,18 +1672,20 @@ export class ProviderCliAdapter implements CliAdapter {
     }
 
     shutdown(): void {
-        this.clearIdleFinishCandidate('shutdown');
+        this.engine.clearIdleFinishCandidate('shutdown');
         this.clearAllTimers();
         this.pendingOutputParseChunks = [];
         this.pendingTerminalQueryTail = '';
         this.ptyOutputChunks = [];
-        this.finishRetryCount = 0;
+        if (this.pendingOutboundFlushTimer) { clearTimeout(this.pendingOutboundFlushTimer); this.pendingOutboundFlushTimer = null; }
+        this.pendingOutboundQueue = [];
+        this.pendingOutboundFlushInFlight = false;
         if (this.ptyProcess) {
             this.ptyProcess.write('\x03');
             setTimeout(() => {
                 try { this.ptyProcess?.kill(); } catch { }
                 this.ptyProcess = null;
-                this.setStatus('stopped', 'stop_cmd');
+                this.engine.setStatus('stopped', 'stop_cmd');
                 this.ready = false;
                 this.startupParseGate = false;
                 this.spawnAt = 0;
@@ -2245,12 +1695,14 @@ export class ProviderCliAdapter implements CliAdapter {
     }
 
     detach(): void {
-        this.clearIdleFinishCandidate('detach');
+        this.engine.clearIdleFinishCandidate('detach');
         this.clearAllTimers();
         this.pendingOutputParseChunks = [];
         this.pendingTerminalQueryTail = '';
         this.ptyOutputChunks = [];
-        this.finishRetryCount = 0;
+        if (this.pendingOutboundFlushTimer) { clearTimeout(this.pendingOutboundFlushTimer); this.pendingOutboundFlushTimer = null; }
+        this.pendingOutboundQueue = [];
+        this.pendingOutboundFlushInFlight = false;
         if (this.ptyProcess) {
             try {
                 if (typeof this.ptyProcess.detach === 'function') {
@@ -2268,82 +1720,128 @@ export class ProviderCliAdapter implements CliAdapter {
     }
 
     clearHistory(): void {
-        this.clearIdleFinishCandidate('clear_history');
+        this.engine.clearIdleFinishCandidate('clear_history');
         this.accumulatedBuffer = '';
         this.accumulatedRawBuffer = '';
-        this.currentTurnScope = null;
-        this.submitRetryUsed = false;
-        this.submitRetryPromptSnippet = '';
+        this.engine.currentTurnScope = null;
+        this.engine.submitRetryUsed = false;
+        this.engine.submitRetryPromptSnippet = '';
         if (this.pendingOutputParseTimer) { clearTimeout(this.pendingOutputParseTimer); this.pendingOutputParseTimer = null; }
         this.pendingOutputParseChunks = [];
         this.pendingTerminalQueryTail = '';
         if (this.ptyOutputFlushTimer) { clearTimeout(this.ptyOutputFlushTimer); this.ptyOutputFlushTimer = null; }
         this.ptyOutputChunks = [];
-        if (this.finishRetryTimer) { clearTimeout(this.finishRetryTimer); this.finishRetryTimer = null; }
-        this.finishRetryCount = 0;
+        if (this.pendingOutboundFlushTimer) { clearTimeout(this.pendingOutboundFlushTimer); this.pendingOutboundFlushTimer = null; }
+        this.pendingOutboundQueue = [];
+        this.pendingOutboundFlushInFlight = false;
         this.resetTerminalScreen();
         this.ptyProcess?.clearBuffer?.();
         this.onStatusChange?.();
     }
 
-    isProcessing(): boolean { return this.isWaitingForResponse; }
+    isProcessing(): boolean { return this.engine.isWaitingForResponse; }
     isReady(): boolean { return this.ready; }
 
-    async writeRaw(data: string): Promise<void> {
-        this.recordTrace('write_raw', {
-            keys: JSON.stringify(data),
-            length: data.length,
-        });
-        await this.writeToPty(data);
+    // ─── State machine property accessors (delegate to engine) ──────────────
+    // These expose engine state for external callers (tests, debug tools, etc.)
+
+    get currentStatus(): CliSessionStatus['status'] { return this.engine.currentStatus; }
+    set currentStatus(v: CliSessionStatus['status']) { this.engine.setStatus(v); }
+
+    get isWaitingForResponse(): boolean { return this.engine.isWaitingForResponse; }
+    set isWaitingForResponse(v: boolean) { this.engine.isWaitingForResponse = v; }
+
+    get activeModal(): { message: string; buttons: string[] } | null { return this.engine.activeModal; }
+    set activeModal(v: { message: string; buttons: string[] } | null) { this.engine.activeModal = v; }
+
+    get currentTurnScope(): TurnParseScope | null { return this.engine.currentTurnScope; }
+    set currentTurnScope(v: TurnParseScope | null) { this.engine.currentTurnScope = v; }
+
+    get responseEpoch(): number { return this.engine.responseEpoch; }
+    set responseEpoch(v: number) { this.engine.responseEpoch = v; }
+
+    get submitRetryUsed(): boolean { return this.engine.submitRetryUsed; }
+    set submitRetryUsed(v: boolean) { this.engine.submitRetryUsed = v; }
+
+    get submitRetryPromptSnippet(): string { return this.engine.submitRetryPromptSnippet; }
+    set submitRetryPromptSnippet(v: string) { this.engine.submitRetryPromptSnippet = v; }
+
+    get responseSettleIgnoreUntil(): number { return this.engine.responseSettleIgnoreUntil; }
+    set responseSettleIgnoreUntil(v: number) { this.engine.responseSettleIgnoreUntil = v; }
+
+    get submitPendingUntil(): number { return this.engine.submitPendingUntil; }
+    set submitPendingUntil(v: number) { this.engine.submitPendingUntil = v; }
+
+    get lastApprovalResolvedAt(): number { return this.engine.lastApprovalResolvedAt; }
+    set lastApprovalResolvedAt(v: number) { this.engine.lastApprovalResolvedAt = v; }
+
+    get providerErrorMessage(): string | null { return this.engine.providerErrorMessage; }
+    get providerErrorReason(): string | null { return this.engine.providerErrorReason; }
+
+    get pendingScriptStatus(): 'generating' | 'waiting_approval' | null { return this.engine.pendingScriptStatus; }
+    get pendingScriptStatusSince(): number { return this.engine.pendingScriptStatusSince; }
+
+    get finishRetryCount(): number { return this.engine.finishRetryCount; }
+    set finishRetryCount(v: number) { this.engine.finishRetryCount = v; }
+
+    get traceSessionId(): string { return this.engine.getTraceSessionId(); }
+    get traceEntries(): CliTraceEntry[] { return this.engine.getTraceEntries(); }
+    get statusHistory(): { status: string; at: number; trigger?: string }[] { return this.engine.getStatusHistory(); }
+    get traceSeq(): number { return this.engine.getTraceEntries().length; }
+
+    /** Expose engine's evaluateSettled for test access */
+    evaluateSettled(): void {
+        LOG.debug(
+            'CLI',
+            `[${this.cliType}] settled diagnostics delegated to state engine`);
+        this.engine.evaluateSettled(this.getSnapshot());
+    }
+    /** Expose engine's scheduleSettle for test access */
+    scheduleSettle(): void { this.engine.scheduleSettle(); }
+    /** Expose engine's clearIdleFinishCandidate for test access */
+    clearIdleFinishCandidate(reason: string): void { this.engine.clearIdleFinishCandidate(reason); }
+    /** Expose engine's finishResponse for test access */
+    finishResponse(): void { this.engine.finishResponse(); }
+    /** Returns a point-in-time snapshot of all buffer/screen state for external consumers (e.g. CliStateEngine). */
+    getSnapshot(): CliBufferSnapshot {
+        const screenText = this.terminalScreen.getText() || '';
+        return {
+            accumulatedBuffer: this.accumulatedBuffer,
+            accumulatedRawBuffer: this.accumulatedRawBuffer,
+            recentOutputBuffer: this.recentOutputBuffer,
+            responseBuffer: this.responseBuffer,
+            screenText,
+            parseScreenText: this.getParseScreenText(screenText),
+            workingDir: this.workingDir,
+            providerSessionId: this.providerSessionId,
+            runtimeSettings: this.runtimeSettings,
+            isWaitingForResponse: this.engine.isWaitingForResponse,
+            currentTurnScope: this.engine.currentTurnScope,
+            lastOutputAt: this.lastOutputAt,
+            lastNonEmptyOutputAt: this.lastNonEmptyOutputAt,
+            lastScreenChangeAt: this.lastScreenChangeAt,
+            lastScreenSnapshot: this.lastScreenSnapshot,
+        };
+    }
+    isAlive(): boolean { return this.ptyProcess !== null; }
+    flushOutboundQueue(): void { this.schedulePendingOutboundFlush(); }
+
+    async writeRaw(data: string | Buffer): Promise<void> {
+        const str = Buffer.isBuffer(data) ? data.toString('utf8') : data;
+        await this.writeToPty(str);
     }
 
     resolveModal(buttonIndex: number): void {
-        let modal = this.activeModal || this.runParseApproval(this.recentOutputBuffer);
-        if (!modal && typeof this.cliScripts?.parseSession === 'function') {
-            try {
-                const parsed = this.getScriptParsedStatus();
-                const parsedModal = parsed?.activeModal && Array.isArray(parsed.activeModal.buttons)
-                    && parsed.activeModal.buttons.some((button: any) => typeof button === 'string' && button.trim())
-                    ? parsed.activeModal
-                    : null;
-                if (parsed?.status === 'waiting_approval' && parsedModal) {
-                    modal = parsedModal;
-                    this.activeModal = parsedModal;
-                    if (this.currentStatus !== 'waiting_approval') {
-                        this.setStatus('waiting_approval', 'resolve_modal_parse');
-                        this.onStatusChange?.();
-                    }
-                }
-            } catch {
-                // Ignore parse failures here; resolveModal falls back to current state.
-            }
-        }
-        if (!this.ptyProcess || ((this.currentStatus !== 'waiting_approval') && !modal)) return;
-        this.clearIdleFinishCandidate('resolve_modal');
-        this.recordTrace('resolve_modal', {
-            buttonIndex,
-            activeModal: modal,
-        });
-        this.activeModal = null;
-        this.lastApprovalResolvedAt = Date.now();
-        this.responseSettleIgnoreUntil = Date.now() + this.timeouts.outputSettle + 400;
-        if (this.approvalExitTimeout) {
-            clearTimeout(this.approvalExitTimeout);
-            this.approvalExitTimeout = null;
-        }
-        this.setStatus('generating', 'approval_resolved');
-        this.onStatusChange?.();
-        if (buttonIndex in this.approvalKeys) {
-            this.ptyProcess.write(this.approvalKeys[buttonIndex]);
-        } else {
-            const buttonCount = Array.isArray(modal?.buttons) ? modal.buttons.length : 0;
-            const clampedIndex = buttonCount > 0
-                ? Math.min(Math.max(0, buttonIndex), buttonCount - 1)
-                : Math.max(0, buttonIndex);
-            const DOWN = '\x1B[B';
-            const keys = DOWN.repeat(clampedIndex) + '\r';
-            this.ptyProcess.write(keys);
-        }
+        this.engine.resolveModal(buttonIndex);
+    }
+
+    getApprovalKeyForIndex(buttonIndex: number): string | undefined {
+        return buttonIndex in this.approvalKeys ? this.approvalKeys[buttonIndex] : undefined;
+    }
+
+    /** Returns true if an approval was resolved within the adapter's cooldown window. */
+    isApprovalRecentlyResolved(): boolean {
+        return this.engine.isApprovalRecentlyResolved();
     }
 
     resize(cols: number, rows: number): void {
@@ -2357,7 +1855,7 @@ export class ProviderCliAdapter implements CliAdapter {
     }
 
     private getParsedDebugState(): Record<string, any> | null {
-        if (this.startupParseGate || typeof this.cliScripts?.parseSession !== 'function') return null;
+        if (this.startupParseGate || !this.runner.hasParseSession()) return null;
         try {
             const parsed = this.getScriptParsedStatus();
             return parsed && typeof parsed === 'object' ? parsed as Record<string, any> : null;
@@ -2369,18 +1867,43 @@ export class ProviderCliAdapter implements CliAdapter {
     getDebugState(): Record<string, any> {
         const screenText = sanitizeTerminalText(this.terminalScreen.getText());
         const startupModal = this.startupParseGate ? this.runParseApproval(this.recentOutputBuffer) : null;
-        const effectiveStatus = this.projectEffectiveStatus(startupModal);
-        const effectiveReady = this.ready || !!startupModal;
+        const startupDetectedStatus = this.startupParseGate && !startupModal
+            ? this.runDetectStatus(this.recentOutputBuffer || screenText)
+            : null;
+        const effectiveReady = this.ready || !!startupModal || startupDetectedStatus === 'waiting_approval';
         const parsedDebugState = this.getParsedDebugState();
         const parsedMessages = Array.isArray(parsedDebugState?.messages) ? parsedDebugState.messages : [];
+        const hasFinalAssistant = (p: any) => {
+            const msgs = Array.isArray(p?.messages) ? p.messages : [];
+            return msgs.some((m: any) => m?.role === 'assistant' && typeof m.content === 'string' && m.content.trim());
+        };
+        let effectiveStatus = this.projectEffectiveStatus(startupModal);
+        if (parsedDebugState?.status === 'error') {
+            effectiveStatus = 'error';
+        }
+        // (fix) Mirror the getStatus contract: never surface waiting_approval
+        // without a concrete modal. detectStatus alone can fire while
+        // parseApproval is still null, and a bare debugState waiting_approval
+        // confused dashboards reading the debug payload.
+        const debugEffectiveModal = startupModal || this.engine.activeModal;
+        if (startupDetectedStatus === 'waiting_approval' && debugEffectiveModal) {
+            effectiveStatus = 'waiting_approval';
+        }
+        if (
+            effectiveStatus === 'idle'
+            && parsedDebugState?.status === 'generating'
+            && !hasFinalAssistant(parsedDebugState)
+        ) {
+            effectiveStatus = 'generating';
+        }
         return {
             type: this.cliType,
             name: this.cliName,
             providerResolution: this.providerResolutionMeta,
             status: effectiveStatus,
             projectedStatus: effectiveStatus,
-            rawStatus: this.currentStatus,
-            lifecycleStatus: this.isWaitingForResponse ? 'awaiting_response' : 'idle',
+            rawStatus: this.engine.currentStatus,
+            lifecycleStatus: this.engine.isWaitingForResponse ? 'awaiting_response' : 'idle',
             ready: effectiveReady,
             startupParseGate: this.startupParseGate,
             spawnAt: this.spawnAt,
@@ -2394,38 +1917,47 @@ export class ProviderCliAdapter implements CliAdapter {
                 providerSessionId: parsedDebugState.providerSessionId,
                 transcriptAuthority: parsedDebugState.transcriptAuthority,
                 coverage: parsedDebugState.coverage,
+                errorMessage: parsedDebugState.errorMessage,
+                errorReason: parsedDebugState.errorReason,
                 activeModal: parsedDebugState.activeModal,
                 messageCount: parsedMessages.length,
             } : null,
             screenText: screenText.slice(-4000),
-            currentTurnScope: this.currentTurnScope,
+            currentTurnScope: this.engine.currentTurnScope,
             startupBuffer: this.startupBuffer.slice(-4000),
             recentOutputBuffer: this.recentOutputBuffer.slice(-500),
-            settledBuffer: this.settledBuffer.slice(-500),
             accumulatedBufferLength: this.accumulatedBuffer.length,
             accumulatedRawBufferLength: this.accumulatedRawBuffer.length,
             rawBufferPreview: this.accumulatedRawBuffer.slice(-1000),
             sanitizedRawPreview: sanitizeTerminalText(this.accumulatedRawBuffer).slice(-1000),
             responseBuffer: this.responseBuffer.slice(-1000),
+            pendingOutboundQueue: this.pendingOutboundQueue.map((message) => ({
+                id: message.id,
+                role: message.role,
+                content: message.content,
+                queuedAt: message.queuedAt,
+                source: message.source,
+            })),
+            pendingOutboundCount: this.pendingOutboundQueue.length,
             lastOutputAt: this.lastOutputAt,
             lastNonEmptyOutputAt: this.lastNonEmptyOutputAt,
             lastScreenChangeAt: this.lastScreenChangeAt,
             lastScreenSnapshot: this.lastScreenSnapshot.slice(-500),
-            isWaitingForResponse: this.isWaitingForResponse,
-            activeModal: startupModal || this.activeModal,
-            lastApprovalResolvedAt: this.lastApprovalResolvedAt,
+            isWaitingForResponse: this.engine.isWaitingForResponse,
+            activeModal: startupModal || this.engine.activeModal,
+            lastApprovalResolvedAt: this.engine.lastApprovalResolvedAt,
             sendDelayMs: this.sendDelayMs,
             sendKey: this.sendKey,
             submitStrategy: this.submitStrategy,
             requirePromptEchoBeforeSubmit: this.requirePromptEchoBeforeSubmit,
-            submitPendingUntil: this.submitPendingUntil,
-            responseSettleIgnoreUntil: this.responseSettleIgnoreUntil,
+            submitPendingUntil: this.engine.submitPendingUntil,
+            responseSettleIgnoreUntil: this.engine.responseSettleIgnoreUntil,
             resizeSuppressUntil: this.resizeSuppressUntil,
             hasCliScripts: this.hasCliScripts(),
-            scriptNames: listCliScriptNames(this.cliScripts),
-            traceSessionId: this.traceSessionId,
-            traceEntryCount: this.traceEntries.length,
-            statusHistory: this.statusHistory.slice(-30),
+            scriptNames: this.runner.getScriptNames(),
+            traceSessionId: this.engine.getTraceSessionId(),
+            traceEntryCount: this.engine.getTraceEntries().length,
+            statusHistory: this.engine.getStatusHistory().slice(-30),
             timeouts: this.timeouts,
             pendingOutputParseBufferLength: this.pendingOutputParseChunks.reduce((total, chunk) => total + chunk.length, 0),
             pendingOutputParseScheduled: !!this.pendingOutputParseTimer,
@@ -2435,20 +1967,21 @@ export class ProviderCliAdapter implements CliAdapter {
 
     getTraceState(limit = 120): Record<string, any> {
         const cappedLimit = Math.max(1, Math.min(500, Number.isFinite(limit) ? Math.floor(limit) : 120));
+        const traceEntries = this.engine.getTraceEntries();
         return {
-            sessionId: this.traceSessionId,
+            sessionId: this.engine.getTraceSessionId(),
             providerResolution: this.providerResolutionMeta,
-            entryCount: this.traceEntries.length,
-            entries: this.traceEntries.slice(-cappedLimit),
+            entryCount: traceEntries.length,
+            entries: traceEntries.slice(-cappedLimit),
             screenText: summarizeCliTraceText(this.terminalScreen.getText(), 4000),
             recentOutputBuffer: summarizeCliTraceText(this.recentOutputBuffer, 1000),
             responseBuffer: summarizeCliTraceText(this.responseBuffer, 1200),
             status: this.projectEffectiveStatus(),
             projectedStatus: this.projectEffectiveStatus(),
-            rawStatus: this.currentStatus,
-            lifecycleStatus: this.isWaitingForResponse ? 'awaiting_response' : 'idle',
-            activeModal: this.activeModal,
-            currentTurnScope: this.currentTurnScope,
+            rawStatus: this.engine.currentStatus,
+            lifecycleStatus: this.engine.isWaitingForResponse ? 'awaiting_response' : 'idle',
+            activeModal: this.engine.activeModal,
+            currentTurnScope: this.engine.currentTurnScope,
             messages: [],
         };
     }