@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

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

@@ -0,0 +1,258 @@
+import { MESH_PROTOCOL_VERSION_V2, type CoordinatorIdentity, type MeshEventScope } from './contracts.js';
+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;
+    /** '2.0' once stamped. Absent on v1 events. */
+    protocolVersion?: typeof MESH_PROTOCOL_VERSION_V2;
+    /** Idempotency key (UUID). The receiver's authoritative dedup key (B3). */
+    eventId?: string;
+    /** Routing scope. Defaulted from the event name unless the emit hint overrides. */
+    scope?: MeshEventScope;
+    /** Identity of the coordinator that dispatched the work this event reports. */
+    dispatchedBy?: CoordinatorIdentity;
+    /** Present only for unicast scope: the coordinator this event is addressed to. */
+    intendedFor?: CoordinatorIdentity;
+    /**
+     * True when this event was stamped as a broadcast SOLELY because no owning
+     * coordinator identity was resolvable at emit time (self-fallback: dispatchedBy
+     * is THIS daemon's own machineId, not a real coordinator). Such a broadcast has
+     * no owner, so the MAGI-REPLICA-COMPLETION-EVENT-LEAK guard — which only exists
+     * to stop a NON-owner coordinator from consuming an OWNED terminal event — must
+     * not apply: an ownerless terminal broadcast is a genuine "deliver to any
+     * coordinator that drains on this machine" event and identity-matching its
+     * self-id dispatchedBy against the drainer would wrongly route it away.
+     * Absent (undefined/false) on a normally-owned event → the leak guard applies.
+     */
+    dispatchedBySelfFallback?: boolean;
+}
+/**
+ * Optional emit-time hint passed to queuePendingMeshCoordinatorEvent so a call
+ * site can override the name-defaulted scope or supply richer coordinator
+ * identity (e.g. a coordinatorRunId the base event fields don't carry). Every
+ * field is optional; when omitted the stamp is derived entirely from the
+ * event's own targetCoordinatorDaemonId / targetCoordinatorSessionId. Kept
+ * separate from the event so existing single-arg callers are untouched.
+ */
+export interface PendingEventEmitHint {
+    scope?: MeshEventScope;
+    /** Overrides the coordinator identity derived from the event's target fields. */
+    dispatchedBy?: CoordinatorIdentity;
+    /** Overrides the unicast target derived from the event's target fields. */
+    intendedFor?: CoordinatorIdentity;
+    /** coordinatorRunId to fold into the derived identity when the event lacks one. */
+    coordinatorRunId?: string;
+}
+/**
+ * T6 (B3c) enforce switch. When ON, the drain path stops passing an unversioned
+ * (v1) or a validation-failing v2 event through to the coordinator — it QUARANTINES
+ * it instead (excluded from the delivered batch + WARN + counter), and unicast
+ * routing is the only delivery path (there is no v1 broadcast fallback). On by
+ * default; set MESH_PROTOCOL_V2_ENFORCE=0/false/off/no to disable and restore the
+ * accept-and-warn rollout behaviour exactly.
+ *
+ * Per the rollout plan (§1 decision 4): enforce is `MESH_PROTOCOL_V2_ENFORCE` (env).
+ * Now that every node emits v2 (§배포 게이트 1 / risk §4), the code default is ON —
+ * a manual env injection is no longer required to get enforce behaviour. Rollback to
+ * accept mode is a pure-env step: set `MESH_PROTOCOL_V2_ENFORCE=0` (or `false`/`off`/
+ * `no`) — no code change, no data migration (the schema is additive). Read at call
+ * time so a test / operator can toggle it without a restart.
+ *
+ * Quarantine (not drop) keeps the loss-free invariant. The DESTRUCTIVE drain has
+ * already consumed the event from its store by the time routing runs, so "held
+ * back" here means: excluded from the delivered batch AND mirrored into the mesh
+ * ledger as a recoverable `event_held` entry (the same recovery channel the
+ * pending-trim path uses). It is observable via the counters + the ledger, so an
+ * operator can requeue it after fixing the producer. The non-destructive PEEK path
+ * (countMetrics=false) merely omits the event from the returned list — it never
+ * consumed it and must not ledger-record on every status poll.
+ */
+export declare function isMeshProtocolV2EnforceEnabled(): boolean;
+/** Observability counters for the v2 drain path. Read by tests and surfaced in
+ *  mesh_status (B4/T6). Process-lifetime totals — never reset in production. */
+declare const meshV2DrainCounters: {
+    /** v2 events that passed validation and unicast/broadcast routing → delivered. */
+    v2Delivered: number;
+    /** v2 unicast events skipped because intendedFor addressed another coordinator. */
+    v2RoutedAway: number;
+    /** v2 events skipped because their eventId was already drained (idempotency). */
+    v2DedupSkipped: number;
+    /** v2 events that failed assertPendingMeshCoordinatorEventV2 but were PASSED
+     *  THROUGH (accept mode). Non-zero here is the rollout signal that a producer
+     *  emits a malformed envelope. */
+    v2ValidationFailedAccepted: number;
+    /** unicast events re-attributed to the drainer via daemon-core match (a
+     *  coordinatorRunId change orphaned them). */
+    v2ReattributedToDrainer: number;
+    /** v1 (unversioned) events passed through as broadcast (rollout baseline). */
+    v1BroadcastAccepted: number;
+    /** T6 enforce: v2 events that FAILED validation and were QUARANTINED (held back
+     *  from delivery, not dropped). Non-zero here means a producer is still emitting a
+     *  malformed envelope after enforce was turned on. */
+    v2ValidationFailedQuarantined: number;
+    /** T6 enforce: v1 (unversioned) events QUARANTINED because no v2 envelope could be
+     *  derived at emit time. Non-zero here means a producer path still emits v1 after
+     *  enforce — it should reach 0 once every node is on a v2-stamping build. */
+    v1UnversionedQuarantined: number;
+};
+/** Test/observability accessor for the v2 drain counters (snapshot copy). */
+export declare function getMeshV2DrainCounters(): Readonly<typeof meshV2DrainCounters>;
+/** Test helper: zero the v2 drain counters so a test starts from a clean slate. */
+export declare function __resetMeshV2DrainCountersForTests(): void;
+/** Test helper: clear the one-shot WARN dedup set. */
+export declare function __resetMeshV2WarnDedupForTests(): void;
+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;
+/**
+ * Retention sweep for the SQLite mesh_pending_events inbox. Deletes long-drained
+ * rows (past the idempotency-useful window) and long-orphaned undrained rows (a
+ * coordinator identity that never returned). Best-effort and idempotent: a store
+ * failure or an empty table is a cheap no-op. Called from the periodic mesh-event
+ * maintenance sweep. Returns the number of rows pruned (0 when nothing to do).
+ */
+export declare function prunePendingMeshCoordinatorEventsRetention(): number;
+/**
+ * Stamp the v2 protocol envelope onto a pending event at emit time (B2a).
+ *
+ * Non-breaking: returns a NEW event object with protocolVersion/eventId/scope/
+ * dispatchedBy/intendedFor added when a coordinator identity can be derived,
+ * otherwise returns the input unchanged (a v1 event, broadcast-treated during
+ * rollout). Identity and the unicast target are derived from the event's own
+ * targetCoordinatorDaemonId / targetCoordinatorSessionId (already carried by
+ * every producer), so most call sites need no change; the optional `hint`
+ * overrides scope/identity where a site knows better.
+ *
+ * The eventId is generated here (randomUUID) exactly once, so re-queues that
+ * pass an already-stamped event keep their original eventId — the idempotency
+ * key is stable across re-delivery. An already-stamped event is returned as-is.
+ */
+export declare function stampPendingEventV2(event: PendingMeshCoordinatorEvent, hint?: PendingEventEmitHint): PendingMeshCoordinatorEvent;
+/**
+ * Copy the v2 envelope fields that are present on `event` onto a flat wire
+ * payload. Only sets a field when it is present, so a v1 event contributes
+ * nothing (the payload stays v1-shaped and version-skew safe).
+ */
+export declare function serializeV2EnvelopeToWire(event: PendingMeshCoordinatorEvent): Record<string, unknown>;
+/**
+ * Restore the v2 envelope fields from a flat wire payload for a re-queue. Only
+ * returns fields that survive validation; a payload missing/malforming a field
+ * yields a partial (or empty) object so the re-queue path stays v1-safe. The
+ * eventId is returned verbatim — its preservation is the idempotency guarantee.
+ */
+export declare function readV2EnvelopeFromWire(payload: Record<string, unknown>): Partial<Pick<PendingMeshCoordinatorEvent, 'protocolVersion' | 'eventId' | 'scope' | 'dispatchedBy' | 'intendedFor'>>;
+export declare function queuePendingMeshCoordinatorEvent(rawEvent: PendingMeshCoordinatorEvent, hint?: PendingEventEmitHint): 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>;
+    drainerIdentity?: CoordinatorIdentity;
+}): 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>, opts?: {
+    drainerIdentity?: CoordinatorIdentity;
+}): 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;
+/**
+ * Test helper: persist a pending event VERBATIM, skipping the emit-time v2 stamp.
+ * The local emit path (queuePendingMeshCoordinatorEvent → stampPendingEventV2) now
+ * always mints a v2 envelope (self-daemon broadcast fallback when no coordinator
+ * identity is present), so a genuinely-unversioned (v1) row can no longer be produced
+ * through the normal queue. The drain-side v1 handling (accept-broadcast / enforce-
+ * quarantine) still matters for durable v1 rows written by a pre-v2 daemon and for
+ * version-skewed remote relays, so tests inject those rows directly through this.
+ */
+export declare function __persistUnstampedPendingEventForTests(event: PendingMeshCoordinatorEvent): boolean;
+/** Narrowing filter for {@link requeueHeldMeshCoordinatorEvents}, scoped within one mesh. */
+export interface MeshHeldEventRequeueFilter {
+    /** Restore only held events whose worker task id matches (from the held event's metadata/taskId). */
+    taskId?: string;
+    /** Restore only held events originating from this node. */
+    nodeId?: string;
+    /** Restore only held events of this event name (e.g. 'session:completed'). */
+    event?: string;
+    /** Restore only held entries recorded at/after this ISO timestamp. */
+    since?: string;
+    /** Restore only held entries with this hold reason (e.g. 'pending_trim_dropped'). */
+    reason?: string;
+}
+export interface MeshHeldEventRequeueResult {
+    meshId: string;
+    /** event_held entries considered after the filter. */
+    matched: number;
+    /** entries skipped because a prior requeue already recovered them. */
+    alreadyRequeued: number;
+    /** entries skipped because they carried no restorable original event / were not recoverable. */
+    unrecoverable: number;
+    /** entries handed to the pending queue (some may have been dedup-suppressed downstream). */
+    requeued: number;
+    /** of `requeued`, how many the pending-queue dedup collapsed onto a live event. */
+    dedupSuppressed: number;
+    entries: Array<{
+        heldEntryId: string;
+        event: string;
+        nodeId?: string;
+        taskId?: string;
+        reason?: string;
+        outcome: 'requeued' | 'already_requeued' | 'unrecoverable';
+    }>;
+}
+/**
+ * Restore recoverable `event_held` ledger entries back to the pending coordinator
+ * queue for `meshId`. See the block comment above for the no-loss / no-double-requeue
+ * invariants. Returns per-entry outcomes for the caller to surface.
+ */
+export declare function requeueHeldMeshCoordinatorEvents(meshId: string, filter?: MeshHeldEventRequeueFilter): MeshHeldEventRequeueResult;
+/** Explicitly clear all pending coordinator events for a mesh (and coordinator if scoped). */
+export declare function clearPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string): void;
+export {};

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;

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

@@ -1,49 +1,6 @@
-import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
-export interface PendingMeshCoordinatorEvent {
-    event: string;
-    meshId: string;
-    nodeLabel: string;
-    nodeId?: string;
-    workspace?: string;
-    metadataEvent: Record<string, unknown>;
-    queuedAt: number;
-}
-export declare function queuePendingMeshCoordinatorEvent(event: PendingMeshCoordinatorEvent): boolean;
-/** Drain and return all pending coordinator events for meshId, removing them from disk. */
-export declare function drainPendingMeshCoordinatorEvents(meshId?: string): PendingMeshCoordinatorEvent[];
-/** Peek at pending coordinator events without draining (non-destructive). */
-export declare function getPendingMeshCoordinatorEvents(meshId?: string): readonly PendingMeshCoordinatorEvent[];
-/** Explicitly clear all pending coordinator events for a mesh. */
-export declare function clearPendingMeshCoordinatorEvents(meshId?: string): void;
-export declare function tryAssignQueueTask(components: DaemonComponents, meshId: string, nodeId: string, sessionId: string, providerType: string): boolean;
-/**
- * Triggers a queue check for all nodes in the mesh.
- * Called when a new task is enqueued, in case nodes are already idle.
- */
-export declare function triggerMeshQueue(components: DaemonComponents, meshId: string): Promise<void>;
-export declare function handleMeshForwardEvent(components: DaemonComponents, payload: Record<string, unknown>): {
-    success: boolean;
-    forwarded: number;
-    suppressed: boolean;
-    intentionalCleanupStop: boolean;
-    duplicateCompletion?: undefined;
-    error?: undefined;
-} | {
-    success: boolean;
-    forwarded: number;
-    suppressed: boolean;
-    duplicateCompletion: boolean;
-    intentionalCleanupStop?: undefined;
-    error?: undefined;
-} | {
-    success: boolean;
-    forwarded: number;
-    suppressed?: undefined;
-    intentionalCleanupStop?: undefined;
-    duplicateCompletion?: undefined;
-    error?: undefined;
-} | {
-    success: boolean;
-    error: string;
-};
-export declare function setupMeshEventForwarding(components: DaemonComponents): void;
+export type { PendingMeshCoordinatorEvent, MeshHeldEventRequeueFilter, MeshHeldEventRequeueResult, } from './mesh-events-pending.js';
+export { queuePendingMeshCoordinatorEvent, drainPendingMeshCoordinatorEvents, getPendingMeshCoordinatorEvents, clearPendingMeshCoordinatorEvents, requeueHeldMeshCoordinatorEvents, serializeV2EnvelopeToWire, readV2EnvelopeFromWire, getMeshV2DrainCounters, isMeshProtocolV2EnforceEnabled, } from './mesh-events-pending.js';
+export { reconcileDirectDispatchCompletionFromTranscript, } from './mesh-events-stale.js';
+export { setupMeshReconcileLoop, runMeshReconcileTick, resolveCoordinatorDrainDeliverability, shouldHoldPendingDrainForBusyLocalCoordinator, getMeshV2BackstopCounters, } from './mesh-reconcile-loop.js';
+export type { MeshQueueTriggerResult } from './mesh-events-coordinator.js';
+export { tryAssignQueueTask, isSessionActivelyGenerating, triggerMeshQueue, handleMeshForwardEvent, setupMeshEventForwarding, isMeshCoordinatorEvent, __resetIdleAutoFastForwardForTests, __resetMeshWorkspaceCacheForTests, } from './mesh-events-coordinator.js';

package/dist/mesh/mesh-fast-forward.d.ts

@@ -0,0 +1,81 @@
+import type { GitRepoStatus } from '../git/git-types.js';
+export interface MeshFastForwardNodeArgs {
+    nodeId?: string;
+    meshId?: string;
+    workspace: string;
+    branch?: string;
+    execute?: boolean;
+    dryRun?: boolean;
+    updateSubmodules?: boolean;
+    submoduleIgnorePaths?: string[];
+    timeoutMs?: number;
+    trigger?: 'manual' | 'idle_auto' | string;
+    /**
+     * Operation mode. 'merge' (default) absorbs upstream commits into the local
+     * branch via git merge --ff-only (requires ahead=0, behind>0). 'push' publishes
+     * local commits to origin via a strict ff-only push (requires HEAD to be a
+     * descendant of origin/<branch>); it never force-pushes, resets, or rebases.
+     */
+    mode?: 'merge' | 'push';
+    /**
+     * When mode='push', also fast-forward push submodule (e.g. oss) HEADs to their
+     * origin main branch. Gated by allowAutoPublishSubmoduleMainCommits — skipped
+     * unless that policy is true. Each submodule must still pass the descendant gate.
+     * Defaults false (root push only).
+     */
+    pushSubmodules?: boolean;
+    /**
+     * Mesh policy flag mirrored from RepoMeshPolicy.allowAutoPublishSubmoduleMainCommits.
+     * Submodule pushes are refused unless this is true.
+     */
+    allowAutoPublishSubmoduleMainCommits?: boolean;
+}
+export interface MeshFastForwardPlannedStep {
+    operation: 'refresh_upstream' | 'verify_clean_worktree' | 'verify_fast_forward' | 'merge_ff_only' | 'submodule_update' | 'verify_post_status' | 'verify_push_descendant' | 'push_ff_only' | 'push_submodules_ff_only';
+    description: string;
+    safe: true;
+    willMutateWorktree: boolean;
+}
+export interface MeshFastForwardSubmodulePushResult {
+    path: string;
+    commit?: string;
+    remote: string;
+    remoteBranch: string;
+    pushed: boolean;
+    skipped: boolean;
+    code: string;
+    refspec?: string;
+    error?: string;
+}
+export interface MeshFastForwardResult {
+    success: boolean;
+    code: string;
+    nodeId?: string;
+    meshId?: string;
+    workspace: string;
+    mode: 'merge' | 'push';
+    allowed: boolean;
+    dryRun: boolean;
+    willRun: boolean;
+    executed: boolean;
+    updateSubmodules: boolean;
+    blockingReasons: string[];
+    plannedSteps: MeshFastForwardPlannedStep[];
+    current?: GitRepoStatus;
+    preStatus?: GitRepoStatus;
+    postStatus?: GitRepoStatus;
+    /** Push target derived from the tracked upstream (mode='push'). */
+    pushTarget?: {
+        remote: string;
+        remoteBranch: string;
+        refspec: string;
+    };
+    /** Submodule ff-only push outcomes (mode='push' with pushSubmodules). */
+    submodulePushes?: MeshFastForwardSubmodulePushResult[];
+    finalBranchConvergenceState?: Record<string, unknown>;
+    operationError?: string;
+    ledgerError?: string;
+    nextStep?: string;
+    trigger?: string;
+}
+export declare function fastForwardMeshNode(args: MeshFastForwardNodeArgs): Promise<MeshFastForwardResult>;

package/dist/mesh/mesh-host-ownership.d.ts

@@ -1,6 +1,26 @@
 import type { RepoMeshDaemonRole, RepoMeshHostMetadata, RepoMeshHostStatus } from '../repo-mesh-types.js';
 export declare function normalizeMeshDaemonRole(value: unknown): RepoMeshDaemonRole | undefined;
-export declare function resolveMeshHostStatus(mesh: unknown): RepoMeshHostStatus;
+/**
+ * Options for resolveMeshHostStatus's read-side host-pin default.
+ *
+ * `localDaemonId` is the id of the daemon evaluating the mesh (typically
+ * `deps.statusInstanceId`). When the persisted `meshHost` declares `role:'host'`
+ * but carries NO `hostDaemonId` (the first-setup miss — a host mesh whose pin was
+ * never written to config), the host daemon IS this local daemon by definition, so
+ * we synthesize `hostDaemonId = localDaemonId` (and, when the mesh has a node
+ * representing this daemon, `hostNodeId`). This is the read-side default — the SSOT
+ * is computed from the role + the evaluating daemon's identity rather than requiring
+ * a config migration to backfill every already-created mesh.
+ *
+ * HARD guard: the synthesis fires ONLY for `role:'host'`. A `role:'member'` daemon
+ * must NEVER fill itself in as host — that would make a member falsely claim
+ * coordinator/queue ownership.
+ */
+export interface ResolveMeshHostOptions {
+    /** Id of the daemon evaluating this mesh (e.g. deps.statusInstanceId). */
+    localDaemonId?: string;
+}
+export declare function resolveMeshHostStatus(mesh: unknown, opts?: ResolveMeshHostOptions): RepoMeshHostStatus;
 export declare function isMeshHostOwner(mesh: unknown): boolean;
 export declare function buildMeshHostRequiredFailure(mesh: unknown, operation: string): Record<string, unknown>;
 export declare function requireMeshHostQueueOwner(opts?: {