@adhdev/daemon-core 0.9.82-rc.16 → 0.9.82-rc.160

package/dist/installer.d.ts

@@ -28,10 +28,7 @@ export interface InstallResult {
     alreadyInstalled: boolean;
     error?: string;
 }
-/**
- * Check if an extension is already installed
- */
-export declare function isExtensionInstalled(ide: IDEInfo, marketplaceId: string): boolean;
+export declare function isExtensionInstalled(ide: IDEInfo, marketplaceId: string): Promise<boolean>;
 /**
  * Install a single extension
  */

package/dist/ipc/local-ipc-server.d.ts

@@ -0,0 +1,91 @@
+/**
+ * LocalIpcServer — generic HTTP + WebSocket IPC endpoint for daemon processes.
+ *
+ * Both daemon-cloud and daemon-standalone need a local IPC surface so
+ * external tools — the `adhdev mcp --mode ipc` MCP server and anything
+ * else that wants to issue commands without going through the cloud
+ * Worker — can connect over `ws://127.0.0.1:<port>/ipc`.
+ *
+ * Until now the implementation lived only in daemon-cloud. Standalone
+ * sessions therefore couldn't host MCP mesh tools — codex/claude config
+ * pointing at `--mode ipc` got `Cannot reach ipc daemon`. This module
+ * moves the transport into daemon-core so both daemons can mount it.
+ *
+ * The transport itself is daemon-agnostic. Cloud-specific behaviors
+ * (mesh relay, mandatory update gates) are injected via the caller's
+ * `handleCommand` hook; the IPC layer just frames/unframes JSON and
+ * routes messages.
+ */
+import { WebSocket } from 'ws';
+/** Parameters passed to `handleCommand` for each incoming ext:command frame. */
+export interface IpcCommandContext {
+    /** The raw `command` field from the message — caller decides routing. */
+    command: string;
+    /** Args provided by the client; may have been normalized by the caller. */
+    args: Record<string, unknown>;
+    /** Stable id correlating the request and the eventual ext:command_result. */
+    requestId: string;
+    /** The connected WebSocket — only needed if the caller wants to send extra events. */
+    ws: WebSocket;
+}
+/** Result reported back to the client. `result` is optional context for success. */
+export interface IpcCommandResult {
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    /**
+     * Additional fields the caller wants merged into the response payload
+     * (e.g. the cloud daemon's mandatory-update-block fields). Reserved.
+     */
+    extra?: Record<string, unknown>;
+}
+/** Status payload returned from GET / on the IPC HTTP port. */
+export interface IpcStatusPayload {
+    ok: true;
+    pid: number;
+    wsPath: string;
+    port: number;
+    /** Arbitrary daemon-specific summary. Cloud daemon includes mesh state, etc. */
+    status: Record<string, unknown> | null;
+}
+export interface LocalIpcServerOptions {
+    /** TCP port to listen on. 19222 is the conventional default. */
+    port: number;
+    /** Build the GET / status payload. Called on every health probe. */
+    buildStatusPayload: () => Record<string, unknown> | null;
+    /** Build the welcome message sent to a freshly-connected client. */
+    buildWelcomePayload: () => Record<string, unknown>;
+    /** Handle a single ext:command frame. Caller decides routing and returns the result. */
+    handleCommand: (ctx: IpcCommandContext) => Promise<IpcCommandResult>;
+    /** Optional notification when a new client connects (lets daemon track them for broadcasts). */
+    onClientConnected?: (ws: WebSocket) => void;
+    /** Optional notification when a client disconnects. */
+    onClientDisconnected?: (ws: WebSocket) => void;
+    /** Optional logger label (defaults to "IPC"). */
+    logCategory?: string;
+}
+/**
+ * Returned controller for stopping the server and broadcasting to clients.
+ * Stored by the daemon and torn down at shutdown.
+ */
+export interface LocalIpcServerHandle {
+    /** True once `listen()` succeeded. */
+    isListening(): boolean;
+    /** Push a message to every connected client. */
+    broadcast(type: string, payload: unknown): void;
+    /** Close all client sockets + the HTTP server. */
+    close(): Promise<void>;
+}
+/**
+ * Build a JSON HTTP response describing the IPC endpoint. Exposed so caller
+ * code (and tests) can build the same shape without spinning a real server.
+ */
+export declare function buildIpcStatusHttpResponse(method: string | undefined, url: string | undefined, payload: IpcStatusPayload): {
+    statusCode: number;
+    body: Record<string, unknown>;
+};
+/**
+ * Start the local IPC server. Returns a handle the caller can use to broadcast
+ * events and tear down at shutdown.
+ */
+export declare function startLocalIpcServer(opts: LocalIpcServerOptions): Promise<LocalIpcServerHandle>;

package/dist/launch.d.ts

@@ -18,7 +18,7 @@
 /** Kill IDE process (graceful → force) */
 export declare function killIdeProcess(ideId: string): Promise<boolean>;
 /** Check if IDE process is running */
-export declare function isIdeRunning(ideId: string): boolean;
+export declare function isIdeRunning(ideId: string): Promise<boolean>;
 export interface LaunchOptions {
     ideId?: string;
     workspace?: string;

package/dist/logging/async-batch-writer.d.ts

@@ -0,0 +1,10 @@
+export declare class AsyncBatchWriter {
+    private static buffers;
+    private static writePromises;
+    private static flushTimer;
+    /**
+     * Queues data to be written to a file asynchronously in a batch.
+     */
+    static write(filePath: string, data: string): void;
+    private static flushAll;
+}

package/dist/mesh/beads-db.d.ts

@@ -0,0 +1,72 @@
+import type { MeshTaskStatus, MeshWorkQueueEntry } from './mesh-work-queue.js';
+export declare class BeadsDB {
+    private static instance;
+    private readonly db;
+    private readonly dbPath;
+    private readonly migratedMeshIds;
+    private fingerprintSweepCounter;
+    private walWriteCounter;
+    private static readonly WAL_CHECK_INTERVAL;
+    private static readonly WAL_MAX_BYTES;
+    private constructor();
+    static getInstance(): BeadsDB;
+    static resetForTests(): void;
+    close(): void;
+    transaction<T>(fn: () => T): T;
+    private migrate;
+    hasCompletionFingerprint(fingerprint: string): boolean;
+    recordCompletionFingerprint(fingerprint: string, ttlMs: number): void;
+    sweepExpiredFingerprints(): void;
+    private maybeCheckpointWal;
+    private ensureLegacyQueueMigrated;
+    getQueueEntries(meshId: string, statuses?: MeshTaskStatus[]): MeshWorkQueueEntry[];
+    getQueueRevision(meshId: string): string;
+    replaceQueue(meshId: string, queue: MeshWorkQueueEntry[]): void;
+    deleteQueue(meshId: string): void;
+    insertQueueEntry(entry: MeshWorkQueueEntry): void;
+    updateQueueEntry(entry: MeshWorkQueueEntry): void;
+    findQueueEntryById(meshId: string, id: string): MeshWorkQueueEntry | null;
+    hasActiveAssignment(meshId: string, sessionId: string, nodeId: string): boolean;
+    claimNextQueueTask(meshId: string, nodeId: string, sessionId: string): MeshWorkQueueEntry | null;
+    getQueueStatsByStatus(meshId: string): {
+        status: string;
+        count: number;
+    }[];
+    getActiveAssignmentDetails(meshId: string): Array<{
+        id: string;
+        nodeId?: string;
+        sessionId?: string;
+        message: string;
+    }>;
+    findAssignedBySession(meshId: string, sessionId: string, occurredAtIso?: string): MeshWorkQueueEntry | null;
+    private toRow;
+    insertDirectDispatch(entry: {
+        taskId: string;
+        meshId: string;
+        nodeId?: string;
+        sessionId?: string;
+        providerType?: string;
+        message: string;
+        taskMode?: string;
+        via: string;
+        dispatchedToIdleSession?: boolean;
+        dispatchedAt: string;
+    }): void;
+    getActiveDirectDispatches(meshId: string): Array<{
+        taskId: string;
+        meshId: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        message: string;
+        taskMode: string | null;
+        via: string;
+        status: string;
+        dispatchedToIdleSession: boolean;
+        dispatchedAt: string;
+        updatedAt: string;
+    }>;
+    updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale'): void;
+    cleanupTerminalDirectDispatches(olderThanMs: number): void;
+    markStaleDirectDispatches(meshId: string, olderThanMs: number): void;
+}

package/dist/mesh/contracts.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Mesh contract v2 — first-class identity, scopes, and protocol version.
+ *
+ * Replaces the implicit conventions that grew across mesh-events.ts,
+ * mesh-work-queue.ts, mesh-ledger.ts, and mesh-tools.ts where the same
+ * concept (a coordinator, a session, a task status) appeared in different
+ * shapes per file. The audit found:
+ *
+ *   - PendingMeshCoordinatorEvent had no targetCoordinatorDaemonId. All
+ *     events were broadcast to every coordinator that drained them. Two
+ *     coordinators sharing a mesh would each receive every event,
+ *     leading to duplicate completion handling and missed targeting.
+ *   - drainPendingMeshCoordinatorEvents accepted only meshId. The caller's
+ *     coordinator identity was never available, so per-coordinator
+ *     routing was impossible by construction.
+ *   - Session identifier keys diverged across stores: targetSessionId /
+ *     assignedSessionId / instanceId / runtimeSessionId / providerSessionId.
+ *     resolveEventSessionId() tried four fallbacks per call.
+ *   - No protocol version on the JSONL ledger or BeadsDB. Schema
+ *     evolutions had no guard rail.
+ *   - mesh_reconcile_ledger existed as a routine recovery tool, not as
+ *     an incident-response escape hatch. That itself signals the routing
+ *     layer cannot be trusted.
+ *
+ * This module introduces the types; the actual wiring lands in B2 (data
+ * model + 3-way transactional store), B3 (MCP layer enforcement), and B4
+ * (frontend consumption). B1 is intentionally non-breaking — it adds the
+ * types and leaves runtime behaviour unchanged.
+ */
+/** Provider type identifier (e.g. 'claude-cli', 'codex-cli', 'roo-code').
+ *  Free-form string; no shared enum exists in daemon-core yet. */
+type ProviderType = string;
+export declare const MESH_PROTOCOL_VERSION_V1: "1.0";
+export declare const MESH_PROTOCOL_VERSION_V2: "2.0";
+export type MeshProtocolVersion = typeof MESH_PROTOCOL_VERSION_V1 | typeof MESH_PROTOCOL_VERSION_V2;
+export declare const SUPPORTED_MESH_PROTOCOL_VERSIONS: readonly MeshProtocolVersion[];
+export declare function isSupportedMeshProtocolVersion(value: unknown): value is MeshProtocolVersion;
+/**
+ * Identity of a mesh coordinator. Required (non-optional) on every dispatch
+ * and drain operation in v2 — opaque/missing identity is the audit's
+ * smoking gun for routing failures and is structurally banned by the v2
+ * types.
+ *
+ * - daemonId: the machineId of the daemon hosting the coordinator. Stable
+ *   across coordinator restarts on the same machine.
+ * - coordinatorRunId: a UUID generated when the coordinator process starts.
+ *   Stable for the coordinator's lifetime, fresh on restart. Required so
+ *   two coordinators on the same daemon (one CLI, one MCP) can be told
+ *   apart without conflating their drains.
+ * - sessionId: optional CLI coordinator session identifier (instanceId).
+ *   Present when the coordinator is itself a CLI session, absent for
+ *   pure MCP coordinators.
+ */
+export interface CoordinatorIdentity {
+    readonly daemonId: string;
+    readonly coordinatorRunId: string;
+    readonly sessionId?: string;
+}
+export declare function coordinatorIdentityEquals(a: CoordinatorIdentity, b: CoordinatorIdentity): boolean;
+export declare function coordinatorIdentityKey(identity: CoordinatorIdentity): string;
+/**
+ * Unified mesh session identifier. v1 referred to "the session" with five
+ * different field names depending on which store you were reading; v2
+ * collapses them into one explicit handle that carries every disambiguator
+ * a consumer might need.
+ *
+ * - nodeId: the mesh node this session belongs to (FK into mesh node table).
+ * - sessionId: provider-instance identifier (the runtime session id).
+ * - providerType: which provider category/type the session runs (e.g.
+ *   'claude-cli', 'codex-cli', 'roo-code').
+ * - coordinatorDaemonId: which coordinator dispatched the work that
+ *   spawned this session. Used for completion event routing.
+ * - assignedAt: ms epoch when the session was bound to its current task.
+ */
+export interface MeshSessionHandle {
+    readonly nodeId: string;
+    readonly sessionId: string;
+    readonly providerType: ProviderType;
+    readonly coordinatorDaemonId: string;
+    readonly assignedAt: number;
+}
+export declare function meshSessionHandleKey(handle: MeshSessionHandle): string;
+/**
+ * Single canonical task status enum. v1 had at least three overlapping
+ * sets (queue / ledger / direct-dispatch). v2 consumers import from here.
+ */
+export declare const MESH_TASK_STATUSES: readonly ["pending", "assigned", "in_progress", "completed", "failed", "cancelled"];
+export type MeshTaskStatus = typeof MESH_TASK_STATUSES[number];
+export declare function isMeshTaskStatus(value: unknown): value is MeshTaskStatus;
+/**
+ * Explicit scope for pending coordinator events. v1 had no scope: every
+ * event was broadcast to every drainer. v2 forces producers to declare
+ * intent.
+ *
+ * - 'unicast': delivered to exactly one coordinator (intendedFor). Other
+ *   coordinators' drains skip it.
+ * - 'broadcast': delivered to every coordinator on the mesh. Used for
+ *   system-wide signals (e.g. mesh-wide policy changes). The v1 default
+ *   becomes explicit here so audit tools can flag unintended broadcasts.
+ * - 'system': delivered to the daemon-level handler, not coordinators.
+ *   Reserved for infrastructure events that no coordinator should see
+ *   (e.g. ledger reconciliation outcomes).
+ */
+export declare const MESH_EVENT_SCOPES: readonly ["unicast", "broadcast", "system"];
+export type MeshEventScope = typeof MESH_EVENT_SCOPES[number];
+export declare function isMeshEventScope(value: unknown): value is MeshEventScope;
+/**
+ * v2 shape of a pending coordinator event. Strict supersets of the v1
+ * shape — every v1 field is preserved so existing readers do not break;
+ * v2 fields (scope, dispatchedBy, intendedFor, protocolVersion) are
+ * additive and consulted by v2-aware drainers only.
+ *
+ * Mixed v1/v2 events coexist during the rollout window. B2 fully cuts
+ * over once every coordinator drain is v2-aware.
+ */
+export interface PendingMeshCoordinatorEventV2 {
+    readonly event: string;
+    readonly meshId: string;
+    readonly nodeLabel: string;
+    readonly nodeId?: string;
+    readonly workspace?: string;
+    readonly metadataEvent: Record<string, unknown>;
+    readonly coordinatorMessage?: string;
+    readonly queuedAt: number;
+    readonly protocolVersion: MeshProtocolVersion;
+    readonly scope: MeshEventScope;
+    readonly dispatchedBy: CoordinatorIdentity;
+    /**
+     * Required when scope === 'unicast', forbidden otherwise. Drainers MUST
+     * skip unicast events whose intendedFor does not equal their own identity.
+     */
+    readonly intendedFor?: CoordinatorIdentity;
+}
+/**
+ * v2 ledger entry additions. The originatingCoordinator field is the
+ * source of truth that lets completion events route back to the
+ * coordinator that dispatched the task. v1's "worker settings carried it
+ * if it happened to be set" approach is replaced.
+ */
+export interface MeshLedgerOriginatingCoordinatorV2 {
+    readonly originatingCoordinator: CoordinatorIdentity;
+    readonly protocolVersion: MeshProtocolVersion;
+}
+export declare class MeshContractViolationError extends Error {
+    readonly violationPath: string;
+    readonly protocolVersion: MeshProtocolVersion;
+    constructor(protocolVersion: MeshProtocolVersion, violationPath: string, detail: string);
+}
+export declare function assertCoordinatorIdentity(raw: unknown, path: string): CoordinatorIdentity;
+export declare function assertPendingMeshCoordinatorEventV2(raw: unknown, path?: string): PendingMeshCoordinatorEventV2;
+/**
+ * Decide whether a v2 pending event should be delivered to the given drainer.
+ * Centralised so every drain implementation uses the same rule.
+ *
+ *   - 'broadcast': always delivered.
+ *   - 'system': never delivered to coordinators (system handler only).
+ *   - 'unicast': delivered iff intendedFor matches drainer identity.
+ *
+ * v1 events (no scope / no protocolVersion) are treated as broadcast for
+ * backward compatibility during rollout; B3 tightens this so v1 events
+ * are quarantined to a dedicated drain endpoint instead.
+ */
+export declare function shouldDeliverPendingEventToCoordinator(event: PendingMeshCoordinatorEventV2, drainer: CoordinatorIdentity): boolean;
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * MeshCoordinatorRegistry — Persisted record of active mesh coordinator sessions.
+ *
+ * Survives daemon restarts: when a CLI coordinator session is re-attached after
+ * a daemon restart the in-memory `settings.meshCoordinatorFor` on the provider
+ * instance is gone, so the registry file fills the gap.
+ *
+ * Keyed by sessionId (the CLI instance key / runtimeKey).
+ */
+export interface CoordinatorRegistryEntry {
+    meshId: string;
+    sessionId: string;
+    workspace?: string;
+    startedAt: number;
+}
+/** Load persisted coordinator registry from disk into in-memory map. Called once on daemon boot. */
+export declare function loadMeshCoordinatorRegistry(): void;
+/** Register a coordinator session. Persists to disk immediately. */
+export declare function registerMeshCoordinator(entry: CoordinatorRegistryEntry): void;
+/** Remove a coordinator session by sessionId. Persists to disk. */
+export declare function unregisterMeshCoordinator(sessionId: string): void;
+/** Look up a coordinator entry by session ID. Returns undefined if not registered. */
+export declare function getCoordinatorForSession(sessionId: string): CoordinatorRegistryEntry | undefined;
+/** List all coordinator entries for a given workspace path. */
+export declare function listCoordinatorsForWorkspace(workspace: string): CoordinatorRegistryEntry[];

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

@@ -0,0 +1,90 @@
+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 BeadsDB. 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;
+};
+export declare function buildCompactStaleDirectWorkSummary(staleDirectWork: MeshActiveWorkRecord[], opts?: {
+    sampleLimit?: number;
+    detailHint?: string;
+    note?: string;
+}): MeshStaleDirectWorkSummary;

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

@@ -6,15 +6,22 @@ export interface PendingMeshCoordinatorEvent {
     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;
 }
 export declare function queuePendingMeshCoordinatorEvent(event: PendingMeshCoordinatorEvent): boolean;
-/** Drain and return all pending coordinator events, clearing the queue. */
-export declare function drainPendingMeshCoordinatorEvents(): PendingMeshCoordinatorEvent[];
+/** Drain and return all pending coordinator events for meshId, removing them from disk. */
+export declare function drainPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string): PendingMeshCoordinatorEvent[];
 /** Peek at pending coordinator events without draining (non-destructive). */
-export declare function getPendingMeshCoordinatorEvents(): readonly PendingMeshCoordinatorEvent[];
-/** Explicitly clear all pending coordinator events. */
-export declare function clearPendingMeshCoordinatorEvents(): void;
+export declare function getPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string): readonly PendingMeshCoordinatorEvent[];
+/** Explicitly clear all pending coordinator events for a mesh (and coordinator if scoped). */
+export declare function clearPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: 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.
@@ -26,12 +33,77 @@ export declare function handleMeshForwardEvent(components: DaemonComponents, pay
     forwarded: number;
     suppressed: boolean;
     intentionalCleanupStop: boolean;
+    terminalLedgerEvidence?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    duplicateCompletion?: undefined;
     error?: undefined;
+    bufferedForGeneratingCoordinator?: undefined;
 } | {
     success: boolean;
     forwarded: number;
+    suppressed: boolean;
+    terminalLedgerEvidence: boolean;
+    terminalLedgerKind: unknown;
+    intentionalCleanupStop?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    duplicateCompletion?: undefined;
+    error?: undefined;
+    bufferedForGeneratingCoordinator?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    suppressed: boolean;
+    duplicateRefineTerminalEvent: boolean;
+    intentionalCleanupStop?: undefined;
+    terminalLedgerEvidence?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateCompletion?: undefined;
+    error?: undefined;
+    bufferedForGeneratingCoordinator?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    suppressed: boolean;
+    duplicateCompletion: boolean;
+    terminalLedgerEvidence: boolean;
+    intentionalCleanupStop?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    error?: undefined;
+    bufferedForGeneratingCoordinator?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    suppressed: boolean;
+    duplicateCompletion: boolean;
+    intentionalCleanupStop?: undefined;
+    terminalLedgerEvidence?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    error?: undefined;
+    bufferedForGeneratingCoordinator?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    suppressed?: undefined;
+    intentionalCleanupStop?: undefined;
+    terminalLedgerEvidence?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    duplicateCompletion?: undefined;
+    error?: undefined;
+    bufferedForGeneratingCoordinator?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    bufferedForGeneratingCoordinator: boolean;
     suppressed?: undefined;
     intentionalCleanupStop?: undefined;
+    terminalLedgerEvidence?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    duplicateCompletion?: undefined;
     error?: undefined;
 } | {
     success: boolean;

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

@@ -0,0 +1,39 @@
+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;
+}
+export interface MeshFastForwardPlannedStep {
+    operation: 'refresh_upstream' | 'verify_clean_worktree' | 'verify_fast_forward' | 'merge_ff_only' | 'submodule_update' | 'verify_post_status';
+    description: string;
+    safe: true;
+    willMutateWorktree: boolean;
+}
+export interface MeshFastForwardResult {
+    success: boolean;
+    code: string;
+    nodeId?: string;
+    meshId?: string;
+    workspace: string;
+    allowed: boolean;
+    dryRun: boolean;
+    willRun: boolean;
+    executed: boolean;
+    updateSubmodules: boolean;
+    blockingReasons: string[];
+    plannedSteps: MeshFastForwardPlannedStep[];
+    current?: GitRepoStatus;
+    preStatus?: GitRepoStatus;
+    postStatus?: GitRepoStatus;
+    finalBranchConvergenceState?: Record<string, unknown>;
+    operationError?: string;
+    ledgerError?: 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;