@adhdev/daemon-core 0.9.82-rc.48 → 0.9.82-rc.481

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

@@ -0,0 +1,220 @@
+/**
+ * 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;
+    /**
+     * Poll-driven static-idle confirm (D4). A hosted CLI session (e.g. a fresh
+     * antigravity coordinator) whose boot banner drove the FSM into 'generating'
+     * can then sit at a STATIC ready prompt emitting no further PTY output. Every
+     * output-driven busy→idle re-eval (handleOutput/resolveStartupState/settle)
+     * is starved because there is no new output, and the startup-settle loop has
+     * hard-stopped past spawnAt+10s — so currentStatus stays frozen at generating
+     * and the dashboard disables Send. This is the ONE path that can release that
+     * wedge from the read-only status poll.
+     *
+     * Safety: this must NEVER flip a real generating turn to idle. The gate is
+     * done by the caller (getStatus) reusing resolveStartupState's proven
+     * predicates: no recent PTY output for a grace window, runDetectStatus of the
+     * current screen === 'idle', and no active/parsed modal. Here we add the
+     * final structural guard: there must be NO active turn scope. A live user
+     * turn always carries a currentTurnScope (set in onTurnStarted), so this only
+     * releases the boot-banner wedge and the post-turn static-idle case, both of
+     * which have already had their scope nulled. Returns true when it transitioned.
+     */
+    confirmPollStaticIdle(reason: string): boolean;
+    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[];