@adhdev/daemon-core 0.9.76 → 0.9.77-rc.10

package/src/mesh/mesh-events.ts

@@ -1,6 +1,9 @@
 import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
 import { getMesh, getMeshByRepo } from '../config/mesh-config.js';
 import { LOG } from '../logging/logger.js';
+import { appendLedgerEntry, getSessionRecoveryContext } from './mesh-ledger.js';
+import type { MeshLedgerKind, SessionRecoveryContext } from './mesh-ledger.js';
+import { claimNextTask, updateSessionTaskStatus, enqueueTask } from './mesh-work-queue.js';
 
 // ---------------------------------------------------------------------------
 // MCP coordinator pending-event queue
@@ -37,6 +40,13 @@ const MESH_COORDINATOR_EVENTS = new Set([
     'monitor:long_generating',
 ]);
 
+const EVENT_TO_LEDGER_KIND: Record<string, MeshLedgerKind> = {
+    'agent:generating_completed': 'task_completed',
+    'agent:waiting_approval': 'task_approval_needed',
+    'agent:stopped': 'task_failed',
+    'monitor:long_generating': 'task_stalled',
+};
+
 function isMeshCoordinatorEvent(eventName: unknown): eventName is string {
     return typeof eventName === 'string' && MESH_COORDINATOR_EVENTS.has(eventName);
 }
@@ -50,10 +60,68 @@ function formatCompletionMetadata(event: Record<string, unknown>): string {
     return parts.length > 0 ? ` (${parts.join('; ')})` : '';
 }
 
+export function tryAssignQueueTask(
+    components: { cliManager: any },
+    meshId: string,
+    nodeId: string,
+    sessionId: string,
+    providerType: string
+): boolean {
+    const task = claimNextTask(meshId, nodeId, sessionId);
+    if (!task) return false;
+
+    LOG.info('MeshQueue', `Node ${nodeId} (${sessionId}) pulled task ${task.id}`);
+    
+    components.cliManager.handleCliCommand('agent_command', {
+        targetSessionId: sessionId,
+        cliType: providerType,
+        action: 'send_chat',
+        input: task.message,
+    }).catch((e: any) => {
+        LOG.error('MeshQueue', `Failed to dispatch task to node ${nodeId}: ${e?.message}`);
+    });
+
+    return true;
+}
+
+/**
+ * Triggers a queue check for all nodes in the mesh.
+ * Called when a new task is enqueued, in case nodes are already idle.
+ */
+export function triggerMeshQueue(components: { instanceManager: any; cliManager: any }, meshId: string) {
+    const mesh = getMesh(meshId);
+    if (!mesh) return;
+
+    // Find all CLI instances that belong to this mesh and are idle
+    const cliInstances = components.instanceManager.getByCategory('cli');
+    for (const inst of cliInstances) {
+        const state = inst.getState();
+        const settings = state.settings as Record<string, unknown> || {};
+        
+        const instMeshId = readNonEmptyString(settings.meshNodeFor);
+        if (instMeshId !== meshId && !settings.launchedByCoordinator) continue;
+
+        const nodeId = readNonEmptyString(settings.meshNodeId) || readNonEmptyString(settings.nodeId);
+        if (!nodeId) continue;
+
+        // Is it idle? (online and waiting for input)
+        if (state.status !== 'idle' && state.status !== 'stopped' && state.activeChat?.status !== 'waiting_input') continue;
+
+        const sessionId = state.instanceId;
+        const providerType = state.type || readNonEmptyString(settings.providerType);
+        
+        if (providerType) {
+            // Try to assign a task to this idle node
+            tryAssignQueueTask(components, meshId, nodeId, sessionId, providerType);
+        }
+    }
+}
+
 function buildMeshSystemMessage(args: {
     event: string;
     nodeLabel: string;
     metadataEvent: Record<string, unknown>;
+    recoveryContext?: SessionRecoveryContext | null;
 }): string {
     const metadata = formatCompletionMetadata(args.metadataEvent);
     if (args.event === 'agent:generating_completed') {
@@ -63,6 +131,28 @@ function buildMeshSystemMessage(args: {
         return `[System] ${args.nodeLabel} is waiting for approval to proceed${metadata}. You may use mesh_read_chat and mesh_approve to handle it.`;
     }
     if (args.event === 'agent:stopped') {
+        const rc = args.recoveryContext;
+        if (rc && rc.consecutiveNodeFailures > 0) {
+            const parts = [
+                `[System] ${args.nodeLabel} has stopped unexpectedly${metadata}.`,
+                `\n\n**Recovery Context:**`,
+                `- Consecutive failures on this node: ${rc.consecutiveNodeFailures}`,
+                rc.taskAttemptCount > 0 ? `- This task has been attempted ${rc.taskAttemptCount} time(s)` : '',
+                `- Recommendation: ${rc.advice}`,
+            ];
+            if (rc.retryRecommended && rc.lastTaskMessage) {
+                parts.push(
+                    `\n\n**Original task to retry:**`,
+                    `> ${rc.lastTaskMessage.length > 300 ? rc.lastTaskMessage.slice(0, 300) + '...' : rc.lastTaskMessage}`,
+                    `\nTo retry: call \`mesh_launch_session\` for this node, then \`mesh_send_task\` with the original task.`,
+                );
+            } else if (!rc.retryRecommended) {
+                parts.push(
+                    `\nDo NOT retry on this node. Consider reassigning to a different node or asking the user for guidance.`,
+                );
+            }
+            return parts.filter(Boolean).join('\n');
+        }
         return `[System] ${args.nodeLabel} has stopped${metadata}. Use mesh_read_chat once if you need to inspect its last output.`;
     }
     if (args.event === 'monitor:long_generating') {
@@ -78,6 +168,111 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
     event: string;
     metadataEvent: Record<string, unknown>;
 }) {
+    // ── Task Queue & Ledger ──
+    if (args.event === 'agent:generating_completed') {
+        const sessionId = readNonEmptyString(args.metadataEvent.targetSessionId);
+        const nodeId = readNonEmptyString(args.metadataEvent.nodeId) || readNonEmptyString(args.metadataEvent.meshNodeId);
+        const providerType = readNonEmptyString(args.metadataEvent.providerType);
+        
+        if (sessionId) {
+            updateSessionTaskStatus(args.meshId, sessionId, 'completed');
+            if (nodeId && providerType) {
+                // Short delay to allow completion event to propagate before pulling next
+                setTimeout(() => {
+                    tryAssignQueueTask(components, args.meshId, nodeId, sessionId, providerType);
+                }, 500);
+            }
+        }
+    } else if (args.event === 'agent:stopped') {
+        const sessionId = readNonEmptyString(args.metadataEvent.targetSessionId);
+        if (sessionId) {
+            updateSessionTaskStatus(args.meshId, sessionId, 'failed');
+        }
+    }
+
+    const ledgerKind = EVENT_TO_LEDGER_KIND[args.event];
+    if (ledgerKind) {
+        try {
+            appendLedgerEntry(args.meshId, {
+                kind: ledgerKind,
+                nodeId: readNonEmptyString(args.metadataEvent.nodeId) || readNonEmptyString(args.metadataEvent.meshNodeId) || undefined,
+                sessionId: readNonEmptyString(args.metadataEvent.targetSessionId) || undefined,
+                providerType: readNonEmptyString(args.metadataEvent.providerType) || undefined,
+                payload: {
+                    event: args.event,
+                    nodeLabel: args.nodeLabel,
+                    providerSessionId: readNonEmptyString(args.metadataEvent.providerSessionId) || undefined,
+                },
+            });
+        } catch (e: any) {
+            LOG.warn('MeshLedger', `Failed to record ${ledgerKind}: ${e?.message || e}`);
+        }
+    }
+
+    // ── Recovery Context: enrich agent:stopped with retry intelligence ──
+    let recoveryContext: SessionRecoveryContext | null = null;
+    if (args.event === 'agent:stopped') {
+        try {
+            // Resolve maxTaskRetries from mesh policy
+            const mesh = getMesh(args.meshId);
+            const maxRetries = mesh?.policy?.maxTaskRetries ?? 1;
+
+            recoveryContext = getSessionRecoveryContext(args.meshId, {
+                sessionId: readNonEmptyString(args.metadataEvent.targetSessionId) || undefined,
+                nodeId: readNonEmptyString(args.metadataEvent.nodeId) || readNonEmptyString(args.metadataEvent.meshNodeId) || undefined,
+                maxRetries,
+            });
+            recoveryContext.failedProviderType = readNonEmptyString(args.metadataEvent.providerType) || null;
+
+            // Record recovery_attempted if retry is recommended
+            if (recoveryContext.retryRecommended && recoveryContext.consecutiveNodeFailures > 0) {
+                appendLedgerEntry(args.meshId, {
+                    kind: 'recovery_attempted',
+                    nodeId: recoveryContext.failedNodeId || undefined,
+                    sessionId: recoveryContext.failedSessionId || undefined,
+                    providerType: recoveryContext.failedProviderType || undefined,
+                    payload: {
+                        consecutiveFailures: recoveryContext.consecutiveNodeFailures,
+                        taskAttemptCount: recoveryContext.taskAttemptCount,
+                        retryRecommended: recoveryContext.retryRecommended,
+                        advice: recoveryContext.advice,
+                    },
+                });
+
+                // Auto-Recovery (Phase 5): Automatically re-enqueue the task and re-launch the session
+                if (recoveryContext.lastTaskMessage && recoveryContext.failedNodeId && recoveryContext.failedProviderType) {
+                    const autoNodeId = recoveryContext.failedNodeId;
+                    try {
+                        const task = enqueueTask(args.meshId, recoveryContext.lastTaskMessage, {
+                            targetNodeId: autoNodeId
+                        });
+                        LOG.info('MeshRecovery', `Auto-requeued failed task: ${task.id} for node ${autoNodeId}`);
+
+                        const node = mesh?.nodes.find(n => n.id === autoNodeId);
+                        if (node) {
+                            components.cliManager.handleCliCommand('launch_cli', {
+                                cliType: recoveryContext.failedProviderType,
+                                dir: node.workspace,
+                                settings: {
+                                    meshNodeFor: args.meshId,
+                                    meshNodeId: node.id,
+                                    spawnedSessionVisibility: mesh?.policy?.spawnedSessionVisibility || 'hidden',
+                                    launchedByCoordinator: true,
+                                }
+                            }).catch((e: any) => LOG.error('MeshRecovery', `Failed to auto-relaunch session for ${node.id}: ${e?.message}`));
+                        }
+                    } catch (e: any) {
+                        LOG.warn('MeshRecovery', `Failed to execute auto-recovery: ${e?.message}`);
+                    }
+                }
+            }
+
+            LOG.info('MeshRecovery', `Recovery context for ${args.nodeLabel}: ${recoveryContext.advice}`);
+        } catch (e: any) {
+            LOG.warn('MeshRecovery', `Failed to build recovery context: ${e?.message || e}`);
+        }
+    }
+
     const coordinatorInstances = components.instanceManager.getByCategory('cli').filter((inst) => {
         const instState = inst.getState();
         if (instState.settings?.meshCoordinatorFor !== args.meshId) return false;
@@ -92,7 +287,10 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
                 event: args.event,
                 meshId: args.meshId,
                 nodeLabel: args.nodeLabel,
-                metadataEvent: args.metadataEvent,
+                metadataEvent: {
+                    ...args.metadataEvent,
+                    ...(recoveryContext ? { recoveryContext } : {}),
+                },
                 queuedAt: Date.now(),
             });
             LOG.info('MeshEvents', `Queued ${args.event} for MCP coordinator (mesh ${args.meshId})`);
@@ -104,6 +302,7 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
         event: args.event,
         nodeLabel: args.nodeLabel,
         metadataEvent: args.metadataEvent,
+        recoveryContext,
     });
     if (!messageText) return { success: false, error: 'unsupported mesh event' };
 

package/src/mesh/mesh-ledger.ts

@@ -0,0 +1,378 @@
+/**
+ * Mesh Task Ledger — GasTown-inspired append-only JSONL task history
+ *
+ * Records all mesh orchestration events (task dispatch, completion, failure,
+ * checkpoint, node lifecycle) as an append-only JSONL file per mesh.
+ *
+ * Inspired by GasTown's "Beads" pattern: every action is a versioned record
+ * that persists across agent sessions, enabling recovery, auditing, and
+ * continuity when individual sessions fail or context windows are exhausted.
+ *
+ * Storage: ~/.adhdev/mesh-ledger/<meshId>.jsonl
+ * Format:  One JSON object per line, newest entries appended at end
+ * Safety:  mode 0o600, atomic append via appendFileSync
+ */
+
+import { existsSync, mkdirSync, readFileSync, appendFileSync, statSync, renameSync } from 'fs';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { getConfigDir } from '../config/config.js';
+import { EventEmitter } from 'events';
+// ─── Types ──────────────────────────────────────
+
+export type MeshLedgerKind =
+    | 'task_dispatched'
+    | 'task_completed'
+    | 'task_failed'
+    | 'task_stalled'
+    | 'task_approval_needed'
+    | 'session_launched'
+    | 'session_stopped'
+    | 'checkpoint_created'
+    | 'node_cloned'
+    | 'node_removed'
+    | 'coordinator_started'
+    | 'recovery_attempted'
+    ;
+
+export interface MeshLedgerEntry {
+    id: string;
+    meshId: string;
+    timestamp: string;
+    kind: MeshLedgerKind;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    payload: Record<string, unknown>;
+}
+
+export interface MeshLedgerSummary {
+    meshId: string;
+    totalEntries: number;
+    taskDispatched: number;
+    taskCompleted: number;
+    taskFailed: number;
+    taskStalled: number;
+    sessionLaunched: number;
+    checkpointCreated: number;
+    lastActivityAt: string | null;
+    recentFailures: number; // failures in last 30 minutes
+}
+
+export interface ReadLedgerOptions {
+    tail?: number;
+    since?: string;
+    kind?: MeshLedgerKind[];
+}
+
+// ─── Constants ──────────────────────────────────
+
+const LEDGER_DIR_NAME = 'mesh-ledger';
+const MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024; // 10 MB
+const RECENT_FAILURE_WINDOW_MS = 30 * 60 * 1000; // 30 minutes
+
+// ─── Path Helpers ───────────────────────────────
+
+export function getLedgerDir(): string {
+    const dir = join(getConfigDir(), LEDGER_DIR_NAME);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    return dir;
+}
+
+function getLedgerPath(meshId: string): string {
+    // Sanitize meshId to prevent path traversal
+    const safe = meshId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return join(getLedgerDir(), `${safe}.jsonl`);
+}
+
+function getRotatedPath(meshId: string, index: number): string {
+    const safe = meshId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return join(getLedgerDir(), `${safe}.${index}.jsonl`);
+}
+
+// ─── Core API ───────────────────────────────────
+
+/**
+ * Append a new entry to the mesh ledger.
+ * Handles file creation, rotation on size overflow, and atomic writes.
+ */
+export const meshLedgerEvents = new EventEmitter();
+
+export function appendLedgerEntry(
+    meshId: string,
+    partial: Omit<MeshLedgerEntry, 'id' | 'meshId' | 'timestamp'>,
+): MeshLedgerEntry {
+    const entry: MeshLedgerEntry = {
+        id: randomUUID(),
+        meshId,
+        timestamp: new Date().toISOString(),
+        ...partial,
+    };
+
+    const filePath = getLedgerPath(meshId);
+
+    // Rotate if file exceeds max size
+    if (existsSync(filePath)) {
+        try {
+            const stat = statSync(filePath);
+            if (stat.size >= MAX_FILE_SIZE_BYTES) {
+                rotateLedgerFile(meshId, filePath);
+            }
+        } catch {
+            // stat failed — proceed with append anyway
+        }
+    }
+
+    try {
+        const line = JSON.stringify(entry) + '\n';
+        appendFileSync(filePath, line, { encoding: 'utf-8', mode: 0o600 });
+        meshLedgerEvents.emit('append', meshId, entry);
+        return entry;
+    } catch (e: any) {
+        throw new Error(`Failed to append to ledger for mesh ${meshId}: ${e.message}`);
+    }
+}
+
+/**
+ * Append entries received from the cloud to the local ledger.
+ * This skips deduplicated entries and just writes new ones.
+ */
+export function appendRemoteLedgerEntries(meshId: string, entries: MeshLedgerEntry[]): void {
+    if (entries.length === 0) return;
+    const ledgerPath = getLedgerPath(meshId);
+
+    // Read existing to deduplicate by ID
+    const existing = new Set(readLedgerEntries(meshId).map(e => e.id));
+    const newEntries = entries.filter(e => !existing.has(e.id));
+
+    if (newEntries.length === 0) return;
+
+    try {
+        const lines = newEntries.map(e => JSON.stringify(e)).join('\n') + '\n';
+        appendFileSync(ledgerPath, lines, { encoding: 'utf-8', mode: 0o600 });
+    } catch (e: any) {
+        throw new Error(`Failed to append remote ledger entries for mesh ${meshId}: ${e.message}`);
+    }
+}
+
+/**
+ * Read ledger entries with optional filtering.
+ */
+export function readLedgerEntries(meshId: string, opts?: ReadLedgerOptions): MeshLedgerEntry[] {
+    const filePath = getLedgerPath(meshId);
+    if (!existsSync(filePath)) return [];
+
+    let content: string;
+    try {
+        content = readFileSync(filePath, 'utf-8');
+    } catch {
+        return [];
+    }
+
+    const lines = content.split('\n').filter(line => line.trim());
+    let entries: MeshLedgerEntry[] = [];
+
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line) as MeshLedgerEntry;
+            if (!entry.id || !entry.kind) continue;
+            entries.push(entry);
+        } catch {
+            // Skip malformed lines
+        }
+    }
+
+    // Apply filters
+    if (opts?.since) {
+        const sinceDate = new Date(opts.since).getTime();
+        if (!isNaN(sinceDate)) {
+            entries = entries.filter(e => new Date(e.timestamp).getTime() >= sinceDate);
+        }
+    }
+
+    if (opts?.kind?.length) {
+        const kindSet = new Set(opts.kind);
+        entries = entries.filter(e => kindSet.has(e.kind));
+    }
+
+    // Apply tail (return last N entries)
+    if (opts?.tail && opts.tail > 0 && entries.length > opts.tail) {
+        entries = entries.slice(-opts.tail);
+    }
+
+    return entries;
+}
+
+/**
+ * Get a summary of mesh activity from the ledger.
+ */
+export function getLedgerSummary(meshId: string): MeshLedgerSummary {
+    const entries = readLedgerEntries(meshId);
+    const now = Date.now();
+    const recentFailureCutoff = now - RECENT_FAILURE_WINDOW_MS;
+
+    const summary: MeshLedgerSummary = {
+        meshId,
+        totalEntries: entries.length,
+        taskDispatched: 0,
+        taskCompleted: 0,
+        taskFailed: 0,
+        taskStalled: 0,
+        sessionLaunched: 0,
+        checkpointCreated: 0,
+        lastActivityAt: null,
+        recentFailures: 0,
+    };
+
+    for (const entry of entries) {
+        switch (entry.kind) {
+            case 'task_dispatched': summary.taskDispatched++; break;
+            case 'task_completed': summary.taskCompleted++; break;
+            case 'task_failed': {
+                summary.taskFailed++;
+                if (new Date(entry.timestamp).getTime() >= recentFailureCutoff) {
+                    summary.recentFailures++;
+                }
+                break;
+            }
+            case 'task_stalled': summary.taskStalled++; break;
+            case 'session_launched': summary.sessionLaunched++; break;
+            case 'checkpoint_created': summary.checkpointCreated++; break;
+        }
+    }
+
+    if (entries.length > 0) {
+        summary.lastActivityAt = entries[entries.length - 1].timestamp;
+    }
+
+    return summary;
+}
+
+// ─── Recovery Context ───────────────────────────
+
+export interface SessionRecoveryContext {
+    /** The original task message that was dispatched to this session/node */
+    lastTaskMessage: string | null;
+    /** The node that was running the failed task */
+    failedNodeId: string | null;
+    /** Session ID of the failed session */
+    failedSessionId: string | null;
+    /** Provider used for the failed session */
+    failedProviderType: string | null;
+    /** Number of consecutive failures for this node (within recent window) */
+    consecutiveNodeFailures: number;
+    /** Number of times this specific task was attempted (matched by truncated message prefix) */
+    taskAttemptCount: number;
+    /** Whether a retry is recommended based on maxRetries policy */
+    retryRecommended: boolean;
+    /** Human-readable recovery advice for the coordinator */
+    advice: string;
+}
+
+/**
+ * Build recovery context for a failed session.
+ * Looks up the ledger to find the original task, count failures, and advise on retry.
+ */
+export function getSessionRecoveryContext(
+    meshId: string,
+    opts: {
+        sessionId?: string;
+        nodeId?: string;
+        maxRetries?: number;
+    },
+): SessionRecoveryContext {
+    const maxRetries = opts.maxRetries ?? 1;
+    const entries = readLedgerEntries(meshId);
+
+    // Find the last task_dispatched for this session or node
+    let lastDispatch: MeshLedgerEntry | null = null;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (e.kind !== 'task_dispatched') continue;
+        if (opts.sessionId && e.sessionId === opts.sessionId) { lastDispatch = e; break; }
+        if (opts.nodeId && e.nodeId === opts.nodeId) { lastDispatch = e; break; }
+    }
+
+    const lastTaskMessage = typeof lastDispatch?.payload?.message === 'string'
+        ? lastDispatch.payload.message
+        : null;
+
+    // Count consecutive recent failures for this node (within 30 min window)
+    const now = Date.now();
+    const recentWindow = now - RECENT_FAILURE_WINDOW_MS;
+    let consecutiveNodeFailures = 0;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (new Date(e.timestamp).getTime() < recentWindow) break;
+        if (opts.nodeId && e.nodeId !== opts.nodeId) continue;
+        if (e.kind === 'task_failed') {
+            consecutiveNodeFailures++;
+        } else if (e.kind === 'task_completed' || e.kind === 'task_dispatched') {
+            // A completion or new dispatch breaks the consecutive failure chain
+            break;
+        }
+    }
+
+    // Count how many times the same task was attempted (match by message prefix)
+    let taskAttemptCount = 0;
+    if (lastTaskMessage) {
+        const prefix = lastTaskMessage.slice(0, 200);
+        for (const e of entries) {
+            if (e.kind === 'task_dispatched' && typeof e.payload?.message === 'string') {
+                if (e.payload.message.startsWith(prefix)) {
+                    taskAttemptCount++;
+                }
+            }
+        }
+    }
+
+    const retryRecommended = consecutiveNodeFailures <= maxRetries;
+
+    // Build advice string
+    let advice: string;
+    if (consecutiveNodeFailures === 0) {
+        advice = 'No recent failures detected. This may be a normal stop.';
+    } else if (retryRecommended) {
+        const remaining = maxRetries - consecutiveNodeFailures + 1;
+        advice = `Retry recommended (${consecutiveNodeFailures}/${maxRetries + 1} attempts used, ${remaining} remaining). `
+            + (lastTaskMessage
+                ? `Re-launch the session and resend the original task.`
+                : `Re-launch the session. Original task message not found in ledger.`);
+    } else {
+        advice = `Max retries exceeded (${consecutiveNodeFailures} consecutive failures). `
+            + `Consider: (1) reassigning to a different node, (2) simplifying the task, or (3) escalating to the user.`;
+    }
+
+    return {
+        lastTaskMessage,
+        failedNodeId: opts.nodeId || null,
+        failedSessionId: opts.sessionId || null,
+        failedProviderType: null, // filled by caller if available
+        consecutiveNodeFailures,
+        taskAttemptCount,
+        retryRecommended,
+        advice,
+    };
+}
+
+// ─── File Rotation ──────────────────────────────
+
+function rotateLedgerFile(meshId: string, currentPath: string): void {
+    // Find next rotation index
+    let index = 1;
+    while (existsSync(getRotatedPath(meshId, index))) {
+        index++;
+        if (index > 10) break; // Max 10 rotations
+    }
+
+    // If all slots full, overwrite the oldest
+    if (index > 10) index = 10;
+
+    try {
+        renameSync(currentPath, getRotatedPath(meshId, index));
+    } catch {
+        // Rotation failed — the next append will just grow the file
+    }
+}

package/src/mesh/mesh-sync.ts

@@ -26,6 +26,8 @@ export interface MeshSyncTransport {
     }): Promise<{ mesh: RemoteMeshRecord }>;
     /** DELETE /api/v1/repo-meshes/:id */
     deleteRemoteMesh(meshId: string): Promise<void>;
+    /** POST /api/v1/repo-meshes/:id/ledger/sync */
+    syncMeshLedger?(meshId: string, data: { newEntries: any[] }): Promise<{ missingEntries: any[] }>;
 }
 
 export interface RemoteMeshRecord {
@@ -105,5 +107,35 @@ export async function syncMeshes(transport: MeshSyncTransport): Promise<MeshSync
         }
     }
 
+    // Sync ledgers for all local meshes if the transport supports it
+    if (transport.syncMeshLedger) {
+        for (const local of localMeshes) {
+            try {
+                await syncMeshLedger(local.id, transport);
+            } catch (e: any) {
+                result.errors.push(`Ledger sync failed for "${local.name}": ${e.message}`);
+            }
+        }
+    }
+
     return result;
 }
+
+/**
+ * Sync the task ledger for a specific mesh.
+ */
+export async function syncMeshLedger(meshId: string, transport: MeshSyncTransport): Promise<void> {
+    if (!transport.syncMeshLedger) return;
+    const { readLedgerEntries, appendRemoteLedgerEntries } = await import('./mesh-ledger.js');
+    
+    // Read all local entries (no tail)
+    const localEntries = readLedgerEntries(meshId);
+    
+    // Send to cloud and get missing entries back
+    const res = await transport.syncMeshLedger(meshId, { newEntries: localEntries });
+    
+    // Append any missing entries from the cloud
+    if (res.missingEntries && res.missingEntries.length > 0) {
+        appendRemoteLedgerEntries(meshId, res.missingEntries);
+    }
+}