@adhdev/daemon-core 0.9.82-rc.466 → 0.9.82-rc.468

package/src/providers/cli-provider-instance.ts

@@ -50,6 +50,23 @@ import {
     getForcedNewSessionScriptName,
     waitForCliAdapterReady,
 } from './cli-provider-status-helpers.js';
+import {
+    STATUS_HYDRATION_TAIL_LIMIT,
+    COMPLETED_FINALIZATION_RETRY_MS,
+    COMPLETED_FINALIZATION_MAX_WAIT_MS,
+    NATIVE_HISTORY_MESH_IDLE_SETTLE_MS,
+    USER_INPUT_ACK_DEDUP_WINDOW_MS,
+    STARTUP_GRACE_IDLE_COLLAPSE_WINDOW_MS,
+    TERMINAL_MESH_EVENTS,
+} from './cli-provider-instance-types.js';
+import type {
+    CompletedDebouncePending,
+    CompletedFinalizationBlock,
+    CompletionFinalAssistantEvidence,
+    ExternalTranscriptProbe,
+} from './cli-provider-instance-types.js';
+import { mergeConversationMessages, buildExternalTranscriptProbe } from './cli-provider-transcript-merge.js';
+import { getEffectDedupKey, formatApprovalRequestMessage, formatMarkerTimestamp } from './cli-provider-effect-format.js';
 
 // Re-export moved public symbols so existing importers (index.ts, tests) keep
 // their `./cli-provider-instance.js` path. Pure move — no behavior change.
@@ -61,133 +78,15 @@ export {
     waitForCliAdapterReady,
 } from './cli-provider-status-helpers.js';
 
-// Status snapshots only ever surface the newest messages: the cloud 'live'
-// profile drops chat messages entirely (loaded lazily via read_chat on
-// subscribe) and the 'full' profile caps activeChat.messages to the last 60
-// (see status/normalize.ts). Unread/completion markers walk only the tail.
-// So getState()'s saved-history hydration — which runs once per resume/manual
-// CLI session on every status report — must read only a bounded tail, not the
-// entire transcript. A full MAX_SAFE_INTEGER read here makes the initial
-// status report O(transcript) × N(sessions), which is the real cold first-
-// connection bottleneck on chat-heavy machines. The window comfortably exceeds
-// the 60-message snapshot cap so dedup/collapse at the boundary stays stable.
-const STATUS_HYDRATION_TAIL_LIMIT = 200;
-
-type CompletedDebouncePending = {
-    chatTitle: string;
-    duration: number;
-    timestamp: number;
-    firstObservedAt: number;
-    previousStatus: string;
-    loggedBlockReason?: string;
-    loggedTranscriptProbe?: boolean;
-    transcriptProbeHistory?: ExternalTranscriptProbe[];
-    // ARCH-REFACTOR R1: the taskId of the turn that produced this (debounced) completion,
-    // captured SYNCHRONOUSLY at the generating→idle transition. The actual completion
-    // event is emitted later by the debounce flush, by which point a follow-up task may
-    // already have started its own turn and overwritten engine.currentTurnTaskId — so the
-    // id must be snapshotted here, not re-read at flush time.
-    taskId?: string;
-    // NOTIF Defect-B: the wall-clock start of the turn that produced this (debounced)
-    // completion, snapshotted SYNCHRONOUSLY at the generating→idle transition (same
-    // reason as taskId — a follow-up turn moves engine.currentTurnStartedAt). The
-    // completion's finalSummary is turn-scoped to bubbles at/after this instant so a
-    // debounce that flushes before the producing turn's final assistant bubble lands
-    // in the native transcript never echoes the PRIOR task's last bubble.
-    turnStartedAt?: number;
-    // FALSE-IDLE continuity: the busyEpoch value at the instant this pending was armed.
-    // The flush guard requires this.busyEpoch to still equal this — proving no busy
-    // phase (generating/waiting_approval) opened since arming. A momentary busy→idle
-    // blip in an inter-approval valley bumps busyEpoch, so a completion armed before
-    // the blip is cancelled at flush instead of emitting a stale mid-turn summary.
-    busyEpochAtArm?: number;
-    // FALSE-IDLE continuity: the adapter's raw PTY lastOutputAt at arm time. New PTY
-    // output after arming means the session was not continuously idle through the
-    // settle window (the agent kept printing), so the completion is cancelled.
-    lastOutputAtArm?: number;
-};
-
-type CompletedFinalizationBlock = {
-    reason: string;
-    terminal?: boolean;
-    allowTimeout?: boolean;
-    // (SETTLE-VALLEY) When set, suppress the CANON-C decoupled-immediate emit for this
-    // missing_final_assistant block and HOLD (retry up to COMPLETED_FINALIZATION_MAX_WAIT_MS)
-    // until the native transcript's final assistant turn arrives (block clears → genuine emit)
-    // or the worker resumes (resume guard cancels). Set only for the inter-approval idle valley
-    // of a native-history mesh worker, where an immediate weak emit would freeze a truncated
-    // preamble summary (evidenceLevel=insufficient) into the append-only ledger before the
-    // worker's next approval turn resumes. Independent of valley length.
-    holdForTranscript?: boolean;
-};
-
-type CompletionFinalAssistantEvidence = {
-    present: boolean;
-    messages: unknown[];
-    source: 'parsed' | 'external-native' | 'unavailable';
-};
-
-type ExternalTranscriptProbe = {
-    readAt: number;
-    msgCount: number;
-    lastRole: string | null;
-    lastKind: string | null;
-    contentLen: number;
-    sourcePath: string | null;
-    sourceMtimeMs: number | null;
-    mtimeAgeMs: number | null;
-};
-
-const COMPLETED_FINALIZATION_RETRY_MS = 1000;
-const COMPLETED_FINALIZATION_MAX_WAIT_MS = 30_000;
-// (FALSEIDLE-BGCHILD-a) Minimum generating→idle settle window for native-history mesh worker
-// sessions. Native-history providers (e.g. claude-cli) normally flush the completion with
-// flushDelay=0 — the transcript is authoritative, so there is no reason to wait. But a worker
-// turn that spawns a BACKGROUND child (e.g. `npm test &`, a backgrounded Bash tool) can paint
-// a burst of child output, fall quiet, and have the screen parser read a PRIOR/intermediate
-// standard assistant as if the turn were done — firing a false idle while the agent is in fact
-// still generating (e.g. mid-commit). With flushDelay=0 there is no window for the resume guard
-// in flushCompletedDebounceIfFinalized (latestVisibleStatus !== 'idle' → cancel) to observe the
-// agent picking the turn back up. A short non-zero settle window restores that resume guard for
-// mesh workers without delaying genuinely-finished turns beyond this bound. Scoped to mesh
-// worker sessions so interactive native-history sessions keep the immediate flush.
-// 4000ms (was 1500): live measurement showed the completion event can fire 1.6–3s
-// BEFORE the worker's final-assistant turn lands in the transcript on a natural
-// generating→idle completion (no approval modal), freezing a prior intermediate
-// bubble as finalSummary (evidenceLevel=insufficient). The 68a3c324 waiting_approval
-// hold only covers the approval-resolved valley; widening this settle window to 4000ms
-// covers that race AND the ~3s waiting_approval valley within the settle bound.
-const NATIVE_HISTORY_MESH_IDLE_SETTLE_MS = 4000;
-// TASKBUBBLE-DUP: window during which an identical user-input ack (same trimmed
-// content on the same instance) is treated as a redelivery of one dispatch and
-// suppressed from the chat transcript. Matches the coordinator-side
-// DUPLICATE_DISPATCH_WINDOW_MS (mesh-tools) so the daemon's bubble-level guard
-// covers the same retry horizon as the MCP-level dispatch dedup.
-const USER_INPUT_ACK_DEDUP_WINDOW_MS = 60_000;
-// GENERATING-BOUNDARY (R4c): window — measured from the startup-grace COLLAPSE moment
-// (startupGraceCollapseAt), not boot — inside which a "first turn that ran+completed
-// without the FSM ever observing a 'generating' frame" is attributed to the startup-grace
-// collapse and synthesized (reason 'startup_grace_idle_turn_collapse').
-// The spec's startup-grace exit is elapsed_ms=8000, so the FSM spends ~8s in 'starting'
-// before collapsing to idle; a turn can be dispatched a few seconds AFTER that collapse
-// (the live R4b miss: collapse at boot+8s, dispatch at boot+12.4s — already past a 12s
-// boot-anchored window before the turn even started). Anchoring on the collapse moment
-// covers dispatch-delay; R4d additionally anchors on the turn-START moment
-// (engine.currentTurnStartedAt) so a non-trivial turn-DURATION cannot push the completion
-// past a now-anchored window (the live rc.405 Probe2 miss). The strong discriminator is
-// generatingStartedAt===0 (generating was never observed) AND a started-but-finished turn
-// — the window only keeps the synthesized reason honest and scopes the synthesis to the
-// boot collapse, so a much-later unobservably-fast turn is not mislabelled a startup collapse.
-const STARTUP_GRACE_IDLE_COLLAPSE_WINDOW_MS = 12_000;
-
-/** Events that signal a dispatched mesh task has reached a terminal state.
- *  Detach the mesh assignment after emitting one of these so the worker's
- *  next unrelated turn doesn't impersonate another completion. */
-const TERMINAL_MESH_EVENTS = new Set([
-    'agent:generating_completed',
-    'agent:stopped',
-    'agent:ready',
-]);
+/**
+ * The auto-approve settle-gate identity signature: the modal's question line plus
+ * the NORMALIZED affirmative label, no volatile counters or raw button set. Shared
+ * by the fire path (maybeAutoApproveStatus) and the mask-stall nudge so both compare
+ * the SAME identity the settle clock tracks (AUTOAPPROVE-SETTLE-FLAP).
+ */
+function approvalModalSignature(message: unknown, affirmativeAnchor: string): string {
+    return [typeof message === 'string' ? message.trim() : '', affirmativeAnchor].join('::');
+}
 
 export class CliProviderInstance implements ProviderInstance {
     readonly type: string;
@@ -480,7 +379,7 @@ export class CliProviderInstance implements ProviderInstance {
             const resumedAt = Date.now();
             this.historyWriter.appendSystemMarker(
                 this.type,
-                `Resumed saved session at ${this.formatMarkerTimestamp(resumedAt)}`,
+                `Resumed saved session at ${formatMarkerTimestamp(resumedAt)}`,
                 {
                     instanceId: this.instanceId,
                     historySessionId: this.providerSessionId,
@@ -649,7 +548,7 @@ export class CliProviderInstance implements ProviderInstance {
                 ? parsedMessages.slice(-historyMessageCount)
                 : [];
         }
-        const mergedMessages = this.mergeConversationMessages(parsedMessages);
+        const mergedMessages = mergeConversationMessages(this.runtimeMessages, parsedMessages);
         const canonicalBackedHistory = this.shouldHydrateExistingProviderHistory()
             ? this.syncCanonicalSavedHistoryIfNeeded()
             : false;
@@ -1257,23 +1156,6 @@ export class CliProviderInstance implements ProviderInstance {
         return true;
     }
 
-    private buildExternalTranscriptProbe(messages: unknown[], sourcePath?: string, sourceMtimeMs?: number): ExternalTranscriptProbe {
-        const visibleMessages = messages.filter((message: any) => isUserFacingChatMessage(message as ChatMessage));
-        const lastVisible = visibleMessages[visibleMessages.length - 1] as ChatMessage | undefined;
-        const readAt = Date.now();
-        const mtimeMs = Number(sourceMtimeMs) || 0;
-        return {
-            readAt,
-            msgCount: messages.length,
-            lastRole: typeof lastVisible?.role === 'string' ? lastVisible.role.trim().toLowerCase() : null,
-            lastKind: typeof (lastVisible as any)?.kind === 'string' ? (lastVisible as any).kind : null,
-            contentLen: lastVisible ? flattenContent(lastVisible.content).trim().length : 0,
-            sourcePath: typeof sourcePath === 'string' && sourcePath ? sourcePath : null,
-            sourceMtimeMs: mtimeMs || null,
-            mtimeAgeMs: mtimeMs ? Math.max(0, readAt - mtimeMs) : null,
-        };
-    }
-
     private recordPendingTranscriptProbe(pending: CompletedDebouncePending): ExternalTranscriptProbe | null {
         const probe = this.lastExternalCompletionProbe;
         if (!probe) return null;
@@ -1327,7 +1209,7 @@ export class CliProviderInstance implements ProviderInstance {
             this.lastExternalCompletionProbe = null;
             return null;
         }
-        this.lastExternalCompletionProbe = this.buildExternalTranscriptProbe(
+        this.lastExternalCompletionProbe = buildExternalTranscriptProbe(
             restoredHistory.messages,
             restoredHistory.sourcePath,
             restoredHistory.sourceMtimeMs,
@@ -1698,6 +1580,31 @@ export class CliProviderInstance implements ProviderInstance {
             : CliProviderInstance.AUTO_APPROVE_GATE_HYSTERESIS_MS;
     }
 
+    /**
+     * The settle-gate identity signature for a raw activeModal, or null when the
+     * modal is NOT a concrete auto-approvable consent prompt (no captured buttons,
+     * a picker/confirm kind, or no reliable affirmative+decline anchor). Mirrors the
+     * gates the auto-approve fire path applies before computing modalSignature, so
+     * the mask-stall nudge can ask the SAME question the settle gate is tracking —
+     * "is THIS frame's modal the identity the settle clock is accruing against?" —
+     * without duplicating the button-pick logic. The signature is message +
+     * normalized affirmative label only (no volatile counters/button set), matching
+     * the fire path exactly (AUTOAPPROVE-SETTLE-FLAP).
+     */
+    private approvableModalSignature(modal: any): string | null {
+        const buttons = Array.isArray(modal?.buttons)
+            ? modal.buttons.map((b: any) => String(b || '').trim()).filter(Boolean)
+            : [];
+        if (!modal || buttons.length === 0) return null;
+        const modalKind = typeof modal?.kind === 'string' ? modal.kind : 'approval';
+        if (modalKind !== 'approval') return null;
+        const { index: buttonIndex, label: buttonLabel } = pickApprovalButton(buttons, this.provider);
+        const hasReliableConsentAnchor = hasNegativeApprovalOption(buttons)
+            || hasReliableApprovalAffirmative(buttons);
+        if (buttonIndex < 0 || !hasReliableConsentAnchor) return null;
+        return approvalModalSignature(modal?.message, normalizeApprovalLabel(buttonLabel));
+    }
+
     // FALSE-IDLE (self-coordinator settle): an autonomously-progressing mesh session
     // is either a delegated worker (isMeshWorkerSession) OR the coordinator's OWN
     // claude-cli session (meshCoordinatorFor). Both run auto-approved tool turns whose
@@ -2184,10 +2091,7 @@ export class CliProviderInstance implements ProviderInstance {
         // identifies the consent question without tracking the volatile button
         // positions.
         const affirmativeAnchor = normalizeApprovalLabel(buttonLabel);
-        const modalSignature = [
-            typeof modal?.message === 'string' ? modal.message.trim() : '',
-            affirmativeAnchor,
-        ].join('::');
+        const modalSignature = approvalModalSignature(modal?.message, affirmativeAnchor);
         // Busy-window re-entry guard still needs the seq: two DISTINCT
         // back-to-back approvals can carry identical message/buttons (common
         // with claude-cli). Without the seq their busy signatures collide and
@@ -2553,7 +2457,7 @@ export class CliProviderInstance implements ProviderInstance {
                 if (approvalFingerprint !== this.lastApprovalEventFingerprint) {
                     this.lastApprovalEventFingerprint = approvalFingerprint;
                     this.appendRuntimeSystemMessage(
-                        this.formatApprovalRequestMessage(modal?.message, modal?.buttons),
+                        formatApprovalRequestMessage(modal?.message, modal?.buttons),
                         `approval_request:${now}`,
                         now,
                     );
@@ -3094,7 +2998,7 @@ export class CliProviderInstance implements ProviderInstance {
             if (effectWhen === 'turn_completed' && options.phase !== 'turn_completed') continue;
             if (effectWhen === 'immediate' && options.phase === 'turn_completed') continue;
 
-            const effectKey = this.getEffectDedupKey(effect);
+            const effectKey = getEffectDedupKey(effect);
             if (this.appliedEffectKeys.has(effectKey)) continue;
             this.appliedEffectKeys.add(effectKey);
 
@@ -3144,40 +3048,6 @@ export class CliProviderInstance implements ProviderInstance {
             this.appliedEffectKeys = new Set(Array.from(this.appliedEffectKeys).slice(-100));
         }
     }
-
-    private getEffectDedupKey(effect: { id?: string; type: string; message?: { content?: unknown }; toast?: { message?: string }; notification?: { title?: string; body?: string } }): string {
-        if (effect.id) return `provider_effect:${effect.id}`;
-        if (effect.type === 'message') {
-            const content = typeof effect.message?.content === 'string'
-                ? effect.message.content
-                : JSON.stringify(effect.message?.content || '');
-            return `provider_effect:message:${content}`;
-        }
-        if (effect.type === 'notification') {
-            return `provider_effect:notification:${effect.notification?.title || ''}:${effect.notification?.body || ''}`;
-        }
-        return `provider_effect:toast:${effect.toast?.message || ''}`;
-    }
-
-    private getPersistedEffectContent(effect: { type: string; message?: { content?: unknown }; toast?: { message?: string }; notification?: { title?: string; body?: string; bubbleContent?: unknown } }): string | null {
-        if (effect.type === 'message') {
-            return typeof effect.message?.content === 'string'
-                ? effect.message.content
-                : JSON.stringify(effect.message?.content || '');
-        }
-        if (effect.type === 'toast') {
-            return effect.toast?.message || null;
-        }
-        if (effect.type === 'notification') {
-            if (typeof effect.notification?.bubbleContent === 'string') return effect.notification.bubbleContent;
-            if (typeof effect.notification?.title === 'string' && effect.notification.title.trim()) {
-                return `${effect.notification.title}\n${effect.notification.body || ''}`.trim();
-            }
-            return effect.notification?.body || null;
-        }
-        return null;
-    }
-
  // ─── Adapter access (backward compat) ──────────────────
 
     getAdapter(): ProviderCliAdapter {
@@ -3263,18 +3133,34 @@ export class CliProviderInstance implements ProviderInstance {
         if (!this.isMeshWorkerSession()) return;
         if (adapterStatus?.status !== 'waiting_approval') return;
         if (!this.autoApproveMaskStalled(now)) return;
-        // AUTOAPPROVE-FLAP-RECUR (Fix C): the mask-stall bound tripped, but if a
-        // concrete approvable modal is on screen RIGHT NOW and the settle gate is
-        // already in progress, auto-approve is about to fire on its own (the same
-        // call runs the settle evaluation just below this nudge). Defer to the fire
-        // rather than paging the coordinator — the nudge would race a resolveModal
-        // that lands milliseconds later, producing the coordinator flap this fix
-        // targets. A genuinely stuck episode (no captured modal, or settle never
-        // engaged) still has pendingAutoApprovalSince === 0 here and pages normally.
-        const modalButtons = Array.isArray(adapterStatus.activeModal?.buttons)
-            ? adapterStatus.activeModal.buttons.map((b: any) => String(b || '').trim()).filter(Boolean)
-            : [];
-        if (this.pendingAutoApprovalSince && modalButtons.length > 0) return;
+        // AUTOAPPROVE-FLAP-RECUR (Fix C, redesigned): the mask-stall bound tripped.
+        // If auto-approve is genuinely about to fire on its own, defer to that fire —
+        // the nudge would race a resolveModal landing milliseconds later, producing
+        // the coordinator flap this fix targets.
+        //
+        // The ORIGINAL guard deferred on `pendingAutoApprovalSince && buttons > 0`
+        // alone. That is FALSE-POSITIVE for a FLAPPING modal: a modal whose identity
+        // changes every frame (message streaming) keeps pendingAutoApprovalSince
+        // nonzero (it is re-stamped to `now` on every signature change) and keeps
+        // buttons present, yet its settle clock is wiped back to ~0 each frame and
+        // NEVER reaches SETTLE_MS — so auto-approve can never fire and this is exactly
+        // the stuck episode the coordinator MUST be paged about. The old guard
+        // silenced it permanently (the live rc.466 regression).
+        //
+        // Discriminator: a settle is genuinely PROGRESSING only if THIS frame's modal
+        // carries the SAME identity the settle clock is already accruing against
+        // (pendingAutoApprovalSignature). A stable modal keeps its signature across
+        // frames → the clock climbs → resolveModal is imminent → defer. A flapping
+        // modal presents a DIFFERENT signature this frame (or none — a non-concrete /
+        // picker / never-captured modal) → the clock is about to reset (or never
+        // engaged) → do NOT defer, page the coordinator. This is evaluated for the
+        // CURRENT frame (not a stale prior-frame value), so a stable modal polled only
+        // twice — start, then past the stall bound — is still correctly deferred.
+        const currentSignature = this.approvableModalSignature(adapterStatus.activeModal);
+        const settleProgressing = !!currentSignature
+            && this.pendingAutoApprovalSince > 0
+            && currentSignature === this.pendingAutoApprovalSignature;
+        if (settleProgressing) return;
         // Exactly once per stalled episode (autoApproveMaskSince uniquely identifies it).
         if (this.stalledApprovalNudgeEpisode === this.autoApproveMaskSince) return;
         this.stalledApprovalNudgeEpisode = this.autoApproveMaskSince;
@@ -3282,7 +3168,7 @@ export class CliProviderInstance implements ProviderInstance {
         const dirName = workingDirBasename(this.workingDir);
         const chatTitle = `${this.provider.name} · ${dirName}`;
         this.appendRuntimeSystemMessage(
-            this.formatApprovalRequestMessage(modal?.message, modal?.buttons),
+            formatApprovalRequestMessage(modal?.message, modal?.buttons),
             `approval_request:${now}`,
             now,
         );
@@ -3313,12 +3199,6 @@ export class CliProviderInstance implements ProviderInstance {
         );
     }
 
-    private formatMarkerTimestamp(timestamp: number): string {
-        const date = new Date(timestamp);
-        const pad = (value: number) => String(value).padStart(2, '0');
-        return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
-    }
-
     private maybeAppendRuntimeRecoveryMessage(runtime: PtyRuntimeMetadata | null): void {
         if (!runtime?.restoredFromStorage || !runtime.runtimeId) return;
 
@@ -3389,103 +3269,7 @@ export class CliProviderInstance implements ProviderInstance {
     }
 
     mergeRuntimeChatMessages(parsedMessages: ChatMessage[]): ChatMessage[] {
-        return this.mergeConversationMessages(parsedMessages);
-    }
-
-    private mergeConversationMessages(parsedMessages: any[]): ChatMessage[] {
-        if (this.runtimeMessages.length === 0) return normalizeChatMessages(parsedMessages);
-
-        type MergeEntry = { message: ChatMessage; index: number; source: 'parsed' | 'runtime'; runtimeKey?: string };
-        const parsedEntries: MergeEntry[] = parsedMessages.map((message, index) => ({
-            message,
-            index,
-            source: 'parsed',
-        }));
-        const getRole = (message: ChatMessage): string => typeof message.role === 'string'
-            ? message.role.trim().toLowerCase()
-            : '';
-        const runtimeEntries: MergeEntry[] = this.runtimeMessages.map((entry, index) => ({
-            message: entry.message,
-            index: parsedMessages.length + index,
-            source: 'runtime' as const,
-            runtimeKey: entry.key,
-        })).filter((entry) => {
-            const meta = entry.message.meta && typeof entry.message.meta === 'object' && !Array.isArray(entry.message.meta)
-                ? entry.message.meta as Record<string, unknown>
-                : {};
-            if (meta.runtimeInputAck !== true) return true;
-            const runtimeText = flattenContent(entry.message.content).replace(/\s+/g, ' ').trim();
-            if (!runtimeText) return false;
-            return !parsedEntries.some((parsedEntry) => {
-                const parsedRole = getRole(parsedEntry.message);
-                if (parsedRole !== 'user' && parsedRole !== 'human') return false;
-                const parsedText = flattenContent(parsedEntry.message.content).replace(/\s+/g, ' ').trim();
-                return parsedText === runtimeText;
-            });
-        });
-        const getTime = (message: ChatMessage): number => {
-            const value = typeof message.receivedAt === 'number'
-                ? message.receivedAt
-                : typeof message.timestamp === 'number'
-                    ? message.timestamp
-                    : 0;
-            return Number.isFinite(value) && value > 0 ? value : 0;
-        };
-
-        const isRuntimeOverlay = (entry: MergeEntry): boolean => {
-            if (entry.source !== 'runtime') return false;
-            const key = typeof entry.runtimeKey === 'string' ? entry.runtimeKey.trim().toLowerCase() : '';
-            if (key.startsWith('auto_approval:')) return true;
-            return !isUserFacingChatMessage(entry.message);
-        };
-        const shouldKeepParsedBeforeUntimedRuntime = (message: ChatMessage): boolean => {
-            const role = getRole(message);
-            return role === 'user' || role === 'human';
-        };
-        const shouldKeepParsedAfterUntimedRuntime = (message: ChatMessage): boolean => {
-            const role = getRole(message);
-            if (role !== 'assistant') return false;
-            const kind = resolveChatMessageKind(message);
-            return kind === 'standard' || kind === 'terminal';
-        };
-
-        return normalizeChatMessages([...parsedEntries, ...runtimeEntries]
-            .sort((a, b) => {
-                const aTime = getTime(a.message);
-                const bTime = getTime(b.message);
-                if (aTime && bTime && aTime !== bTime) return aTime - bTime;
-                if (a.source !== b.source && aTime !== bTime) {
-                    const parsedEntry = a.source === 'parsed' ? a : b.source === 'parsed' ? b : null;
-                    const runtimeEntry = a.source === 'runtime' ? a : b.source === 'runtime' ? b : null;
-                    if (parsedEntry && runtimeEntry && isRuntimeOverlay(runtimeEntry) && getTime(parsedEntry.message) === 0 && getTime(runtimeEntry.message) > 0) {
-                        if (shouldKeepParsedBeforeUntimedRuntime(parsedEntry.message)) {
-                            return a.source === 'parsed' ? -1 : 1;
-                        }
-                        if (shouldKeepParsedAfterUntimedRuntime(parsedEntry.message)) {
-                            return a.source === 'parsed' ? 1 : -1;
-                        }
-                    }
-                }
-                // Many provider-owned CLI transcripts (including Hermes CLI in debug bundles)
-                // do not carry timestamps on parsed messages. In that case there is no safe
-                // clock basis for interleaving timestamped runtime/system messages into the
-                // provider transcript. Keep user prompts before runtime overlays, but do not
-                // let timed runtime/system/tool/internal overlays become the final chat turns
-                // after an untimed parsed assistant transcript.
-                return a.index - b.index;
-            })
-            .map((entry) => entry.message));
-    }
-
-    private formatApprovalRequestMessage(modalMessage?: string, buttons?: string[]): string {
-        const lines = ['Approval requested'];
-        const cleanMessage = String(modalMessage || '').trim();
-        if (cleanMessage) lines.push(cleanMessage);
-        const labels = (buttons || []).map((button) => String(button || '').trim()).filter(Boolean);
-        if (labels.length > 0) {
-            lines.push(labels.map((label) => `[${label}]`).join(' '));
-        }
-        return lines.join('\n');
+        return mergeConversationMessages(this.runtimeMessages, parsedMessages);
     }
 
     private promoteProviderSessionId(sessionId: string, opts: { authoritative?: boolean } = {}): void {

package/src/providers/cli-provider-transcript-merge.ts

@@ -0,0 +1,114 @@
+// Transcript assembly helpers extracted from cli-provider-instance.ts.
+// Pure move — no behavior change. `mergeConversationMessages` was a private
+// method reading only `this.runtimeMessages`; it now takes that array as a
+// parameter. `buildExternalTranscriptProbe` used no instance state.
+
+import { flattenContent } from './contracts.js';
+import { normalizeChatMessages, resolveChatMessageKind, isUserFacingChatMessage } from './chat-message-normalization.js';
+import type { ChatMessage } from '../types.js';
+import type { ExternalTranscriptProbe } from './cli-provider-instance-types.js';
+
+export function mergeConversationMessages(
+    runtimeMessages: Array<{ key: string; message: ChatMessage }>,
+    parsedMessages: any[],
+): ChatMessage[] {
+    if (runtimeMessages.length === 0) return normalizeChatMessages(parsedMessages);
+
+    type MergeEntry = { message: ChatMessage; index: number; source: 'parsed' | 'runtime'; runtimeKey?: string };
+    const parsedEntries: MergeEntry[] = parsedMessages.map((message, index) => ({
+        message,
+        index,
+        source: 'parsed',
+    }));
+    const getRole = (message: ChatMessage): string => typeof message.role === 'string'
+        ? message.role.trim().toLowerCase()
+        : '';
+    const runtimeEntries: MergeEntry[] = runtimeMessages.map((entry, index) => ({
+        message: entry.message,
+        index: parsedMessages.length + index,
+        source: 'runtime' as const,
+        runtimeKey: entry.key,
+    })).filter((entry) => {
+        const meta = entry.message.meta && typeof entry.message.meta === 'object' && !Array.isArray(entry.message.meta)
+            ? entry.message.meta as Record<string, unknown>
+            : {};
+        if (meta.runtimeInputAck !== true) return true;
+        const runtimeText = flattenContent(entry.message.content).replace(/\s+/g, ' ').trim();
+        if (!runtimeText) return false;
+        return !parsedEntries.some((parsedEntry) => {
+            const parsedRole = getRole(parsedEntry.message);
+            if (parsedRole !== 'user' && parsedRole !== 'human') return false;
+            const parsedText = flattenContent(parsedEntry.message.content).replace(/\s+/g, ' ').trim();
+            return parsedText === runtimeText;
+        });
+    });
+    const getTime = (message: ChatMessage): number => {
+        const value = typeof message.receivedAt === 'number'
+            ? message.receivedAt
+            : typeof message.timestamp === 'number'
+                ? message.timestamp
+                : 0;
+        return Number.isFinite(value) && value > 0 ? value : 0;
+    };
+
+    const isRuntimeOverlay = (entry: MergeEntry): boolean => {
+        if (entry.source !== 'runtime') return false;
+        const key = typeof entry.runtimeKey === 'string' ? entry.runtimeKey.trim().toLowerCase() : '';
+        if (key.startsWith('auto_approval:')) return true;
+        return !isUserFacingChatMessage(entry.message);
+    };
+    const shouldKeepParsedBeforeUntimedRuntime = (message: ChatMessage): boolean => {
+        const role = getRole(message);
+        return role === 'user' || role === 'human';
+    };
+    const shouldKeepParsedAfterUntimedRuntime = (message: ChatMessage): boolean => {
+        const role = getRole(message);
+        if (role !== 'assistant') return false;
+        const kind = resolveChatMessageKind(message);
+        return kind === 'standard' || kind === 'terminal';
+    };
+
+    return normalizeChatMessages([...parsedEntries, ...runtimeEntries]
+        .sort((a, b) => {
+            const aTime = getTime(a.message);
+            const bTime = getTime(b.message);
+            if (aTime && bTime && aTime !== bTime) return aTime - bTime;
+            if (a.source !== b.source && aTime !== bTime) {
+                const parsedEntry = a.source === 'parsed' ? a : b.source === 'parsed' ? b : null;
+                const runtimeEntry = a.source === 'runtime' ? a : b.source === 'runtime' ? b : null;
+                if (parsedEntry && runtimeEntry && isRuntimeOverlay(runtimeEntry) && getTime(parsedEntry.message) === 0 && getTime(runtimeEntry.message) > 0) {
+                    if (shouldKeepParsedBeforeUntimedRuntime(parsedEntry.message)) {
+                        return a.source === 'parsed' ? -1 : 1;
+                    }
+                    if (shouldKeepParsedAfterUntimedRuntime(parsedEntry.message)) {
+                        return a.source === 'parsed' ? 1 : -1;
+                    }
+                }
+            }
+            // Many provider-owned CLI transcripts (including Hermes CLI in debug bundles)
+            // do not carry timestamps on parsed messages. In that case there is no safe
+            // clock basis for interleaving timestamped runtime/system messages into the
+            // provider transcript. Keep user prompts before runtime overlays, but do not
+            // let timed runtime/system/tool/internal overlays become the final chat turns
+            // after an untimed parsed assistant transcript.
+            return a.index - b.index;
+        })
+        .map((entry) => entry.message));
+}
+
+export function buildExternalTranscriptProbe(messages: unknown[], sourcePath?: string, sourceMtimeMs?: number): ExternalTranscriptProbe {
+    const visibleMessages = messages.filter((message: any) => isUserFacingChatMessage(message as ChatMessage));
+    const lastVisible = visibleMessages[visibleMessages.length - 1] as ChatMessage | undefined;
+    const readAt = Date.now();
+    const mtimeMs = Number(sourceMtimeMs) || 0;
+    return {
+        readAt,
+        msgCount: messages.length,
+        lastRole: typeof lastVisible?.role === 'string' ? lastVisible.role.trim().toLowerCase() : null,
+        lastKind: typeof (lastVisible as any)?.kind === 'string' ? (lastVisible as any).kind : null,
+        contentLen: lastVisible ? flattenContent(lastVisible.content).trim().length : 0,
+        sourcePath: typeof sourcePath === 'string' && sourcePath ? sourcePath : null,
+        sourceMtimeMs: mtimeMs || null,
+        mtimeAgeMs: mtimeMs ? Math.max(0, readAt - mtimeMs) : null,
+    };
+}