@adhdev/daemon-core 0.9.82-rc.43 → 0.9.82-rc.430

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

@@ -0,0 +1,428 @@
+/**
+ * Mesh refine validation gates & gitlink fast-forward evaluation
+ *
+ * Extracted from commands/router.ts (behavior-preserving move). Contains:
+ *   - the MeshCoordinator config-format type
+ *   - refine validation / patch-equivalence / effective-diff / submodule
+ *     reachability gates and their summary types + job handles
+ *   - gitlink trivial-fast-forward evaluation and submodule alignment helpers
+ *
+ * router.ts re-exports every public symbol from here so existing import paths
+ * keep working. `CommandRouterResult` is imported type-only from router.ts
+ * (erased at compile time — no runtime import cycle).
+ */
+import type { WorktreeBootstrapState } from '../mesh/worktree-bootstrap-config.js';
+import type { CommandRouterResult } from '../commands/router.js';
+export type MeshCoordinatorConfigFormat = 'claude_mcp_json' | 'hermes_config_yaml';
+type MeshRefineValidationStatus = 'passed' | 'failed' | 'skipped';
+type MeshRefineValidationSummary = {
+    status: MeshRefineValidationStatus;
+    required: true;
+    commandsRun: Array<Record<string, unknown>>;
+    bootstrapCommandsRun: Array<Record<string, unknown>>;
+    rejectedCommands: Array<Record<string, unknown>>;
+    skippedReason?: string;
+    failureKind?: string;
+    failureCode?: string;
+    /** Human-readable cause when failureKind === 'spawn_resolution_failed' (win32 .cmd shim, etc). */
+    spawnResolutionError?: string;
+    timeoutMs: number;
+    outputLimitBytes: number;
+    configSource?: string;
+    configSourceType?: string;
+    suggestions?: unknown[];
+    suggestedConfig?: unknown;
+    /**
+     * M2-3: the bootstrap stage recorded separately from validation so review
+     * surfaces can distinguish environment failures from validation failures.
+     *   cached — worktree_bootstrap was 'ready' (staleInputs unchanged), skipped
+     *   ran    — worktree_bootstrap was stale/never-ran and re-ran successfully
+     *   failed — bootstrap run failed (refine stops before validation)
+     *   skipped — refine config validation.bootstrap === 'skip'
+     *   legacy — deprecated validation.bootstrapCommands path was used
+     *   not_configured — no bootstrap definition anywhere
+     */
+    bootstrap?: {
+        stage: 'cached' | 'ran' | 'failed' | 'skipped' | 'legacy' | 'not_configured';
+        status?: string;
+        skipped?: boolean;
+        configSource?: string;
+        staleReason?: string;
+        error?: string;
+        commandsRun?: Array<Record<string, unknown>>;
+    };
+    /** M2-2: deprecation notices from the refine config (e.g. bootstrapCommands). */
+    deprecationWarnings?: string[];
+};
+type MeshRefineStageStatus = 'passed' | 'failed' | 'skipped';
+type MeshRefinePatchEquivalenceSummary = {
+    status: MeshRefineStageStatus;
+    equivalent: boolean;
+    baseHead: string;
+    branchHead: string;
+    mergeBase?: string;
+    mergedTree?: string;
+    expectedPatchId?: string;
+    actualPatchId?: string;
+    durationMs: number;
+    error?: string;
+    stdout?: string;
+    stderr?: string;
+    actionableHint?: MeshRefineSubmoduleConflictHint;
+    /**
+     * Set when a `merge-tree` submodule conflict was reclassified as a trivial
+     * gitlink fast-forward and the gate passed via a synthesized merge tree.
+     */
+    gitlinkTrivialFastForward?: {
+        resolved: boolean;
+        gitlinks: Array<{
+            path: string;
+            baseCommit?: string;
+            branchCommit?: string;
+            fastForward: boolean;
+        }>;
+        reason?: string;
+    };
+};
+type MeshRefineEffectiveDiffSummary = {
+    status: MeshRefineStageStatus;
+    /** True when there is at least one root-tree change between base and branch (incl. gitlink bumps). */
+    hasEffectiveDiff: boolean;
+    baseHead: string;
+    branchHead: string;
+    /** Root-level paths that differ between base and branch (capped). */
+    changedPaths?: string[];
+    /** Submodule paths with uncommitted/divergent commits but NO committed gitlink bump in the root tree. */
+    submoduleHints?: Array<{
+        path: string;
+        reason: string;
+    }>;
+    durationMs: number;
+    error?: string;
+    stdout?: string;
+    stderr?: string;
+};
+type MeshRefineSubmoduleConflictHint = {
+    kind: 'submodule_conflict';
+    message: string;
+    conflicts: Array<{
+        path: string;
+        baseCommit?: string;
+        branchCommit?: string;
+    }>;
+    nextSteps: string[];
+};
+type MeshRefineSubmoduleAlignmentSummary = {
+    status: 'passed' | 'failed' | 'skipped';
+    changedGitlinkPaths: string[];
+    outOfSyncPaths: string[];
+    updatedPaths: string[];
+    verifiedPaths: string[];
+    durationMs: number;
+    reason?: string;
+    command?: string;
+    error?: string;
+    stdout?: string;
+    stderr?: string;
+};
+type MeshRefineSubmoduleReachabilityEntry = {
+    path: string;
+    commit: string;
+    reachable: boolean;
+    publishRequired?: boolean;
+    autoPublishAllowed?: boolean;
+    autoPublishAttempted?: boolean;
+    autoPublishSucceeded?: boolean;
+    autoPublishVerified?: boolean;
+    autoPublishRefspec?: string;
+    autoPublishSkippedReason?: string;
+    importedFromWorktree?: boolean;
+    checkedLocal?: boolean;
+    localReachable?: boolean;
+    remote?: string;
+    remoteUrl?: string;
+    remoteReachable?: boolean;
+    remoteMainBranch?: string;
+    remoteMainReachable?: boolean;
+    fetchedFromOrigin?: boolean;
+    error?: string;
+    publishStdout?: string;
+    publishStderr?: string;
+};
+type MeshRefineSubmoduleReachabilitySummary = {
+    status: MeshRefineStageStatus;
+    checked: number;
+    unreachable: MeshRefineSubmoduleReachabilityEntry[];
+    entries: MeshRefineSubmoduleReachabilityEntry[];
+    durationMs: number;
+    autoPublishAllowed?: boolean;
+    autoPublishPolicySource?: string;
+    error?: string;
+};
+export type MeshRefineAsyncJobStatus = 'accepted' | 'completed' | 'failed';
+export type MeshRefineJobHandle = {
+    success: true;
+    async: true;
+    status: MeshRefineAsyncJobStatus;
+    jobId: string;
+    interactionId: string;
+    meshId: string;
+    nodeId: string;
+    targetNodeId: string;
+    targetDaemonId?: string;
+    workspace?: string;
+    startedAt: string;
+    completedAt?: string;
+    duplicate?: boolean;
+    retryOfJobId?: string;
+    /**
+     * The coordinator daemon ID that initiated this refine job.
+     * When set, events for this job are scoped to that coordinator's
+     * pending-events queue instead of the shared broadcast queue.
+     */
+    targetCoordinatorDaemonId?: string;
+    eventDelivery: {
+        pendingEvents: true;
+        ledger: true;
+    };
+    evidence: {
+        pendingEventsCommand: 'get_pending_mesh_events';
+        ledgerCommand: 'get_mesh_ledger_slice';
+        taskHistoryKind: 'task_dispatched' | 'task_completed' | 'task_failed';
+    };
+};
+export type MeshRefineTerminalJob = MeshRefineJobHandle & {
+    result?: Record<string, unknown>;
+};
+export type MeshRefineBatchJobStatus = 'accepted' | 'completed' | 'failed';
+/**
+ * Async handle returned by the batch Refinery the instant a convergence run is
+ * accepted. Mirrors {@link MeshRefineJobHandle} (async:true / status:'accepted' +
+ * terminal pending-event + ledger delivery) but scopes a whole batch of sibling
+ * nodes rather than a single node. The synthetic `batchLabel` is used as the
+ * `nodeLabel` for the shared refine event/message renderer.
+ */
+export type MeshRefineBatchJobHandle = {
+    success: true;
+    async: true;
+    batch: true;
+    status: MeshRefineBatchJobStatus;
+    jobId: string;
+    interactionId: string;
+    meshId: string;
+    batchLabel: string;
+    nodeIds: string[];
+    nodeCount: number;
+    order: string[];
+    startedAt: string;
+    completedAt?: string;
+    duplicate?: boolean;
+    targetCoordinatorDaemonId?: string;
+    eventDelivery: {
+        pendingEvents: true;
+        ledger: true;
+    };
+    evidence: {
+        pendingEventsCommand: 'get_pending_mesh_events';
+        ledgerCommand: 'get_mesh_ledger_slice';
+        taskHistoryKind: 'task_dispatched' | 'task_completed' | 'task_failed';
+    };
+};
+export type MeshRefineBatchTerminalJob = MeshRefineBatchJobHandle & {
+    result?: Record<string, unknown>;
+};
+export declare function truncateValidationOutput(value: unknown): string;
+/**
+ * A spawn-resolution failure is when the executable itself could not be found by
+ * the OS spawn boundary — `spawn <cmd> ENOENT` — as opposed to the command
+ * running and exiting non-zero. On win32 this is the .cmd-shim case: libuv's
+ * spawn search appends only .com/.exe, so a bare `npm`/`npx`/`tsc` (which are
+ * .cmd shims) ENOENTs even though it is installed. It carries no stderr, so it
+ * must be detected by error.code/syscall, not by string-matching output.
+ */
+export declare function isSpawnResolutionError(error: any): boolean;
+export declare function describeSpawnError(error: any, command: string, spawnResolutionFailed: boolean): string;
+export declare function recordMeshRefineStage(stages: Array<Record<string, unknown>>, stage: string, status: MeshRefineStageStatus, startedAt: number, details?: Record<string, unknown>): void;
+export declare function buildSubmodulePublishRequiredNextStep(entries: MeshRefineSubmoduleReachabilityEntry[]): string;
+/**
+ * Async git exec helper used across the synchronous-refine stage pipeline. Bound
+ * once in the orchestrator and threaded through RefineContext so every stage runs
+ * git the same way (execFile + promisify, utf8). Returns the child's stdout/stderr.
+ */
+export type RefineExecFileAsync = (file: string, args: string[], options: {
+    cwd: string;
+    encoding: 'utf8';
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Accumulated state shared by the synchronous-refine stages. The orchestrator
+ * (executeMeshRefineNodeSynchronously) seeds this in the resolve_refs stage and
+ * each later stage reads / extends it. `branchHead` and `patchEquivalence` are the
+ * only fields a stage mutates after creation (auto-rebase updates both), so they
+ * are carried on the mutable context rather than re-threaded through return types.
+ */
+export interface RefineContext {
+    meshId: string;
+    nodeId: string;
+    args: any;
+    refineStages: Array<Record<string, unknown>>;
+    execFileAsync: RefineExecFileAsync;
+    mesh: any;
+    node: any;
+    sourceNode: any;
+    repoRoot: string;
+    branch: string;
+    baseBranch: string;
+    baseHead: string;
+    branchHead: string;
+    validationSummary: Awaited<ReturnType<typeof runMeshRefineValidationGate>>;
+    patchEquivalence: Awaited<ReturnType<typeof runMeshRefinePatchEquivalenceGate>>;
+    submoduleReachability: Awaited<ReturnType<typeof runMeshRefineSubmoduleReachabilityGate>>;
+}
+/**
+ * Stage outcome for the synchronous-refine pipeline. A stage either produces a
+ * terminal CommandRouterResult (an early-exit gate failure, or a successful
+ * already-merged short-circuit), in which case the orchestrator returns it
+ * immediately, or it returns `continue` with the (possibly extended) context for
+ * the next stage. This makes the orchestrator a flat sequence of stage calls
+ * while preserving the original body's exact early-return control flow.
+ */
+export type RefineStageOutcome = {
+    kind: 'terminal';
+    result: CommandRouterResult;
+} | {
+    kind: 'continue';
+    ctx: RefineContext;
+};
+export declare function resolveRefineryAutoPublishSubmoduleMainCommits(mesh: any, workspace: string): {
+    enabled: boolean;
+    source?: string;
+};
+export declare function runMeshRefinePatchEquivalenceGate(repoRoot: string, baseHead: string, branchHead: string): Promise<MeshRefinePatchEquivalenceSummary>;
+export type MeshWorktreePatchContainmentSummary = {
+    /** True only when merging worktreeHead into ref introduces no new patch. */
+    contained: boolean;
+    ref: string;
+    worktreeHead: string;
+    mergeBase?: string;
+    mergedTree?: string;
+    /** patch-id of (ref -> synthesized merge tree); empty string when nothing new is added. */
+    residualPatchId?: string;
+    durationMs: number;
+    /** Set when the check could not run (treated conservatively as NOT contained). */
+    error?: string;
+};
+/**
+ * Patch-equivalence containment check for the worktree force-cleanup convergence
+ * guard. Answers a narrower question than {@link runMeshRefinePatchEquivalenceGate}:
+ * "are the worktree branch's changes ALREADY present in `ref` (e.g. origin/main),
+ * even though the worktree HEAD's commit SHA is not an ancestor of ref?"
+ *
+ * This is the cherry-pick / squash / rebase case: the same content landed on the
+ * default ref under a different commit SHA, so `merge-base --is-ancestor` (the
+ * primary cleanup guard) reports the worktree as un-converged and refuses to
+ * remove it. Refinery already accepts patch-equivalent landings via merge-tree +
+ * patch-id; this brings the same notion of "convergence" to the cleanup guard.
+ *
+ * Mechanism: synthesize the merge of `worktreeHead` into `ref` (reusing the same
+ * trivial-gitlink-fast-forward handling as the refine gate) and compute the
+ * patch-id of (ref -> mergedTree). If that residual diff is EMPTY, merging the
+ * worktree adds nothing new on top of ref — its changes are already present there
+ * and the worktree is safe to remove. A non-empty residual means the worktree
+ * still carries content not in ref, so it is NOT contained and must stay blocked.
+ *
+ * Conservative by construction: any merge-tree / patch-id failure, a genuine
+ * (non-trivial) submodule conflict, or any thrown error yields `contained: false`
+ * so an exception can never widen the cleanup allow-list.
+ */
+export declare function checkWorktreeChangesPatchEquivalentInRef(repoRoot: string, ref: string, worktreeHead: string): Promise<MeshWorktreePatchContainmentSummary>;
+/**
+ * No-op guard: detect a "silent no-op" merge before the Refinery merge runs.
+ *
+ * A silent no-op occurs when the refine target branch's ROOT tree is byte-identical
+ * to the merge base (origin/main). This is the trap where a submodule (e.g. oss) has
+ * real commits but the root branch never committed the gitlink (oss-pointer) bump, so
+ * the root diff Refinery would merge is empty. Merging that produces a merge commit with
+ * no content change — reported as "success" while the actual work never reaches main.
+ *
+ * A committed gitlink bump (the legitimate oss-pointer bump) DOES show up in the root
+ * tree diff (as a 160000-mode entry), so this guard does NOT block legitimate refines —
+ * it only fires when the root tree diff vs base is COMPLETELY empty.
+ *
+ * Runs after the patch-equivalence gate; the "already merged via other path" case
+ * (branch has real changes already present in base) is handled upstream and never
+ * reaches here, so an empty root diff at this point is genuinely a no-op.
+ */
+export declare function runMeshRefineEffectiveDiffGate(repoRoot: string, baseHead: string, branchHead: string): Promise<MeshRefineEffectiveDiffSummary>;
+/**
+ * Result of evaluating whether a `git merge-tree --write-tree` submodule
+ * conflict is in fact a trivial gitlink fast-forward that should pass the
+ * patch-equivalence gate.
+ *
+ * `git merge-tree` (and `git merge` with the default recursive strategy)
+ * refuses to 3-way merge gitlinks unless the case is "trivial" — and it
+ * treats *any* gitlink that differs across merge-base/base/branch as
+ * non-trivial, even when the branch-side commit is a strict descendant of the
+ * base-side commit (i.e. a real fast-forward). Refinery only ever wants to
+ * accept the branch's recorded gitlink, so a fast-forwardable bump is safe to
+ * resolve to the branch side without any conflict.
+ */
+type GitlinkTrivialFastForwardEvaluation = {
+    /** True only when the merge-tree conflict is *fully* explained by trivial-ff gitlinks. */
+    trivial: boolean;
+    /** Why the evaluation declined to treat the conflict as trivial (set when trivial=false). */
+    reason?: string;
+    /** Per-path detail for the changed gitlinks that were inspected. */
+    gitlinks: Array<{
+        path: string;
+        baseCommit?: string;
+        branchCommit?: string;
+        fastForward: boolean;
+    }>;
+};
+/**
+ * Return the changed gitlink paths between base and branch whose advance is a
+ * strict fast-forward (the base-side commit is an ancestor of the branch-side
+ * commit inside that submodule's repo). These are the paths whose patch-id hunk
+ * may legitimately differ when base has advanced the same submodule, so they
+ * are safe to exclude from the patch-equivalence comparison. A non-ff (genuinely
+ * diverged) gitlink is deliberately excluded from this set so it still fails the
+ * gate.
+ */
+export declare function collectFastForwardGitlinkPaths(repoRoot: string, baseHead: string, branchHead: string): string[];
+/**
+ * Decide whether a merge-tree submodule conflict between base and branch is a
+ * trivial gitlink fast-forward (and nothing else).
+ *
+ * The conflict is treated as trivial ONLY when:
+ *   1. at least one changed gitlink exists,
+ *   2. every changed gitlink fast-forwards (base-commit is an ancestor of the
+ *      branch-commit inside that submodule's repo), and
+ *   3. the *only* paths that changed on both sides of the merge (i.e. the paths
+ *      that could possibly produce a 3-way conflict — the intersection of
+ *      mergeBase→base and mergeBase→branch changes) are gitlinks. Any
+ *      overlapping non-gitlink path means a genuine content conflict could be
+ *      hiding behind the submodule failure, so we keep the block.
+ *
+ * If any of these fail, the conflict is left as a genuine block. This never
+ * passes a regular-file conflict or a diverged (non-ff) gitlink.
+ */
+export declare function evaluateGitlinkTrivialFastForward(repoRoot: string, baseHead: string, branchHead: string): GitlinkTrivialFastForwardEvaluation;
+export declare function alignRefinerySubmodulesAfterMerge(repoRoot: string, previousBaseHead: string, currentHead: string, options?: {
+    submoduleIgnorePaths?: string[];
+}): Promise<MeshRefineSubmoduleAlignmentSummary>;
+export declare function runMeshRefineSubmoduleReachabilityGate(repoRoot: string, mergedTree: string, options?: {
+    allowAutoPublishSubmoduleMainCommits?: boolean;
+    autoPublishPolicySource?: string;
+    worktreeRoot?: string;
+}): Promise<MeshRefineSubmoduleReachabilitySummary>;
+export declare function buildMeshRefineValidationPlan(mesh: any, workspace: string): Record<string, unknown>;
+export declare function runMeshRefineValidationGate(mesh: any, workspace: string, opts?: {
+    /** M2-2: persisted node bootstrap state for staleness evaluation. */
+    persistedBootstrapState?: WorktreeBootstrapState | null;
+    /** M2-2: called after an inherit-mode bootstrap run so the caller can persist the new state. */
+    onBootstrapStateChange?: (state: WorktreeBootstrapState) => void;
+}): Promise<MeshRefineValidationSummary>;
+export {};

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 {};