@adhdev/daemon-core 0.9.82-rc.142 → 0.9.82-rc.144

package/src/boot/daemon-lifecycle.ts

@@ -38,6 +38,8 @@ import type { IdeProviderInstance } from '../providers/ide-provider-instance.js'
 import { createDefaultGitCommandServices } from '../git/git-commands.js';
 import { setupMeshEventForwarding } from '../mesh/mesh-events.js';
 import { loadMeshCoordinatorRegistry } from '../mesh/coordinator-registry.js';
+import { applyProcessHardening } from './process-hardening.js';
+import { installProviderProcessShim } from '../providers/sdk/v1/sandbox/require-whitelist.js';
 
 // ─── Init Config ───
 
@@ -130,6 +132,13 @@ export interface DaemonDevSupportOptions {
  *   8. Start instance ticking
  */
 export async function initDaemonComponents(config: DaemonInitConfig): Promise<DaemonComponents> {
+    // 0. Process-level hardening (must run before any provider script is loaded).
+    //    Freezes built-in prototypes (Object/Array/Function/String/Number/Boolean/Promise)
+    //    and shadows process.exit/kill/abort/binding/dlopen so provider-script callers
+    //    throw instead of killing the daemon. See ./process-hardening.ts for details.
+    applyProcessHardening();
+    installProviderProcessShim();
+
     // 1. Global log interceptor
     installGlobalInterceptor();
     loadMeshCoordinatorRegistry();
@@ -144,16 +153,11 @@ export async function initDaemonComponents(config: DaemonInitConfig): Promise<Da
         userDir: appConfig.providerDir,
     });
 
-    // If no upstream providers exist, fetch them first (blocking — critical for new users)
-    if (!disableUpstream && !providerLoader.hasUpstream()) {
-        LOG.info('Provider', 'No upstream providers found — downloading from GitHub...');
-        try {
-            await providerLoader.fetchLatest();
-        } catch (e: any) {
-            LOG.warn('Provider', `⚠ Failed to fetch providers: ${e?.message}`);
-        }
-    }
-
+    // Boot-time auto-sync is intentionally disabled. The user picks which
+    // providers to install via the dashboard onboarding / Providers tab; the
+    // daemon ships empty and only contains what the user explicitly installs.
+    // Manual sync is still available via the install / check_provider_updates
+    // commands (and the REST endpoint at /api/v1/providers/updates).
     providerLoader.loadAll();
     providerLoader.registerToDetector();
 

package/src/boot/process-hardening.ts

@@ -0,0 +1,89 @@
+/**
+ * Process-level hardening — boot-time mitigations against provider scripts.
+ *
+ * Provider scripts run in-process (see providers/sdk/v1/sandbox/README-design.ts).
+ * The require() whitelist (sandbox/require-whitelist.ts) blocks the obvious
+ * attack surfaces (no `child_process.exec`, no `fs.writeFile`, no `net`, etc.)
+ * but a malicious or buggy script can still:
+ *
+ *   1. Pollute Object.prototype to influence the daemon's downstream consumers
+ *      (e.g. `Object.prototype.toString = () => '...'` makes every untagged
+ *      object stringify to that value across the whole process).
+ *   2. Mutate Array/Function/String prototypes for similar effect.
+ *   3. Call `process.exit()` / `process.kill()` to kill the daemon.
+ *
+ * Sandbox isolation (isolated-vm) is the proper fix but has a real perf cost
+ * and a real marshalling-complexity cost. As a cheaper layer we just freeze
+ * the built-in prototypes at boot, which is irreversible and catches every
+ * prototype-pollution variant for the lifetime of the process.
+ *
+ * `applyProcessHardening()` is idempotent — calling it twice is a no-op the
+ * second time. The function intentionally swallows any "cannot redefine
+ * property" errors that would arise if some upstream code already froze
+ * the same prototype: the post-condition (prototype is frozen) is satisfied
+ * either way.
+ *
+ * Trade-offs:
+ *   - Read-only access to prototype methods (`Object.prototype.hasOwnProperty.call`,
+ *     `Array.prototype.slice.call`, etc.) is unaffected — only writes throw.
+ *   - Some older npm libraries patch Array.prototype or Function.prototype at
+ *     import time. If a daemon-core dep does this, the import will throw. The
+ *     daemon-core vitest suite is the canonical regression check for this.
+ *   - We deliberately do NOT freeze RegExp.prototype, Error.prototype, Map/Set
+ *     prototypes, or Date.prototype because at least one of those tends to be
+ *     mutated by mainstream test/runtime libs and the value of freezing them
+ *     is low (no useful prototype-pollution attack surface).
+ */
+
+let _hardened = false;
+
+/** Prototypes that get frozen at boot. */
+const HARDENED_PROTOS: Array<{ name: string; proto: object }> = [
+    { name: 'Object', proto: Object.prototype },
+    { name: 'Array', proto: Array.prototype },
+    { name: 'Function', proto: Function.prototype },
+    { name: 'String', proto: String.prototype },
+    { name: 'Number', proto: Number.prototype },
+    { name: 'Boolean', proto: Boolean.prototype },
+    { name: 'Promise', proto: Promise.prototype },
+];
+
+/**
+ * Freeze the canonical built-in prototypes so provider scripts (and anything
+ * else running in this process) cannot mutate them. Idempotent.
+ *
+ * Returns the list of prototype names that were newly frozen — primarily for
+ * tests / observability. Already-frozen prototypes are not re-reported.
+ */
+export function applyProcessHardening(): string[] {
+    if (_hardened) return [];
+    _hardened = true;
+
+    const newlyFrozen: string[] = [];
+    for (const entry of HARDENED_PROTOS) {
+        if (Object.isFrozen(entry.proto)) continue;
+        try {
+            Object.freeze(entry.proto);
+            newlyFrozen.push(entry.name);
+        } catch {
+            // Some host/runtime combinations refuse to freeze a built-in
+            // prototype (e.g. it has a non-configurable accessor). We treat
+            // this as best-effort — log nothing here (logger not guaranteed
+            // to be initialized this early) and move on. Subsequent reads
+            // of `Object.isFrozen(proto)` will reveal the gap.
+        }
+    }
+    return newlyFrozen;
+}
+
+/** For tests only — clears the internal "already hardened" flag. The
+ *  prototypes themselves cannot be un-frozen, so this is mostly useful for
+ *  testing the idempotency guard. */
+export function _resetProcessHardeningForTest(): void {
+    _hardened = false;
+}
+
+/** For tests only — peek at the hardened state. */
+export function _isProcessHardened(): boolean {
+    return _hardened;
+}

package/src/cli-adapters/cli-script-runner.ts

@@ -20,30 +20,240 @@ import {
     type CliStatusInput,
     type ParsedSession,
 } from './provider-cli-shared.js';
+import { buildDetectStatusFromTui } from '../providers/sdk/v1/builders/cli/detect-status.js';
+import { buildParseApprovalFromTui } from '../providers/sdk/v1/builders/cli/parse-approval.js';
+import { buildParseSessionFromTui, normalizeMessageIdentity } from '../providers/sdk/v1/builders/cli/parse-session.js';
+
+/**
+ * Capability bag injected into provider scripts as the third argument.
+ *
+ * v1 manifests declare line-shape recognition in their `tui` block — for
+ * those providers, the daemon builds the canonical (input → verdict)
+ * functions from the manifest and hands them to the script via `sdk`. The
+ * script's job is then only to wrap that verdict with stateful logic
+ * (idle-hold timers, frame counting, etc.) that can't be expressed
+ * declaratively.
+ *
+ * Without these, the extended-tier overrides bail with `return 'idle'`
+ * and the session sticks in generating forever. That's the regression
+ * we hit on codex-cli during the registry-install path.
+ */
+interface CliScriptSdk {
+    declarativeDetectStatus?: (input: CliStatusInput) => string | null;
+    declarativeParseApproval?: (input: CliApprovalInput) => { message: string; buttons: string[] } | null;
+}
+
+/**
+ * One entry per script invocation, kept in a ring buffer so debug
+ * tooling can answer "what did the script see, and what did it return?"
+ * without having to re-run the daemon with custom logs. This is the
+ * trace that would have answered the codex-cli #102 regression in one
+ * pass instead of a dozen guesses.
+ *
+ * Body fields are bounded: input is reduced to a small summary (sizes
+ * + a salted hash + the first few normalized chars of screenText), and
+ * result is JSON-serialized then capped. Full PTY frames are NOT
+ * captured here — they live in CliBufferSnapshot and are exposed by
+ * the chat debug bundle separately.
+ */
+export interface CliScriptInvocationTrace {
+    at: number;                       // Date.now()
+    scriptName: string;
+    arity: number;
+    inputSummary: {
+        screenTextLen: number;
+        rawBufferLen: number;
+        tailLen: number;
+        isWaitingForResponse?: boolean;
+        screenTextHead?: string;       // first 200 chars of screenText (post-strip)
+    };
+    ok: boolean;
+    elapsedUs: number;
+    resultSummary?: string;            // JSON.stringify(result).slice(0, 400)
+    error?: string;
+    /**
+     * True when the invocation's elapsed time exceeded the runner's
+     * `scriptCallBudgetMs`. The script is NOT aborted (Node CJS can't
+     * interrupt sync code without a worker thread) — this flag plus the
+     * trace ring lets an operator identify which provider is hanging the
+     * settle loop. A throttled WARN is emitted alongside.
+     */
+    timedOut?: boolean;
+}
+
+const TRACE_RING_CAPACITY = 64;
+
+/** Default per-invocation wall-clock budget (ms) when the manifest omits one. */
+const DEFAULT_SCRIPT_CALL_BUDGET_MS = 50;
+
+/** Minimum interval between repeated budget-violation WARNs per script. */
+const BUDGET_WARN_THROTTLE_MS = 30_000;
+
+function summarizeInput(input: any): CliScriptInvocationTrace['inputSummary'] {
+    const screenText = typeof input?.screenText === 'string' ? input.screenText : '';
+    const rawBuffer = typeof input?.rawBuffer === 'string' ? input.rawBuffer : '';
+    const tail = typeof input?.tail === 'string' ? input.tail : '';
+    return {
+        screenTextLen: screenText.length,
+        rawBufferLen: rawBuffer.length,
+        tailLen: tail.length,
+        isWaitingForResponse: typeof input?.isWaitingForResponse === 'boolean' ? input.isWaitingForResponse : undefined,
+        screenTextHead: screenText ? screenText.slice(0, 200) : undefined,
+    };
+}
+
+function summarizeResult(result: unknown): string {
+    try {
+        const json = JSON.stringify(result);
+        return json && json.length > 400 ? `${json.slice(0, 400)}…[truncated ${json.length - 400}]` : (json ?? 'undefined');
+    } catch (e: any) {
+        return `<unserializable: ${e?.message || e}>`;
+    }
+}
 
 export class CliScriptRunner {
     private scripts: CliScripts = {};
     private scriptState: unknown = null;
     private _parseErrorMessage: string | null = null;
     private readonly cliType: string;
+    private sdk: CliScriptSdk = {};
+    private invocationTrace: CliScriptInvocationTrace[] = [];
+    /** Per-invocation wall-clock budget (ms). Configurable via setScriptCallBudget. */
+    private scriptCallBudgetMs = DEFAULT_SCRIPT_CALL_BUDGET_MS;
+    /** Last WARN emit time per scriptName, used to throttle repeated budget violations. */
+    private lastBudgetWarnAt = new Map<string, number>();
 
     constructor(cliType: string) {
         this.cliType = cliType;
     }
 
+    /** Returns the most-recent script invocation traces (oldest → newest). */
+    getInvocationTrace(): CliScriptInvocationTrace[] {
+        return this.invocationTrace.slice();
+    }
+
+    /** Clear the trace ring — used by tests and after PTY reset. */
+    clearInvocationTrace(): void {
+        this.invocationTrace = [];
+    }
+
+    /**
+     * Configure the wall-clock budget (ms) applied to every script invocation.
+     *
+     * Out-of-range or non-finite values are clamped to [1, 5000] and the
+     * default (50ms) is used as a fallback. The budget is enforced per-call,
+     * not aggregated — it does not abort a runaway script (Node CJS cannot
+     * interrupt synchronous code without a worker thread). Instead, an
+     * exceeded budget flags the trace entry with `timedOut: true` and emits
+     * a throttled WARN naming the script and elapsed time so an operator
+     * can identify which provider is hanging the settle loop.
+     */
+    setScriptCallBudget(ms: number): void {
+        if (typeof ms !== 'number' || !Number.isFinite(ms)) {
+            this.scriptCallBudgetMs = DEFAULT_SCRIPT_CALL_BUDGET_MS;
+            return;
+        }
+        const clamped = Math.max(1, Math.min(5000, Math.floor(ms)));
+        this.scriptCallBudgetMs = clamped;
+    }
+
+    /** Test/debug accessor — current effective budget in ms. */
+    getScriptCallBudgetMs(): number {
+        return this.scriptCallBudgetMs;
+    }
+
+    private recordTrace(entry: CliScriptInvocationTrace): void {
+        this.invocationTrace.push(entry);
+        if (this.invocationTrace.length > TRACE_RING_CAPACITY) {
+            this.invocationTrace.splice(0, this.invocationTrace.length - TRACE_RING_CAPACITY);
+        }
+    }
+
     // ─── Script lifecycle ─────────────────────────────
 
-    setScripts(scripts: CliScripts): void {
-        this.scripts = scripts;
+    setScripts(scripts: CliScripts, providerTui?: Record<string, unknown> | undefined): void {
+        // SDK is built first so the synth functions below have access to it.
+        this.sdk = this.buildSdk(providerTui);
+
+        // Fill missing scripts from the SDK synth. This is the heart of the
+        // declarative model: a v1 manifest with a complete tui block (spinner
+        // + modal + settledPrompt + transcriptPty) gets working detectStatus
+        // / parseApproval / parseSession functions for free, no provider .js
+        // required. Providers that supply their own override always win
+        // because we don't overwrite when scripts[name] is already a function.
+        const tui = providerTui as Record<string, unknown> | undefined;
+        const enriched: CliScripts = { ...scripts };
+
+        if (typeof enriched.detectStatus !== 'function' && this.sdk.declarativeDetectStatus) {
+            enriched.detectStatus = this.sdk.declarativeDetectStatus as any;
+        }
+        if (typeof enriched.parseApproval !== 'function' && this.sdk.declarativeParseApproval) {
+            enriched.parseApproval = this.sdk.declarativeParseApproval as any;
+        }
+        if (typeof enriched.parseSession !== 'function' && tui?.transcriptPty) {
+            try {
+                const synth = buildParseSessionFromTui({
+                    spinner: tui.spinner,
+                    settledPrompt: tui.settledPrompt,
+                    modal: tui.modal as any,
+                    dispatchOrder: tui.dispatchOrder,
+                    transcriptPty: tui.transcriptPty as any,
+                });
+                // Wrap to apply identity stamps the daemon downstream expects.
+                enriched.parseSession = ((input: any) => {
+                    const out = synth(input);
+                    return {
+                        ...out,
+                        messages: normalizeMessageIdentity(out.messages, out.status ?? 'idle'),
+                    };
+                }) as any;
+            } catch (e: any) {
+                LOG.warn('CLI', `[${this.cliType}] buildParseSessionFromTui failed: ${e?.message || e}`);
+            }
+        }
+
+        this.scripts = enriched;
         this._parseErrorMessage = null;
-        this.scriptState = typeof scripts.createState === 'function'
-            ? (scripts.createState() ?? null)
+        this.scriptState = typeof enriched.createState === 'function'
+            ? (enriched.createState() ?? null)
             : null;
     }
 
+    private buildSdk(providerTui: Record<string, unknown> | undefined): CliScriptSdk {
+        const tui = providerTui as Record<string, unknown> | undefined;
+        if (!tui) return {};
+        const sdk: CliScriptSdk = {};
+        // Build declarativeDetectStatus from the manifest tui block. The
+        // builder requires at least spinner OR settledPrompt OR modal; if
+        // none are present we skip silently so a non-tui manifest doesn't
+        // throw at boot time.
+        if (tui.spinner || tui.settledPrompt || tui.modal || tui.dispatchOrder) {
+            try {
+                sdk.declarativeDetectStatus = buildDetectStatusFromTui({
+                    spinner: tui.spinner as any,
+                    settledPrompt: tui.settledPrompt as any,
+                    modal: tui.modal as any,
+                    dispatchOrder: tui.dispatchOrder as any,
+                }) as unknown as (input: CliStatusInput) => string | null;
+            } catch (e: any) {
+                LOG.warn('CLI', `[${this.cliType}] buildDetectStatusFromTui failed: ${e?.message || e}`);
+            }
+        }
+        if (tui.modal) {
+            try {
+                sdk.declarativeParseApproval = buildParseApprovalFromTui(tui.modal as any) as unknown as (input: CliApprovalInput) => { message: string; buttons: string[] } | null;
+            } catch (e: any) {
+                LOG.warn('CLI', `[${this.cliType}] buildParseApprovalFromTui failed: ${e?.message || e}`);
+            }
+        }
+        return sdk;
+    }
+
     /** Reset per-session state — called when the PTY process exits. */
     resetSessionState(): void {
         this.scriptState = null;
+        this.invocationTrace = [];
+        this.lastBudgetWarnAt.clear();
     }
 
     // ─── Script access (for reflection and test patching) ────────────────────
@@ -81,7 +291,7 @@ export class CliScriptRunner {
     detectStatus(input: CliStatusInput): string | null {
         if (!this.scripts.detectStatus) return null;
         try {
-            return this.invoke<string | null>(this.scripts.detectStatus, input);
+            return this.invoke<string | null>('detectStatus', this.scripts.detectStatus, input);
         } catch (e: any) {
             LOG.warn('CLI', `[${this.cliType}] detectStatus error: ${e?.message || e}`);
             return null;
@@ -94,6 +304,7 @@ export class CliScriptRunner {
         if (!this.scripts.parseApproval) return null;
         try {
             return this.invoke<{ message: string; buttons: string[] } | null>(
+                'parseApproval',
                 this.scripts.parseApproval,
                 input,
             );
@@ -111,7 +322,7 @@ export class CliScriptRunner {
             return null;
         }
         try {
-            const result = this.invoke<ParsedSession | null>(this.scripts.parseSession, input);
+            const result = this.invoke<ParsedSession | null>('parseSession', this.scripts.parseSession, input);
             this._parseErrorMessage = null;
             return result && typeof result === 'object' ? result : null;
         } catch (e: any) {
@@ -130,16 +341,81 @@ export class CliScriptRunner {
         if (typeof fn !== 'function') {
             throw new Error(`CLI script '${name}' not available`);
         }
-        return this.invoke(fn, input);
+        return this.invoke(name, fn, input);
     }
 
     // ─── Internal ─────────────────────────────────────
 
-    private invoke<T>(fn: Function, input: any): T {
-        const hasStateFactory = typeof this.scripts.createState === 'function';
-        const expectsState = hasStateFactory || this.scriptState !== null || fn.length >= 2;
-        return expectsState
-            ? (fn as (state: unknown, input: any) => T)(this.scriptState, input)
-            : (fn as (input: any) => T)(input);
+    private invoke<T>(scriptName: string, fn: Function, input: any): T {
+        // Pick the call shape from fn.length so each script gets exactly the
+        // args its signature declares:
+        //   (input)             — v0 single-arg scripts
+        //   (state, input)      — v0 stateful scripts that opt in via createState()
+        //   (state, input, sdk) — v1 extended-tier overrides that consume the SDK
+        const arity = fn.length;
+        const startedAt = Date.now();
+        const startedHr = typeof process !== 'undefined' && typeof process.hrtime === 'function'
+            ? process.hrtime.bigint()
+            : null;
+        let result: T;
+        try {
+            if (arity >= 3) {
+                result = (fn as (state: unknown, input: any, sdk: CliScriptSdk) => T)(this.scriptState, input, this.sdk);
+            } else if (arity === 2) {
+                result = (fn as (state: unknown, input: any) => T)(this.scriptState, input);
+            } else {
+                result = (fn as (input: any) => T)(input);
+            }
+            const elapsedUs = startedHr ? Number((process.hrtime.bigint() - startedHr) / 1000n) : 0;
+            const timedOut = this.checkBudget(scriptName, elapsedUs);
+            this.recordTrace({
+                at: startedAt,
+                scriptName,
+                arity,
+                inputSummary: summarizeInput(input),
+                ok: true,
+                elapsedUs,
+                resultSummary: summarizeResult(result),
+                ...(timedOut ? { timedOut: true } : {}),
+            });
+            return result;
+        } catch (e: any) {
+            const elapsedUs = startedHr ? Number((process.hrtime.bigint() - startedHr) / 1000n) : 0;
+            const timedOut = this.checkBudget(scriptName, elapsedUs);
+            this.recordTrace({
+                at: startedAt,
+                scriptName,
+                arity,
+                inputSummary: summarizeInput(input),
+                ok: false,
+                elapsedUs,
+                error: e?.message ? String(e.message).slice(0, 400) : String(e).slice(0, 400),
+                ...(timedOut ? { timedOut: true } : {}),
+            });
+            throw e;
+        }
+    }
+
+    /**
+     * Returns true when `elapsedUs` exceeded the configured budget. On the
+     * first violation per script (or after the throttle window expires) we
+     * emit a single WARN so the operator learns which provider is slow.
+     *
+     * We deliberately throttle per-scriptName so a chronically-slow
+     * detectStatus doesn't spam the log on every PTY frame settle.
+     */
+    private checkBudget(scriptName: string, elapsedUs: number): boolean {
+        const budgetUs = this.scriptCallBudgetMs * 1000;
+        if (elapsedUs <= budgetUs) return false;
+        const now = Date.now();
+        const last = this.lastBudgetWarnAt.get(scriptName) ?? 0;
+        if (now - last >= BUDGET_WARN_THROTTLE_MS) {
+            this.lastBudgetWarnAt.set(scriptName, now);
+            LOG.warn(
+                'CLI',
+                `[${this.cliType}] script ${scriptName} took ${elapsedUs}us, budget ${budgetUs}us`,
+            );
+        }
+        return true;
     }
 }

package/src/cli-adapters/cli-state-engine.ts

@@ -986,11 +986,14 @@ export class CliStateEngine {
     }
 
     private shouldDeferFinishForTranscript(parsed: any): boolean {
-        // Support both explicit flag and legacy codex-cli type check
-        // Also check transport.cliType to support tests that patch adapter.cliType directly
-        const effectiveType = this.transport.cliType ?? this.provider.type;
-        const requiresFinalAssistant = !!this.provider.requiresFinalAssistantBeforeIdle
-            || effectiveType === 'codex-cli';
+        // Honor only the explicit manifest opt-in. We used to also hard-code
+        // codex-cli here, but that left codex sessions wedged in `generating`
+        // whenever the PTY parser or native transcript missed the final
+        // assistant line — a much more common failure mode than the original
+        // background-tool race this was meant to guard against. If a provider
+        // really needs the gate, the manifest can set
+        // `requiresFinalAssistantBeforeIdle: true`.
+        const requiresFinalAssistant = !!this.provider.requiresFinalAssistantBeforeIdle;
         if (!requiresFinalAssistant) return false;
         if (!this.isWaitingForResponse || !this.currentTurnScope || this.hasActionableApproval()) return false;
         const parsedStatus = typeof parsed?.status === 'string' ? parsed.status.trim() : '';

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

@@ -179,6 +179,29 @@ export class ProviderCliAdapter implements CliAdapter {
     private readonly runner: CliScriptRunner;
     /** @deprecated use runner.cliScripts for direct script access */
     get cliScripts(): CliScripts { return this.runner.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() {
+        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 */
@@ -367,8 +390,19 @@ export class ProviderCliAdapter implements CliAdapter {
             resolvedConfig.timeouts,
         );
 
-        // Scripts delegated to CliScriptRunner — adapter stays as transport
-        this.runner.setScripts(provider.scripts || {});
+        // 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(', ')}]`);

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

@@ -158,6 +158,10 @@ 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. */
@@ -172,6 +176,8 @@ export interface CliProviderModule {
     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;

package/src/commands/chat-commands.ts

@@ -1677,6 +1677,9 @@ export async function handleGetChatDebugBundle(h: CommandHelpers, args: any): Pr
             ready: typeof adapter.isReady === 'function' ? adapter.isReady() : undefined,
             processing: typeof adapter.isProcessing === 'function' ? adapter.isProcessing() : undefined,
             debugSnapshot: adapterDebugSnapshot,
+            scriptInvocationTrace: typeof (adapter as any).getScriptInvocationTrace === 'function'
+                ? (adapter as any).getScriptInvocationTrace()
+                : undefined,
         } : null,
         readChat,
         frontend: args?.frontendSnapshot && typeof args.frontendSnapshot === 'object' ? args.frontendSnapshot : null,
@@ -1858,7 +1861,25 @@ export async function handleChatHistory(h: CommandHelpers, args: any): Promise<C
 }
 
 export async function handleReadChat(h: CommandHelpers, args: any): Promise<CommandResult> {
-    const provider = h.getProvider(args?.agentType || args?.providerType);
+    // Resolve provider in order: explicit agentType/providerType > registered session.
+    // Without this fallback, callers that only have a sessionId (e.g. a chat tail
+    // controller that just got handed a session ID over WS) get an empty result
+    // because getProvider(undefined) returns undefined and the rest of the pipeline
+    // bails. This makes the UI look like the session "disappeared".
+    let providerHint: string | undefined = args?.agentType || args?.providerType;
+    if (!providerHint) {
+        const targetSessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim() : '';
+        if (targetSessionId) {
+            const session = (h.ctx as any)?.sessionRegistry?.get?.(targetSessionId);
+            if (session && typeof session.providerType === 'string') {
+                providerHint = session.providerType;
+            }
+        }
+        if (!providerHint && h.currentSession?.providerType) {
+            providerHint = h.currentSession.providerType;
+        }
+    }
+    const provider = h.getProvider(providerHint);
     const transport = getTargetTransport(h, provider);
     const historySessionId = getHistorySessionId(h, args);