@adhdev/daemon-core 0.9.82-rc.20 → 0.9.82-rc.200

package/src/mesh/mesh-ledger.ts

@@ -13,7 +13,7 @@
  * Safety:  mode 0o600, atomic append via appendFileSync
  */
 
-import { existsSync, mkdirSync, readFileSync, appendFileSync, statSync, renameSync } from 'fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, renameSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { randomUUID } from 'crypto';
 import { getConfigDir } from '../config/config.js';
@@ -26,16 +26,19 @@ export type MeshLedgerKind =
     | 'task_failed'
     | 'task_stalled'
     | 'task_approval_needed'
+    | 'p2p_dispatch_failed'
     | 'session_launched'
     | 'session_auto_launch'
     | 'session_stopped'
     | 'checkpoint_created'
     | 'node_cloned'
+    | 'node_joined'
     | 'node_removed'
     | 'coordinator_started'
     | 'recovery_attempted'
     | 'ledger_replicated'
     | 'ledger_reconciled'
+    | 'direct_fast_forward'
     ;
 
 export interface MeshLedgerEntry {
@@ -61,6 +64,44 @@ export function isIntentionalCleanupStopEntry(entry: Pick<MeshLedgerEntry, 'kind
             || payload.source === 'mesh_remove_node');
 }
 
+export type MeshWorkerResultStatus = 'completed' | 'failed' | 'blocked' | 'partial' | 'unknown';
+export type MeshProcessArtifactKind = 'process' | 'log' | 'port' | 'window' | 'session' | 'file' | 'url' | 'other';
+
+export interface MeshValidationResultArtifact {
+    command?: string;
+    status: 'passed' | 'failed' | 'skipped' | 'unknown';
+    durationMs?: number;
+    outputPath?: string;
+    summary?: string;
+}
+
+export interface MeshProcessArtifact {
+    kind: MeshProcessArtifactKind;
+    id?: string;
+    label?: string;
+    locator?: string;
+    pid?: number;
+    port?: number;
+    url?: string;
+    path?: string;
+    sessionId?: string;
+    keepRunning?: boolean;
+    metadata?: Record<string, unknown>;
+}
+
+export interface MeshWorkerResultArtifact {
+    status: MeshWorkerResultStatus;
+    classification?: string;
+    changedFiles: string[];
+    validationResults: MeshValidationResultArtifact[];
+    gitStatus?: Record<string, unknown>;
+    processArtifacts: MeshProcessArtifact[];
+    errors: string[];
+    nextAction?: string;
+    requiresUserAction: boolean;
+    source: 'explicit_metadata' | 'final_summary_json' | 'default';
+}
+
 export interface MeshTaskCompletionEvidence {
     source: 'agent_status_event';
     event: 'agent:generating_completed' | 'agent:ready';
@@ -74,6 +115,7 @@ export interface MeshTaskCompletionEvidence {
         providerSessionId?: string;
         finalSummaryAvailable: boolean;
     };
+    workerResult: MeshWorkerResultArtifact;
     git: {
         status: 'deferred';
         reason: string;
@@ -96,6 +138,7 @@ export interface BuildTaskCompletionEvidenceOptions {
     providerType?: string;
     providerSessionId?: string;
     finalSummary?: string;
+    workerResult?: Record<string, unknown>;
     completedAt?: string;
 }
 
@@ -160,8 +203,19 @@ export interface AppendRemoteLedgerResult {
 // ─── Constants ──────────────────────────────────
 
 const LEDGER_DIR_NAME = 'mesh-ledger';
-const MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024; // 10 MB
+const MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024; // 10 MB — full rotation threshold
+const COMPACT_THRESHOLD_BYTES = 2 * 1024 * 1024; // 2 MB — compaction threshold
+const ARCHIVE_TERMINAL_OLDER_THAN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 const RECENT_FAILURE_WINDOW_MS = 30 * 60 * 1000; // 30 minutes
+
+// Kinds that accumulate indefinitely and are safe to archive after ARCHIVE_TERMINAL_OLDER_THAN_MS.
+// Non-terminal kinds (dispatched, sessions, nodes, checkpoints) are always kept in the active file.
+const ARCHIVABLE_KINDS: ReadonlySet<MeshLedgerKind> = new Set([
+    'task_completed',
+    'task_failed',
+    'task_stalled',
+    'recovery_attempted',
+] as MeshLedgerKind[]);
 const DEFAULT_LEDGER_SLICE_LIMIT = 100;
 export const MAX_LEDGER_SLICE_LIMIT = 500;
 
@@ -186,8 +240,251 @@ function getRotatedPath(meshId: string, index: number): string {
     return join(getLedgerDir(), `${safe}.${index}.jsonl`);
 }
 
+function getArchivePath(meshId: string): string {
+    const safe = meshId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return join(getLedgerDir(), `${safe}.archive.jsonl`);
+}
+
+function getRotatedArchivePath(meshId: string, index: number): string {
+    const safe = meshId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return join(getLedgerDir(), `${safe}.archive.${index}.jsonl`);
+}
+
+function getArchivedCountsPath(meshId: string): string {
+    const safe = meshId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return join(getLedgerDir(), `${safe}.archived-counts.json`);
+}
+
+function rotateArchiveFile(meshId: string, archivePath: string): void {
+    let index = 1;
+    while (existsSync(getRotatedArchivePath(meshId, index))) {
+        index++;
+        if (index > 5) break;
+    }
+    if (index > 5) index = 5;
+    try {
+        renameSync(archivePath, getRotatedArchivePath(meshId, index));
+    } catch (e: any) {
+        process.stderr.write(`[adhdev-mesh] Archive rotation failed for mesh ${meshId}: ${e?.message || e}\n`);
+    }
+}
+
+interface LedgerArchivedCounts {
+    taskCompleted: number;
+    taskFailed: number;
+    taskStalled: number;
+    recoveryAttempted: number;
+    totalArchived: number;
+    lastArchivedAt: string;
+}
+
+function readArchivedCounts(meshId: string): LedgerArchivedCounts {
+    const path = getArchivedCountsPath(meshId);
+    if (!existsSync(path)) return { taskCompleted: 0, taskFailed: 0, taskStalled: 0, recoveryAttempted: 0, totalArchived: 0, lastArchivedAt: '' };
+    try { return JSON.parse(readFileSync(path, 'utf-8')) as LedgerArchivedCounts; } catch { return { taskCompleted: 0, taskFailed: 0, taskStalled: 0, recoveryAttempted: 0, totalArchived: 0, lastArchivedAt: '' }; }
+}
+
+function updateArchivedCounts(meshId: string, archived: MeshLedgerEntry[]): void {
+    const counts = readArchivedCounts(meshId);
+    for (const e of archived) {
+        if (e.kind === 'task_completed') counts.taskCompleted++;
+        else if (e.kind === 'task_failed') counts.taskFailed++;
+        else if (e.kind === 'task_stalled') counts.taskStalled++;
+        else if (e.kind === 'recovery_attempted') counts.recoveryAttempted++;
+    }
+    counts.totalArchived += archived.length;
+    counts.lastArchivedAt = new Date().toISOString();
+    try { writeFileSync(getArchivedCountsPath(meshId), JSON.stringify(counts), { encoding: 'utf-8', mode: 0o600 }); } catch { /* best-effort */ }
+}
+
+// ─── Worker Result Footer ───────────────────────
+
+/**
+ * Footer to append to worker task messages so workers output structured results
+ * that the daemon parses via extractJsonObjectFromSummary / normalizeMeshWorkerResult.
+ *
+ * Usage: append buildWorkerTaskFooter() to the task message in mesh_send_task /
+ * mesh_enqueue_task. The coordinator prompt rules instruct coordinators to do this.
+ */
+export function buildWorkerTaskFooter(): string {
+    return `
+
+---
+When your task is done, end your final response with a JSON code block in this exact format (omit fields that don't apply):
+\`\`\`json
+{
+  "status": "completed",
+  "changedFiles": ["src/foo.ts", "tests/foo.test.ts"],
+  "gitStatus": { "branch": "feat/your-branch", "committed": true, "pushed": false },
+  "validationResults": [{ "command": "npm test", "status": "passed" }],
+  "errors": [],
+  "nextAction": "optional guidance for the coordinator"
+}
+\`\`\`
+Valid status values: \`completed\` | \`failed\` | \`blocked\` | \`partial\`.`;
+}
+
+// ─── Ledger Compaction ──────────────────────────
+
+/**
+ * Compact the active ledger file for a mesh by moving old terminal entries
+ * (task_completed, task_failed, task_stalled, recovery_attempted older than 7 days)
+ * to <meshId>.archive.jsonl, keeping the active file lean.
+ *
+ * Non-terminal entries (dispatch, sessions, node lifecycle) are always retained.
+ * Called automatically from appendLedgerEntry when the file exceeds COMPACT_THRESHOLD_BYTES.
+ */
+export function compactLedger(meshId: string): { archivedCount: number; retainedCount: number } {
+    const filePath = getLedgerPath(meshId);
+    if (!existsSync(filePath)) return { archivedCount: 0, retainedCount: 0 };
+
+    const cutoff = Date.now() - ARCHIVE_TERMINAL_OLDER_THAN_MS;
+    const entries = readLedgerEntries(meshId);
+
+    const keep: MeshLedgerEntry[] = [];
+    const archive: MeshLedgerEntry[] = [];
+    for (const entry of entries) {
+        if (ARCHIVABLE_KINDS.has(entry.kind) && new Date(entry.timestamp).getTime() < cutoff) {
+            archive.push(entry);
+        } else {
+            keep.push(entry);
+        }
+    }
+
+    if (archive.length === 0) return { archivedCount: 0, retainedCount: keep.length };
+
+    // Append archived entries to the archive file, rotate if it exceeds 50MB
+    const archivePath = getArchivePath(meshId);
+    try {
+        if (existsSync(archivePath) && statSync(archivePath).size > 50 * 1024 * 1024) {
+            rotateArchiveFile(meshId, archivePath);
+        }
+        const archiveLines = archive.map(e => JSON.stringify(e)).join('\n') + '\n';
+        appendFileSync(archivePath, archiveLines, { encoding: 'utf-8', mode: 0o600 });
+        updateArchivedCounts(meshId, archive);
+    } catch (e: any) {
+        process.stderr.write(`[adhdev-mesh] Ledger archive write failed for mesh ${meshId}: ${e?.message || e}\n`);
+        return { archivedCount: 0, retainedCount: entries.length };
+    }
+
+    // Rewrite active file with retained entries only
+    try {
+        const keepLines = keep.length ? keep.map(e => JSON.stringify(e)).join('\n') + '\n' : '';
+        writeFileSync(filePath, keepLines, { encoding: 'utf-8', mode: 0o600 });
+        invalidateLedgerCache(meshId);
+    } catch (e: any) {
+        process.stderr.write(`[adhdev-mesh] Ledger compaction rewrite failed for mesh ${meshId}: ${e?.message || e}\n`);
+        return { archivedCount: archive.length, retainedCount: keep.length };
+    }
+
+    return { archivedCount: archive.length, retainedCount: keep.length };
+}
+
 // ─── Core API ───────────────────────────────────
 
+function readNonEmptyString(value: unknown): string | undefined {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readStringArray(value: unknown): string[] {
+    if (!Array.isArray(value)) return [];
+    return value.map(item => readNonEmptyString(item)).filter(Boolean) as string[];
+}
+
+function extractJsonObjectFromSummary(summary?: string): Record<string, unknown> | undefined {
+    const text = readNonEmptyString(summary);
+    if (!text) return undefined;
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const candidates = [fenced?.[1], text].filter(Boolean) as string[];
+    for (const candidate of candidates) {
+        const trimmed = candidate.trim();
+        if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                // Require at least one mesh worker result field to avoid false positives
+                // (e.g. JSON from tool call outputs or log lines in the final summary).
+                const hasWorkerShape = 'status' in parsed && (
+                    'changedFiles' in parsed || 'errors' in parsed
+                    || 'gitStatus' in parsed || 'nextAction' in parsed
+                    || 'validationResults' in parsed
+                );
+                if (hasWorkerShape) return parsed;
+            }
+        } catch { /* try next candidate */ }
+    }
+    return undefined;
+}
+
+function normalizeValidationResults(value: unknown): MeshValidationResultArtifact[] {
+    if (!Array.isArray(value)) return [];
+    return value
+        .filter(item => item && typeof item === 'object' && !Array.isArray(item))
+        .map((item: any) => {
+            const status = ['passed', 'failed', 'skipped', 'unknown'].includes(item.status) ? item.status : 'unknown';
+            return {
+                ...(readNonEmptyString(item.command) ? { command: readNonEmptyString(item.command) } : {}),
+                status,
+                ...(Number.isFinite(Number(item.durationMs)) ? { durationMs: Number(item.durationMs) } : {}),
+                ...(readNonEmptyString(item.outputPath) ? { outputPath: readNonEmptyString(item.outputPath) } : {}),
+                ...(readNonEmptyString(item.summary) ? { summary: readNonEmptyString(item.summary) } : {}),
+            };
+        });
+}
+
+function normalizeProcessArtifacts(value: unknown): MeshProcessArtifact[] {
+    if (!Array.isArray(value)) return [];
+    const kinds = new Set(['process', 'log', 'port', 'window', 'session', 'file', 'url', 'other']);
+    return value
+        .filter(item => item && typeof item === 'object' && !Array.isArray(item))
+        .map((item: any) => ({
+            kind: kinds.has(item.kind) ? item.kind : 'other',
+            ...(readNonEmptyString(item.id) ? { id: readNonEmptyString(item.id) } : {}),
+            ...(readNonEmptyString(item.label) ? { label: readNonEmptyString(item.label) } : {}),
+            ...(readNonEmptyString(item.locator) ? { locator: readNonEmptyString(item.locator) } : {}),
+            ...(Number.isFinite(Number(item.pid)) ? { pid: Number(item.pid) } : {}),
+            ...(Number.isFinite(Number(item.port)) ? { port: Number(item.port) } : {}),
+            ...(readNonEmptyString(item.url) ? { url: readNonEmptyString(item.url) } : {}),
+            ...(readNonEmptyString(item.path) ? { path: readNonEmptyString(item.path) } : {}),
+            ...(readNonEmptyString(item.sessionId) ? { sessionId: readNonEmptyString(item.sessionId) } : {}),
+            ...(typeof item.keepRunning === 'boolean' ? { keepRunning: item.keepRunning } : {}),
+            ...(item.metadata && typeof item.metadata === 'object' && !Array.isArray(item.metadata) ? { metadata: item.metadata as Record<string, unknown> } : {}),
+        }));
+}
+
+export function normalizeMeshWorkerResult(input?: Record<string, unknown>, source: MeshWorkerResultArtifact['source'] = 'explicit_metadata'): MeshWorkerResultArtifact {
+    const raw = input && typeof input === 'object' ? input : {};
+    const status = ['completed', 'failed', 'blocked', 'partial', 'unknown'].includes(String(raw.status))
+        ? raw.status as MeshWorkerResultStatus
+        : 'unknown';
+    const gitStatus = raw.gitStatus && typeof raw.gitStatus === 'object' && !Array.isArray(raw.gitStatus)
+        ? raw.gitStatus as Record<string, unknown>
+        : undefined;
+    return {
+        status,
+        ...(readNonEmptyString(raw.classification) ? { classification: readNonEmptyString(raw.classification) } : {}),
+        changedFiles: readStringArray(raw.changedFiles),
+        validationResults: normalizeValidationResults(raw.validationResults),
+        ...(gitStatus ? { gitStatus } : {}),
+        processArtifacts: normalizeProcessArtifacts(raw.processArtifacts),
+        errors: readStringArray(raw.errors),
+        ...(readNonEmptyString(raw.nextAction) ? { nextAction: readNonEmptyString(raw.nextAction) } : {}),
+        requiresUserAction: raw.requiresUserAction === true,
+        source,
+    };
+}
+
+function resolveWorkerResult(opts: BuildTaskCompletionEvidenceOptions): MeshWorkerResultArtifact {
+    if (opts.workerResult && typeof opts.workerResult === 'object') {
+        return normalizeMeshWorkerResult(opts.workerResult, 'explicit_metadata');
+    }
+    const parsed = extractJsonObjectFromSummary(opts.finalSummary);
+    if (parsed) {
+        return normalizeMeshWorkerResult(parsed, 'final_summary_json');
+    }
+    return normalizeMeshWorkerResult(undefined, 'default');
+}
+
 export function buildTaskCompletionEvidence(opts: BuildTaskCompletionEvidenceOptions): MeshTaskCompletionEvidence {
     const providerSessionId = opts.providerSessionId?.trim() || undefined;
     const providerType = opts.providerType?.trim() || undefined;
@@ -204,6 +501,7 @@ export function buildTaskCompletionEvidence(opts: BuildTaskCompletionEvidenceOpt
             providerSessionId,
             finalSummaryAvailable: typeof opts.finalSummary === 'string' && opts.finalSummary.trim().length > 0,
         },
+        workerResult: resolveWorkerResult(opts),
         git: {
             status: 'deferred',
             reason: 'ordinary_completion_git_status_not_checked',
@@ -239,12 +537,14 @@ export function appendLedgerEntry(
 
     const filePath = getLedgerPath(meshId);
 
-    // Rotate if file exceeds max size
+    // Compact or rotate based on file size
     if (existsSync(filePath)) {
         try {
             const stat = statSync(filePath);
             if (stat.size >= MAX_FILE_SIZE_BYTES) {
                 rotateLedgerFile(meshId, filePath);
+            } else if (stat.size >= COMPACT_THRESHOLD_BYTES) {
+                compactLedger(meshId);
             }
         } catch {
             // stat failed — proceed with append anyway
@@ -254,6 +554,7 @@ export function appendLedgerEntry(
     try {
         const line = JSON.stringify(entry) + '\n';
         appendFileSync(filePath, line, { encoding: 'utf-8', mode: 0o600 });
+        invalidateLedgerCache(meshId);
         meshLedgerEvents.emit('append', meshId, entry);
         return entry;
     } catch (e: any) {
@@ -285,8 +586,9 @@ export function appendRemoteLedgerEntries(meshId: string, entries: MeshLedgerEnt
     if (entries.length === 0) return { accepted: 0, skippedDuplicate: 0, rejectedInvalid: 0, entries: [] };
     const ledgerPath = getLedgerPath(meshId);
 
-    // Read existing to deduplicate by ID
-    const existing = new Set(readLedgerEntries(meshId).map(e => e.id));
+    // Dedup against recent entries only — P2P replication is incremental (cursor-based),
+    // so duplicates appear in the recent tail, not deep history.
+    const existing = new Set(readLedgerEntries(meshId, { tail: 1000 }).map(e => e.id));
     const validEntries: MeshLedgerEntry[] = [];
     let rejectedInvalid = 0;
     let skippedDuplicate = 0;
@@ -310,6 +612,7 @@ export function appendRemoteLedgerEntries(meshId: string, entries: MeshLedgerEnt
     try {
         const lines = validEntries.map(e => JSON.stringify(e)).join('\n') + '\n';
         appendFileSync(ledgerPath, lines, { encoding: 'utf-8', mode: 0o600 });
+        invalidateLedgerCache(meshId);
         for (const entry of validEntries) {
             meshLedgerEvents.emit('append', meshId, entry);
         }
@@ -319,103 +622,81 @@ export function appendRemoteLedgerEntries(meshId: string, entries: MeshLedgerEnt
     }
 }
 
-/**
- * Read ledger entries with optional filtering.
- */
-export function readLedgerEntries(meshId: string, opts?: ReadLedgerOptions): MeshLedgerEntry[] {
+// ─── Ledger Read Cache ─────────────────────────
+// Absorbs repeated reads within a single event-processing burst (e.g. agent:stopped
+// triggers shouldSuppressIntentionalCleanupStop, findRecentTerminalLedgerEvidence,
+// hasDispatchAfterTerminal, and getSessionRecoveryContext — all reading the same file).
+// TTL is 100ms: short enough to stay current, long enough to cover one event cycle.
+// Cache is invalidated on every write (append, remote import, compaction).
+
+const ledgerReadCache = new Map<string, { entries: MeshLedgerEntry[]; cachedAt: number }>();
+const LEDGER_CACHE_TTL_MS = 100;
+
+function readLedgerFile(meshId: string): 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 { content = readFileSync(filePath, 'utf-8'); } catch { return []; }
+    const entries: MeshLedgerEntry[] = [];
+    for (const line of content.split('\n')) {
+        if (!line.trim()) continue;
         try {
             const entry = JSON.parse(line) as MeshLedgerEntry;
-            if (!entry.id || !entry.kind) continue;
-            entries.push(entry);
-        } catch {
-            // Skip malformed lines
-        }
+            if (entry.id && entry.kind) entries.push(entry);
+        } catch { /* skip malformed lines */ }
     }
+    return entries;
+}
+
+function getCachedRawEntries(meshId: string): MeshLedgerEntry[] {
+    const now = Date.now();
+    const cached = ledgerReadCache.get(meshId);
+    if (cached && now - cached.cachedAt < LEDGER_CACHE_TTL_MS) return cached.entries;
+    const entries = readLedgerFile(meshId);
+    ledgerReadCache.set(meshId, { entries, cachedAt: now });
+    return entries;
+}
+
+function invalidateLedgerCache(meshId: string): void {
+    ledgerReadCache.delete(meshId);
+}
+
+/**
+ * Read ledger entries with optional filtering.
+ */
+export function readLedgerEntries(meshId: string, opts?: ReadLedgerOptions): MeshLedgerEntry[] {
+    let entries = getCachedRawEntries(meshId);
 
-    // 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 (!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;
 }
 
 /**
- * Read a bounded, cursor-addressable ledger slice for local-first/P2P replication.
- * The result is intentionally small and self-describing so coordinators can query
- * remote daemons on demand without Cloud/D1 becoming a ledger data-plane.
+ * Build a ledger summary from pre-loaded entries. Used by both getLedgerSummary
+ * and readLedgerSlice so they share a single getCachedRawEntries() call.
  */
-export function readLedgerSlice(meshId: string, opts?: ReadLedgerSliceOptions): MeshLedgerSlice {
-    const limit = clampLedgerSliceLimit(opts?.limit);
-    let entries = readLedgerEntries(meshId, { since: opts?.since, kind: opts?.kind });
-    const afterId = typeof opts?.afterId === 'string' && opts.afterId.trim() ? opts.afterId.trim() : null;
-    if (afterId) {
-        const index = entries.findIndex(entry => entry.id === afterId);
-        entries = index >= 0 ? entries.slice(index + 1) : entries;
-    }
-    const bounded = entries.slice(0, limit);
-    return {
-        protocol: 'adhdev.mesh.ledger.slice.v1',
-        meshId,
-        entries: bounded,
-        cursor: {
-            afterId,
-            nextAfterId: bounded.length ? bounded[bounded.length - 1].id : afterId,
-            limit,
-            hasMore: entries.length > bounded.length,
-        },
-        summary: getLedgerSummary(meshId),
-        sourceOfTruth: {
-            kind: 'local_jsonl',
-            path: getLedgerPath(meshId),
-            bounded: true,
-            maxLimit: MAX_LEDGER_SLICE_LIMIT,
-        },
-    };
-}
-
-/**
- * Get a summary of mesh activity from the ledger.
- */
-export function getLedgerSummary(meshId: string): MeshLedgerSummary {
-    const entries = readLedgerEntries(meshId);
+function buildLedgerSummary(meshId: string, entries: MeshLedgerEntry[]): MeshLedgerSummary {
+    const archived = readArchivedCounts(meshId);
     const now = Date.now();
     const recentFailureCutoff = now - RECENT_FAILURE_WINDOW_MS;
 
     const summary: MeshLedgerSummary = {
         meshId,
-        totalEntries: entries.length,
+        totalEntries: entries.length + archived.totalArchived,
         taskDispatched: 0,
-        taskCompleted: 0,
-        taskFailed: 0,
-        taskStalled: 0,
+        taskCompleted: archived.taskCompleted,
+        taskFailed: archived.taskFailed,
+        taskStalled: archived.taskStalled,
         sessionLaunched: 0,
         checkpointCreated: 0,
         lastActivityAt: null,
@@ -450,6 +731,59 @@ export function getLedgerSummary(meshId: string): MeshLedgerSummary {
     return summary;
 }
 
+/**
+ * Read a bounded, cursor-addressable ledger slice for local-first/P2P replication.
+ * The result is intentionally small and self-describing so coordinators can query
+ * remote daemons on demand without Cloud/D1 becoming a ledger data-plane.
+ */
+export function readLedgerSlice(meshId: string, opts?: ReadLedgerSliceOptions): MeshLedgerSlice {
+    const limit = clampLedgerSliceLimit(opts?.limit);
+    // Load raw entries once and share between filtering, pagination, and summary.
+    const rawEntries = getCachedRawEntries(meshId);
+
+    let entries: MeshLedgerEntry[] = rawEntries;
+    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));
+    }
+
+    const afterId = typeof opts?.afterId === 'string' && opts.afterId.trim() ? opts.afterId.trim() : null;
+    if (afterId) {
+        const index = entries.findIndex(entry => entry.id === afterId);
+        entries = index >= 0 ? entries.slice(index + 1) : entries;
+    }
+    const bounded = entries.slice(0, limit);
+    return {
+        protocol: 'adhdev.mesh.ledger.slice.v1',
+        meshId,
+        entries: bounded,
+        cursor: {
+            afterId,
+            nextAfterId: bounded.length ? bounded[bounded.length - 1].id : afterId,
+            limit,
+            hasMore: entries.length > bounded.length,
+        },
+        summary: buildLedgerSummary(meshId, rawEntries),
+        sourceOfTruth: {
+            kind: 'local_jsonl',
+            path: getLedgerPath(meshId),
+            bounded: true,
+            maxLimit: MAX_LEDGER_SLICE_LIMIT,
+        },
+    };
+}
+
+/**
+ * Get a summary of mesh activity from the ledger.
+ */
+export function getLedgerSummary(meshId: string): MeshLedgerSummary {
+    return buildLedgerSummary(meshId, getCachedRawEntries(meshId));
+}
+
 // ─── Recovery Context ───────────────────────────
 
 export interface SessionRecoveryContext {
@@ -484,46 +818,64 @@ export function getSessionRecoveryContext(
     },
 ): SessionRecoveryContext {
     const maxRetries = opts.maxRetries ?? 1;
-    const entries = readLedgerEntries(meshId);
+    // tail:500 is sufficient — task_dispatched is never archived (only terminal kinds are),
+    // so dispatch history is always present. The 30-min failure window means we never need
+    // more than a few dozen recent entries for consecutiveNodeFailures. Bounding to 500
+    // avoids a full O(n) scan for meshes with many historical entries.
+    const entries = readLedgerEntries(meshId, { tail: 500 });
 
-    // Find the last task_dispatched for this session or node
+    // Single backward pass: find last task_dispatched AND count consecutive recent failures.
+    const now = Date.now();
+    const recentWindow = now - RECENT_FAILURE_WINDOW_MS;
     let lastDispatch: MeshLedgerEntry | null = null;
+    let consecutiveNodeFailures = 0;
+    let failureCountDone = false;
     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 ts = new Date(e.timestamp).getTime();
+
+        // Failure counting: scan until we exit the recent window or hit a chain-breaker
+        if (!failureCountDone) {
+            if (ts < recentWindow) {
+                failureCountDone = true;
+            } else if (opts.nodeId && e.nodeId !== opts.nodeId) {
+                // Entry for a different node — skip for failure counting but continue scanning for dispatch
+            } else if (e.kind === 'task_failed') {
+                if (!isIntentionalCleanupStopEntry(e)) consecutiveNodeFailures++;
+            } else if (e.kind === 'task_completed' || e.kind === 'task_dispatched') {
+                // A completion or new dispatch breaks the consecutive failure chain
+                failureCountDone = true;
+            }
+        }
+
+        // Dispatch search: find the last dispatch matching this session or node
+        if (lastDispatch === null && e.kind === 'task_dispatched') {
+            if (opts.sessionId && e.sessionId === opts.sessionId) { lastDispatch = e; }
+            else if (!opts.sessionId && opts.nodeId && e.nodeId === opts.nodeId) { lastDispatch = e; }
+        }
+
+        // Stop once both tasks are done
+        if (lastDispatch !== null && failureCountDone) 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') {
-            if (isIntentionalCleanupStopEntry(e)) continue;
-            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)
+    // Count how many times the same task was attempted.
+    // Prefer exact taskId match (payload.taskId) to avoid 200-char prefix collisions.
     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++;
+    if (lastDispatch) {
+        const taskId = typeof lastDispatch.payload?.taskId === 'string' ? lastDispatch.payload.taskId : null;
+        if (taskId) {
+            for (const e of entries) {
+                if (e.kind === 'task_dispatched' && e.payload?.taskId === taskId) taskAttemptCount++;
+            }
+        } else 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++;
                 }
             }
         }
@@ -573,7 +925,8 @@ function rotateLedgerFile(meshId: string, currentPath: string): void {
 
     try {
         renameSync(currentPath, getRotatedPath(meshId, index));
-    } catch {
+    } catch (e: any) {
         // Rotation failed — the next append will just grow the file
+        process.stderr.write(`[adhdev-mesh] Ledger rotation failed for mesh ${meshId}: ${e?.message || e}. File will continue to grow.\n`);
     }
 }