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

package/dist/mesh/beads-db.d.ts

@@ -2,17 +2,71 @@ import type { MeshTaskStatus, MeshWorkQueueEntry } from './mesh-work-queue.js';
 export declare class BeadsDB {
     private static instance;
     private readonly db;
+    private readonly dbPath;
     private readonly migratedMeshIds;
+    private fingerprintSweepCounter;
+    private walWriteCounter;
+    private static readonly WAL_CHECK_INTERVAL;
+    private static readonly WAL_MAX_BYTES;
     private constructor();
     static getInstance(): BeadsDB;
     static resetForTests(): void;
     close(): void;
     transaction<T>(fn: () => T): T;
     private migrate;
+    hasCompletionFingerprint(fingerprint: string): boolean;
+    recordCompletionFingerprint(fingerprint: string, ttlMs: number): void;
+    sweepExpiredFingerprints(): void;
+    private maybeCheckpointWal;
     private ensureLegacyQueueMigrated;
     getQueueEntries(meshId: string, statuses?: MeshTaskStatus[]): MeshWorkQueueEntry[];
     getQueueRevision(meshId: string): string;
     replaceQueue(meshId: string, queue: MeshWorkQueueEntry[]): void;
     deleteQueue(meshId: string): void;
+    insertQueueEntry(entry: MeshWorkQueueEntry): void;
+    updateQueueEntry(entry: MeshWorkQueueEntry): void;
+    findQueueEntryById(meshId: string, id: string): MeshWorkQueueEntry | null;
+    hasActiveAssignment(meshId: string, sessionId: string, nodeId: string): boolean;
+    claimNextQueueTask(meshId: string, nodeId: string, sessionId: string): MeshWorkQueueEntry | null;
+    getQueueStatsByStatus(meshId: string): {
+        status: string;
+        count: number;
+    }[];
+    getActiveAssignmentDetails(meshId: string): Array<{
+        id: string;
+        nodeId?: string;
+        sessionId?: string;
+        message: string;
+    }>;
+    findAssignedBySession(meshId: string, sessionId: string, occurredAtIso?: string): MeshWorkQueueEntry | null;
     private toRow;
+    insertDirectDispatch(entry: {
+        taskId: string;
+        meshId: string;
+        nodeId?: string;
+        sessionId?: string;
+        providerType?: string;
+        message: string;
+        taskMode?: string;
+        via: string;
+        dispatchedToIdleSession?: boolean;
+        dispatchedAt: string;
+    }): void;
+    getActiveDirectDispatches(meshId: string): Array<{
+        taskId: string;
+        meshId: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        message: string;
+        taskMode: string | null;
+        via: string;
+        status: string;
+        dispatchedToIdleSession: boolean;
+        dispatchedAt: string;
+        updatedAt: string;
+    }>;
+    updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale'): void;
+    cleanupTerminalDirectDispatches(olderThanMs: number): void;
+    markStaleDirectDispatches(meshId: string, olderThanMs: number): void;
 }

package/dist/mesh/contracts.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Mesh contract v2 — first-class identity, scopes, and protocol version.
+ *
+ * Replaces the implicit conventions that grew across mesh-events.ts,
+ * mesh-work-queue.ts, mesh-ledger.ts, and mesh-tools.ts where the same
+ * concept (a coordinator, a session, a task status) appeared in different
+ * shapes per file. The audit found:
+ *
+ *   - PendingMeshCoordinatorEvent had no targetCoordinatorDaemonId. All
+ *     events were broadcast to every coordinator that drained them. Two
+ *     coordinators sharing a mesh would each receive every event,
+ *     leading to duplicate completion handling and missed targeting.
+ *   - drainPendingMeshCoordinatorEvents accepted only meshId. The caller's
+ *     coordinator identity was never available, so per-coordinator
+ *     routing was impossible by construction.
+ *   - Session identifier keys diverged across stores: targetSessionId /
+ *     assignedSessionId / instanceId / runtimeSessionId / providerSessionId.
+ *     resolveEventSessionId() tried four fallbacks per call.
+ *   - No protocol version on the JSONL ledger or BeadsDB. Schema
+ *     evolutions had no guard rail.
+ *   - mesh_reconcile_ledger existed as a routine recovery tool, not as
+ *     an incident-response escape hatch. That itself signals the routing
+ *     layer cannot be trusted.
+ *
+ * This module introduces the types; the actual wiring lands in B2 (data
+ * model + 3-way transactional store), B3 (MCP layer enforcement), and B4
+ * (frontend consumption). B1 is intentionally non-breaking — it adds the
+ * types and leaves runtime behaviour unchanged.
+ */
+/** Provider type identifier (e.g. 'claude-cli', 'codex-cli', 'roo-code').
+ *  Free-form string; no shared enum exists in daemon-core yet. */
+type ProviderType = string;
+export declare const MESH_PROTOCOL_VERSION_V1: "1.0";
+export declare const MESH_PROTOCOL_VERSION_V2: "2.0";
+export type MeshProtocolVersion = typeof MESH_PROTOCOL_VERSION_V1 | typeof MESH_PROTOCOL_VERSION_V2;
+export declare const SUPPORTED_MESH_PROTOCOL_VERSIONS: readonly MeshProtocolVersion[];
+export declare function isSupportedMeshProtocolVersion(value: unknown): value is MeshProtocolVersion;
+/**
+ * Identity of a mesh coordinator. Required (non-optional) on every dispatch
+ * and drain operation in v2 — opaque/missing identity is the audit's
+ * smoking gun for routing failures and is structurally banned by the v2
+ * types.
+ *
+ * - daemonId: the machineId of the daemon hosting the coordinator. Stable
+ *   across coordinator restarts on the same machine.
+ * - coordinatorRunId: a UUID generated when the coordinator process starts.
+ *   Stable for the coordinator's lifetime, fresh on restart. Required so
+ *   two coordinators on the same daemon (one CLI, one MCP) can be told
+ *   apart without conflating their drains.
+ * - sessionId: optional CLI coordinator session identifier (instanceId).
+ *   Present when the coordinator is itself a CLI session, absent for
+ *   pure MCP coordinators.
+ */
+export interface CoordinatorIdentity {
+    readonly daemonId: string;
+    readonly coordinatorRunId: string;
+    readonly sessionId?: string;
+}
+export declare function coordinatorIdentityEquals(a: CoordinatorIdentity, b: CoordinatorIdentity): boolean;
+export declare function coordinatorIdentityKey(identity: CoordinatorIdentity): string;
+/**
+ * Unified mesh session identifier. v1 referred to "the session" with five
+ * different field names depending on which store you were reading; v2
+ * collapses them into one explicit handle that carries every disambiguator
+ * a consumer might need.
+ *
+ * - nodeId: the mesh node this session belongs to (FK into mesh node table).
+ * - sessionId: provider-instance identifier (the runtime session id).
+ * - providerType: which provider category/type the session runs (e.g.
+ *   'claude-cli', 'codex-cli', 'roo-code').
+ * - coordinatorDaemonId: which coordinator dispatched the work that
+ *   spawned this session. Used for completion event routing.
+ * - assignedAt: ms epoch when the session was bound to its current task.
+ */
+export interface MeshSessionHandle {
+    readonly nodeId: string;
+    readonly sessionId: string;
+    readonly providerType: ProviderType;
+    readonly coordinatorDaemonId: string;
+    readonly assignedAt: number;
+}
+export declare function meshSessionHandleKey(handle: MeshSessionHandle): string;
+/**
+ * Single canonical task status enum. v1 had at least three overlapping
+ * sets (queue / ledger / direct-dispatch). v2 consumers import from here.
+ */
+export declare const MESH_TASK_STATUSES: readonly ["pending", "assigned", "in_progress", "completed", "failed", "cancelled"];
+export type MeshTaskStatus = typeof MESH_TASK_STATUSES[number];
+export declare function isMeshTaskStatus(value: unknown): value is MeshTaskStatus;
+/**
+ * Explicit scope for pending coordinator events. v1 had no scope: every
+ * event was broadcast to every drainer. v2 forces producers to declare
+ * intent.
+ *
+ * - 'unicast': delivered to exactly one coordinator (intendedFor). Other
+ *   coordinators' drains skip it.
+ * - 'broadcast': delivered to every coordinator on the mesh. Used for
+ *   system-wide signals (e.g. mesh-wide policy changes). The v1 default
+ *   becomes explicit here so audit tools can flag unintended broadcasts.
+ * - 'system': delivered to the daemon-level handler, not coordinators.
+ *   Reserved for infrastructure events that no coordinator should see
+ *   (e.g. ledger reconciliation outcomes).
+ */
+export declare const MESH_EVENT_SCOPES: readonly ["unicast", "broadcast", "system"];
+export type MeshEventScope = typeof MESH_EVENT_SCOPES[number];
+export declare function isMeshEventScope(value: unknown): value is MeshEventScope;
+/**
+ * v2 shape of a pending coordinator event. Strict supersets of the v1
+ * shape — every v1 field is preserved so existing readers do not break;
+ * v2 fields (scope, dispatchedBy, intendedFor, protocolVersion) are
+ * additive and consulted by v2-aware drainers only.
+ *
+ * Mixed v1/v2 events coexist during the rollout window. B2 fully cuts
+ * over once every coordinator drain is v2-aware.
+ */
+export interface PendingMeshCoordinatorEventV2 {
+    readonly event: string;
+    readonly meshId: string;
+    readonly nodeLabel: string;
+    readonly nodeId?: string;
+    readonly workspace?: string;
+    readonly metadataEvent: Record<string, unknown>;
+    readonly coordinatorMessage?: string;
+    readonly queuedAt: number;
+    readonly protocolVersion: MeshProtocolVersion;
+    readonly scope: MeshEventScope;
+    readonly dispatchedBy: CoordinatorIdentity;
+    /**
+     * Required when scope === 'unicast', forbidden otherwise. Drainers MUST
+     * skip unicast events whose intendedFor does not equal their own identity.
+     */
+    readonly intendedFor?: CoordinatorIdentity;
+}
+/**
+ * v2 ledger entry additions. The originatingCoordinator field is the
+ * source of truth that lets completion events route back to the
+ * coordinator that dispatched the task. v1's "worker settings carried it
+ * if it happened to be set" approach is replaced.
+ */
+export interface MeshLedgerOriginatingCoordinatorV2 {
+    readonly originatingCoordinator: CoordinatorIdentity;
+    readonly protocolVersion: MeshProtocolVersion;
+}
+export declare class MeshContractViolationError extends Error {
+    readonly violationPath: string;
+    readonly protocolVersion: MeshProtocolVersion;
+    constructor(protocolVersion: MeshProtocolVersion, violationPath: string, detail: string);
+}
+export declare function assertCoordinatorIdentity(raw: unknown, path: string): CoordinatorIdentity;
+export declare function assertPendingMeshCoordinatorEventV2(raw: unknown, path?: string): PendingMeshCoordinatorEventV2;
+/**
+ * Decide whether a v2 pending event should be delivered to the given drainer.
+ * Centralised so every drain implementation uses the same rule.
+ *
+ *   - 'broadcast': always delivered.
+ *   - 'system': never delivered to coordinators (system handler only).
+ *   - 'unicast': delivered iff intendedFor matches drainer identity.
+ *
+ * v1 events (no scope / no protocolVersion) are treated as broadcast for
+ * backward compatibility during rollout; B3 tightens this so v1 events
+ * are quarantined to a dedicated drain endpoint instead.
+ */
+export declare function shouldDeliverPendingEventToCoordinator(event: PendingMeshCoordinatorEventV2, drainer: CoordinatorIdentity): boolean;
+export {};

package/dist/mesh/mesh-active-work.d.ts

@@ -1,5 +1,5 @@
 import type { MeshLedgerEntry } from './mesh-ledger.js';
-import type { MeshWorkQueueEntry } from './mesh-work-queue.js';
+import type { MeshWorkQueueEntry, DirectDispatchRecord } from './mesh-work-queue.js';
 export type MeshActiveWorkSource = 'queue' | 'direct';
 export type MeshActiveWorkStatus = 'pending' | 'assigned' | 'generating' | 'idle' | 'failed' | 'awaiting_approval';
 export interface MeshActiveWorkRecord {
@@ -64,6 +64,12 @@ export interface BuildMeshActiveWorkOptions {
     meshId: string;
     queue?: MeshWorkQueueEntry[];
     ledgerEntries?: MeshLedgerEntry[];
+    /**
+     * Active direct dispatches from BeadsDB. When provided, these are used instead of
+     * scanning ledger entries for direct dispatches — eliminates the O(n_ledger) scan.
+     * Falls back to ledger scanning when not provided.
+     */
+    directDispatches?: DirectDispatchRecord[];
     nodes?: any[];
     now?: number;
     /** Include terminal direct rows (idle/failed) for handoff/recent-work surfaces. Defaults false. */

package/dist/mesh/mesh-events.d.ts

@@ -8,14 +8,20 @@ export interface PendingMeshCoordinatorEvent {
     metadataEvent: Record<string, unknown>;
     coordinatorMessage?: string;
     queuedAt: number;
+    /**
+     * When set, this event is intended for a specific coordinator daemon.
+     * Coordinators on other daemons should ignore it during drain.
+     * Absent on legacy events — treated as broadcast to any coordinator.
+     */
+    targetCoordinatorDaemonId?: string;
 }
 export declare function queuePendingMeshCoordinatorEvent(event: PendingMeshCoordinatorEvent): boolean;
 /** Drain and return all pending coordinator events for meshId, removing them from disk. */
-export declare function drainPendingMeshCoordinatorEvents(meshId?: string): PendingMeshCoordinatorEvent[];
+export declare function drainPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string): PendingMeshCoordinatorEvent[];
 /** Peek at pending coordinator events without draining (non-destructive). */
-export declare function getPendingMeshCoordinatorEvents(meshId?: string): readonly PendingMeshCoordinatorEvent[];
-/** Explicitly clear all pending coordinator events for a mesh. */
-export declare function clearPendingMeshCoordinatorEvents(meshId?: string): void;
+export declare function getPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string): readonly PendingMeshCoordinatorEvent[];
+/** Explicitly clear all pending coordinator events for a mesh (and coordinator if scoped). */
+export declare function clearPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string): void;
 export declare function tryAssignQueueTask(components: DaemonComponents, meshId: string, nodeId: string, sessionId: string, providerType: string): boolean;
 /**
  * Triggers a queue check for all nodes in the mesh.

package/dist/mesh/mesh-ledger.d.ts

@@ -13,7 +13,7 @@
  * Safety:  mode 0o600, atomic append via appendFileSync
  */
 import { EventEmitter } from 'events';
-export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'session_launched' | 'session_auto_launch' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_joined' | 'node_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled' | 'direct_fast_forward';
+export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'p2p_dispatch_failed' | 'session_launched' | 'session_auto_launch' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_joined' | 'node_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled' | 'direct_fast_forward';
 export interface MeshLedgerEntry {
     id: string;
     meshId: string;
@@ -151,6 +151,26 @@ export interface AppendRemoteLedgerResult {
 }
 export declare const MAX_LEDGER_SLICE_LIMIT = 500;
 export declare function getLedgerDir(): string;
+/**
+ * Footer to append to worker task messages so workers output structured results
+ * that the daemon parses via extractJsonObjectFromSummary / normalizeMeshWorkerResult.
+ *
+ * Usage: append buildWorkerTaskFooter() to the task message in mesh_send_task /
+ * mesh_enqueue_task. The coordinator prompt rules instruct coordinators to do this.
+ */
+export declare function buildWorkerTaskFooter(): string;
+/**
+ * Compact the active ledger file for a mesh by moving old terminal entries
+ * (task_completed, task_failed, task_stalled, recovery_attempted older than 7 days)
+ * to <meshId>.archive.jsonl, keeping the active file lean.
+ *
+ * Non-terminal entries (dispatch, sessions, node lifecycle) are always retained.
+ * Called automatically from appendLedgerEntry when the file exceeds COMPACT_THRESHOLD_BYTES.
+ */
+export declare function compactLedger(meshId: string): {
+    archivedCount: number;
+    retainedCount: number;
+};
 export declare function normalizeMeshWorkerResult(input?: Record<string, unknown>, source?: MeshWorkerResultArtifact['source']): MeshWorkerResultArtifact;
 export declare function buildTaskCompletionEvidence(opts: BuildTaskCompletionEvidenceOptions): MeshTaskCompletionEvidence;
 /**

package/dist/mesh/mesh-refine-status.d.ts

@@ -1,7 +1,8 @@
 import type { MeshLedgerEntry } from './mesh-ledger.js';
 import type { PendingMeshCoordinatorEvent } from './mesh-events.js';
+import type { MeshAsyncJobLifecycle } from '../repo-mesh-types.js';
 export type MeshAsyncRefineJobStatus = 'accepted' | 'running' | 'completed' | 'failed';
-export interface MeshAsyncRefineJobSummary {
+export interface MeshAsyncRefineJobSummary extends MeshAsyncJobLifecycle {
     jobId: string;
     interactionId?: string;
     status: MeshAsyncRefineJobStatus;
@@ -12,8 +13,6 @@ export interface MeshAsyncRefineJobSummary {
     workspace?: string;
     branch?: string;
     into?: string;
-    startedAt?: string;
-    completedAt?: string;
     retryOfJobId?: string;
     lastEvent?: string;
     lastLedgerKind?: string;

package/dist/mesh/mesh-work-queue.d.ts

@@ -1,4 +1,5 @@
 import type { RepoMeshDaemonRole } from '../repo-mesh-types.js';
+import { BeadsDB } from './beads-db.js';
 export type MeshTaskStatus = 'pending' | 'assigned' | 'completed' | 'failed' | 'cancelled';
 export type MeshActiveTaskStatus = Extract<MeshTaskStatus, 'pending' | 'assigned'>;
 export type MeshHistoricalTaskStatus = Extract<MeshTaskStatus, 'completed' | 'failed' | 'cancelled'>;
@@ -127,3 +128,19 @@ export declare function getMeshQueueStats(meshId: string): MeshWorkQueueStats;
 export declare function __replaceMeshQueueForTests(meshId: string, queue: MeshWorkQueueEntry[]): void;
 export declare function __clearMeshQueueForTests(meshId: string): void;
 export declare function __resetBeadsDBForTests(): void;
+export type DirectDispatchRecord = ReturnType<BeadsDB['getActiveDirectDispatches']>[number];
+export declare function insertDirectDispatch(meshId: string, data: {
+    taskId: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    message: string;
+    taskMode?: string;
+    via: string;
+    dispatchedToIdleSession?: boolean;
+    dispatchedAt: string;
+}): void;
+export declare function getActiveDirectDispatches(meshId: string): DirectDispatchRecord[];
+export declare function updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale'): void;
+export declare function cleanupTerminalDirectDispatches(olderThanMs?: number): void;
+export declare function markStaleDirectDispatches(meshId: string, olderThanMs?: number): void;

package/dist/mesh/worktree-bootstrap-config.d.ts

@@ -1,4 +1,5 @@
 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';
 export interface RepoMeshWorktreeBootstrapConfig {
     version: 1;
@@ -8,16 +9,13 @@ export interface RepoMeshWorktreeBootstrapConfig {
     commands?: RepoMeshRefineValidationCommandConfig[];
     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[];
 }

package/dist/providers/contracts.d.ts

@@ -10,6 +10,14 @@ import type { ProviderSummaryMetadata } from '../shared-types.js';
 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;
@@ -590,6 +598,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;
 }
 /**
  * Auto-implement spawn config — controls how the provider is spawned for autonomous AI-driven

package/dist/providers/read-chat-contract.d.ts

@@ -1,2 +1,31 @@
 import type { ReadChatResult } from './contracts.js';
+import { CHAT_CONTRACT_VERSION_V1, CHAT_CONTRACT_VERSION_V2, type ChatContractVersion, type ReadChatResultV2 } from './transcript-v2.js';
+/**
+ * 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 declare function readPayloadContractVersion(raw: unknown): ChatContractVersion;
+/**
+ * Validate a v2 payload. Thin wrapper around assertReadChatResultV2Payload
+ * that prefixes the contract violation with the caller's source label.
+ */
+export declare function validateReadChatResultV2Payload(raw: unknown, source?: string): ReadChatResultV2;
+/**
+ * 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 declare function validateReadChatResultPayloadVersioned(raw: unknown, source?: string): {
+    version: typeof CHAT_CONTRACT_VERSION_V1;
+    payload: ReadChatResult & Record<string, unknown>;
+} | {
+    version: typeof CHAT_CONTRACT_VERSION_V2;
+    payload: ReadChatResultV2;
+};
 export declare function validateReadChatResultPayload(raw: unknown, source?: string): ReadChatResult & Record<string, unknown>;

package/dist/providers/transcript-v2.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Chat Transcript Contract v2
+ *
+ * First-class message identity, monotonic sequence, strict enums. Designed to
+ * replace the v1 contract (contracts.ts ReadChatResult + types.ts ChatMessage)
+ * during the A2 big-bang. This module defines the contract; it does not yet
+ * change runtime behaviour. v1 keeps working until A2 flips the switch.
+ *
+ * Invariants v2 enforces (and v1 does not):
+ *   1. Every ChatMessageV2 has providerUnitKey, bubbleId, sequence — none optional.
+ *   2. sequence is a monotonic integer per (sessionId, source) tuple. Producers
+ *      never reuse it; consumers MAY assume strict ordering.
+ *   3. providerUnitKey is stable across re-reads: the same logical message
+ *      always yields the same key even if its index shifts or content is
+ *      edited mid-stream. Producers derive it from provider-owned identifiers
+ *      (turn id, native message id), not from content hashes or array index.
+ *   4. timestamp is producer-asserted wall-clock; orderingTimestamp is monotonic
+ *      and used for snapshot diffs. 1ms fallback increments are forbidden — if
+ *      a producer cannot supply a stable monotonic value, the daemon assigns
+ *      sequence at ingest and orderingTimestamp = ingestedAt.
+ *   5. visibility / source / role / kind are strict unions. No `(string & {})`
+ *      escape hatches.
+ *   6. Coverage is exactly one of full/tail/current-turn. Mixing it with
+ *      partialReason or unavailableReason is a contract violation.
+ *   7. workspace / sessionId are explicit on every ReadChatResultV2; the daemon
+ *      no longer infers them from message bodies.
+ */
+import type { MessagePart, ToolCallInfo } from './contracts.js';
+export declare const CHAT_CONTRACT_VERSION_V1: "1.0";
+export declare const CHAT_CONTRACT_VERSION_V2: "2.0";
+export type ChatContractVersion = typeof CHAT_CONTRACT_VERSION_V1 | typeof CHAT_CONTRACT_VERSION_V2;
+export declare const SUPPORTED_CHAT_CONTRACT_VERSIONS: readonly ChatContractVersion[];
+export declare const CHAT_ROLES_V2: readonly ["user", "assistant", "system"];
+export type ChatRoleV2 = typeof CHAT_ROLES_V2[number];
+export declare const CHAT_MESSAGE_KINDS_V2: readonly ["standard", "thought", "tool", "terminal", "system"];
+export type ChatMessageKindV2 = typeof CHAT_MESSAGE_KINDS_V2[number];
+export declare const CHAT_VISIBILITIES_V2: readonly ["user", "debug", "internal", "hidden"];
+export type ChatVisibilityV2 = typeof CHAT_VISIBILITIES_V2[number];
+export declare const CHAT_AUDIENCES_V2: readonly ["chat", "debug", "trace", "internal"];
+export type ChatAudienceV2 = typeof CHAT_AUDIENCES_V2[number];
+export declare const CHAT_SOURCES_V2: readonly ["assistant_text", "tool_call", "terminal_command", "runtime_activity", "runtime_status", "provider_chrome", "control"];
+export type ChatSourceV2 = typeof CHAT_SOURCES_V2[number];
+export declare const CHAT_BUBBLE_STATES_V2: readonly ["draft", "streaming", "final", "removed"];
+export type ChatBubbleStateV2 = typeof CHAT_BUBBLE_STATES_V2[number];
+/**
+ * Stable identity of a single chat message. All fields are required in v2.
+ *
+ * - providerUnitKey: provider-owned canonical id. Must be derivable from
+ *   provider primitives (native message id, turn id, bubble id), NOT from
+ *   array index or content hash. Stable across re-reads of the same logical
+ *   message even if neighbours change.
+ * - bubbleId: dashboard-owned bubble identity. May equal providerUnitKey when
+ *   the provider already exposes a bubble-grained id; otherwise daemon
+ *   derives it deterministically from providerUnitKey (e.g. `bubble:${key}`).
+ * - sequence: monotonic integer per (sessionId, source). Strictly increasing
+ *   over the lifetime of the session. Used for snapshot diffs and dedup.
+ * - turnKey: stable identifier for the conversation turn this message belongs
+ *   to. Required so consumers can group messages without re-deriving turns.
+ */
+export interface MessageIdentityV2 {
+    providerUnitKey: string;
+    bubbleId: string;
+    sequence: number;
+    turnKey: string;
+}
+/**
+ * Producer-asserted wall-clock time (ms since epoch). Forward jumps are
+ * permitted; consumers MUST NOT rely on this for ordering.
+ */
+export type ChatTimestampMs = number;
+/**
+ * Monotonic ordering value (ms since epoch, but assigned by the daemon at
+ * ingest to guarantee monotonicity even if the producer's wall clock skews).
+ * Used by snapshot diffs in place of timestamp.
+ */
+export type ChatOrderingTimestampMs = number;
+export interface ChatMessageV2 extends MessageIdentityV2 {
+    role: ChatRoleV2;
+    kind: ChatMessageKindV2;
+    content: string | MessagePart[];
+    bubbleState: ChatBubbleStateV2;
+    timestamp: ChatTimestampMs;
+    orderingTimestamp: ChatOrderingTimestampMs;
+    visibility: ChatVisibilityV2;
+    audience: ChatAudienceV2;
+    source: ChatSourceV2;
+    /** Sender display name (for shared sessions). Empty string when unused. */
+    senderName: string;
+    /** Tool calls associated with this message. Empty array when none. */
+    toolCalls: ToolCallInfo[];
+    /** Producer-defined metadata. Daemon never inspects this except for passthrough. */
+    meta: Readonly<Record<string, unknown>>;
+}
+export interface WorkspaceContextV2 {
+    /** Absolute realpath of the workspace the session is reading from. */
+    workspacePath: string;
+    /** Workspace the session was intended to operate on (may differ during cross-workspace ops). */
+    intendedWorkspacePath: string;
+}
+export interface SessionContextV2 {
+    /** Provider-owned session id (e.g. claude.jsonl uuid, codex session_meta.id). */
+    providerSessionId: string;
+    /** Optional daemon-side history alias used to disambiguate within a workspace. */
+    historySessionId?: string;
+}
+/**
+ * v1 allowed `coverage='full'` to coexist with `partialReason`/`unavailableReason`,
+ * which is a contract lie. v2 makes the three states mutually exclusive.
+ */
+export type CoverageHintV2 = {
+    kind: 'full';
+} | {
+    kind: 'tail';
+    tailMessageCount: number;
+} | {
+    kind: 'current-turn';
+    turnKey: string;
+} | {
+    kind: 'partial';
+    partialReason: string;
+} | {
+    kind: 'unavailable';
+    unavailableReason: string;
+};
+export type CanonicalHistoryModeV2 = 'native-source' | 'disabled' | 'materialized-mirror';
+export interface CanonicalHistoryDeclarationV2 {
+    contractVersion: ChatContractVersion;
+    format: string;
+    mode: CanonicalHistoryModeV2;
+    watchPath?: string;
+    scripts: {
+        readSession: string;
+        listSessions: string;
+    };
+}
+export type ReadChatStatusV2 = 'idle' | 'generating' | 'waiting_approval' | 'error' | 'panel_hidden' | 'streaming';
+export type ReadChatTurnStatusV2 = 'open' | 'waiting_approval' | 'complete' | 'error';
+export interface ReadChatResultV2 {
+    contractVersion: typeof CHAT_CONTRACT_VERSION_V2;
+    workspace: WorkspaceContextV2;
+    session: SessionContextV2;
+    coverage: CoverageHintV2;
+    status: ReadChatStatusV2;
+    messages: ChatMessageV2[];
+    currentTurnId: string;
+    turnStatus: ReadChatTurnStatusV2;
+    transcriptAuthority: 'provider' | 'daemon';
+}
+export declare class ChatContractViolationError extends Error {
+    readonly violationPath: string;
+    readonly contractVersion: ChatContractVersion;
+    constructor(contractVersion: ChatContractVersion, violationPath: string, detail: string);
+}
+/**
+ * Validate a v2 read_chat payload. Throws ChatContractViolationError on the
+ * first violation. v2 invariants beyond per-field checks:
+ *   - messages[*].sequence strictly increasing
+ *   - messages[*].orderingTimestamp monotonic non-decreasing
+ *   - coverage union is well-formed
+ */
+export declare function assertReadChatResultV2Payload(raw: unknown): ReadChatResultV2;
+export declare function isSupportedChatContractVersion(value: unknown): value is ChatContractVersion;
+/**
+ * Read a provider's declared chat contract version from its parsed
+ * provider.json `canonicalHistory.contractVersion` field.
+ *
+ * - Absent or unrecognized → treated as v1 (legacy behaviour preserved during
+ *   the A1 transition). A2 will tighten this to reject unsupported versions
+ *   at provider load time.
+ * - Present and supported → returned as-is.
+ *
+ * The returned version drives which validator (assertReadChatResultV2Payload
+ * vs the legacy validateReadChatResultPayload) processes the provider's
+ * read_chat output.
+ */
+export declare function readDeclaredChatContractVersion(canonicalHistory: unknown): ChatContractVersion;

package/dist/repo-mesh-types.d.ts

@@ -408,3 +408,8 @@ export interface RepoMeshLedgerStatus {
     entries: RepoMeshLedgerEntryStatus[];
     summary: RepoMeshLedgerSummaryStatus;
 }
+export interface MeshAsyncJobLifecycle {
+    startedAt?: string;
+    completedAt?: string;
+    error?: string;
+}

package/dist/shared-types.d.ts

@@ -49,6 +49,13 @@ export interface ReadChatSyncResult {
         message: string;
         buttons: string[];
     } | null;
+    /**
+     * Chat source provenance from ChatSourceMachine (A2). Carries the
+     * selected source, transition cause, lock state, and legacy
+     * fallbackReason — opaque to the daemon-core, consumed by web-core
+     * for the source debug badge and SourceTimeline (A3).
+     */
+    messageSource?: Record<string, unknown>;
 }
 export interface ProviderSummaryItem {
     id: string;