@adhdev/daemon-core 0.9.82-rc.136 → 0.9.82-rc.138

package/src/mesh/mesh-work-queue.ts

@@ -21,10 +21,12 @@ export interface MeshTaskModeValidationResult {
 
 const LIVE_DEBUG_READONLY_FORBIDDEN: Array<{ label: string; pattern: RegExp }> = [
     { label: 'source_edit', pattern: /\b(edit|modify|patch|apply\s+patch|write\s+(?:to\s+)?(?:file|source)|overwrite|delete\s+file|remove\s+file|create\s+file|touch\s+file)\b/i },
-    { label: 'git_mutation', pattern: /\b(?:git\s+(?:add|commit|push|reset|rebase|clean|checkout|switch|merge|tag|restore|rm|mv)|push\b)/i },
+    { label: 'git_mutation', pattern: /\b(?:git\s+(?:add|commit|push|reset|rebase|clean|checkout|switch|merge|tag|restore|rm|mv|stash|worktree\s+(?:add|remove|move))|push\b)/i },
     { label: 'checkpoint', pattern: /\b(checkpoint|mesh_checkpoint)\b/i },
-    { label: 'deploy_or_version_bump', pattern: /\b(deploy|wrangler\s+deploy|version[-\s]?bump|npm\s+version|release)\b/i },
-    { label: 'destructive_shell', pattern: /\b(rm\s+-rf|mv\s+\S+\s+\S+|truncate\s|tee\s+\S+|sed\s+-i)\b/i },
+    { label: 'deploy_or_version_bump', pattern: /\b(deploy|wrangler\s+deploy|version[-\s]?bump|npm\s+version|release|npm\s+publish|yarn\s+publish|pnpm\s+publish)\b/i },
+    { label: 'destructive_shell', pattern: /\b(rm\s+-rf|mv\s+\S+\s+\S+|truncate\s|tee\s+\S+|sed\s+-i|shred\b)\b/i },
+    { label: 'package_install', pattern: /\b(npm\s+(?:install|i|add|link|uninstall|remove)|yarn\s+(?:add|remove|link)|pnpm\s+(?:add|remove|link)|pip\s+install|brew\s+install|apt\s+install|cargo\s+install)\b/i },
+    { label: 'container_mutation', pattern: /\b(docker\s+(?:build|run|exec|push|tag|rmi|rm|create|start|stop|kill)|kubectl\s+(?:apply|delete|patch|replace|create|scale))\b/i },
 ];
 
 export function normalizeMeshTaskMode(value: unknown): MeshTaskMode | undefined {
@@ -122,35 +124,26 @@ export function enqueueTask(
     if (!modeValidation.valid) {
         throw new Error(`live_debug_readonly_guardrail_violation: forbidden operations (${modeValidation.violations.join(', ')})`);
     }
-    return withQueueLock(meshId, () => {
-        const queue = readQueue(meshId);
-        const entry: MeshWorkQueueEntry = {
-            id: randomUUID(),
-            meshId,
-            message,
-            status: 'pending',
-            taskMode: modeValidation.taskMode,
-            targetNodeId: opts?.targetNodeId,
-            targetSessionId: opts?.targetSessionId,
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString(),
-        };
-        queue.push(entry);
-        writeQueue(meshId, queue);
-        return entry;
-    });
+    const entry: MeshWorkQueueEntry = {
+        id: randomUUID(),
+        meshId,
+        message,
+        status: 'pending',
+        taskMode: modeValidation.taskMode,
+        targetNodeId: opts?.targetNodeId,
+        targetSessionId: opts?.targetSessionId,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+    };
+    BeadsDB.getInstance().insertQueueEntry(entry);
+    return entry;
 }
 
 /**
  * Get all tasks in the queue, optionally filtered by status.
  */
 export function getQueue(meshId: string, opts?: { status?: MeshTaskStatus[] }): MeshWorkQueueEntry[] {
-    let queue = readQueue(meshId);
-    if (opts?.status?.length) {
-        const statuses = new Set(opts.status);
-        queue = queue.filter(q => statuses.has(q.status));
-    }
-    return queue;
+    return BeadsDB.getInstance().getQueueEntries(meshId, opts?.status?.length ? opts.status : undefined);
 }
 
 export function getMeshQueueRevision(meshId: string): string {
@@ -161,29 +154,7 @@ export function getMeshQueueRevision(meshId: string): string {
  * Find the next pending task that this node is allowed to claim, and mark it as assigned.
  */
 export function claimNextTask(meshId: string, nodeId: string, sessionId: string): MeshWorkQueueEntry | null {
-    return withQueueLock(meshId, () => {
-        const queue = readQueue(meshId);
-        const hasActiveAssignment = queue.some(q => q.status === 'assigned' && (
-            q.assignedSessionId === sessionId || q.assignedNodeId === nodeId
-        ));
-        if (hasActiveAssignment) return null;
-        let targetIdx = queue.findIndex(q => q.status === 'pending' && q.targetSessionId === sessionId);
-        if (targetIdx === -1) {
-            targetIdx = queue.findIndex(q => q.status === 'pending' && q.targetNodeId === nodeId && !q.targetSessionId);
-        }
-        if (targetIdx === -1) {
-            targetIdx = queue.findIndex(q => q.status === 'pending' && !q.targetNodeId && !q.targetSessionId);
-        }
-        if (targetIdx === -1) return null;
-        const entry = queue[targetIdx];
-        entry.status = 'assigned';
-        entry.assignedNodeId = nodeId;
-        entry.assignedSessionId = sessionId;
-        entry.dispatchTimestamp = new Date().toISOString();
-        entry.updatedAt = new Date().toISOString();
-        writeQueue(meshId, queue);
-        return entry;
-    });
+    return BeadsDB.getInstance().claimNextQueueTask(meshId, nodeId, sessionId);
 }
 
 /**
@@ -198,13 +169,11 @@ export function updateTaskStatus(
 ): MeshWorkQueueEntry | null {
     requireMeshHostQueueOwner(opts);
     return withQueueLock(meshId, () => {
-        const queue = readQueue(meshId);
-        const idx = queue.findIndex(q => q.id === taskId);
-        if (idx === -1) return null;
-        queue[idx].status = status;
-        queue[idx].updatedAt = new Date().toISOString();
-        writeQueue(meshId, queue);
-        return queue[idx];
+        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        if (!entry) return null;
+        entry.status = status;
+        BeadsDB.getInstance().updateQueueEntry(entry);
+        return entry;
     });
 }
 
@@ -214,14 +183,12 @@ export function recordTaskAutoLaunch(
     autoLaunch: Omit<NonNullable<MeshWorkQueueEntry['autoLaunch']>, 'updatedAt'>,
 ): MeshWorkQueueEntry | null {
     return withQueueLock(meshId, () => {
-        const queue = readQueue(meshId);
-        const idx = queue.findIndex(q => q.id === taskId);
-        if (idx === -1) return null;
+        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        if (!entry) return null;
         const now = new Date().toISOString();
-        queue[idx].autoLaunch = { ...autoLaunch, updatedAt: now };
-        queue[idx].updatedAt = now;
-        writeQueue(meshId, queue);
-        return queue[idx];
+        entry.autoLaunch = { ...autoLaunch, updatedAt: now };
+        BeadsDB.getInstance().updateQueueEntry(entry);
+        return entry;
     });
 }
 
@@ -235,16 +202,14 @@ export function cancelTask(
 ): MeshWorkQueueEntry | null {
     requireMeshHostQueueOwner(opts);
     return withQueueLock(meshId, () => {
-        const queue = readQueue(meshId);
-        const idx = queue.findIndex(q => q.id === taskId);
-        if (idx === -1) return null;
+        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        if (!entry) return null;
         const now = new Date().toISOString();
-        queue[idx].status = 'cancelled';
-        queue[idx].updatedAt = now;
-        queue[idx].cancelledAt = now;
-        if (opts?.reason) queue[idx].cancelReason = opts.reason;
-        writeQueue(meshId, queue);
-        return queue[idx];
+        entry.status = 'cancelled';
+        entry.cancelledAt = now;
+        if (opts?.reason) entry.cancelReason = opts.reason;
+        BeadsDB.getInstance().updateQueueEntry(entry);
+        return entry;
     });
 }
 
@@ -265,11 +230,8 @@ export function requeueTask(
 ): MeshWorkQueueEntry | null {
     requireMeshHostQueueOwner(opts);
     return withQueueLock(meshId, () => {
-        const queue = readQueue(meshId);
-        const idx = queue.findIndex(q => q.id === taskId);
-        if (idx === -1) return null;
-        const entry = queue[idx];
-        const now = new Date().toISOString();
+        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        if (!entry) return null;
         entry.status = 'pending';
         delete entry.assignedNodeId;
         delete entry.assignedSessionId;
@@ -279,11 +241,10 @@ export function requeueTask(
         if (typeof opts?.targetNodeId === 'string') entry.targetNodeId = opts.targetNodeId;
         if (opts?.clearTargetSession !== false) delete entry.targetSessionId;
         if (typeof opts?.targetSessionId === 'string') entry.targetSessionId = opts.targetSessionId;
-        entry.updatedAt = now;
-        entry.requeuedAt = now;
+        entry.requeuedAt = new Date().toISOString();
         entry.requeueCount = (entry.requeueCount || 0) + 1;
         if (opts?.reason) entry.requeueReason = opts.reason;
-        writeQueue(meshId, queue);
+        BeadsDB.getInstance().updateQueueEntry(entry);
         return entry;
     });
 }
@@ -298,22 +259,12 @@ export function updateSessionTaskStatus(
     opts?: { occurredAt?: string },
 ): MeshWorkQueueEntry | null {
     return withQueueLock(meshId, () => {
-        const queue = readQueue(meshId);
-        const occurredAtTime = opts?.occurredAt ? new Date(opts.occurredAt).getTime() : Number.NaN;
-        const hasOccurredAt = Number.isFinite(occurredAtTime);
-        let bestIdx = -1;
-        let bestTime = 0;
-        for (let i = queue.length - 1; i >= 0; i--) {
-            if (queue[i].assignedSessionId !== sessionId || queue[i].status !== 'assigned') continue;
-            const time = new Date(queue[i].dispatchTimestamp || queue[i].updatedAt).getTime();
-            if (hasOccurredAt && Number.isFinite(time) && time > occurredAtTime) continue;
-            if (time > bestTime) { bestTime = time; bestIdx = i; }
-        }
-        if (bestIdx === -1) return null;
-        queue[bestIdx].status = status;
-        queue[bestIdx].updatedAt = new Date().toISOString();
-        writeQueue(meshId, queue);
-        return queue[bestIdx];
+        const occurredAtIso = opts?.occurredAt ? new Date(opts.occurredAt).toISOString() : undefined;
+        const entry = BeadsDB.getInstance().findAssignedBySession(meshId, sessionId, occurredAtIso);
+        if (!entry) return null;
+        entry.status = status;
+        BeadsDB.getInstance().updateQueueEntry(entry);
+        return entry;
     });
 }
 
@@ -342,14 +293,16 @@ export interface MeshWorkQueueStats {
  * Return aggregate queue statistics for the given mesh.
  */
 export function getMeshQueueStats(meshId: string): MeshWorkQueueStats {
-    const queue = readQueue(meshId);
-    const pending = queue.filter(q => q.status === 'pending').length;
-    const assigned = queue.filter(q => q.status === 'assigned').length;
-    const completed = queue.filter(q => q.status === 'completed').length;
-    const failed = queue.filter(q => q.status === 'failed').length;
-    const cancelled = queue.filter(q => q.status === 'cancelled').length;
+    const rows = BeadsDB.getInstance().getQueueStatsByStatus(meshId);
+    const counts: Record<string, number> = {};
+    for (const r of rows) counts[r.status] = r.count;
+    const pending = counts['pending'] ?? 0;
+    const assigned = counts['assigned'] ?? 0;
+    const completed = counts['completed'] ?? 0;
+    const failed = counts['failed'] ?? 0;
+    const cancelled = counts['cancelled'] ?? 0;
     return {
-        total: queue.length,
+        total: pending + assigned + completed + failed + cancelled,
         active: pending + assigned,
         historical: completed + failed + cancelled,
         pending,
@@ -357,23 +310,9 @@ export function getMeshQueueStats(meshId: string): MeshWorkQueueStats {
         completed,
         failed,
         cancelled,
-        activeCounts: {
-            pending,
-            assigned,
-        },
-        historicalCounts: {
-            completed,
-            failed,
-            cancelled,
-        },
-        activeAssignments: queue
-            .filter(q => q.status === 'assigned')
-            .map(q => ({
-                id: q.id,
-                nodeId: q.assignedNodeId,
-                sessionId: q.assignedSessionId,
-                message: q.message,
-            })),
+        activeCounts: { pending, assigned },
+        historicalCounts: { completed, failed, cancelled },
+        activeAssignments: BeadsDB.getInstance().getActiveAssignmentDetails(meshId),
     };
 }
 
@@ -390,3 +329,60 @@ export function __clearMeshQueueForTests(meshId: string): void {
 export function __resetBeadsDBForTests(): void {
     BeadsDB.resetForTests();
 }
+
+// ── Direct Dispatch Tracking ─────────────────────────────────────────────────
+// Persists direct (non-queue) task dispatches so buildMeshActiveWork can read
+// active work from BeadsDB instead of scanning ledger JSONL entries.
+
+export type DirectDispatchRecord = ReturnType<BeadsDB['getActiveDirectDispatches']>[number];
+
+export function insertDirectDispatch(
+    meshId: string,
+    data: {
+        taskId: string;
+        nodeId?: string;
+        sessionId?: string;
+        providerType?: string;
+        message: string;
+        taskMode?: string;
+        via: string;
+        dispatchedToIdleSession?: boolean;
+        dispatchedAt: string;
+    },
+): void {
+    try {
+        BeadsDB.getInstance().insertDirectDispatch({ ...data, meshId });
+    } catch (e: any) {
+        process.stderr.write(`[adhdev-mesh] insertDirectDispatch failed for task ${data.taskId}: ${e?.message || e}\n`);
+    }
+}
+
+export function getActiveDirectDispatches(meshId: string): DirectDispatchRecord[] {
+    try {
+        return BeadsDB.getInstance().getActiveDirectDispatches(meshId);
+    } catch {
+        return [];
+    }
+}
+
+export function updateDirectDispatchStatus(
+    meshId: string,
+    sessionId: string,
+    status: 'acked' | 'completed' | 'failed' | 'stale',
+): void {
+    try {
+        BeadsDB.getInstance().updateDirectDispatchStatus(meshId, sessionId, status);
+    } catch { /* best-effort */ }
+}
+
+export function cleanupTerminalDirectDispatches(olderThanMs = 7 * 24 * 60 * 60_000): void {
+    try {
+        BeadsDB.getInstance().cleanupTerminalDirectDispatches(olderThanMs);
+    } catch { /* best-effort */ }
+}
+
+export function markStaleDirectDispatches(meshId: string, olderThanMs = 60 * 60_000): void {
+    try {
+        BeadsDB.getInstance().markStaleDirectDispatches(meshId, olderThanMs);
+    } catch { /* best-effort */ }
+}

package/src/mesh/worktree-bootstrap-config.ts

@@ -9,6 +9,7 @@ import {
     type MeshRefineValidationCommandPlan,
     type RepoMeshRefineValidationCommandConfig,
 } from './refine-config.js';
+import type { MeshAsyncJobLifecycle } from '../repo-mesh-types.js';
 
 export type WorktreeBootstrapStatus = 'ready' | 'running' | 'failed' | 'not_configured' | 'disabled' | 'stale';
 
@@ -21,16 +22,13 @@ export interface RepoMeshWorktreeBootstrapConfig {
     staleInputs?: string[];
 }
 
-export interface WorktreeBootstrapState {
+export interface WorktreeBootstrapState extends MeshAsyncJobLifecycle {
     status: WorktreeBootstrapStatus;
     required: boolean;
     configSource?: string;
     configSourceType?: 'repo_file' | 'mesh_policy' | 'unavailable' | 'invalid';
-    startedAt?: string;
-    completedAt?: string;
     lastCommand?: string;
     exitCode?: number | null;
-    error?: string;
     commandsRun?: Array<Record<string, unknown>>;
     staleInputs?: string[];
 }
@@ -177,7 +175,22 @@ export async function runMeshWorktreeBootstrap(mesh: any, workspace: string): Pr
         commandsRun: [],
         staleInputs: loaded.config.staleInputs,
     };
+    const staleInputPaths = loaded.config.staleInputs ?? [];
+    // Snapshot which staleInputs files are absent at bootstrap start.
+    // Files already present before we start are not interference signals.
+    const initiallyAbsent = staleInputPaths.filter(p => !existsSync(join(workspace, p)));
     for (const command of validation.commands) {
+        // Check if any initially-absent staleInputs files appeared since bootstrap started
+        // (indicates another process modified the environment mid-run).
+        if (initiallyAbsent.length > 0) {
+            const appearedNow = initiallyAbsent.filter(p => existsSync(join(workspace, p)));
+            if (appearedNow.length > 0) {
+                state.status = 'stale';
+                state.completedAt = new Date().toISOString();
+                state.error = `Bootstrap interrupted: staleInputs files appeared during run: ${appearedNow.join(', ')}`;
+                return state;
+            }
+        }
         const cwd = command.cwd ? pathResolve(workspace, command.cwd) : workspace;
         const startedAt = Date.now();
         state.lastCommand = command.displayCommand;

package/src/providers/contracts.ts

@@ -15,6 +15,14 @@ import type { ChatMessageKind } from './chat-message-normalization.js';
 export type ReadChatTurnStatus = 'open' | 'waiting_approval' | 'complete' | 'error';
 
 export interface ReadChatResult {
+  /**
+   * Declared chat contract version. Absent or `'1.0'` → legacy v1 payload
+   * (current shape). `'2.0'` → v2 payload conforming to transcript-v2.ts
+   * (ReadChatResultV2). Validators in read-chat-contract.ts route on this
+   * field. A1 only adds the field; A2 will make v2 the daemon-internal
+   * canonical form and reject unrecognised versions at provider load time.
+   */
+  contractVersion?: import('./transcript-v2.js').ChatContractVersion;
   messages: ChatMessage[];
   status: AgentStatus;
   activeModal?: ModalInfo | null;
@@ -702,6 +710,17 @@ export interface ProviderCanonicalHistoryConfig {
    * Omitted mode defaults to 'native-source'.
    */
   mode?: 'native-source' | 'materialized-mirror' | 'disabled';
+  /**
+   * Chat transcript contract version this provider's read_chat output
+   * conforms to. See transcript-v2.ts for the v2 invariants. Absent or `'1.0'`
+   * → legacy v1 payload (current behaviour). `'2.0'` → strict v2 payload
+   * (stable providerUnitKey/bubbleId/sequence, strict enums, honest coverage).
+   *
+   * A1 only surfaces this field; validators in read-chat-contract.ts route
+   * on it. A2 makes v2 the daemon-internal canonical form and rejects
+   * unrecognised values at provider load time.
+   */
+  contractVersion?: import('./transcript-v2.js').ChatContractVersion;
 }
 
 /**

package/src/providers/provider-loader.ts

@@ -1378,11 +1378,15 @@ export class ProviderLoader {
       return args ? args.map((arg) => /\s/.test(arg) ? JSON.stringify(arg) : arg).join(' ') : '';
     }
     const schemaDef = this.getSettingsSchema(providerType)[key];
-    const defaultVal = schemaDef
-      ? (key === 'autoApprove' && schemaDef.type === 'boolean'
-        ? true
-        : schemaDef.default)
-      : undefined;
+    // (fix) Previously this hard-coded `autoApprove` boolean default to `true`,
+    // overriding whatever schemaDef.default the provider.json declared. That
+    // surfaced as soon as a provider added an `autoApprove` schema entry with
+    // default=false: the user had never opted in but the daemon treated the
+    // session as auto-approve, which then triggered recordAutoApproval every
+    // time the CLI showed an approval modal — producing a flood of system
+    // "Auto-approved: ..." messages and keeping the session pinned to
+    // generating while modals cycled in and out. Trust the schemaDef.default.
+    const defaultVal = schemaDef ? schemaDef.default : undefined;
 
     const config = this.readConfig();
     const userVal = config?.providerSettings?.[providerType]?.[key];
@@ -1496,10 +1500,17 @@ export class ProviderLoader {
       ...this.getSyntheticSettings(type, provider),
       ...(provider.settings || {}),
     };
+    // (fix) Previously this clause forced `autoApprove.default = true` for any
+    // boolean autoApprove schema, even when the provider.json explicitly set
+    // `default: false`. Combined with the synthetic-settings fallback at
+    // getSyntheticSettings (which also defaults autoApprove to true when the
+    // provider doesn't supply one), that meant CLI providers silently turned on
+    // auto-approval, producing a flood of "Auto-approved: ..." system messages
+    // every time an approval modal appeared and pinning the session to
+    // generating while modals cycled. Trust the provider's declared default.
     if (result.autoApprove?.type === 'boolean') {
       result.autoApprove = {
         ...result.autoApprove,
-        default: true,
         public: true,
         label: result.autoApprove.label || 'Auto Approve',
         description: result.autoApprove.description || 'Automatically approve actionable prompts without sending approval alerts.',
@@ -1524,7 +1535,10 @@ export class ProviderLoader {
     if (!provider.settings?.autoApprove) {
       result.autoApprove = {
         type: 'boolean',
-        default: true,
+        // (fix) Safe default is *off*. Auto-approving every modal without the
+        // user opting in produced silent-bash-execution surprises and the
+        // "Auto-approved: ..." system-message flood seen on AGY/Codex.
+        default: false,
         public: true,
         label: 'Auto Approve',
         description: 'Automatically approve actionable prompts without sending approval alerts.',

package/src/providers/provider-schema.ts

@@ -64,6 +64,8 @@ const KNOWN_PROVIDER_FIELDS = new Set<string>([
   'sendKey',
   'submitStrategy',
   'requirePromptEchoBeforeSubmit',
+  'requiresFinalAssistantBeforeIdle',
+  'augmentStaleSnapshot',
   'timeouts',
   'disableUpstream',
 ])
@@ -251,6 +253,16 @@ function validateCanonicalHistory(raw: unknown, errors: string[]): void {
     errors.push('canonicalHistory.mode must be one of: native-source, materialized-mirror, disabled')
   }
 
+  // Chat transcript contract version (transcript-v2.ts). Absent → treated as
+  // v1 by readDeclaredChatContractVersion(). A2 will reject unrecognised
+  // values at load time; A1 only validates the field shape.
+  const chatContractVersion = canonicalHistory.contractVersion
+  if (chatContractVersion !== undefined
+      && chatContractVersion !== '1.0'
+      && chatContractVersion !== '2.0') {
+    errors.push(`canonicalHistory.contractVersion must be '1.0' or '2.0' when provided (got ${JSON.stringify(chatContractVersion)})`)
+  }
+
   const scripts = canonicalHistory.scripts
   if (scripts === undefined) return
   if (!scripts || typeof scripts !== 'object' || Array.isArray(scripts)) {

package/src/providers/read-chat-contract.ts

@@ -1,6 +1,14 @@
 import type { MessagePart, ModalInfo, ReadChatResult } from './contracts.js'
 import { normalizeMessageParts } from './contracts.js'
 import type { ChatBubbleState, ChatMessage } from '../types.js'
+import {
+  CHAT_CONTRACT_VERSION_V1,
+  CHAT_CONTRACT_VERSION_V2,
+  assertReadChatResultV2Payload,
+  isSupportedChatContractVersion,
+  type ChatContractVersion,
+  type ReadChatResultV2,
+} from './transcript-v2.js'
 
 const VALID_STATUSES = ['idle', 'generating', 'waiting_approval', 'error', 'panel_hidden', 'starting', 'streaming', 'long_generating'] as const
 const VALID_ROLES = ['user', 'assistant', 'system', 'human'] as const
@@ -63,7 +71,7 @@ function validateMessage(message: unknown, source: string, index: number): ChatM
     content: validateMessageContent(message.content, source, index),
   }
 
-  if (typeof message.kind === 'string') normalized.kind = message.kind as any
+  if (typeof message.kind === 'string') normalized.kind = message.kind as ChatMessage['kind']
   if (typeof message.id === 'string') normalized.id = message.id
   if (typeof message.bubbleId === 'string') normalized.bubbleId = message.bubbleId
   if (typeof message.providerUnitKey === 'string') normalized.providerUnitKey = message.providerUnitKey
@@ -71,20 +79,23 @@ function validateMessage(message: unknown, source: string, index: number): ChatM
   if (isFiniteNumber(message.index)) normalized.index = message.index
   if (isFiniteNumber(message.timestamp)) normalized.timestamp = message.timestamp
   if (isFiniteNumber(message.receivedAt)) normalized.receivedAt = message.receivedAt
-  if (typeof (message as any)._turnKey === 'string') normalized._turnKey = (message as any)._turnKey
-  if (Array.isArray(message.toolCalls)) normalized.toolCalls = message.toolCalls as any
-  if (isPlainObject(message.meta)) normalized.meta = message.meta as any
+  // (A2.3) sequence is the monotonic ordering key consumed by ChatSourceMachine.
+  // v1 producers omit it; the daemon derives it in normalizeNativeHistoryMessages.
+  if (isFiniteNumber(message.sequence)) normalized.sequence = message.sequence
+  if (typeof message._turnKey === 'string') normalized._turnKey = message._turnKey
+  if (Array.isArray(message.toolCalls)) normalized.toolCalls = message.toolCalls as ChatMessage['toolCalls']
+  if (isPlainObject(message.meta)) normalized.meta = message.meta as ChatMessage['meta']
   if (typeof message.senderName === 'string') normalized.senderName = message.senderName
-  if (typeof (message as any)._type === 'string') normalized._type = (message as any)._type
-  if (typeof (message as any)._sub === 'string') normalized._sub = (message as any)._sub
-  if (typeof (message as any).visibility === 'string') normalized.visibility = (message as any).visibility
-  if (typeof (message as any).transcriptVisibility === 'string') normalized.transcriptVisibility = (message as any).transcriptVisibility
-  if (typeof (message as any).audience === 'string') normalized.audience = (message as any).audience
-  if (typeof (message as any).source === 'string') normalized.source = (message as any).source
-  if (typeof (message as any).userFacing === 'boolean') normalized.userFacing = (message as any).userFacing
-  if (typeof (message as any).internal === 'boolean') normalized.internal = (message as any).internal
-  if (typeof (message as any).isInternal === 'boolean') normalized.isInternal = (message as any).isInternal
-  if (typeof (message as any).debug === 'boolean') normalized.debug = (message as any).debug
+  if (typeof message._type === 'string') normalized._type = message._type
+  if (typeof message._sub === 'string') normalized._sub = message._sub
+  if (typeof message.visibility === 'string') normalized.visibility = message.visibility
+  if (typeof message.transcriptVisibility === 'string') normalized.transcriptVisibility = message.transcriptVisibility
+  if (typeof message.audience === 'string') normalized.audience = message.audience
+  if (typeof message.source === 'string') normalized.source = message.source
+  if (typeof message.userFacing === 'boolean') normalized.userFacing = message.userFacing
+  if (typeof message.internal === 'boolean') normalized.internal = message.internal
+  if (typeof message.isInternal === 'boolean') normalized.isInternal = message.isInternal
+  if (typeof message.debug === 'boolean') normalized.debug = message.debug
 
   return normalized
 }
@@ -129,6 +140,55 @@ function validateControlValues(controlValues: unknown, source: string): Record<s
   return normalized
 }
 
+/**
+ * Read the producer-declared contract version from a raw read_chat payload.
+ * Returns v1 when absent or unrecognised, so legacy producers keep working
+ * through A1. A2 will tighten this to throw when an unsupported version is
+ * declared.
+ */
+export function readPayloadContractVersion(raw: unknown): ChatContractVersion {
+  if (!isPlainObject(raw)) return CHAT_CONTRACT_VERSION_V1
+  const declared = (raw as Record<string, unknown>).contractVersion
+  if (isSupportedChatContractVersion(declared)) return declared
+  return CHAT_CONTRACT_VERSION_V1
+}
+
+/**
+ * Validate a v2 payload. Thin wrapper around assertReadChatResultV2Payload
+ * that prefixes the contract violation with the caller's source label.
+ */
+export function validateReadChatResultV2Payload(raw: unknown, source = 'read_chat'): ReadChatResultV2 {
+  try {
+    return assertReadChatResultV2Payload(raw)
+  } catch (err) {
+    if (err instanceof Error) {
+      err.message = `${source}: ${err.message}`
+    }
+    throw err
+  }
+}
+
+/**
+ * Versioned entry point. Routes on the producer-declared contractVersion:
+ *   - v2 → strict v2 validation (transcript-v2.ts invariants)
+ *   - v1 (or absent) → legacy permissive validation
+ *
+ * Callers that have not yet been audited to handle v2 outputs should use
+ * validateReadChatResultPayload directly; that path stays bound to v1 shape
+ * during the A1 transition.
+ */
+export function validateReadChatResultPayloadVersioned(
+  raw: unknown,
+  source = 'read_chat',
+): { version: typeof CHAT_CONTRACT_VERSION_V1; payload: ReadChatResult & Record<string, unknown> }
+  | { version: typeof CHAT_CONTRACT_VERSION_V2; payload: ReadChatResultV2 } {
+  const version = readPayloadContractVersion(raw)
+  if (version === CHAT_CONTRACT_VERSION_V2) {
+    return { version, payload: validateReadChatResultV2Payload(raw, source) }
+  }
+  return { version: CHAT_CONTRACT_VERSION_V1, payload: validateReadChatResultPayload(raw, source) }
+}
+
 export function validateReadChatResultPayload(raw: unknown, source = 'read_chat'): ReadChatResult & Record<string, unknown> {
   if (!isPlainObject(raw)) {
     throw new Error(`${source}: payload must be an object`)