@adhdev/daemon-core 0.9.82-rc.45 → 0.9.82-rc.450

package/dist/cli-adapters/cli-state-engine.d.ts

@@ -0,0 +1,200 @@
+/**
+ * CliStateEngine — CLI provider status state machine
+ *
+ * Owns all status-transition logic, timer management, and script-driven
+ * evaluation. Reads buffer state from the transport and writes to PTY via
+ * the transport interface — adapter stays as pure I/O layer.
+ */
+import { type TurnParseScope } from './provider-cli-parse.js';
+import { type CliProviderModule, type CliSessionStatus, type CliTraceEntry, type ParsedSession } from './provider-cli-shared.js';
+import type { CliScriptRunner } from './cli-script-runner.js';
+export interface CliBufferSnapshot {
+    accumulatedBuffer: string;
+    accumulatedRawBuffer: string;
+    recentOutputBuffer: string;
+    responseBuffer: string;
+    screenText: string;
+    parseScreenText: string;
+    workingDir: string;
+    providerSessionId: string | null;
+    runtimeSettings: Record<string, any>;
+    isWaitingForResponse: boolean;
+    currentTurnScope: TurnParseScope | null;
+    lastOutputAt: number;
+    lastNonEmptyOutputAt: number;
+    lastScreenChangeAt: number;
+    lastScreenSnapshot: string;
+}
+/** What the engine needs from the transport layer */
+export interface CliTransportAccess {
+    getSnapshot(): CliBufferSnapshot;
+    writeRaw(data: string | Buffer): void;
+    getApprovalKeyForIndex(buttonIndex: number): string | undefined;
+    flushOutboundQueue(): void;
+    isAlive(): boolean;
+    /** Optional: override script dispatch (used by tests to mock detection) */
+    runDetectStatus?(text: string): string | null;
+    /** Optional: override script dispatch (used by tests to mock approval) */
+    runParseApproval?(tail: string): {
+        message: string;
+        buttons: string[];
+    } | null;
+    /** Optional: override full session parse (used by tests to mock parsing) */
+    runParseSession?(): ParsedSession | null;
+    /** Optional: provider type override — used when tests patch the adapter's cliType */
+    cliType?: string;
+}
+export interface CliStateEngineCallbacks {
+    onStatusChange(): void;
+    onApplyParsedSession(session: ParsedSession): void;
+    onTurnCompleted(): void;
+}
+export declare class CliStateEngine {
+    private readonly provider;
+    private readonly runner;
+    private readonly transport;
+    private readonly callbacks;
+    private readonly timeouts;
+    currentStatus: CliSessionStatus['status'];
+    isWaitingForResponse: boolean;
+    currentTurnScope: TurnParseScope | null;
+    currentTurnTaskId: string | null;
+    currentTurnStartedAt: number;
+    activeModal: {
+        message: string;
+        buttons: string[];
+    } | null;
+    lastApprovalResolvedAt: number;
+    lastResolvedModalMessage: string;
+    /**
+     * Monotonic counter bumped every time the FSM *enters* waiting_approval
+     * with a freshly captured modal (see `applyWaitingApproval`). It is the
+     * single discriminator between "the same approval re-observed across TUI
+     * paint flaps" and "a genuinely new, distinct approval".
+     *
+     * The message-equality cooldown below (`lastResolvedModalMessage`) cannot
+     * tell these apart on its own: claude-cli routinely presents consecutive
+     * approvals whose modal message text is identical (e.g. two back-to-back
+     * Bash-command prompts). When that second approval arrived inside
+     * `approvalCooldown`, the message-equality guard silently swallowed the
+     * key write and the approval stuck forever — fatal under auto-approval.
+     *
+     * `approvalEntrySeq` increments on every fresh entry; `lastResolvedEntrySeq`
+     * records which entry the cooldown belongs to. We only short-circuit the
+     * write when we are still resolving *that same* entry — a new entry (new
+     * seq) is always a real, distinct approval and must be written.
+     */
+    approvalEntrySeq: number;
+    lastResolvedEntrySeq: number;
+    /**
+     * When the engine previously held a modal but the latest parse failed
+     * to extract one, we record the timestamp here and only drop the modal
+     * after the configured `approvalCooldown` to avoid flapping between
+     * waiting_approval and generating on every Claude TUI redraw — that
+     * flapping is what fed auto-approve a fresh modal signature on each
+     * paint and made the engine type "1" repeatedly into the prompt.
+     */
+    modalLostAt: number;
+    private approvalExitTimeout;
+    responseEpoch: number;
+    submitPendingUntil: number;
+    responseSettleIgnoreUntil: number;
+    submitRetryUsed: boolean;
+    submitRetryPromptSnippet: string;
+    finishRetryCount: number;
+    providerErrorMessage: string | null;
+    providerErrorReason: string | null;
+    private settleTimer;
+    private idleTimeout;
+    private finishRetryTimer;
+    private providerErrorRetryTimer;
+    private providerErrorRetryKey;
+    pendingScriptStatus: 'generating' | 'waiting_approval' | null;
+    pendingScriptStatusSince: number;
+    private pendingScriptStatusTimer;
+    private idleFinishCandidate;
+    /**
+     * `finishResponse` produces the `generating → idle` transition that
+     * coordinators interpret as "task complete". Some providers (antigravity-
+     * cli observed in the wild) briefly paint a screen that looks like an
+     * idle prompt between tool result frames while still actively running,
+     * which fired `response_finished` and broke completion semantics.
+     * We defer the actual idle transition by IDLE_CONFIRMATION_GRACE_MS and
+     * cancel it if the scripted detection re-detects generating during that
+     * window — a true completion stays idle for many seconds, so a 2-second
+     * grace is sufficient to filter the paint blip.
+     */
+    private pendingIdleFinishTimer;
+    private pendingIdleFinishAt;
+    private statusHistory;
+    private traceEntries;
+    private traceSeq;
+    private traceSessionId;
+    constructor(provider: CliProviderModule, runner: CliScriptRunner, transport: CliTransportAccess, callbacks: CliStateEngineCallbacks, timeouts: Required<NonNullable<CliProviderModule['timeouts']>>);
+    setStatus(status: CliSessionStatus['status'], trigger?: string): void;
+    scheduleSettle(): void;
+    /** Called from sendMessage in transport once a turn scope is established. */
+    onTurnStarted(turnScope: TurnParseScope): void;
+    /** Called when PTY exits */
+    onPtyExit(): void;
+    /** Called when adapter starts up successfully */
+    onSpawnReady(): void;
+    resolveModal(buttonIndex: number): void;
+    isApprovalRecentlyResolved(): boolean;
+    /**
+     * Called from sendMessage before starting a new turn.
+     * Clears stale idle response state when the terminal looks idle and no modal is active.
+     */
+    clearStaleIdleResponseGuard(reason: string, snap: CliBufferSnapshot): boolean;
+    /**
+     * Called from sendMessage before starting a new turn.
+     * Clears stale idle response state when the parsed session confirms idle with a final assistant message.
+     */
+    clearParsedIdleResponseGuard(reason: string, parsedStatus: any, snap: CliBufferSnapshot): boolean;
+    clearAllTimers(): void;
+    resetActiveTurnState(): void;
+    clearIdleFinishCandidate(reason: string): void;
+    hasActionableApproval(startupModal?: {
+        message: string;
+        buttons: string[];
+    } | null): boolean;
+    getTraceEntries(): CliTraceEntry[];
+    getStatusHistory(): {
+        status: string;
+        at: number;
+        trigger?: string;
+    }[];
+    getTraceSessionId(): string;
+    /** Record a trace entry from the transport layer (e.g. output events in debug mode). */
+    recordExternalTrace(type: string, payload?: Record<string, any>): void;
+    runDetectStatus(snap: CliBufferSnapshot): string | null;
+    runParseApproval(snap: CliBufferSnapshot): {
+        message: string;
+        buttons: string[];
+    } | null;
+    runParseSession(snap: CliBufferSnapshot): ParsedSession | null;
+    evaluateSettled(snap: CliBufferSnapshot): void;
+    private applyPendingScriptStatusDebounce;
+    private applyHoldGenerating;
+    private applyWaitingApproval;
+    private applyGenerating;
+    private applyError;
+    private maybeScheduleProviderErrorRetry;
+    private applyIdle;
+    finishResponse(): void;
+    private scheduleIdleFinish;
+    private cancelPendingIdleFinish;
+    private armApprovalExitTimeout;
+    private armIdleFinishCandidate;
+    private shouldDeferIdleTimeoutFinish;
+    private hasRecentInteractiveActivity;
+    private hasMeaningfulResponseBuffer;
+    private shouldDeferFinishForTranscript;
+    private rescheduleTranscriptFinishCheck;
+    private shouldRetryFinishResponse;
+    private commitCurrentTranscript;
+    private maybeCommitVisibleIdleTranscript;
+    private parsedStatusHasFinalAssistantMessage;
+    private parsedStatusHasFinalStandardAssistantMessage;
+    private recordTrace;
+}

package/dist/cli-adapters/provider-cli-adapter.d.ts

@@ -13,31 +13,33 @@
  *   type, name, category: 'cli', binary, spawn, approvalKeys
  *   compatibility: [{ ideVersion, scriptDir }]  ← versioned scripts
  */
-import type { CliAdapter } from '../cli-adapter-types.js';
+import type { CliAdapter, CliLaunchInfo } from '../cli-adapter-types.js';
+import type { InteractivePromptResponse } from '../providers/types/interactive-prompt.js';
 import { type PtyRuntimeMetadata, type PtyTransportFactory } from './pty-transport.js';
-import { type CliProviderModule, type CliScripts, type CliSessionStatus } from './provider-cli-shared.js';
+import { type CliProviderModule, type CliScripts, type CliSessionStatus, type CliTraceEntry, type ParsedSession } from './provider-cli-shared.js';
+import { CliStateEngine, type CliBufferSnapshot } from './cli-state-engine.js';
+import { type TurnParseScope } from './provider-cli-parse.js';
 import { type ProviderResolutionMeta } from './provider-cli-config.js';
 export { normalizeCliProviderForRuntime, type CliApprovalInput, type CliChatMessage, type CliProviderModule, type CliScreenLine, type CliScreenSnapshot, type CliScriptInput, type CliScripts, type CliSessionStatus, type CliStatusInput, type CliTraceEntry, } from './provider-cli-shared.js';
 export declare function appendBoundedText(current: string, chunk: string, maxChars: number): string;
 export declare class ProviderCliAdapter implements CliAdapter {
     private extraArgs;
     private extraEnv;
-    readonly cliType: string;
+    cliType: string;
     readonly cliName: string;
     workingDir: string;
     private provider;
     private ptyProcess;
     private transportFactory;
-    private currentStatus;
     private onStatusChange;
+    readonly engine: CliStateEngine;
     private responseBuffer;
     private recentOutputBuffer;
-    private isWaitingForResponse;
-    private activeModal;
-    private parseErrorMessage;
+    private get parseErrorMessage();
+    private providerSessionId;
     private responseTimeout;
-    private idleTimeout;
     private ready;
+    private firstTurnSent;
     private startupBuffer;
     private startupParseGate;
     private startupSettleTimer;
@@ -57,28 +59,32 @@ export declare class ProviderCliAdapter implements CliAdapter {
     private lastScreenSnapshotReadAt;
     private serverConn;
     private logBuffer;
-    private lastApprovalResolvedAt;
-    private approvalTransitionBuffer;
-    private approvalExitTimeout;
-    private pendingScriptStatus;
-    private pendingScriptStatusSince;
-    private pendingScriptStatusTimer;
-    private settleTimer;
-    private settledBuffer;
-    private submitPendingUntil;
-    private responseSettleIgnoreUntil;
-    private responseEpoch;
+    private pendingOutboundQueue;
+    private pendingOutboundFlushTimer;
+    private pendingOutboundFlushInFlight;
     private submitRetryTimer;
-    private submitRetryUsed;
-    private submitRetryPromptSnippet;
-    private idleFinishCandidate;
-    private finishRetryTimer;
-    private finishRetryCount;
     private resizeSuppressUntil;
-    private statusHistory;
-    private cliScripts;
-    /** Per-session opaque state object created by cliScripts.createState(), reset on stop. */
-    private scriptState;
+    private readonly runner;
+    /** @deprecated use runner.cliScripts for direct script access */
+    get cliScripts(): CliScripts;
+    /**
+     * 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(): import("./cli-script-runner.js").CliScriptInvocationTrace[];
+    /**
+     * 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;
+    };
+    set cliScripts(scripts: CliScripts);
     private runtimeSettings;
     /** Full accumulated rendered PTY transcript for parser/readback use */
     private accumulatedBuffer;
@@ -98,16 +104,9 @@ export declare 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;
-    private currentTurnScope;
-    private traceEntries;
-    private traceSeq;
-    private traceSessionId;
     private parsedStatusCache;
     private static readonly SCREEN_SNAPSHOT_MIN_INTERVAL_MS;
-    private static readonly MAX_TRACE_ENTRIES;
     private readonly providerResolutionMeta;
-    private static readonly FINISH_RETRY_DELAY_MS;
-    private static readonly MAX_FINISH_RETRIES;
     private getBufferState;
     private recordBoundedAppendDrop;
     private readTerminalScreenText;
@@ -120,18 +119,12 @@ export declare class ProviderCliAdapter implements CliAdapter {
     private shouldUseFullProviderTranscriptContext;
     private getIdleFinishConfirmMs;
     private getStatusActivityHoldMs;
-    private setStatus;
-    private clearIdleFinishCandidate;
-    private armIdleFinishCandidate;
-    private recordTrace;
-    private resetTraceSession;
     private readonly timeouts;
     private readonly approvalKeys;
     private readonly sendDelayMs;
     private readonly sendKey;
     private readonly submitStrategy;
     private readonly requirePromptEchoBeforeSubmit;
-    private static readonly SCRIPT_STATUS_DEBOUNCE_MS;
     constructor(provider: CliProviderModule, workingDir: string, extraArgs?: string[], extraEnv?: Record<string, string>, transportFactory?: PtyTransportFactory);
     /** Inject CLI scripts after construction (e.g. when resolved by ProviderLoader) */
     setCliScripts(scripts: CliScripts): void;
@@ -146,29 +139,15 @@ export declare class ProviderCliAdapter implements CliAdapter {
     private handleOutput;
     private resolveStartupState;
     private scheduleStartupSettleCheck;
-    private scheduleSettle;
-    private armApprovalExitTimeout;
-    private shouldRetryFinishResponse;
-    private hasRecentInteractiveActivity;
-    private shouldDeferIdleTimeoutFinish;
     private waitForInteractivePrompt;
     private clearAllTimers;
-    private clearStaleIdleResponseGuard;
-    private hasMeaningfulResponseBuffer;
-    private evaluateSettled;
-    private applyPendingScriptStatusDebounce;
-    private applyHoldGenerating;
-    private applyWaitingApproval;
-    private applyGenerating;
-    private applyIdle;
-    private finishResponse;
-    private maybeCommitVisibleIdleTranscript;
-    private commitCurrentTranscript;
-    private invokeCliScript;
-    private runParseSession;
-    private runDetectStatus;
-    private runParseApproval;
-    private hasActionableApproval;
+    runParseSession(): ParsedSession | null;
+    runDetectStatus(text: string): string | null;
+    runParseApproval(tail: string): {
+        message: string;
+        buttons: string[];
+    } | null;
+    private applyParsedSessionMetadata;
     private projectEffectiveStatus;
     getStatus(options?: {
         allowParse?: boolean;
@@ -187,21 +166,47 @@ export declare class ProviderCliAdapter implements CliAdapter {
      * Uses resolveAction script if available, otherwise falls back to standard text.
      */
     resolveAction(data: any): Promise<void>;
+    setInteractivePromptResponse(_response: InteractivePromptResponse): Promise<void>;
     private isSubmitStuck;
+    private hasMeaningfulResponseBufferLocal;
     private writeToPty;
+    /** Write `data` to the PTY in bounded, surrogate-safe chunks with a short
+     *  inter-chunk gap (win32 paced write). Awaits each chunk's write and the gap
+     *  so the returned promise resolves only after the FINAL chunk (carrying any
+     *  trailing submit key) has been written. */
+    private writeWin32Chunked;
     private resetPendingSendState;
     private commitSendUserTurn;
     private armResponseTimeout;
     private writeSubmitKeyForRetry;
+    private writeStuckRetry;
     private retrySubmitIfStuck;
     private retryImmediateSubmitIfStuck;
     private submitSendKey;
     private submitImmediatePrompt;
     private waitForEchoAndSubmit;
-    sendMessage(text: string): Promise<void>;
+    sendMessage(text: string, options?: {
+        force?: boolean;
+        meshTaskId?: string;
+    }): Promise<void>;
+    forceSendMessage(text: string, meshTaskId?: string): Promise<void>;
+    private waitForForceSubmitSettle;
+    private enqueuePendingOutboundMessage;
+    private shouldQueuePendingOutboundMessage;
+    private schedulePendingOutboundFlush;
+    private flushPendingOutboundQueue;
+    private sendMessageNow;
     getPartialResponse(): string;
     getDebugSnapshot(): Record<string, unknown>;
     getRuntimeMetadata(): PtyRuntimeMetadata | null;
+    /**
+     * Launch metadata for the dashboard Session info panel. Re-derives the spawn plan
+     * (pure — same inputs the live PTY was spawned with) so the dashboard sees the
+     * resolved binary, full arg vector, and cwd without us having to persist it.
+     * extraEnv values are intentionally dropped (keys only) so secrets passed at
+     * launch time never reach the dashboard.
+     */
+    getLaunchInfo(): CliLaunchInfo;
     updateRuntimeMeta(meta: Record<string, unknown>, replace?: boolean): void;
     cancel(): void;
     saveAndStop(): Promise<void>;
@@ -211,8 +216,65 @@ export declare class ProviderCliAdapter implements CliAdapter {
     clearHistory(): void;
     isProcessing(): boolean;
     isReady(): boolean;
-    writeRaw(data: string): Promise<void>;
+    get currentStatus(): CliSessionStatus['status'];
+    set currentStatus(v: CliSessionStatus['status']);
+    get isWaitingForResponse(): boolean;
+    set isWaitingForResponse(v: boolean);
+    get activeModal(): {
+        message: string;
+        buttons: string[];
+    } | null;
+    set activeModal(v: {
+        message: string;
+        buttons: string[];
+    } | null);
+    get currentTurnScope(): TurnParseScope | null;
+    set currentTurnScope(v: TurnParseScope | null);
+    get currentTurnTaskId(): string | null;
+    get currentTurnStartedAt(): number;
+    get responseEpoch(): number;
+    set responseEpoch(v: number);
+    get submitRetryUsed(): boolean;
+    set submitRetryUsed(v: boolean);
+    get submitRetryPromptSnippet(): string;
+    set submitRetryPromptSnippet(v: string);
+    get responseSettleIgnoreUntil(): number;
+    set responseSettleIgnoreUntil(v: number);
+    get submitPendingUntil(): number;
+    set submitPendingUntil(v: number);
+    get lastApprovalResolvedAt(): number;
+    set lastApprovalResolvedAt(v: number);
+    get providerErrorMessage(): string | null;
+    get providerErrorReason(): string | null;
+    get pendingScriptStatus(): 'generating' | 'waiting_approval' | null;
+    get pendingScriptStatusSince(): number;
+    get finishRetryCount(): number;
+    set finishRetryCount(v: number);
+    get traceSessionId(): string;
+    get traceEntries(): CliTraceEntry[];
+    get statusHistory(): {
+        status: string;
+        at: number;
+        trigger?: string;
+    }[];
+    get traceSeq(): number;
+    /** Expose engine's evaluateSettled for test access */
+    evaluateSettled(): void;
+    /** Expose engine's scheduleSettle for test access */
+    scheduleSettle(): void;
+    /** Expose engine's clearIdleFinishCandidate for test access */
+    clearIdleFinishCandidate(reason: string): void;
+    /** Expose engine's finishResponse for test access */
+    finishResponse(): void;
+    /** Returns a point-in-time snapshot of all buffer/screen state for external consumers (e.g. CliStateEngine). */
+    getSnapshot(): CliBufferSnapshot;
+    isAlive(): boolean;
+    flushOutboundQueue(): void;
+    writeRaw(data: string | Buffer): Promise<void>;
     resolveModal(buttonIndex: number): void;
+    getApprovalKeyForIndex(buttonIndex: number): string | undefined;
+    /** Returns true if an approval was resolved within the adapter's cooldown window. */
+    isApprovalRecentlyResolved(): boolean;
     resize(cols: number, rows: number): void;
     private getParsedDebugState;
     getDebugState(): Record<string, any>;

package/dist/cli-adapters/provider-cli-parse.d.ts

@@ -4,6 +4,7 @@ export interface TurnParseScope {
     startedAt: number;
     bufferStart: number;
     rawBufferStart: number;
+    taskId?: string;
 }
 export declare function normalizeCliParsedMessages(parsedMessages: any[], _options: {
     scope?: TurnParseScope | null;
@@ -15,11 +16,15 @@ export declare function buildCliParseInput(options: {
     accumulatedRawBuffer: string;
     recentOutputBuffer: string;
     terminalScreenText: string;
+    workingDir?: string;
+    providerSessionId?: string;
+    historySessionId?: string;
     baseMessages: CliChatMessage[];
     partialResponse: string;
     isWaitingForResponse?: boolean;
     scope?: TurnParseScope | null;
     runtimeSettings: Record<string, any>;
+    spawnAt?: number;
 }): CliScriptInput;
 export declare function summarizeCliTraceText(text: string, max?: number): string;
 export declare function summarizeCliTraceMessages(messages: CliChatMessage[], limit?: number): {

package/dist/cli-adapters/provider-cli-runtime.d.ts

@@ -17,6 +17,40 @@ export declare function resolveCliSpawnPlan(options: {
     extraArgs: string[];
     extraEnv?: Record<string, string>;
 }): CliSpawnPlan;
+/**
+ * Cols/rows for a PTY spawn. Defaults to the session-host terminal size; the
+ * spec driver may override per-instance.
+ */
+export interface CliSpawnGeometry {
+    cols?: number;
+    rows?: number;
+}
+/**
+ * Core spawn-plan resolution from already-flattened spawn parts — the single
+ * source of truth for binary resolution (findBinary: PATH + npm-global / Node
+ * dir fallback), `{{workingDir}}` token substitution, shell wrapping
+ * (script-shims / non-absolute / non-native binaries), and env sanitization +
+ * TERMINAL_CWD. Both the legacy provider-module path (resolveCliSpawnPlan) and
+ * the spec/FSM path (FsmDriver.buildAdapterOpts) feed into this so the two
+ * spawn paths can never diverge.
+ */
+export declare function resolveCliSpawnPlanFromParts(options: {
+    /** Raw command from the spec/provider (`binary` / `spawn.command`), or an
+     *  operator-configured executable path override. */
+    command: string;
+    /** Base launch args declared by the spec/provider (`spawn_args` /
+     *  `spawn.args`). */
+    baseArgs?: string[];
+    /** When true, always wrap the launch in a login shell. */
+    shell?: boolean;
+    /** Base env declared by the spec/provider (`env` / `spawn.env`). */
+    baseEnv?: Record<string, string>;
+    workingDir: string;
+    /** Per-launch extra args (e.g. resume session id) appended after baseArgs. */
+    extraArgs?: string[];
+    extraEnv?: Record<string, string>;
+    geometry?: CliSpawnGeometry;
+}): CliSpawnPlan;
 export declare function buildCliLoginShellRetry(plan: Pick<CliSpawnPlan, 'binaryPath' | 'allArgs'>): {
     shellCmd: string;
     shellArgs: string[];

package/dist/cli-adapters/provider-cli-shared.d.ts

@@ -1,6 +1,7 @@
 import type { ProviderResumeCapability } from '../providers/contracts.js';
 import type { ChatMessageKind } from '../providers/chat-message-normalization.js';
 import type { ChatBubbleState } from '../types.js';
+import type { InteractivePrompt } from '../providers/types/interactive-prompt.js';
 import { sanitizeSpawnEnv } from './spawn-env.js';
 export interface CliChatMessage {
     role: string;
@@ -26,8 +27,63 @@ export interface CliSessionStatus {
         message: string;
         buttons: string[];
     } | null;
+    /**
+     * Monotonic counter identifying which approval *entry* the current modal
+     * belongs to. Bumped by the FSM on every fresh waiting_approval entry.
+     * Consumers (e.g. auto-approval) use it to distinguish a genuinely new
+     * approval from the same approval re-observed across TUI paint flaps —
+     * two distinct approvals can carry identical message/button text, so the
+     * seq is the only reliable discriminator.
+     */
+    approvalEntrySeq?: number;
+    /**
+     * The approval entry seq that the engine's last resolveModal() handled. When
+     * `lastResolvedEntrySeq >= approvalEntrySeq` (and approvalEntrySeq > 0) it is positive
+     * evidence that the current/latest approval entry was resolved through ADHDev (auto-approve
+     * fire, dashboard / mesh_approve, or dev-cli-debug — all route through resolveModal). The
+     * completion finalization gate uses this to avoid confirming a waiting_approval→idle
+     * transition for which no resolution actually occurred (a false idle: the spec's text-based
+     * approval→idle rule tripped while the modal is still on screen).
+     */
+    lastResolvedEntrySeq?: number;
+    activeInteractivePrompt?: InteractivePrompt | null;
+    pendingOutboundCount?: number;
+    pendingOutboundMessages?: Array<{
+        id: string;
+        role: 'user';
+        content: string;
+        queuedAt: number;
+        source: string;
+    }>;
     errorMessage?: string;
     errorReason?: string;
+    providerSessionId?: string;
+    /**
+     * Spec/FSM adapters only (SpecCliAdapter): true once the driver has observed
+     * its first non-initial idle state — the prompt is genuinely drawn. The
+     * legacy ProviderCliAdapter never sets it (undefined). CliProviderInstance
+     * uses it to re-arm the queue-claim agent:ready on the first genuine ready,
+     * independent of the boot-time starting→idle one-shot (which is consumed too
+     * early for specs whose initial state already reports status 'idle', e.g.
+     * antigravity-cli — without the re-arm the worker never claims its queued
+     * task and the coordinator relaunch-loops).
+     */
+    fsmReadySeen?: boolean;
+    /**
+     * Timestamp (ms) of the most recent raw PTY output chunk. Advances on every
+     * byte the process emits, including tool/build output that produces no
+     * parsed assistant text. Liveness watchdogs use this to distinguish a real
+     * stall (no output at all) from an active turn whose assistant buffer is
+     * momentarily static while a tool runs.
+     */
+    lastOutputAt?: number;
+    /**
+     * Timestamp (ms) of the most recent *visible* terminal screen change.
+     * Stricter than lastOutputAt — only advances when the rendered screen
+     * content actually differs, so repeated keepalive bytes do not register as
+     * progress. Preferred liveness signal for the no-progress watchdog.
+     */
+    lastScreenChangeAt?: number;
     bufferState?: {
         responseBuffer?: {
             truncated: boolean;
@@ -59,6 +115,9 @@ export interface ParsedSession {
         buttons: string[];
     } | null;
     parsedStatus: string | null;
+    errorMessage?: string;
+    errorReason?: string;
+    providerSessionId?: string;
     transcriptAuthority?: 'provider' | 'daemon';
     coverage?: 'full' | 'tail' | 'current-turn';
 }
@@ -112,6 +171,10 @@ export interface CliScriptInput {
     rawBuffer: string;
     recentBuffer: string;
     screenText: string;
+    workspace?: string;
+    workingDir?: string;
+    providerSessionId?: string;
+    historySessionId?: string;
     screen: CliScreenSnapshot;
     bufferScreen: CliScreenSnapshot;
     recentScreen: CliScreenSnapshot;
@@ -121,6 +184,7 @@ export interface CliScriptInput {
     promptText?: string;
     settings?: Record<string, any>;
     args?: Record<string, any>;
+    spawnAt?: number;
 }
 export interface CliStatusInput {
     tail: string;
@@ -158,16 +222,26 @@ export interface CliProviderModule {
     binary: string;
     approvalKeys?: Record<number, string>;
     sendDelayMs?: number;
+    /** Wall-clock budget (ms) for a single provider script invocation. Default 50. Range 1..5000.
+     *  Exceeding the budget records `timedOut: true` on the invocation trace and emits a
+     *  throttled WARN — it does NOT abort the script (Node CJS can't interrupt sync code). */
+    scriptCallBudgetMs?: number;
     sendKey?: string;
     submitStrategy?: 'wait_for_echo' | 'immediate';
     /** Require the typed prompt to be visible on the PTY screen before sending Enter. */
     requirePromptEchoBeforeSubmit?: boolean;
     /** Allow sending another prompt while the CLI is still generating so users can intervene mid-turn. */
     allowInputDuringGeneration?: boolean;
+    /** When true, only transition to idle after the parsed transcript includes a final standard assistant message. */
+    requiresFinalAssistantBeforeIdle?: boolean;
+    /** When true, allow providers to augment stale snapshot data before parse. Reserved for future use. */
+    augmentStaleSnapshot?: boolean;
     /** When provider-owned, daemon treats provider parser output as canonical transcript authority. */
     transcriptAuthority?: 'provider' | 'daemon';
     /** Full context lets provider-owned parsers canonicalize retained history instead of daemon prefix stitching. */
     transcriptContext?: 'full' | 'tail';
+    /** v1 declarative tui block — used by CliScriptRunner to synthesize SDK helpers (declarativeDetectStatus, declarativeParseApproval). */
+    tui?: Record<string, unknown>;
     scripts?: CliScripts;
     spawn: {
         command: string;