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

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-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,91 @@
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+import type { RepoMeshSchedulingStrategy } from '../repo-mesh-types.js';
+export declare function __resetIdleAutoFastForwardForTests(): void;
+export declare function __resetMeshWorkspaceCacheForTests(): void;
+export declare function tryAssignQueueTask(components: DaemonComponents, meshId: string, nodeId: string, sessionId: string, providerType: string): boolean;
+/** Active assignments that hold the one-active-per-node / global-parallel invariant
+ *  (everything except read-only diagnoses, which run unbounded by the write cap). */
+export declare function activeWriteAssignedCount(meshId: string): number;
+/** Active read-only (live_debug_readonly) assignments, for the read-only safety cap. */
+export declare function activeReadonlyAssignedCount(meshId: string): number;
+/**
+ * Order eligible nodes for assignment per the mesh scheduling pipeline:
+ *   PRIORITY (schedulingPriority desc) → TIE-BREAK (strategy).
+ *
+ * The caller has already applied the TAG hard-filter and is responsible for the
+ * MAX-ALLOC capacity gate (the per-node launch/claim checks). This function only
+ * decides the *preference order* among nodes that are otherwise eligible.
+ *
+ * - 'first_eligible' (default): returns the input order verbatim and does NOT touch
+ *   the round-robin cursor — byte-for-byte the pre-feature behavior.
+ * - 'priority_only': schedulingPriority desc, then input order (load ignored).
+ * - 'least_loaded': schedulingPriority desc, then active load asc, then input order.
+ * - 'round_robin': same as least_loaded, but among nodes tied at (priority, load)
+ *   the input order is rotated by a per-mesh cursor that advances once per pass.
+ *
+ * `nodes` carries the original config/array index so the tie-break can fall back to
+ * deterministic input order. `bumpCursor` advances the round-robin cursor exactly
+ * once per scheduling pass (only consulted for 'round_robin').
+ */
+interface RankableNode {
+    nodeId: string;
+    node: any;
+    index: number;
+}
+/** Test-only: the pure node-ordering stage (PRIORITY → TIE-BREAK). Exposed so the
+ *  scheduling pipeline can be unit-tested without standing up live CLI sessions. */
+export declare function __orderEligibleNodesForTests(meshId: string, strategy: RepoMeshSchedulingStrategy, nodes: RankableNode[], opts?: {
+    bumpCursor?: boolean;
+}): RankableNode[];
+export interface MeshQueueTriggerResult {
+    success: true;
+    meshId: string;
+    pendingBefore: number;
+    assignedBefore: number;
+    pendingAfter: number;
+    assignedAfter: number;
+    claimed: boolean;
+    newlyAssignedTasks: Array<{
+        id: string;
+        nodeId?: string;
+        sessionId?: string;
+    }>;
+    localIdleSessionsChecked: number;
+    remoteIdleSessionsChecked: number;
+    skippedSessions: Array<{
+        nodeId?: string;
+        sessionId?: string;
+        reason: string;
+        status?: string;
+    }>;
+    autoLaunchStarted: boolean;
+    /**
+     * True when a worker session is already on its way to claim a still-pending task —
+     * either launched this tick (autoLaunchStarted) or launched on a prior tick and still
+     * booting/awaiting-claim. Callers MUST treat this as "wait, do not launch another
+     * session": a second launch double-edits the worktree. Mutually informative with
+     * `noIdleMeshSessionAvailable`, which is suppressed whenever this is true.
+     */
+    autoLaunchPending?: boolean;
+    noIdleMeshSessionAvailable?: boolean;
+}
+export declare function triggerMeshQueue(components: DaemonComponents, meshId: string): Promise<MeshQueueTriggerResult>;
+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;
+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;
+};
+export declare function setupMeshEventForwarding(components: DaemonComponents): void;
+export {};

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

@@ -0,0 +1,55 @@
+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[];
+/** 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,40 @@
+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 reconcileDirectDispatchCompletionFromTranscript(args: {
+    meshId: string;
+    nodeId?: string;
+    sessionId: string;
+    providerType?: string;
+    providerSessionId?: string;
+    taskId: string;
+    finalSummary: string;
+    transcriptMessageAt?: string;
+    completedAt?: string;
+    targetCoordinatorDaemonId?: 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,61 @@
+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 isWeakCompletionMetadata(metadataEvent: Record<string, unknown>): boolean;
+export declare function buildMeshSystemMessage(args: {
+    event: string;
+    nodeLabel: string;
+    metadataEvent: Record<string, unknown>;
+    recoveryContext?: SessionRecoveryContext | null;
+}): 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 } from './mesh-events-pending.js';
+export { queuePendingMeshCoordinatorEvent, drainPendingMeshCoordinatorEvents, getPendingMeshCoordinatorEvents, clearPendingMeshCoordinatorEvents, } from './mesh-events-pending.js';
+export { reconcileDirectDispatchCompletionFromTranscript, } from './mesh-events-stale.js';
+export { setupMeshReconcileLoop, runMeshReconcileTick, } from './mesh-reconcile-loop.js';
+export type { MeshQueueTriggerResult } from './mesh-events-coordinator.js';
+export { tryAssignQueueTask, 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

@@ -0,0 +1,9 @@
+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;
+export declare function isMeshHostOwner(mesh: unknown): boolean;
+export declare function buildMeshHostRequiredFailure(mesh: unknown, operation: string): Record<string, unknown>;
+export declare function requireMeshHostQueueOwner(opts?: {
+    ownerRole?: RepoMeshDaemonRole;
+}): void;
+export declare function createDefaultMeshHostMetadata(): RepoMeshHostMetadata;

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

@@ -0,0 +1,86 @@
+/**
+ * Mesh init / onboarding helper.
+ *
+ * One-shot helper that onboards an existing git project into Repo Mesh:
+ *   1. suggest + write `.adhdev/refine.json`           (Refinery validation config)
+ *   2. suggest + write `.adhdev/worktree_bootstrap.json` (worktree bootstrap config)
+ *   3. recommend a node providerPriority from the installed CLI providers
+ *
+ * Design contract (matches the rest of the mesh tooling):
+ *   - Heuristics are suggestion/scaffold only. The written files are the
+ *     execution source of truth; Refinery/bootstrap only ever read the saved
+ *     config. The suggestion functions never become the execution path.
+ *   - Writing is opt-in (`write: true`) and never clobbers an existing config
+ *     unless `overwrite: true` is set, so re-running init on an already-onboarded
+ *     repo is safe.
+ *   - The providerPriority recommendation is returned, not auto-applied to the
+ *     node policy — applying it mutates mesh policy, which is the coordinator's
+ *     decision.
+ */
+import { type RepoMeshRefineConfig, type RepoMeshRefineValidationCommandConfig } from './refine-config.js';
+import { type RepoMeshWorktreeBootstrapConfig } from './worktree-bootstrap-config.js';
+import type { CLIInfo } from '../detection/cli-detector.js';
+/** Canonical write targets — the first/preferred location for each config family. */
+export declare const MESH_INIT_REFINE_CONFIG_PATH: string;
+export declare const MESH_INIT_WORKTREE_BOOTSTRAP_CONFIG_PATH: string;
+export interface MeshInitConfigFileResult {
+    path: string;
+    relativePath: string;
+    written: boolean;
+    /** Why it was not written (already_exists / not_suggested / no change). */
+    skippedReason?: 'already_exists' | 'no_suggestion';
+    config?: RepoMeshRefineConfig | RepoMeshWorktreeBootstrapConfig;
+}
+/**
+ * Build a worktree_bootstrap scaffold from package scripts. Mirrors
+ * suggestMeshRefineConfig's "scaffold only" posture: prefers an `install`/`ci`
+ * style script, else falls back to `npm install`, and records existing
+ * lockfiles as staleInputs so a base merge that changes them re-runs bootstrap.
+ *
+ * Returns undefined when there is nothing meaningful to scaffold.
+ */
+export declare function suggestMeshWorktreeBootstrapConfig(workspace: string): {
+    commands: RepoMeshRefineValidationCommandConfig[];
+    staleInputs: string[];
+    suggestedConfig?: RepoMeshWorktreeBootstrapConfig;
+};
+export declare function suggestNodeProviderPriority(detected: CLIInfo[]): {
+    providerPriority: string[];
+    installedProviders: Array<{
+        id: string;
+        displayName: string;
+        version?: string;
+    }>;
+};
+export interface RunMeshInitOptions {
+    /** When true, persist suggested configs to disk. Defaults to dry-run (false). */
+    write?: boolean;
+    /** When true, overwrite an existing config file. Defaults to false (never clobber). */
+    overwrite?: boolean;
+}
+export interface RunMeshInitResult {
+    success: true;
+    workspace: string;
+    dryRun: boolean;
+    refine: MeshInitConfigFileResult;
+    worktreeBootstrap: MeshInitConfigFileResult;
+    providers: {
+        providerPriority: string[];
+        installedProviders: Array<{
+            id: string;
+            displayName: string;
+            version?: string;
+        }>;
+    };
+    note: string;
+}
+/**
+ * Orchestrate the full onboarding flow for one workspace:
+ *   detect installed CLIs → suggest refine + bootstrap configs → (optionally)
+ *   write them → recommend a node providerPriority.
+ *
+ * `detected` is injected (the caller resolves it via detectCLIs with its
+ * ProviderLoader) so this module stays free of provider-loader wiring and is
+ * trivially unit-testable.
+ */
+export declare function runMeshInit(mesh: any, workspace: string, detected: CLIInfo[], options?: RunMeshInitOptions): RunMeshInitResult;