@adhdev/daemon-core 0.9.82-rc.10 → 0.9.82-rc.101

package/src/commands/chat-commands.ts

@@ -13,7 +13,7 @@ import { flattenContent, normalizeInputEnvelope, type InputEnvelope, type Provid
 import { assertProviderSupportsDeclaredInput, assertTextOnlyInput } from '../providers/provider-input-support.js';
 import { validateReadChatResultPayload } from '../providers/read-chat-contract.js';
 import type { ProviderInstance } from '../providers/provider-instance.js';
-import { readProviderChatHistory } from '../config/chat-history.js';
+import { isNativeSourceCanonicalHistory, readProviderChatHistory } from '../config/chat-history.js';
 import { LOG, getRecentLogs } from '../logging/logger.js';
 import { getRecentDebugTrace, recordDebugTrace } from '../logging/debug-trace.js';
 import { buildChatMessageSignature, hashSignatureParts } from '../chat/chat-signatures.js';
@@ -24,6 +24,8 @@ import { filterUserFacingChatMessages, normalizeChatMessages } from '../provider
 const RECENT_SEND_WINDOW_MS = 1200;
 export const READ_CHAT_PROVIDER_EVAL_TIMEOUT_MS = 25_000;
 const HERMES_CLI_STARTING_SEND_SETTLE_MS = 2_000;
+const CLI_NATIVE_HISTORY_FRESH_MS = 5 * 60_000;
+const CLI_NATIVE_TRANSCRIPT_PROVIDERS = new Set(['codex-cli', 'claude-cli', 'hermes-cli', 'antigravity-cli']);
 const recentSendByTarget = new Map<string, number>();
 
 interface ApprovalSelectableInstance extends ProviderInstance {
@@ -48,6 +50,16 @@ function getTargetedCliAdapter(h: CommandHelpers, args: any, providerType?: stri
     return h.getCliAdapter(args?.targetSessionId || providerType || h.currentSession?.providerType || h.currentManagerKey);
 }
 
+function getExplicitHistorySessionId(args: any): string | undefined {
+    const explicit = typeof args?.historySessionId === 'string' ? args.historySessionId.trim() : '';
+    if (explicit) return explicit;
+
+    const explicitProviderSessionId = typeof args?.providerSessionId === 'string' ? args.providerSessionId.trim() : '';
+    if (explicitProviderSessionId) return explicitProviderSessionId;
+
+    return undefined;
+}
+
 function getTargetInstance(h: CommandHelpers, args: any): ApprovalSelectableInstance | null {
     const targetSessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim() : '';
     const sessionId = targetSessionId || h.currentSession?.sessionId || '';
@@ -139,19 +151,47 @@ async function waitOnceForFreshHermesCliStart(adapter: CliAdapter, log: (msg: st
 }
 
 function getHistorySessionId(h: CommandHelpers, args: any): string | undefined {
-    const explicit = typeof args?.historySessionId === 'string' ? args.historySessionId.trim() : '';
+    const explicit = getExplicitHistorySessionId(args);
     if (explicit) return explicit;
 
-    const explicitProviderSessionId = typeof args?.providerSessionId === 'string' ? args.providerSessionId.trim() : '';
-    if (explicitProviderSessionId) return explicitProviderSessionId;
-
     const targetSessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim() : '';
     if (!targetSessionId) return undefined;
 
-    const instance = h.ctx.instanceManager?.getInstance(targetSessionId);
+    const session = h.ctx.sessionRegistry?.get(targetSessionId) as any;
+    const registeredProviderSessionId = typeof session?.providerSessionId === 'string' ? session.providerSessionId.trim() : '';
+    if (registeredProviderSessionId) return registeredProviderSessionId;
+
+    const instance = getTargetInstance(h, args);
     const state = instance?.getState?.();
     const providerSessionId = typeof state?.providerSessionId === 'string' ? state.providerSessionId.trim() : '';
-    return providerSessionId || targetSessionId;
+    if (providerSessionId) return providerSessionId;
+
+    const currentSession = h.currentSession as any;
+    if (currentSession?.sessionId === targetSessionId) {
+        const currentProviderSessionId = typeof currentSession.providerSessionId === 'string'
+            ? currentSession.providerSessionId.trim()
+            : '';
+        if (currentProviderSessionId) return currentProviderSessionId;
+    }
+
+    return targetSessionId;
+}
+
+function resolveCliNativeHistorySessionId(args: any, currentHistorySessionId: string | undefined, parsedProviderSessionId: string | undefined): string | undefined {
+    const explicit = getExplicitHistorySessionId(args);
+    if (explicit) return explicit;
+
+    const parsed = typeof parsedProviderSessionId === 'string' ? parsedProviderSessionId.trim() : '';
+    const current = typeof currentHistorySessionId === 'string' ? currentHistorySessionId.trim() : '';
+    const targetSessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim() : '';
+
+    // getHistorySessionId falls back to the runtime session id when no native
+    // handle has been registered yet. For live CLI adapters the parser may
+    // already know the provider-native handle; prefer it over the runtime id so
+    // exact native reads do not miss the worker transcript and fall back to PTY
+    // or same-workspace history.
+    if (parsed && (!current || current === targetSessionId)) return parsed;
+    return current || parsed || undefined;
 }
 
 function getInteractionId(args: any): string | undefined {
@@ -221,6 +261,263 @@ function normalizeReadChatMessages(payload: Record<string, any>): ChatMessage[]
     return normalizeChatMessages(messages);
 }
 
+function getMessageNewestReceivedAt(messages: Array<{ receivedAt?: unknown; timestamp?: unknown }>): number {
+    let newest = 0;
+    for (const message of messages) {
+        const receivedAt = Number(message?.receivedAt ?? message?.timestamp ?? 0);
+        if (Number.isFinite(receivedAt) && receivedAt > newest) newest = receivedAt;
+    }
+    return newest;
+}
+
+function readHistorySessionIdFromMessages(messages: ChatMessage[]): string | undefined {
+    for (const message of messages as Array<ChatMessage & { historySessionId?: unknown }>) {
+        const historySessionId = typeof message?.historySessionId === 'string' ? message.historySessionId.trim() : '';
+        if (historySessionId) return historySessionId;
+    }
+    return undefined;
+}
+
+function normalizeNativeHistoryMessages(providerType: string, messages: ChatMessage[]): ChatMessage[] {
+    let turnIndex = 0;
+    return normalizeChatMessages(messages).map((message, index) => {
+        const role = typeof message.role === 'string' ? message.role.trim().toLowerCase() : '';
+        const kind = typeof message.kind === 'string' && message.kind.trim() ? message.kind.trim() : (role === 'system' ? 'system' : 'standard');
+        if ((role === 'user' || role === 'human') && index > 0) turnIndex += 1;
+        const historySessionId = typeof (message as any).historySessionId === 'string'
+            ? (message as any).historySessionId.trim()
+            : '';
+        const contentHash = hashSignatureParts([
+            providerType,
+            historySessionId,
+            String(message.receivedAt || message.timestamp || index),
+            role,
+            kind,
+            flattenContent(message.content),
+        ]).slice(0, 12);
+        const providerUnitKey = typeof message.providerUnitKey === 'string' && message.providerUnitKey.trim()
+            ? message.providerUnitKey.trim()
+            : `${providerType}:native:${historySessionId || 'workspace'}:${index}:${role || 'message'}:${kind}:${contentHash}`;
+        const meta = message.meta && typeof message.meta === 'object' ? message.meta as Record<string, unknown> : undefined;
+        const isSystemSessionStart = role === 'system' || kind === 'system' || kind === 'session_start';
+        const isActivity = role === 'assistant' && (kind === 'tool' || kind === 'terminal' || kind === 'thought');
+        return {
+            ...message,
+            role: role === 'human' ? 'user' : (role || 'assistant'),
+            kind: isSystemSessionStart ? 'system' : kind,
+            providerUnitKey,
+            bubbleId: typeof message.bubbleId === 'string' && message.bubbleId.trim()
+                ? message.bubbleId.trim()
+                : `bubble:${providerUnitKey}`,
+            _turnKey: typeof message._turnKey === 'string' && message._turnKey.trim()
+                ? message._turnKey.trim()
+                : `${providerType}:native-turn:${historySessionId || 'workspace'}:${turnIndex}`,
+            bubbleState: message.bubbleState || 'final',
+            ...(isSystemSessionStart ? {
+                visibility: message.visibility || 'hidden',
+                transcriptVisibility: message.transcriptVisibility || 'hidden',
+                audience: message.audience || 'internal',
+                source: message.source || 'runtime_status',
+            } : isActivity ? {
+                source: message.source || (kind === 'terminal' ? 'terminal_command' : 'tool_call'),
+                meta: { ...meta, label: message.senderName || meta?.label || (kind === 'terminal' ? 'Terminal' : 'Tool') },
+            } : {
+                source: message.source || (role === 'assistant' ? 'assistant_text' : undefined),
+            }),
+        } as ChatMessage;
+    });
+}
+
+function buildCliMessageSourceProvenance(args: {
+    selected: 'native-history' | 'pty-parser';
+    provider: string;
+    nativeHandle?: string;
+    fallbackReason?: string;
+    nativeSource?: string;
+    sourcePath?: string;
+    sourceMtimeMs?: number;
+    nativeMessages?: ChatMessage[];
+    ptyMessages?: ChatMessage[];
+    returnedMessages?: ChatMessage[];
+    safeMapping?: boolean;
+    freshEnough?: boolean;
+    ptyStatusApprovalOnly?: boolean;
+}): Record<string, unknown> {
+    const sourceMtimeMs = Number(args.sourceMtimeMs || 0);
+    const sourceMtimeAgeMs = sourceMtimeMs > 0 ? Math.max(0, Date.now() - sourceMtimeMs) : undefined;
+    const nativeMessages = args.nativeMessages || [];
+    const ptyMessages = args.ptyMessages || [];
+    const returnedMessages = args.returnedMessages || [];
+    return {
+        selected: args.selected,
+        provider: args.provider,
+        providerType: args.provider,
+        ...(args.nativeHandle ? { nativeHandle: args.nativeHandle } : {}),
+        ...(args.nativeHandle ? { nativeSessionId: args.nativeHandle } : {}),
+        ...(args.fallbackReason ? { fallbackReason: args.fallbackReason } : {}),
+        ...(args.nativeSource ? { nativeSource: args.nativeSource } : {}),
+        ...(args.sourcePath ? { sourcePath: args.sourcePath } : {}),
+        ptyStatusApprovalOnly: args.ptyStatusApprovalOnly === true,
+        staleness: {
+            sourceMtimeMs: sourceMtimeMs || undefined,
+            sourceMtimeAgeMs,
+            nativeNewestMessageAt: getMessageNewestReceivedAt(nativeMessages),
+            ptyNewestMessageAt: getMessageNewestReceivedAt(ptyMessages),
+            freshEnough: args.freshEnough === true,
+        },
+        coverage: {
+            nativeMessageCount: nativeMessages.length,
+            ptyMessageCount: ptyMessages.length,
+            returnedMessageCount: returnedMessages.length,
+            safeMapping: args.safeMapping === true,
+        },
+    };
+}
+
+function buildNativeHistoryFallbackReason(args: {
+    providerType: string;
+    provider?: ProviderModule;
+    nativeSource?: string;
+    nativeMessageCount: number;
+    safeMapping: boolean;
+    freshEnough: boolean;
+}): string {
+    if (!supportsCliNativeTranscript(args.providerType, args.provider)) return 'provider_native_transcript_not_supported';
+    if (args.nativeSource === 'native-unavailable') return 'native_history_unavailable';
+    if (args.nativeSource && args.nativeSource !== 'provider-native') return `native_history_source_${args.nativeSource}`;
+    if (args.nativeMessageCount <= 0) return 'native_history_empty';
+    if (!args.safeMapping) return 'native_history_not_safely_mapped';
+    if (!args.freshEnough) return 'native_history_stale';
+    return 'native_history_not_selected';
+}
+
+function supportsCliNativeTranscript(providerType: string, provider?: ProviderModule): boolean {
+    if (CLI_NATIVE_TRANSCRIPT_PROVIDERS.has(providerType)) return true;
+    return provider?.category === 'cli' && isNativeSourceCanonicalHistory(provider?.canonicalHistory);
+}
+
+function getComparableVisibleText(message: ChatMessage | undefined): string {
+    if (!message) return '';
+    const role = String((message as any).role || '').trim().toLowerCase();
+    if (role !== 'user' && role !== 'assistant') return '';
+    const kind = String((message as any).kind || 'standard').trim().toLowerCase();
+    if (kind && kind !== 'standard') return '';
+    const content = flattenContent((message as any).content).replace(/\s+/g, ' ').trim();
+    return content;
+}
+
+function hasOverlappingVisibleConversationText(nativeMessages: ChatMessage[], ptyMessages: ChatMessage[]): boolean {
+    const nativeTexts = nativeMessages.map(getComparableVisibleText).filter(Boolean);
+    const ptyTexts = ptyMessages.map(getComparableVisibleText).filter(Boolean);
+    if (nativeTexts.length === 0 || ptyTexts.length === 0) return false;
+    for (const nativeText of nativeTexts) {
+        for (const ptyText of ptyTexts) {
+            if (nativeText === ptyText) return true;
+            const shorter = nativeText.length <= ptyText.length ? nativeText : ptyText;
+            const longer = nativeText.length <= ptyText.length ? ptyText : nativeText;
+            if (shorter.length >= 32 && longer.includes(shorter)) return true;
+        }
+    }
+    return false;
+}
+
+function hasSafeNativeHistoryMapping(args: {
+    historySessionId?: string;
+    providerSessionId?: string;
+    workspace?: string;
+    nativeMessages: ChatMessage[];
+    ptyMessages?: ChatMessage[];
+    requireWorkspaceContentOverlap?: boolean;
+}): boolean {
+    const explicitSessionId = String(args.historySessionId || args.providerSessionId || '').trim();
+    if (explicitSessionId) {
+        const messageSessionIds = args.nativeMessages
+            .map((message: any) => typeof message?.historySessionId === 'string' ? message.historySessionId.trim() : '')
+            .filter(Boolean);
+        if (messageSessionIds.length === 0) return true;
+        return messageSessionIds.some((id) => id === explicitSessionId);
+    }
+    const workspace = String(args.workspace || '').trim();
+    if (!workspace) return false;
+    const workspaceMatches = args.nativeMessages.some((message: any) => String(message?.workspace || '').trim() === workspace);
+    if (!workspaceMatches) return false;
+    if (!args.requireWorkspaceContentOverlap) return true;
+    return hasOverlappingVisibleConversationText(args.nativeMessages, args.ptyMessages || []);
+}
+
+function readCliProviderNativeHistory(agentStr: string, args: {
+    canonicalHistory?: ProviderModule['canonicalHistory'];
+    historySessionId?: string;
+    workspace?: string;
+    offset: number;
+    limit: number;
+    excludeRecentCount: number;
+    historyBehavior?: ProviderModule['historyBehavior'];
+    scripts?: ProviderScripts;
+    exactSessionScoped?: boolean;
+}): ReturnType<typeof readProviderChatHistory> & { lookup: 'session' | 'workspace' } {
+    const sessionHistory = readProviderChatHistory(agentStr, {
+        canonicalHistory: args.canonicalHistory,
+        historySessionId: args.historySessionId,
+        workspace: args.workspace,
+        offset: args.offset,
+        limit: args.limit,
+        excludeRecentCount: args.excludeRecentCount,
+        historyBehavior: args.historyBehavior,
+        scripts: args.scripts as any,
+    });
+    // Exact runtime/provider transcript reads must not silently fall back to the
+    // workspace's active or most recent native transcript: multiple Hermes/Gemini/
+    // Codex sessions can run in the same workspace, and workspace fallback can make
+    // read_chat/completion evidence point at a different runtime's prompt.
+    if ((sessionHistory as any).source !== 'native-unavailable' || args.exactSessionScoped || !args.historySessionId || !args.workspace) {
+        return { ...(sessionHistory as any), lookup: args.historySessionId ? 'session' : 'workspace' };
+    }
+    const workspaceHistory = readProviderChatHistory(agentStr, {
+        canonicalHistory: args.canonicalHistory,
+        historySessionId: undefined,
+        workspace: args.workspace,
+        offset: args.offset,
+        limit: args.limit,
+        excludeRecentCount: args.excludeRecentCount,
+        historyBehavior: args.historyBehavior,
+        scripts: args.scripts as any,
+    });
+    return { ...(workspaceHistory as any), lookup: 'workspace' };
+}
+
+function isNativeHistoryFreshEnough(args: {
+    sourceMtimeMs?: number;
+    nativeMessages: ChatMessage[];
+    ptyMessages: ChatMessage[];
+}): boolean {
+    const nativeNewest = getMessageNewestReceivedAt(args.nativeMessages);
+    const ptyNewest = getMessageNewestReceivedAt(args.ptyMessages);
+    if (nativeNewest > 0 && nativeNewest >= ptyNewest) return true;
+    const sourceMtimeMs = Number(args.sourceMtimeMs || 0);
+    if (sourceMtimeMs > 0 && Date.now() - sourceMtimeMs <= CLI_NATIVE_HISTORY_FRESH_MS) return true;
+    return ptyNewest === 0 && nativeNewest > 0;
+}
+
+function shouldPreserveReadChatPayloadField(key: string): boolean {
+    return key === 'messageSource' || key === 'transcriptProvenance';
+}
+
+function updateMessageSourceReturnedCount(value: unknown, returnedMessageCount: number): unknown {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
+    const record = value as Record<string, unknown>;
+    const coverage = record.coverage && typeof record.coverage === 'object' && !Array.isArray(record.coverage)
+        ? record.coverage as Record<string, unknown>
+        : undefined;
+    if (!coverage) return value;
+    return {
+        ...record,
+        coverage: {
+            ...coverage,
+            returnedMessageCount,
+        },
+    };
+}
 
 function deriveHistoryDedupKey(message: ChatMessage & { _unitKey?: string; _turnKey?: string }): string | undefined {
     const unitKey = typeof message._unitKey === 'string' ? message._unitKey.trim() : '';
@@ -281,7 +578,7 @@ function normalizeReadChatCommandStatus(status: unknown, activeModal: unknown):
     }
     switch (raw) {
         case 'starting':
-            return hasNonEmptyModalButtons(activeModal) ? 'waiting_approval' : 'generating';
+            return hasNonEmptyModalButtons(activeModal) ? 'waiting_approval' : 'starting';
         case 'stopped':
         case 'disconnected':
         case 'not_monitored':
@@ -295,6 +592,16 @@ function isGeneratingLikeStatus(status: unknown): boolean {
     return status === 'generating' || status === 'streaming' || status === 'long_generating' || status === 'starting';
 }
 
+function hasVisibleAssistantMessage(messages: unknown[] | undefined): boolean {
+    if (!Array.isArray(messages)) return false;
+    return messages.some((message: any) => {
+        if (!message || message.role !== 'assistant') return false;
+        const kind = typeof message.kind === 'string' ? message.kind : 'standard';
+        if (kind !== 'standard') return false;
+        return String(message.content || '').trim().length > 0;
+    });
+}
+
 function shouldTrustCliAdapterTerminalStatus(parsedStatus: unknown, activeModal: unknown, adapter: CliAdapter, adapterStatus: any): boolean {
     if (!isGeneratingLikeStatus(parsedStatus)) return false;
     if (hasNonEmptyModalButtons(activeModal)) return false;
@@ -304,7 +611,26 @@ function shouldTrustCliAdapterTerminalStatus(parsedStatus: unknown, activeModal:
     return true;
 }
 
-function normalizeCliReadChatStatus(parsedStatus: unknown, activeModal: unknown, adapter: CliAdapter, adapterStatus: any): string {
+function normalizeCliReadChatStatus(parsedStatus: unknown, activeModal: unknown, adapter: CliAdapter, adapterStatus: any, parsedMessages?: unknown[]): string {
+    const adapterRawStatus = typeof adapterStatus?.status === 'string' ? adapterStatus.status.trim() : '';
+    if (adapterRawStatus === 'starting'
+        && isGeneratingLikeStatus(parsedStatus)
+        && !hasNonEmptyModalButtons(activeModal)
+        && Array.isArray(parsedMessages)
+        && parsedMessages.length === 0
+        && Array.isArray(adapterStatus?.messages)
+        && adapterStatus.messages.length === 0
+        && !(typeof adapter.isProcessing === 'function' && adapter.isProcessing())) {
+        return 'starting';
+    }
+    if (
+        isGeneratingLikeStatus(adapterRawStatus)
+        && parsedStatus === 'idle'
+        && !hasNonEmptyModalButtons(activeModal)
+        && !hasVisibleAssistantMessage(parsedMessages)
+    ) {
+        return adapterRawStatus;
+    }
     if (shouldTrustCliAdapterTerminalStatus(parsedStatus, activeModal, adapter, adapterStatus)) return 'idle';
     return typeof parsedStatus === 'string' && parsedStatus.trim() ? parsedStatus : 'idle';
 }
@@ -342,6 +668,13 @@ function buildReadChatCommandResult(payload: Record<string, any>, args: any): Co
     const visibleMessages = filterUserFacingChatMessages(messages);
     const sync = buildFullTail(visibleMessages, normalizeReadChatTailLimit(args));
     const hiddenMsgCount = Math.max(0, messages.length - visibleMessages.length);
+    const preservedPayloadFields = Object.fromEntries(Object.entries(payload).filter(([key]) => shouldPreserveReadChatPayloadField(key)));
+    if (preservedPayloadFields.messageSource) {
+        preservedPayloadFields.messageSource = updateMessageSourceReturnedCount(preservedPayloadFields.messageSource, sync.messages.length);
+    }
+    if (preservedPayloadFields.transcriptProvenance) {
+        preservedPayloadFields.transcriptProvenance = updateMessageSourceReturnedCount(preservedPayloadFields.transcriptProvenance, sync.messages.length);
+    }
     const returnedDebugReadChat = debugReadChat
         ? {
             ...debugReadChat,
@@ -356,6 +689,7 @@ function buildReadChatCommandResult(payload: Record<string, any>, args: any): Co
     return {
         success: true,
         ...validatedPayload,
+        ...preservedPayloadFields,
         messages: sync.messages,
         totalMessages: sync.totalMessages,
         ...(returnedDebugReadChat ? { debugReadChat: returnedDebugReadChat } : {}),
@@ -584,6 +918,8 @@ function buildChatDebugBundleSummary(bundle: Record<string, unknown>): Record<st
             adapterStatus: debugReadChat.adapterStatus,
             parsedStatus: debugReadChat.parsedStatus,
             returnedStatus: debugReadChat.returnedStatus,
+            selectedMessageSource: debugReadChat.selectedMessageSource,
+            messageSource: debugReadChat.messageSource,
             parsedMsgCount: debugReadChat.parsedMsgCount,
             returnedMsgCount: debugReadChat.returnedMsgCount,
             shouldPreferAdapterMessages: debugReadChat.shouldPreferAdapterMessages,
@@ -646,6 +982,8 @@ export async function handleGetChatDebugBundle(h: CommandHelpers, args: any): Pr
                 providerSessionId: readResult.providerSessionId,
                 transcriptAuthority: readResult.transcriptAuthority,
                 coverage: readResult.coverage,
+                messageSource: readResult.messageSource,
+                transcriptProvenance: readResult.transcriptProvenance,
                 activeModal: readResult.activeModal,
                 messagesTail: Array.isArray(readResult.messages) ? readResult.messages.slice(-20) : [],
                 debugReadChat: readResult.debugReadChat,
@@ -874,7 +1212,7 @@ export async function handleReadChat(h: CommandHelpers, args: any): Promise<Comm
                 ? parsedRecord.coverage
                 : undefined;
             const activeModal = parsedRecord.activeModal ?? parsedRecord.modal ?? null;
-            const returnedStatus = normalizeCliReadChatStatus(parsedRecord.status, activeModal, adapter, adapterStatus);
+            const returnedStatus = normalizeCliReadChatStatus(parsedRecord.status, activeModal, adapter, adapterStatus, parsedRecord.messages);
             const runtimeMessageMerger = getTargetInstance(h, args) as RuntimeChatMessageMerger | null;
             const parsedMessages = finalizeStreamingMessagesWhenIdle(parsedRecord.messages as ChatMessage[], returnedStatus);
             const returnedMessages = runtimeMessageMerger?.category === 'cli'
@@ -882,25 +1220,166 @@ export async function handleReadChat(h: CommandHelpers, args: any): Promise<Comm
                 && typeof runtimeMessageMerger.mergeRuntimeChatMessages === 'function'
                 ? runtimeMessageMerger.mergeRuntimeChatMessages(parsedMessages)
                 : parsedMessages;
+            const providerType = provider?.type || adapter.cliType;
+            let selectedMessages = returnedMessages;
+            let selectedTitle = title;
+            let selectedProviderSessionId = providerSessionId;
+            let selectedTranscriptAuthority = transcriptAuthority;
+            let selectedCoverage = coverage;
+            let messageSource = buildCliMessageSourceProvenance({
+                selected: 'pty-parser',
+                provider: adapter.cliType,
+                fallbackReason: supportsCliNativeTranscript(providerType, provider) ? 'native_history_not_checked' : 'provider_native_transcript_not_supported',
+                ptyMessages: returnedMessages,
+                returnedMessages,
+                ptyStatusApprovalOnly: false,
+            });
+
+            if (supportsCliNativeTranscript(providerType, provider) && isNativeSourceCanonicalHistory(provider?.canonicalHistory)) {
+                const agentStr = provider?.type || args?.agentType || getCurrentProviderType(h, adapter.cliType);
+                const workspace = typeof args?.workspace === 'string'
+                    ? args.workspace
+                    : typeof (h.currentSession as any)?.workspace === 'string'
+                        ? (h.currentSession as any).workspace
+                        : typeof adapter.workingDir === 'string'
+                            ? adapter.workingDir
+                            : undefined;
+                const nativeHistoryLimit = Math.max(
+                    normalizeReadChatTailLimit(args) || 0,
+                    returnedMessages.length,
+                    200,
+                );
+                const nativeHistorySessionId = resolveCliNativeHistorySessionId(args, historySessionId, providerSessionId);
+                const targetSessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim() : '';
+                const exactNativeHistoryScope = Boolean(
+                    (typeof args?.historySessionId === 'string' && args.historySessionId.trim())
+                    || (typeof args?.providerSessionId === 'string' && args.providerSessionId.trim())
+                    || providerSessionId
+                    || (nativeHistorySessionId && nativeHistorySessionId !== targetSessionId)
+                    || ((h.currentSession as any)?.sessionId === args?.targetSessionId && typeof (h.currentSession as any)?.providerSessionId === 'string' && (h.currentSession as any).providerSessionId.trim())
+                );
+                let nativeHistory: (ReturnType<typeof readProviderChatHistory> & { lookup?: 'session' | 'workspace' }) | null = null;
+                try {
+                    nativeHistory = readCliProviderNativeHistory(agentStr, {
+                        canonicalHistory: provider?.canonicalHistory,
+                        historySessionId: nativeHistorySessionId,
+                        workspace,
+                        offset: 0,
+                        limit: nativeHistoryLimit,
+                        excludeRecentCount: 0,
+                        historyBehavior: provider?.historyBehavior,
+                        scripts: provider?.scripts as any,
+                        exactSessionScoped: exactNativeHistoryScope,
+                    });
+                } catch (error: any) {
+                    const fallbackReason = `native_history_error:${error?.message || String(error)}`;
+                    messageSource = buildCliMessageSourceProvenance({
+                        selected: 'pty-parser',
+                        provider: adapter.cliType,
+                        fallbackReason,
+                        ptyMessages: returnedMessages,
+                        returnedMessages,
+                        ptyStatusApprovalOnly: false,
+                    });
+                    nativeHistory = null;
+                }
+
+                if (nativeHistory) {
+                    const nativeMessages = Array.isArray((nativeHistory as any).messages)
+                        ? normalizeNativeHistoryMessages(agentStr, (nativeHistory as any).messages as ChatMessage[])
+                        : [];
+                    const historyProviderSessionId = typeof (nativeHistory as any)?.providerSessionId === 'string'
+                        ? (nativeHistory as any).providerSessionId
+                        : readHistorySessionIdFromMessages(nativeMessages) || nativeHistorySessionId || historySessionId;
+                    const lookup = (nativeHistory as any).lookup === 'workspace' ? 'workspace' : 'session';
+                    const safeMapping = hasSafeNativeHistoryMapping({
+                        historySessionId: lookup === 'workspace' ? undefined : nativeHistorySessionId,
+                        providerSessionId: lookup === 'workspace' ? undefined : historyProviderSessionId || providerSessionId,
+                        workspace,
+                        nativeMessages,
+                        ptyMessages: returnedMessages,
+                        requireWorkspaceContentOverlap: lookup === 'workspace' && !exactNativeHistoryScope,
+                    });
+                    const freshEnough = isNativeHistoryFreshEnough({
+                        sourceMtimeMs: (nativeHistory as any).sourceMtimeMs,
+                        nativeMessages,
+                        ptyMessages: returnedMessages,
+                    });
+                    if ((nativeHistory as any).source === 'provider-native' && nativeMessages.length > 0 && safeMapping && freshEnough) {
+                        selectedMessages = finalizeStreamingMessagesWhenIdle(nativeMessages, returnedStatus);
+                        selectedProviderSessionId = historyProviderSessionId || providerSessionId;
+                        selectedTranscriptAuthority = 'provider';
+                        selectedCoverage = (nativeHistory as any).hasMore ? 'tail' : 'full';
+                        messageSource = buildCliMessageSourceProvenance({
+                            selected: 'native-history',
+                            provider: adapter.cliType,
+                            nativeHandle: selectedProviderSessionId || nativeHistorySessionId || historySessionId,
+                            nativeSource: (nativeHistory as any).source,
+                            sourcePath: (nativeHistory as any).sourcePath,
+                            sourceMtimeMs: (nativeHistory as any).sourceMtimeMs,
+                            nativeMessages,
+                            ptyMessages: returnedMessages,
+                            returnedMessages: selectedMessages,
+                            safeMapping,
+                            freshEnough,
+                            ptyStatusApprovalOnly: true,
+                        });
+                    } else {
+                        const fallbackReason = buildNativeHistoryFallbackReason({
+                            providerType,
+                            provider,
+                            nativeSource: (nativeHistory as any).source,
+                            nativeMessageCount: nativeMessages.length,
+                            safeMapping,
+                            freshEnough,
+                        });
+                        messageSource = buildCliMessageSourceProvenance({
+                            selected: 'pty-parser',
+                            provider: adapter.cliType,
+                            nativeHandle: historyProviderSessionId || nativeHistorySessionId || historySessionId,
+                            fallbackReason,
+                            nativeSource: (nativeHistory as any).source,
+                            sourcePath: (nativeHistory as any).sourcePath,
+                            sourceMtimeMs: (nativeHistory as any).sourceMtimeMs,
+                            nativeMessages,
+                            ptyMessages: returnedMessages,
+                            returnedMessages,
+                            safeMapping,
+                            freshEnough,
+                            ptyStatusApprovalOnly: false,
+                        });
+                    }
+                }
+            }
             LOG.debug('Command', `[read_chat] cli-like parsed provider=${adapter.cliType} target=${String(args?.targetSessionId || '')} adapterStatus=${String(adapterStatus.status || '')} parsedStatus=${String(parsedRecord.status || '')} parsedMsgCount=${parsedRecord.messages.length} returnedMsgCount=${returnedMessages.length}`);
             return buildReadChatCommandResult({
-                messages: returnedMessages,
+                messages: selectedMessages,
                 status: returnedStatus,
                 activeModal,
+                messageSource,
+                transcriptProvenance: messageSource,
                 debugReadChat: {
                     provider: adapter.cliType,
                     targetSessionId: String(args?.targetSessionId || ''),
                     adapterStatus: String(adapterStatus.status || ''),
                     parsedStatus: String(parsedRecord.status || ''),
                     returnedStatus: String(returnedStatus || ''),
-                    shouldPreferAdapterMessages: false,
+                    selectedMessageSource: (messageSource as any).selected,
+                    messageSource,
+                    shouldPreferAdapterMessages: supportsCliNativeTranscript(providerType, provider)
+                        && isNativeSourceCanonicalHistory(provider?.canonicalHistory)
+                        && (messageSource as any).selected !== 'native-history'
+                        && typeof (messageSource as any).fallbackReason === 'string'
+                        && (messageSource as any).fallbackReason.startsWith('native_history_')
+                        && (messageSource as any).fallbackReason !== 'native_history_not_checked'
+                        && !(selectedTranscriptAuthority === 'provider' && selectedCoverage === 'full'),
                     parsedMsgCount: parsedRecord.messages.length,
-                    returnedMsgCount: returnedMessages.length,
+                    returnedMsgCount: selectedMessages.length,
                 },
-                ...(title ? { title } : {}),
-                ...(providerSessionId ? { providerSessionId } : {}),
-                ...(transcriptAuthority ? { transcriptAuthority } : {}),
-                ...(coverage ? { coverage } : {}),
+                ...(selectedTitle ? { title: selectedTitle } : {}),
+                ...(selectedProviderSessionId ? { providerSessionId: selectedProviderSessionId } : {}),
+                ...(selectedTranscriptAuthority ? { transcriptAuthority: selectedTranscriptAuthority } : {}),
+                ...(selectedCoverage ? { coverage: selectedCoverage } : {}),
             }, args);
         }
         const historyLimit = normalizeReadChatTailLimit(args);
@@ -911,7 +1390,25 @@ export async function handleReadChat(h: CommandHelpers, args: any): Promise<Comm
                 : typeof (h.currentSession as any)?.workspace === 'string'
                     ? (h.currentSession as any).workspace
                     : undefined;
-            const history = readProviderChatHistory(agentStr, {
+            const exactNativeHistoryScope = Boolean(
+                (typeof args?.targetSessionId === 'string' && args.targetSessionId.trim())
+                || (typeof args?.historySessionId === 'string' && args.historySessionId.trim())
+                || (typeof args?.providerSessionId === 'string' && args.providerSessionId.trim())
+                || ((h.currentSession as any)?.sessionId === args?.targetSessionId && typeof (h.currentSession as any)?.providerSessionId === 'string' && (h.currentSession as any).providerSessionId.trim())
+            );
+            const history = supportsCliNativeTranscript(agentStr, provider) && isNativeSourceCanonicalHistory(provider?.canonicalHistory)
+                ? readCliProviderNativeHistory(agentStr, {
+                    canonicalHistory: provider?.canonicalHistory,
+                    historySessionId,
+                    workspace,
+                    offset: 0,
+                    limit: historyLimit,
+                    excludeRecentCount: 0,
+                    historyBehavior: provider?.historyBehavior,
+                    scripts: provider?.scripts as any,
+                    exactSessionScoped: exactNativeHistoryScope,
+                })
+                : readProviderChatHistory(agentStr, {
                 canonicalHistory: provider?.canonicalHistory,
                 historySessionId,
                 workspace,
@@ -921,12 +1418,65 @@ export async function handleReadChat(h: CommandHelpers, args: any): Promise<Comm
                 historyBehavior: provider?.historyBehavior,
                 scripts: provider?.scripts as any,
             });
+            const lookup = (history as any).lookup === 'workspace' ? 'workspace' : 'session';
+            const historyMessages = Array.isArray((history as any)?.messages)
+                ? normalizeNativeHistoryMessages(agentStr, (history as any).messages as ChatMessage[])
+                : [];
             const historyProviderSessionId = typeof (history as any)?.providerSessionId === 'string'
                 ? (history as any).providerSessionId
-                : historySessionId;
+                : readHistorySessionIdFromMessages(historyMessages) || historySessionId;
+            const safeMapping = supportsCliNativeTranscript(agentStr, provider)
+                ? hasSafeNativeHistoryMapping({
+                    historySessionId: lookup === 'workspace' ? undefined : historySessionId,
+                    providerSessionId: lookup === 'workspace' ? undefined : historyProviderSessionId,
+                    workspace,
+                    nativeMessages: historyMessages,
+                })
+                : false;
+            const nativeSelected = supportsCliNativeTranscript(agentStr, provider)
+                && (history as any).source === 'provider-native'
+                && historyMessages.length > 0
+                && safeMapping;
+            const messageSource = buildCliMessageSourceProvenance({
+                selected: nativeSelected ? 'native-history' : 'pty-parser',
+                provider: agentStr,
+                nativeHandle: historyProviderSessionId || historySessionId,
+                fallbackReason: nativeSelected
+                    ? undefined
+                    : buildNativeHistoryFallbackReason({
+                        providerType: agentStr,
+                        provider,
+                        nativeSource: (history as any).source,
+                        nativeMessageCount: historyMessages.length,
+                        safeMapping,
+                        freshEnough: true,
+                    }),
+                nativeSource: (history as any).source,
+                sourcePath: (history as any).sourcePath,
+                sourceMtimeMs: (history as any).sourceMtimeMs,
+                nativeMessages: historyMessages,
+                returnedMessages: historyMessages,
+                safeMapping,
+                freshEnough: true,
+                ptyStatusApprovalOnly: false,
+            });
+            const requiresNativeSource = supportsCliNativeTranscript(agentStr, provider)
+                && isNativeSourceCanonicalHistory(provider?.canonicalHistory);
+            if (requiresNativeSource && !nativeSelected) {
+                return {
+                    success: false,
+                    code: 'native_history_not_safely_available',
+                    error: 'Provider-native history was not safely available for the requested CLI session.',
+                    providerSessionId: historyProviderSessionId,
+                    messageSource,
+                    transcriptProvenance: messageSource,
+                };
+            }
             return buildReadChatCommandResult({
-                messages: Array.isArray((history as any)?.messages) ? (history as any).messages : [],
+                messages: historyMessages,
                 status: 'idle',
+                messageSource,
+                transcriptProvenance: messageSource,
                 ...(typeof (history as any)?.title === 'string' ? { title: (history as any).title } : {}),
                 ...(historyProviderSessionId ? { providerSessionId: historyProviderSessionId } : {}),
                 ...(((provider?.historyBehavior as any)?.transcriptAuthority === 'provider' || (provider?.historyBehavior as any)?.transcriptAuthority === 'daemon')