@adhdev/daemon-core 0.9.82-rc.37 → 0.9.82-rc.370

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

@@ -1,4 +1,24 @@
-import type { AppendRemoteLedgerResult, MeshLedgerSlice, MeshLedgerSummary } from './mesh-ledger.js';
+import type { AppendRemoteLedgerResult, MeshLedgerSummary } from './mesh-ledger.js';
+/** Minimal ledger slice shape accepted by buildMeshLedgerReplicaEvidence. Covers both JSONL and SQLite slices. */
+export interface AnyLedgerSlice {
+    entries: Array<{
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId?: string | null;
+        sessionId?: string | null;
+        providerType?: string | null;
+        payload: unknown;
+    }>;
+    cursor: {
+        afterId: string | null;
+        nextAfterId: string | null;
+        limit: number;
+        hasMore: boolean;
+    };
+    summary?: MeshLedgerSummary;
+}
 export type MeshLedgerReplicaStatus = 'local' | 'queried' | 'imported' | 'failed';
 export interface MeshLedgerReplicaEvidence {
     nodeId: string;
@@ -22,7 +42,7 @@ export interface MeshLedgerReconciliationEvidence {
     meshId: string;
     generatedAt: string;
     sourceOfTruth: {
-        kind: 'coordinator_local_jsonl';
+        kind: 'coordinator_local_sqlite';
         p2pOnly: true;
         cloudD1LedgerSync: false;
         notes: string;
@@ -47,7 +67,7 @@ export declare function buildMeshLedgerReplicaEvidence(args: {
     nodeId: string;
     daemonId?: string;
     transport: 'local' | 'p2p_datachannel';
-    slice?: MeshLedgerSlice;
+    slice?: AnyLedgerSlice;
     importResult?: AppendRemoteLedgerResult;
     status?: MeshLedgerReplicaStatus;
     error?: string;

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

@@ -13,7 +13,8 @@
  * 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_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled';
+import { MeshRuntimeStore } from './mesh-runtime-store.js';
+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' | 'delivery_unroutable' | 'direct_dispatch_pruned' | 'event_held' | 'task_reclaimed';
 export interface MeshLedgerEntry {
     id: string;
     meshId: string;
@@ -25,6 +26,40 @@ export interface MeshLedgerEntry {
     payload: Record<string, unknown>;
 }
 export declare function isIntentionalCleanupStopEntry(entry: Pick<MeshLedgerEntry, 'kind' | 'payload'>): boolean;
+export type MeshWorkerResultStatus = 'completed' | 'failed' | 'blocked' | 'partial' | 'unknown';
+export type MeshProcessArtifactKind = 'process' | 'log' | 'port' | 'window' | 'session' | 'file' | 'url' | 'other';
+export interface MeshValidationResultArtifact {
+    command?: string;
+    status: 'passed' | 'failed' | 'skipped' | 'unknown';
+    durationMs?: number;
+    outputPath?: string;
+    summary?: string;
+}
+export interface MeshProcessArtifact {
+    kind: MeshProcessArtifactKind;
+    id?: string;
+    label?: string;
+    locator?: string;
+    pid?: number;
+    port?: number;
+    url?: string;
+    path?: string;
+    sessionId?: string;
+    keepRunning?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface MeshWorkerResultArtifact {
+    status: MeshWorkerResultStatus;
+    classification?: string;
+    changedFiles: string[];
+    validationResults: MeshValidationResultArtifact[];
+    gitStatus?: Record<string, unknown>;
+    processArtifacts: MeshProcessArtifact[];
+    errors: string[];
+    nextAction?: string;
+    requiresUserAction: boolean;
+    source: 'explicit_metadata' | 'final_summary_json' | 'default';
+}
 export interface MeshTaskCompletionEvidence {
     source: 'agent_status_event';
     event: 'agent:generating_completed' | 'agent:ready';
@@ -38,6 +73,7 @@ export interface MeshTaskCompletionEvidence {
         providerSessionId?: string;
         finalSummaryAvailable: boolean;
     };
+    workerResult: MeshWorkerResultArtifact;
     git: {
         status: 'deferred';
         reason: string;
@@ -59,6 +95,7 @@ export interface BuildTaskCompletionEvidenceOptions {
     providerType?: string;
     providerSessionId?: string;
     finalSummary?: string;
+    workerResult?: Record<string, unknown>;
     completedAt?: string;
 }
 export interface MeshLedgerSummary {
@@ -115,6 +152,27 @@ 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;
 /**
  * Append a new entry to the mesh ledger.
@@ -127,8 +185,16 @@ export declare function appendLedgerEntry(meshId: string, partial: Omit<MeshLedg
  * This skips deduplicated entries and rejects malformed/cross-mesh entries.
  */
 export declare function appendRemoteLedgerEntries(meshId: string, entries: MeshLedgerEntry[]): AppendRemoteLedgerResult;
+/**
+ * Test helper: clear all runtime ledger state for a mesh — SQLite rows, read
+ * cache, and the one-time import flag. JSONL files are the caller's concern.
+ */
+export declare function __clearMeshLedgerForTests(meshId: string): void;
 /**
  * Read ledger entries with optional filtering.
+ * G2: SQLite (mesh_event_ledger) is the primary read path; legacy JSONL is
+ * imported once per store instance and otherwise retained as an
+ * export/import/debug artifact only.
  */
 export declare function readLedgerEntries(meshId: string, opts?: ReadLedgerOptions): MeshLedgerEntry[];
 /**
@@ -137,6 +203,16 @@ export declare function readLedgerEntries(meshId: string, opts?: ReadLedgerOptio
  * remote daemons on demand without Cloud/D1 becoming a ledger data-plane.
  */
 export declare function readLedgerSlice(meshId: string, opts?: ReadLedgerSliceOptions): MeshLedgerSlice;
+/**
+ * G4: Read a bounded ledger slice from the SQLite mesh_event_ledger table.
+ * This is the preferred P2P reconcile read path; JSONL files are retained as
+ * export/import/debug/legacy artifacts only.
+ *
+ * Returns a shape structurally compatible with MeshLedgerSlice (minus the
+ * JSONL-specific `summary` and `sourceOfTruth.path` fields) so callers can
+ * pass it to buildMeshLedgerReplicaEvidence without modification.
+ */
+export declare function readLedgerSliceFromStore(meshId: string, opts?: ReadLedgerSliceOptions): ReturnType<typeof MeshRuntimeStore.prototype.readLedgerSlice>;
 /**
  * Get a summary of mesh activity from the ledger.
  */

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

@@ -0,0 +1,164 @@
+/**
+ * M3: Mission persistence (minimal form).
+ *
+ * A mission is a persistent record of a multi-task goal so the plan lives in
+ * the system rather than in the coordinator LLM's context. Coordinator
+ * sessions can die or compact; a new coordinator reads the mission back at
+ * launch and continues.
+ *
+ * Explicit non-goals (see docs/mesh-product-plan-v2.md Phase M3): this is not
+ * a workflow engine and there is no automatic takeover daemon. Progress is
+ * never stored — it is derived from queue task statuses (mission_id) at
+ * query time.
+ */
+import { type MeshMissionStats } from './mesh-task-stats.js';
+export type MeshMissionStatus = 'active' | 'paused' | 'completed' | 'abandoned';
+export declare const MESH_MISSION_STATUSES: MeshMissionStatus[];
+export interface MeshMissionRecord {
+    id: string;
+    meshId: string;
+    title: string;
+    goal: string;
+    status: MeshMissionStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MeshMissionTaskAggregate {
+    total: number;
+    pending: number;
+    assigned: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    /** Pending tasks held back by a dependency failure (blockedReason set). */
+    blocked: number;
+    /** Latest updatedAt across the mission's tasks, or null with no tasks. */
+    lastActivityAt: string | null;
+}
+export interface MeshMissionSummary extends MeshMissionRecord {
+    tasks: MeshMissionTaskAggregate;
+    /**
+     * Operational rollup (durations / attempts) derived from the ledger via
+     * computeMeshMissionStats. Optional: only populated by surfaces that opt in
+     * (e.g. mesh_status), since the rollup scans a bounded ledger tail per
+     * mission. Absent on the lightweight task-aggregate-only summaries.
+     */
+    stats?: MeshMissionStats;
+}
+/**
+ * Slim mission summary for the mesh_status compact (default) surface. Drops the
+ * full `goal` text — which can be hundreds of chars per mission and is repeated
+ * for every mission on every status call — keeping only a short preview plus a
+ * `goalTruncated` flag when the original was longer. The stored goal is never
+ * mutated; this is an output-only projection. Coordinators that need the full
+ * goal call mesh_status with verbose=true, or read the mission directly via
+ * mesh_mission_upsert / getMeshMission.
+ */
+export interface MeshMissionSlimSummary extends Omit<MeshMissionSummary, 'goal'> {
+    /** Short preview of the goal (≤ GOAL_PREVIEW_MAX chars), '' when goal empty. */
+    goalPreview: string;
+    /** True when the stored goal was longer than the preview (full text elided). */
+    goalTruncated: boolean;
+}
+/** Max chars of goal text retained in the slim (compact) mission summary. */
+export declare const GOAL_PREVIEW_MAX = 120;
+/**
+ * Shorter goal preview used by the mesh_status compact (LLM coordinator) surface.
+ * The coordinator only needs to recognize a mission, not read its full goal, and
+ * mesh_status repeats every live mission on every poll — so the status preview is
+ * tighter than the dashboard / mesh_mission_list preview (GOAL_PREVIEW_MAX).
+ */
+export declare const COMPACT_STATUS_GOAL_PREVIEW_MAX = 80;
+export declare function upsertMeshMission(meshId: string, input: {
+    id?: string;
+    title: string;
+    goal?: string;
+    status?: string;
+}): MeshMissionRecord;
+export declare function getMeshMissions(meshId: string, statuses?: MeshMissionStatus[]): MeshMissionRecord[];
+export declare function getMeshMission(meshId: string, missionId: string): MeshMissionRecord | null;
+/** Aggregate task statuses for a mission at query time (no stored progress). */
+export declare function summarizeMissionTasks(meshId: string, missionId: string): MeshMissionTaskAggregate;
+export declare function summarizeMeshMission(meshId: string, mission: MeshMissionRecord): MeshMissionSummary;
+/** Active mission summaries for mesh_status / coordinator prompt injection. */
+export declare function getActiveMeshMissionSummaries(meshId: string): MeshMissionSummary[];
+/**
+ * Mission summaries for the mesh_status dashboard surface: every active/paused
+ * mission plus a capped, newest-first slice of completed/abandoned history so
+ * the dashboard can render a collapsible "history" section without unbounded
+ * payload growth. Returned newest-first within each group (active/paused first,
+ * then history), so the frontend can split on `status` directly.
+ *
+ * Compact mode (the default) elides each mission's full `goal` text — which is
+ * repeated verbatim on every status poll and dominates the payload when a mesh
+ * has many missions — returning only a short `goalPreview` + `goalTruncated`
+ * flag. Pass `verbose: true` to get the full `goal` text per mission. The stored
+ * goal is untouched in both modes; this is an output-only projection.
+ */
+export declare function getMeshStatusMissionSummaries(meshId: string, options?: {
+    historyLimit?: number;
+    verbose?: boolean;
+    withStats?: boolean;
+}): MeshMissionSummary[] | MeshMissionSlimSummary[];
+/** Folded completed/abandoned history for the mesh_status compact surface. */
+export interface MeshStatusMissionsHistoryFold {
+    /** Total completed + abandoned missions. */
+    count: number;
+    /** Count by lifecycle status (e.g. { completed, abandoned }). */
+    byStatus: Record<string, number>;
+    /** Newest-first id list (capped) so each folded mission stays addressable. */
+    missionIds: string[];
+    note: string;
+}
+/** Compact mesh_status mission projection: live detail + folded history. */
+export interface MeshStatusMissionsCompact {
+    /**
+     * Active + paused missions, goal-elided to COMPACT_STATUS_GOAL_PREVIEW_MAX and
+     * WITHOUT the operational `stats` rollup — the `tasks` aggregate already carries
+     * progress, and stats (durations/retries) is a verbose/dashboard concern.
+     */
+    live: MeshMissionSlimSummary[];
+    /** Completed + abandoned missions folded to counts + ids; null when none. */
+    historyFold: MeshStatusMissionsHistoryFold | null;
+}
+/**
+ * Mission projection for the mesh_status COMPACT (LLM coordinator) surface.
+ *
+ * Unlike getMeshStatusMissionSummaries (which emits every live mission plus a
+ * capped slice of full-detail history, each carrying a stats rollup), this keeps
+ * per-mission detail ONLY for live (active/paused) missions and folds the whole
+ * completed/abandoned history into a counts + id-list summary. Combined with the
+ * tighter goal preview and dropped stats, this is what keeps the compact
+ * mesh_status payload bounded as a mesh accumulates missions — the missions
+ * section previously dominated the payload (full goalPreview + tasks + stats per
+ * mission, for every live mission and up to 10 history missions, on every poll).
+ *
+ * The stored missions are untouched; this is an output-only projection. Full
+ * mission detail (goal text + stats + history) stays available via
+ * mesh_status verbose=true or mesh_mission_list.
+ */
+export declare function getMeshStatusMissionsCompact(meshId: string, options?: {
+    previewMax?: number;
+    historyIdLimit?: number;
+}): MeshStatusMissionsCompact;
+/**
+ * Read-only mission listing for the mesh_mission_list tool. Returns summaries
+ * (record + live task aggregate) for missions matching `statuses` — or every
+ * mission when `statuses` is omitted/empty — newest-first by updatedAt. Unlike
+ * getMeshStatusMissionSummaries this does NOT cap or group by lifecycle, so a
+ * coordinator can deliberately surface paused/abandoned/completed missions that
+ * the live status view would hide or truncate.
+ *
+ * Compact (the default) elides each goal to a capped preview + goalTruncated
+ * flag; verbose returns the full goal text. The stored goal is never mutated.
+ */
+export declare function listMeshMissionSummaries(meshId: string, options?: {
+    statuses?: MeshMissionStatus[];
+    verbose?: boolean;
+}): MeshMissionSummary[] | MeshMissionSlimSummary[];
+/**
+ * M3-3: render active missions as a prompt section for {{mission}}.
+ * Empty string when no active mission — the prompt stays byte-identical to
+ * the pre-M3 output in that case (regression guarantee).
+ */
+export declare function buildMissionPromptSection(meshId: string): string;

package/dist/mesh/mesh-reconcile-loop.d.ts

@@ -0,0 +1,7 @@
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+export declare function runMeshReconcileTick(components: DaemonComponents): Promise<void>;
+interface ReconcileLoopHandle {
+    stop(): void;
+}
+export declare function setupMeshReconcileLoop(components: DaemonComponents): ReconcileLoopHandle;
+export {};

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

@@ -0,0 +1,68 @@
+/**
+ * Change-area analysis for one worktree node, used to order sibling nodes for
+ * batch refinement so that nodes least likely to conflict merge first.
+ *
+ * The heuristic is deliberately git-only and side-effect-free: it inspects the
+ * commits the node's branch adds on top of the base (`base..branch`) and records
+ *   - whether any submodule gitlink path is touched (high-conflict signal: the
+ *     batch must rebase later siblings onto the advanced submodule main), and
+ *   - the set of changed top-level paths (so siblings touching disjoint trees can
+ *     be ordered ahead of ones that overlap).
+ */
+export interface MeshRefineBatchNodeChangeArea {
+    nodeId: string;
+    workspace: string;
+    branch: string;
+    /** Top-level path segments changed by the branch vs. base (e.g. 'oss', 'packages'). */
+    changedTopLevelPaths: string[];
+    /** Full changed file list (bounded) for overlap detection. */
+    changedFiles: string[];
+    /** Submodule gitlink paths touched by the branch (subset of changedTopLevelPaths). */
+    touchedSubmodulePaths: string[];
+    /** True when the branch touches at least one submodule gitlink. */
+    touchesSubmodule: boolean;
+    /** Number of commits the branch is ahead of base; 0 means nothing to merge. */
+    aheadCount: number;
+    /** Non-fatal analysis error (e.g. base/branch unresolved); ordering falls back to neutral. */
+    error?: string;
+}
+export interface MeshRefineBatchOrderingResult {
+    /** Node IDs in the order they should be refined. */
+    order: string[];
+    /** Per-node change areas, keyed by node id, for plan transparency. */
+    changeAreas: Record<string, MeshRefineBatchNodeChangeArea>;
+    /** Human-readable explanation of why the order was chosen. */
+    rationale: string[];
+}
+/**
+ * Analyze one worktree node's change area against its merge base.
+ *
+ * @param baseRef  ref that the node will merge into (e.g. 'origin/main' or a SHA)
+ * @param branchRef the node's branch tip
+ * @param diffCwd  repo to run the diff in (the worktree itself is authoritative for
+ *                 `branch` resolution, but the diff `base..branch` is symmetric, so
+ *                 the worktree cwd works for both refs once base is a reachable SHA).
+ */
+export declare function analyzeMeshRefineNodeChangeArea(args: {
+    nodeId: string;
+    workspace: string;
+    branch: string;
+    baseRef: string;
+    branchRef: string;
+    diffCwd: string;
+    submodulePaths: Set<string>;
+}): Promise<MeshRefineBatchNodeChangeArea>;
+/**
+ * Order nodes for batch refinement to minimize cross-sibling conflicts.
+ *
+ * Heuristic (deterministic, stable):
+ *   1. Nodes that do NOT touch any submodule come first — they cannot advance the
+ *      submodule main, so they never force a later submodule rebase.
+ *   2. Within each group, fewer touched top-level paths first (smaller blast radius).
+ *   3. Tie-break by node id for determinism.
+ *
+ * Submodule-touching siblings are intrinsically serial: each one that merges
+ * advances oss main, so the next must rebase. Ordering them last keeps the
+ * non-submodule merges (which never need a submodule rebase) clean and up front.
+ */
+export declare function orderMeshRefineBatchNodes(changeAreas: MeshRefineBatchNodeChangeArea[]): MeshRefineBatchOrderingResult;

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

@@ -0,0 +1,62 @@
+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 extends MeshAsyncJobLifecycle {
+    jobId: string;
+    interactionId?: string;
+    status: MeshAsyncRefineJobStatus;
+    meshId?: string;
+    nodeId?: string;
+    targetNodeId?: string;
+    targetDaemonId?: string;
+    workspace?: string;
+    branch?: string;
+    into?: string;
+    retryOfJobId?: string;
+    lastEvent?: string;
+    lastLedgerKind?: string;
+    lastUpdatedAt?: string;
+    instruction: string;
+}
+export declare function buildMeshAsyncRefineJobs(args: {
+    meshId?: string;
+    ledgerEntries?: MeshLedgerEntry[];
+    pendingEvents?: PendingMeshCoordinatorEvent[];
+}): MeshAsyncRefineJobSummary[];
+/** Terminal refine jobs older than this (relative to the newest job in the set) are
+ * "stale" — already-resolved historical refinery rejections/successes that should not
+ * keep inflating the status counts in mesh_status. 6h covers a long working session
+ * while still folding multi-day-old residue. */
+export declare const STALE_TERMINAL_REFINE_WINDOW_MS: number;
+/** Cap on how many recent terminal jobs are counted even if all fall inside the freshness
+ * window — prevents a burst of refines from dominating the summary. */
+export declare const RECENT_TERMINAL_REFINE_CAP = 8;
+export interface MeshAsyncRefineJobsSummary {
+    /** Count of jobs reflected in `byStatus` (active jobs + recent terminal jobs). */
+    total: number;
+    byStatus: Record<string, number>;
+    /** Terminal jobs dropped from the counts because they are stale residue. */
+    staleTerminal: number;
+    /** Non-terminal (accepted/running) jobs still in flight. */
+    activeJobs: MeshAsyncRefineJobSummary[];
+}
+/**
+ * Build a compact summary of refine jobs that folds stale terminal jobs.
+ *
+ * The full job list (from `buildMeshAsyncRefineJobs`) is derived from a recent ledger
+ * window and deduped by jobId, but it still includes every terminal (completed/failed)
+ * job that happens to fall in that window — including multi-day-old refinery rejections
+ * that have long since been resolved. Those stale terminals inflate `byStatus.failed`
+ * and read as "current breakage" when they are historical noise.
+ *
+ * Active (accepted/running) jobs are always counted. Terminal jobs are counted only when
+ * they are recent: within `STALE_TERMINAL_REFINE_WINDOW_MS` of the newest job's activity
+ * time AND among the `RECENT_TERMINAL_REFINE_CAP` most-recent terminals. Everything else
+ * is folded into `staleTerminal` and excluded from `byStatus`.
+ *
+ * Freshness is measured relative to the newest job in the set (not wall-clock), so the
+ * result is deterministic for a given input — important for tests and for stale-clock
+ * environments.
+ */
+export declare function summarizeMeshAsyncRefineJobs(jobs: MeshAsyncRefineJobSummary[]): MeshAsyncRefineJobsSummary;

package/dist/mesh/mesh-review-inbox.d.ts

@@ -0,0 +1,90 @@
+/**
+ * M4.0: Review inbox — derive review items from existing truth.
+ *
+ * No new store: review items are a query-time projection of
+ *   - mesh_status node statuses (daemon-owned branchConvergence), and
+ *   - the task ledger (completion evidence envelopes + refine job results).
+ *
+ * Scope (M4.0): host-daemon-local nodes only. Remote nodes are excluded and
+ * surfaced via remoteNodesExcluded/excludedRemoteNodeIds until the
+ * daemon↔daemon P2P relay path is live-verified (M4.2).
+ */
+import type { MeshLedgerEntry } from './mesh-ledger.js';
+export type MeshReviewInboxReason = 'merge_candidate' | 'refine_blocked_review';
+export interface MeshReviewInboxConvergence {
+    status: string;
+    reason: string | null;
+    nextStep: string | null;
+    needsConvergence: boolean;
+}
+export interface MeshReviewInboxEvidence {
+    available: boolean;
+    /** Ledger kind of the entry the evidence came from. */
+    kind?: 'task_completed' | 'task_failed';
+    /** 'task_completion' = ordinary worker completion envelope; 'refine_job' = Refinery result. */
+    source?: 'task_completion' | 'refine_job';
+    timestamp?: string;
+    taskId?: string;
+    sessionId?: string;
+    /** M2-3 bootstrap stage from the refine validation gate: cached|ran|failed|skipped|legacy|not_configured. */
+    bootstrap?: Record<string, unknown> | null;
+    validation?: Record<string, unknown> | null;
+    checkpoint?: Record<string, unknown> | null;
+    worker?: {
+        status: string;
+        classification?: string;
+        changedFiles: string[];
+        changedFilesTruncated?: true;
+        validationResults: Array<Record<string, unknown>>;
+        errors: string[];
+        requiresUserAction: boolean;
+    } | null;
+    finalBranchConvergenceState?: Record<string, unknown>;
+    refineJob?: Record<string, unknown>;
+}
+export interface MeshReviewInboxDiffFile {
+    path: string;
+    status?: string;
+    insertions?: number;
+    deletions?: number;
+    binary?: boolean;
+    oldPath?: string;
+}
+export interface MeshReviewInboxDiffSummary {
+    baseRef: string;
+    files: MeshReviewInboxDiffFile[];
+    totalFiles: number;
+    totalInsertions: number;
+    totalDeletions: number;
+    truncated: boolean;
+    error?: string;
+}
+export interface MeshReviewInboxItem {
+    nodeId: string;
+    workspace: string | null;
+    branch: string | null;
+    defaultBranch: string | null;
+    isLocalWorktree: boolean;
+    reviewReason: MeshReviewInboxReason;
+    convergence: MeshReviewInboxConvergence;
+    evidence: MeshReviewInboxEvidence;
+    transcriptHandle: Record<string, unknown> | null;
+    /** Latest non-terminal Refinery job for this node (accepted/running), if any. */
+    activeRefineJob: Record<string, unknown> | null;
+    lastActivityAt: string | null;
+    /** Filled by the daemon command with a bounded base-branch diff probe; null when the workspace is not locally readable. */
+    diffSummary?: MeshReviewInboxDiffSummary | null;
+}
+export interface MeshReviewInboxDerivation {
+    items: MeshReviewInboxItem[];
+    remoteNodesExcluded: boolean;
+    excludedRemoteNodeIds: string[];
+}
+/**
+ * Derive review inbox items from mesh_status node statuses and a bounded
+ * ledger tail. Pure and read-only; the caller attaches diffSummary separately.
+ */
+export declare function deriveMeshReviewInboxItems(args: {
+    nodes: Array<Record<string, unknown>>;
+    ledgerEntries: MeshLedgerEntry[];
+}): MeshReviewInboxDerivation;

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

@@ -0,0 +1,70 @@
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+export type WorkerDelegateRejectionReason = 'not_cli' | 'no_workspace' | 'no_worker_envelope' | 'coordinator_not_dispatch_target' | 'mesh_unresolved';
+export interface WorkerDelegateRouting {
+    /** True when the source session is a mesh worker whose events must route to a coordinator. */
+    isDelegate: boolean;
+    /** Resolved mesh id (runtime stamp, direct-dispatch recovery, or workspace lookup). */
+    meshId: string;
+    /** Resolved node id within the mesh, or '' when it cannot be determined. */
+    nodeId: string;
+    /** Human-readable node label for the coordinator system message. */
+    nodeLabel: string;
+    /** Coordinator daemon anchor (prefixed id) when the worker carries one; '' otherwise. */
+    coordinatorDaemonId: string;
+    /** Source session workspace (best-effort; '' when the session/workspace is missing). */
+    workspace: string;
+    /** Source session id echoed back, so diagnostics can name the dropped event's origin. */
+    sessionId: string;
+    /** Why routing was rejected (isDelegate=false), for fail-loud diagnostics (R4). */
+    rejectionReason?: WorkerDelegateRejectionReason;
+}
+interface ResolveDeps {
+    /** Resolve a mesh by id (local config + inline cache). */
+    getMeshById: (meshId: string) => any | undefined;
+    /** Resolve a mesh by workspace path (cached repo lookup). */
+    getMeshByWorkspace: (workspace: string) => any | undefined;
+}
+/**
+ * Resolve how a source CLI session's mesh events should route to a coordinator.
+ *
+ * This is the single authoritative interpretation of the worker envelope. It folds
+ * together every signal that previously lived in inline branches:
+ *  - runtime stamps (meshNodeFor / meshNodeId)
+ *  - the coordinator anchor (meshCoordinatorDaemonId) and launch marker (launchedByCoordinator,
+ *    meshCoordinatorNodeId) — any one proves delegation even if the node/mesh stamp was dropped
+ *  - direct-dispatch recovery: a coordinator session that is itself a dispatch target
+ *  - workspace→mesh fallback when no runtime mesh id survived
+ *
+ * Returns isDelegate=false (with a rejectionReason) instead of throwing, so the caller
+ * can either ignore non-delegate events or surface a diagnostic.
+ */
+export declare function resolveWorkerDelegateRouting(components: DaemonComponents, instanceId: string, deps: ResolveDeps): WorkerDelegateRouting;
+/** Ledger stream that collects delivery_unroutable diagnostics (no real mesh id exists for them). */
+export declare const UNROUTABLE_DIAGNOSTIC_STREAM = "__unroutable__";
+export declare function __resetUnroutableDiagnosticsForTests(): void;
+/** True only for rejections that represent a silently-dropped delegate event worth a diagnostic. */
+export declare function isUnroutableDelegateRejection(routing: WorkerDelegateRouting): boolean;
+/**
+ * R4: record that a worker event with a valid envelope could not be routed to a coordinator.
+ * Writes a `delivery_unroutable` ledger entry (deduped within a short window) so operators see
+ * WHY a completion never arrived instead of it vanishing. No-op for non-diagnostic rejections.
+ */
+export declare function recordUnroutableDelegateEvent(routing: WorkerDelegateRouting, eventName: string): boolean;
+export interface UnroutableDeliveryDiagnostic {
+    timestamp: string;
+    event: string;
+    sessionId?: string;
+    workspace?: string;
+    coordinatorDaemonId?: string;
+}
+/**
+ * R4 visibility: recent delivery_unroutable diagnostics, newest first. Surfaced in mesh_status
+ * so an operator/coordinator can see that completions were dropped (envelope present, mesh
+ * unresolved) rather than the drops being invisible in a ledger nobody reads. The diagnostics
+ * live in a single shared stream because an unroutable event has no resolvable mesh.
+ */
+export declare function getRecentUnroutableDeliveries(opts?: {
+    sinceMs?: number;
+    limit?: number;
+}): UnroutableDeliveryDiagnostic[];
+export {};