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

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

@@ -0,0 +1,174 @@
+import type { MeshLedgerEntry } from './mesh-ledger.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 {
+    taskId: string;
+    source: MeshActiveWorkSource;
+    status: MeshActiveWorkStatus;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskTitle: string;
+    taskSummary: string;
+    message?: string;
+    taskMode?: string;
+    createdAt: string;
+    updatedAt: string;
+    dispatchedAt?: string;
+    elapsedMs: number;
+    terminal?: boolean;
+    terminalKind?: string;
+    terminalAt?: string;
+    staleReason?: string;
+    /**
+     * When true, the session targeted by this direct dispatch still exists in the live mesh
+     * but did not transition to generating — the dispatch was not acknowledged by the provider.
+     * Distinct from historical/orphaned stale entries where the node/session is gone.
+     */
+    staleDispatchUnacknowledged?: boolean;
+}
+export interface MeshActiveWorkSummary {
+    totalActiveCount: number;
+    queueActiveCount: number;
+    directActiveCount: number;
+    awaitingApprovalCount: number;
+    generatingCount: number;
+    failedCount: number;
+    idleCount: number;
+    sourceCounts: Record<MeshActiveWorkSource, number>;
+    statusCounts: Record<MeshActiveWorkStatus, number>;
+    staleDirectCount: number;
+    /**
+     * Count of stale direct entries where the target session still exists in the live mesh
+     * but never transitioned to generating — these are fresh dispatch failures, not historical orphans.
+     * Requires immediate recovery: launch a fresh session and retry the task.
+     */
+    staleDirectUnacknowledgedCount?: number;
+    /**
+     * When staleDirectCount > 0, this note clarifies what kind of stale records exist.
+     * Fresh unacknowledged dispatches carry an actionable recovery note; orphaned historical
+     * entries carry the "historical evidence only" note. Both may coexist.
+     */
+    staleDirectNote?: string;
+}
+export interface MeshStaleDirectWorkSummary {
+    count: number;
+    sampleLimit: number;
+    sample: Array<Pick<MeshActiveWorkRecord, 'taskId' | 'status' | 'nodeId' | 'sessionId' | 'taskTitle' | 'createdAt' | 'staleReason'>>;
+    reasonCounts: Record<string, number>;
+    detailHint: string;
+    note?: string;
+}
+export interface BuildMeshActiveWorkOptions {
+    meshId: string;
+    queue?: MeshWorkQueueEntry[];
+    ledgerEntries?: MeshLedgerEntry[];
+    /**
+     * Active direct dispatches from MeshRuntimeStore. 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. */
+    includeTerminalDirect?: boolean;
+}
+export declare function buildMeshActiveWorkSummary(activeWork: MeshActiveWorkRecord[]): MeshActiveWorkSummary;
+export declare function buildMeshActiveWork(opts: BuildMeshActiveWorkOptions): {
+    activeWork: MeshActiveWorkRecord[];
+    staleDirectWork: MeshActiveWorkRecord[];
+    staleDirectWorkNote?: string;
+    terminalDirectWork: MeshActiveWorkRecord[];
+    summary: MeshActiveWorkSummary;
+};
+/**
+ * staleReason strings (produced by sessionStatusFromNodes above) that indicate the original
+ * node/session is GONE from the live mesh — i.e. the staleDirect record is an orphaned ledger
+ * artifact, not active or recoverable work. These are the only reasons safe to prune from the
+ * active staleDirect surface. The "no provider acknowledgement" reason is deliberately excluded:
+ * those entries have a still-live node/session (staleDispatchUnacknowledged) and represent
+ * recoverable dispatch failures, never orphans.
+ */
+export declare const PRUNABLE_ORPHAN_STALE_REASONS: ReadonlySet<string>;
+export type StaleDirectPruneClassification = 'prunable_orphan' | 'prunable_terminal' | 'preserve_unacknowledged' | 'preserve_active';
+/**
+ * Classify a direct-work record for the staleDirect prune path. Pure function — the prune tool
+ * uses this so the safety rules (never touch active work or recoverable unacknowledged dispatches)
+ * live next to the staleReason producers and are independently testable.
+ */
+export declare function classifyStaleDirectForPrune(record: Pick<MeshActiveWorkRecord, 'staleReason' | 'staleDispatchUnacknowledged' | 'terminal'>, opts?: {
+    includeTerminal?: boolean;
+}): StaleDirectPruneClassification;
+/**
+ * Outcome of one staleDirect prune pass. Pure data — callers (the MCP tool, the
+ * daemon reconcile loop) format/log this however they need. The MCP tool wraps it in
+ * its JSON response; the reconcile loop logs prunedCount when > 0.
+ */
+export interface StaleDirectPruneResult {
+    mode: 'execute' | 'dry_run';
+    includeTerminal: boolean;
+    /** Total staleDirect (+terminal when included) candidates surfaced this pass. */
+    candidateCount: number;
+    /** Records classified prunable AND (when minAgeMs > 0) old enough to auto-prune. */
+    prunable: MeshActiveWorkRecord[];
+    prunedCount: number;
+    /** Prunable by classification but younger than the age gate — only populated when minAgeMs > 0. */
+    skippedTooYoung: MeshActiveWorkRecord[];
+    preservedUnacknowledged: MeshActiveWorkRecord[];
+    /** Prunable orphans/terminals with no store-backed row to delete (ledger-only audit). */
+    preservedLedgerOnly: MeshActiveWorkRecord[];
+    preservedNotOrphan: MeshActiveWorkRecord[];
+}
+export interface PruneStaleDirectDispatchesOptions {
+    meshId: string;
+    /** Active direct dispatches from MeshRuntimeStore (getActiveDirectDispatches). */
+    directDispatches: DirectDispatchRecord[];
+    /** Ledger tail used to attribute remote/terminal dispatches (readLedgerEntries). */
+    ledgerEntries?: MeshLedgerEntry[];
+    queue?: MeshWorkQueueEntry[];
+    /** Live mesh nodes (decorated with live session details) — drives orphan detection. */
+    nodes?: any[];
+    /** When true, actually delete + append the audit ledger entry. Default false (dry run). */
+    execute?: boolean;
+    /** Include terminal (idle/failed) direct rows as prune candidates. Default false. */
+    includeTerminal?: boolean;
+    /**
+     * Minimum age (ms, measured from createdAt/dispatchedAt) before a prunable orphan is
+     * eligible. 0 (default) prunes immediately regardless of age — the manual prune behavior.
+     * The daemon auto-prune passes a conservative threshold so a node/session that is only
+     * transiently invisible is never pruned on the spot.
+     */
+    minAgeMs?: number;
+    /** Audit source string written into the direct_dispatch_pruned ledger payload. */
+    source?: string;
+    now?: number;
+}
+/**
+ * Shared staleDirect prune core. Single source of truth for the prune decision + the
+ * mutation (store-row delete + audit-ledger append) used by BOTH the manual MCP tool
+ * (mesh_prune_stale_direct, minAgeMs=0) and the daemon reconcile loop's auto-prune
+ * PHASE (minAgeMs > 0). Pure decision logic via buildMeshActiveWork + classifyStaleDirectForPrune;
+ * the only side effects (on execute) are deleteDirectDispatchesByTaskId and a single
+ * direct_dispatch_pruned ledger entry — never touching the append-only audit history of the
+ * pruned dispatches themselves.
+ *
+ * Safety rules (identical for manual + auto):
+ *  - Only records classified as staleDirectWork against the CURRENT live mesh are eligible.
+ *  - Of those, only orphans (node/session gone) — and terminals when includeTerminal — are prunable.
+ *    Fresh unacknowledged dispatch failures (node/session still live) are always preserved.
+ *  - Only store-backed rows (taskId present in MeshRuntimeStore) are deleted; ledger-only remote
+ *    entries are preserved.
+ *  - When minAgeMs > 0, a prunable orphan younger than the gate is held back (skippedTooYoung).
+ *    This applies ONLY to the auto path; the manual path passes minAgeMs=0 (immediate).
+ *
+ * Idempotent: a deleted row no longer appears in getActiveDirectDispatches, so a second pass
+ * over the same orphan finds nothing to prune.
+ */
+export declare function pruneStaleDirectDispatches(opts: PruneStaleDirectDispatchesOptions): StaleDirectPruneResult;
+export declare function buildCompactStaleDirectWorkSummary(staleDirectWork: MeshActiveWorkRecord[], opts?: {
+    sampleLimit?: number;
+    detailHint?: string;
+    note?: string;
+}): MeshStaleDirectWorkSummary;

package/dist/mesh/mesh-clone-grace.d.ts

@@ -0,0 +1,8 @@
+export declare const CLONE_BOOTSTRAP_GRACE_MS: number;
+/** Record that a worktree node id was just cloned, opening its transient grace window. */
+export declare function noteRecentlyClonedNode(nodeId: string | undefined | null, nowMs?: number): void;
+/** True when nodeId was cloned within the grace window (and the entry has not expired). */
+export declare function isWithinCloneBootstrapGrace(nodeId: string | undefined | null, nowMs?: number): boolean;
+/** Drop a node's grace entry (e.g. once it has fully resolved into the mesh view). */
+export declare function clearCloneBootstrapGrace(nodeId: string | undefined | null): void;
+export declare function __resetCloneBootstrapGraceForTests(): void;

package/dist/mesh/mesh-coordinator-config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hermes / MCP coordinator config helpers
+ *
+ * Extracted from commands/router.ts (behavior-preserving move). Contains the
+ * MCP-server config parse/serialize helpers and the Hermes coordinator base
+ * config loading / temp-override stripping / credential-copy helpers.
+ *
+ * router.ts re-exports every public symbol from here so existing import paths
+ * keep working.
+ */
+import type { MeshCoordinatorConfigFormat } from './mesh-refine-gates.js';
+export declare function getMcpServersKey(format: MeshCoordinatorConfigFormat): 'mcpServers' | 'mcp_servers';
+export declare function parseMeshCoordinatorMcpConfig(text: string, format: MeshCoordinatorConfigFormat): Record<string, any>;
+export declare function serializeMeshCoordinatorMcpConfig(config: Record<string, any>, format: MeshCoordinatorConfigFormat): string;
+export declare function loadHermesCoordinatorBaseConfig(targetConfigPath: string): {
+    config: Record<string, any>;
+    sourceHome: string;
+    sourceConfigPath: string;
+};
+export declare function stripHermesCoordinatorTempModelProviderOverrides(config: Record<string, any>): Record<string, any>;
+export declare function copyHermesCoordinatorCredentialFiles(sourceHome: string, targetHome: string): void;

package/dist/mesh/mesh-delivery-policy.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Possible delivery statuses for a session delivery record.
+ */
+export type MeshSessionDeliveryStatus = 'queued' | 'delivering' | 'delivered' | 'acked' | 'completed' | 'failed' | 'expired' | 'cancelled';
+/**
+ * Kind of delivery — controls priority and policy handling.
+ */
+export type MeshSessionDeliveryKind = 'task' | 'followup' | 'approval' | 'recovery' | 'system_notice';
+/**
+ * A session delivery decision — what to do when a task arrives for a session.
+ */
+export type MeshDeliveryDecision = 'immediate' | 'queued' | 'rejected';
+export interface MeshDeliveryPolicyResult {
+    decision: MeshDeliveryDecision;
+    reason: string;
+    /** When decision='queued', estimated deliver-after ISO timestamp if known. */
+    deliverAfter?: string;
+    /** Human-readable explanation for coordinator/operator. */
+    message: string;
+}
+/**
+ * Determine whether to deliver immediately, queue, or reject based on session status.
+ *
+ * This is a pure function — it does not write to any store.
+ */
+export declare function resolveDeliveryDecision(sessionStatus: string | undefined, opts?: {
+    kind?: MeshSessionDeliveryKind;
+    /** When true, busy session immediate injection is allowed (provider-specific capability). */
+    allowBusyInjection?: boolean;
+}): MeshDeliveryPolicyResult;
+export interface SessionDeliveryRecord {
+    id: string;
+    meshId: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskId?: string;
+    kind: MeshSessionDeliveryKind;
+    priority: number;
+    message: string;
+    status: MeshSessionDeliveryStatus;
+    deliverAfter?: string;
+    expiresAt?: string;
+    attemptCount: number;
+    sourceCoordinatorSessionId?: string;
+    sourceCoordinatorDaemonId?: string;
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Create a delivery record in the store.
+ */
+export declare function createSessionDelivery(opts: {
+    meshId: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskId?: string;
+    kind: MeshSessionDeliveryKind;
+    message: string;
+    status: MeshSessionDeliveryStatus;
+    priority?: number;
+    deliverAfter?: string;
+    expiresAt?: string;
+    sourceCoordinatorSessionId?: string;
+    sourceCoordinatorDaemonId?: string;
+}): SessionDeliveryRecord;
+/**
+ * Update the status of a delivery record.
+ */
+export declare function updateSessionDeliveryStatus(id: string, status: MeshSessionDeliveryStatus, opts?: {
+    lastError?: string;
+    incrementAttempt?: boolean;
+}): void;
+/**
+ * Get active (non-terminal) deliveries for a mesh, optionally filtered by session.
+ */
+export declare function getActiveSessionDeliveries(meshId: string, sessionId?: string): {
+    id: string;
+    meshId: string;
+    nodeId: string | null;
+    sessionId: string | null;
+    providerType: string | null;
+    taskId: string | null;
+    kind: string;
+    priority: number;
+    message: string;
+    status: string;
+    deliverAfter: string | null;
+    expiresAt: string | null;
+    attemptCount: number;
+    sourceCoordinatorSessionId: string | null;
+    sourceCoordinatorDaemonId: string | null;
+    lastError: string | null;
+    createdAt: string;
+    updatedAt: string;
+}[];
+/**
+ * Record a completion conflict diagnostic when a duplicate event points to
+ * different task/session than the already-seen event with the same fingerprint.
+ */
+export declare function recordCompletionConflict(opts: {
+    meshId: string;
+    fingerprint: string;
+    conflictingTaskId?: string;
+    conflictingSessionId?: string;
+    originalTaskId?: string;
+    originalSessionId?: string;
+    event: string;
+}): void;
+/**
+ * Get recent completion conflicts for diagnostic inspection.
+ */
+export declare function getRecentCompletionConflicts(meshId: string, limitMs?: number): {
+    id: string;
+    meshId: string;
+    fingerprint: string;
+    conflictingTaskId: string | null;
+    conflictingSessionId: string | null;
+    originalTaskId: string | null;
+    originalSessionId: string | null;
+    event: string;
+    createdAt: string;
+}[];
+export declare function __clearSessionDeliveriesForTests(meshId: string): void;
+/**
+ * Mark all active (queued/delivering/delivered/acked) deliveries for a session as completed or failed.
+ * Called when a task's terminal status is confirmed so delivery records stay in sync.
+ */
+export declare function markSessionDeliveriesTerminal(meshId: string, sessionId: string, terminalStatus: 'completed' | 'failed'): void;

package/dist/mesh/mesh-event-classify.d.ts

@@ -0,0 +1,5 @@
+import type { MeshLedgerKind } from './mesh-ledger.js';
+export declare const EVENT_TO_LEDGER_KIND: Record<string, MeshLedgerKind>;
+export declare function isMeshCoordinatorEvent(eventName: unknown): eventName is string;
+export declare const MESH_FORCE_INJECT_EVENTS: ReadonlySet<string>;
+export declare function shouldForceInjectMeshEvent(eventName: unknown): boolean;

package/dist/mesh/mesh-event-forwarding.d.ts

@@ -0,0 +1,41 @@
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+export declare function recoverMeshIdByCoordinatorAndNode(coordinatorDaemonId: string, nodeId: string): string;
+export declare function resolveForwardEventMeshId(components: DaemonComponents, payload: Record<string, unknown>): string;
+export declare function __resetMeshWorkspaceCacheForTests(): void;
+export declare function buildRelayMetadataEvent(payload: Record<string, unknown>): Record<string, unknown>;
+export declare function handleMeshForwardEvent(components: DaemonComponents, payload: Record<string, unknown>): {
+    [extra: string]: unknown;
+    success: true;
+    forwarded: 0;
+    suppressed: true;
+} | {
+    success: boolean;
+    forwarded: number;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string;
+};
+/**
+ * NOTIF-HELD-DRAIN (Fix 2): event-driven coordinator drain. The reconcile loop delivers a
+ * worker's queued completion to an IDLE local coordinator only on its periodic poll. When a
+ * coordinator is sitting idle awaiting exactly that completion, waiting up to a full poll
+ * interval is the avoidable delivery latency the RCA flags — and combined with the (now-fixed)
+ * modal-park false-positive it stretched into the multi-minute notification stall. So the
+ * MOMENT a worker delegate event is persisted for a mesh, attempt the same idle-coordinator
+ * drain immediately, mirroring the event-driven worker-claim path (agent:ready /
+ * agent:generating_completed → triggerMeshQueue).
+ *
+ * Safety:
+ *  - drainPendingMeshCoordinatorEvents marks rows drained=1 atomically, so this races the
+ *    reconcile poll and the coordinator's own idle auto-flush harmlessly — exactly one consumes
+ *    each row.
+ *  - Only IDLE, non-modal-parked coordinators are delivery targets (never a generating /
+ *    consent-modal PTY).
+ *  - Strict session routing is honoured: an event naming an originating coordinator session is
+ *    delivered only to that live idle session; anything not currently deliverable here
+ *    (wrong/absent session, or a message-less lifecycle event) is RE-QUEUED — never dropped —
+ *    so the reconcile loop's strict hold/expire path remains the single authority for it.
+ */
+export declare function flushPendingForMeshIdleCoordinators(components: DaemonComponents, meshId: string): void;
+export declare function setupMeshEventForwarding(components: DaemonComponents): void;

package/dist/mesh/mesh-event-trace.d.ts

@@ -0,0 +1,21 @@
+export interface MeshEventTraceCtx {
+    /** Primary correlation anchor — the mesh task id (meshActiveTaskId / metadataEvent.taskId). */
+    taskId?: unknown;
+    /** Optional per-event id when the producer assigns one. */
+    eventId?: unknown;
+    /** Worker session id — the fallback anchor when no task is attached. */
+    sessionId?: unknown;
+    nodeId?: unknown;
+    meshId?: unknown;
+    event?: unknown;
+}
+/**
+ * Stable, greppable correlation key. `task=` and `sess=` are ALWAYS rendered (as `-`
+ * when absent) so the key shape is uniform across stages and a single grep alternation
+ * (`task=<id>\|sess=<id>`) follows the event end-to-end.
+ */
+export declare function meshEventTraceKey(ctx: MeshEventTraceCtx): string;
+/** Lifecycle progress (INFO). One line per stage the event clears. */
+export declare function traceMeshEventStage(stage: string, ctx: MeshEventTraceCtx, detail?: string): void;
+/** Event did not advance — rejected / held / skipped / deduped (WARN). */
+export declare function traceMeshEventDrop(reason: string, ctx: MeshEventTraceCtx, detail?: string): void;

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

@@ -0,0 +1,4 @@
+export { isMeshCoordinatorEvent, MESH_FORCE_INJECT_EVENTS, shouldForceInjectMeshEvent, } from './mesh-event-classify.js';
+export { __orderEligibleNodesForTests, __resolveSchedulingStrategyForTests, __resetIdleAutoFastForwardForTests, activeReadonlyAssignedCount, activeWriteAssignedCount, isSessionActivelyGenerating, triggerMeshQueue, tryAssignQueueTask, } from './mesh-queue-assignment.js';
+export type { MeshQueueTriggerResult } from './mesh-queue-assignment.js';
+export { __resetMeshWorkspaceCacheForTests, buildRelayMetadataEvent, handleMeshForwardEvent, resolveForwardEventMeshId, setupMeshEventForwarding, } from './mesh-event-forwarding.js';

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

@@ -0,0 +1,69 @@
+export interface PendingMeshCoordinatorEvent {
+    event: string;
+    meshId: string;
+    nodeLabel: string;
+    nodeId?: string;
+    workspace?: string;
+    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;
+    /**
+     * When set, this event is intended for a specific coordinator SESSION on the
+     * target daemon (the session that originally dispatched the work). PHASE 2 inject
+     * strict-matches the live coordinator by this session id so a sibling coordinator
+     * session on the same daemon does not receive another coordinator's completion.
+     * Absent on legacy / version-skewed events → daemon-level broadcast (no regression).
+     * Rides inside the event payload, so it survives the SQLite payload round-trip and
+     * the JSONL file without a dedicated column; it is NOT a drain-scoping key.
+     */
+    targetCoordinatorSessionId?: string;
+}
+export declare function readRefineJobId(event: {
+    metadataEvent?: Record<string, unknown>;
+} | Record<string, unknown>): string;
+export declare function buildPendingEventFingerprint(event: PendingMeshCoordinatorEvent): string;
+export declare function hasPendingCoordinatorEventDuplicate(event: PendingMeshCoordinatorEvent): boolean;
+export declare function queuePendingMeshCoordinatorEvent(event: PendingMeshCoordinatorEvent): boolean;
+/**
+ * Drain and return pending coordinator events for meshId, removing the drained
+ * ones from both the SQLite inbox and the JSONL legacy file.
+ *
+ * When `opts.onlyEvents` is supplied, ONLY events whose name is in that set are
+ * drained; every other event stays queued (undrained in SQLite, rewritten back to
+ * the JSONL file). The reconcile loop uses this to force-drain terminal/force-inject
+ * events into a *generating* coordinator while leaving non-force progress events for
+ * the coordinator's next idle transition. The atomic SQLite drained=1 marking and the
+ * atomic JSONL rename keep force-drain and a concurrent full drain from double-consuming.
+ */
+export declare function drainPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string | ReadonlyArray<string>, opts?: {
+    onlyEvents?: ReadonlySet<string>;
+}): PendingMeshCoordinatorEvent[];
+/**
+ * FALSE-BLOCKER-CLONE-QUEUE: retract any still-UNDELIVERED `mesh:dispatch_blocked`
+ * actionable-skip event for a task whose blocker has since resolved (the task was
+ * claimed, or its skip transitioned to a self-resolving transient reason). Without
+ * this, a `target_node_id_unmatched` blocker paged during the brief clone/bootstrap
+ * propagation window would linger in the coordinator's pending queue and surface as a
+ * false "actionable blocker — will NOT clear on its own" even after the task dispatched.
+ *
+ * Only removes events that have NOT yet been drained/delivered to the coordinator — an
+ * already-delivered message cannot be unsent, but de-dup re-arm (caller side) plus this
+ * retraction guarantee no NEW stale blocker accumulates. Best-effort across both the
+ * SQLite inbox and the JSONL legacy files (scoped + shared). Returns rows removed.
+ */
+export declare function retractPendingDispatchBlockedEvent(meshId: string | undefined, taskId: string | undefined, coordinatorDaemonId?: string): number;
+/** Peek at pending coordinator events without draining (non-destructive). */
+export declare function getPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string | ReadonlyArray<string>): readonly PendingMeshCoordinatorEvent[];
+/**
+ * Test helper: purge all pending-event state for a mesh — SQLite rows
+ * (including drained fingerprint history) and JSONL files.
+ */
+export declare function __clearMeshPendingEventsForTests(meshId: string): void;
+/** Explicitly clear all pending coordinator events for a mesh (and coordinator if scoped). */
+export declare function clearPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string): void;

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

@@ -0,0 +1,61 @@
+import type { MeshLedgerKind } from './mesh-ledger.js';
+export declare function findRecentTerminalLedgerEvidence(args: {
+    meshId: string;
+    sessionId?: string;
+    nodeId?: string;
+}): {
+    id: string;
+    kind: MeshLedgerKind;
+    payload: Record<string, unknown>;
+    timestamp: string;
+} | null;
+export declare function hasDispatchAfterTerminal(meshId: string, sessionId: string, terminalId: string): boolean;
+export declare function hasUnterminalDirectDispatchLedgerEntry(meshId: string, sessionId: string): boolean;
+export declare function findTerminalLedgerEvidenceForTask(args: {
+    meshId: string;
+    taskId?: string;
+    sessionId?: string;
+    nodeId?: string;
+    tail?: number;
+}): {
+    id: string;
+    kind: Extract<MeshLedgerKind, 'task_completed' | 'task_failed' | 'task_stalled'>;
+    payload: Record<string, unknown>;
+    timestamp: string;
+} | null;
+export declare function reconcileDirectDispatchCompletionFromTranscript(args: {
+    meshId: string;
+    nodeId?: string;
+    sessionId: string;
+    providerType?: string;
+    providerSessionId?: string;
+    taskId: string;
+    finalSummary: string;
+    transcriptMessageAt?: string;
+    completedAt?: string;
+    targetCoordinatorDaemonId?: string;
+    /**
+     * NOTIF-DROP-SYNTH-NO-MESSAGE: the originating coordinator SESSION that dispatched this
+     * task (the `coordinatorSessionId` stamped onto the task_dispatched ledger payload at
+     * dispatch). Stamped onto the synthesized completion's targetCoordinatorSessionId so PHASE 2
+     * STRICT routing matches the exact coordinator session — instead of relying on the
+     * daemon-keyed fallback. When the caller does not pass it, it is recovered from the dispatch
+     * ledger entry below; absent on legacy rows → daemon-level routing (unchanged).
+     */
+    targetCoordinatorSessionId?: string;
+    source?: string;
+}): {
+    reconciled: boolean;
+    kind?: MeshLedgerKind;
+    alreadyTerminal?: boolean;
+    workerResult?: unknown;
+    ledgerEntryId?: string;
+    reason?: string;
+};
+export declare function buildNoProgressCompletionReconciliation(args: {
+    meshId: string;
+    nodeId?: string;
+    nodeLabel: string;
+    metadataEvent: Record<string, unknown>;
+    sourceInstanceId?: string;
+}): Record<string, unknown> | null;

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

@@ -0,0 +1,75 @@
+import type { SessionRecoveryContext } from './mesh-ledger.js';
+export declare function readNonEmptyString(value: unknown): string;
+export declare function readRecord(value: unknown): Record<string, unknown> | undefined;
+/**
+ * The relay-safety metadata a worker session must carry so that its completion /
+ * generating events route back to the coordinator proactively (without waiting for
+ * a mesh_read_chat reconcile). meshCoordinatorDaemonId is the routing anchor the
+ * core forwarder (injectMeshSystemMessage) keys on to pick a remote coordinator
+ * target; meshNodeFor/meshNodeId identify the worker, and launchedByCoordinator is
+ * the delegation proof. See resolveWorkerDelegateRouting().
+ */
+export interface MeshWorkerRelayStamp {
+    meshNodeFor?: string;
+    meshNodeId?: string;
+    meshCoordinatorDaemonId?: string;
+    meshCoordinatorSessionId?: string;
+    launchedByCoordinator?: boolean;
+}
+/**
+ * Build the relay-safety stamp from a dispatch's meshContext, only including fields
+ * the session does not already carry. Returns undefined when there is nothing new to
+ * stamp, so callers can skip a no-op updateSettings() write.
+ *
+ * This closes the remote-session relay gap: a worker session reached by a dispatch
+ * that carries coordinatorDaemonId (mesh_send_task / queue assignment over P2P) gets
+ * the coordinator anchor persisted onto its settings at dispatch time, even if it was
+ * not launched via mesh_launch_session. Without the stamp the forwarder cannot resolve
+ * a remote coordinator and the completion event sits in the pending queue until a
+ * read_chat-triggered reconcile drains it.
+ */
+export declare function buildMeshWorkerRelayStamp(currentSettings: Record<string, unknown> | undefined, meshContext: {
+    meshId?: unknown;
+    nodeId?: unknown;
+    coordinatorDaemonId?: unknown;
+    coordinatorSessionId?: unknown;
+} | undefined): MeshWorkerRelayStamp | undefined;
+export declare function resolveEventSessionId(event: Record<string, unknown>, fallback?: unknown): string;
+export declare function readRefineJobId(event: {
+    metadataEvent?: Record<string, unknown>;
+} | Record<string, unknown>): string;
+export declare function readWorkerResultMetadata(event: Record<string, unknown>): Record<string, unknown> | undefined;
+/**
+ * The worker's final assistant text carried on a completion event — read from
+ * `finalSummary` (and the `workerResult.summary` / `result.summary` fallbacks some
+ * paths use). Returns '' when the event carries no assistant text (lifecycle events
+ * without a summary). Shared by the coordinator chat surface (buildMeshSystemMessage)
+ * and the held-event ledger audit record so both read the summary the same way.
+ */
+export declare function readMeshCompletionSummary(metadataEvent: Record<string, unknown>): string;
+export declare function resolveMeshSurfacedSessionPreview(metadataEvent: Record<string, unknown>): {
+    preview: string;
+    role: 'assistant';
+    receivedAt: number;
+} | undefined;
+export declare function isMissingFinalAssistantDiagnostic(record: Record<string, unknown> | undefined): boolean;
+export declare function isFalseIdleCompletion(record: Record<string, unknown>): boolean;
+export declare function isWeakCompletionEvidence(record: Record<string, unknown> | undefined): boolean;
+export declare function isWeakCompletionMetadata(metadataEvent: Record<string, unknown>): boolean;
+export declare function buildMeshSystemMessage(args: {
+    event: string;
+    nodeLabel: string;
+    metadataEvent: Record<string, unknown>;
+    recoveryContext?: SessionRecoveryContext | null;
+    /**
+     * BOOTSTRAP-MSG: true when a queued task targeting this freshly-bootstrapped
+     * worktree node is pending/assigned and will be (or has just been) auto-claimed
+     * by the post-bootstrap queue re-fire. When set, the worktree_bootstrap_complete
+     * message drops the misleading "use mesh_launch_session" advice (which would
+     * spawn a DUPLICATE session alongside the auto-claimed one) and tells the
+     * coordinator the queue will handle it. Absent/false → no targeted task → keep
+     * the manual-launch advice. The caller computes this from the work queue; the
+     * builder stays pure so both branches are unit-testable via this flag.
+     */
+    worktreeHasQueuedTask?: boolean;
+}): string;