@adhdev/daemon-core 0.9.82-rc.31 → 0.9.82-rc.310

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

@@ -0,0 +1,138 @@
+import type { DaemonComponents } from '../boot/daemon-lifecycle.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;
+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;
+    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 handleMeshForwardEvent(components: DaemonComponents, payload: Record<string, unknown>): {
+    success: boolean;
+    forwarded: number;
+    suppressed: boolean;
+    intentionalCleanupStop: boolean;
+    terminalLedgerEvidence?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    duplicateApproval?: undefined;
+    duplicateCompletion?: undefined;
+    duplicateStopped?: undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    suppressed: boolean;
+    terminalLedgerEvidence: boolean;
+    terminalLedgerKind: unknown;
+    intentionalCleanupStop?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    duplicateApproval?: undefined;
+    duplicateCompletion?: undefined;
+    duplicateStopped?: undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    suppressed: boolean;
+    duplicateRefineTerminalEvent: boolean;
+    intentionalCleanupStop?: undefined;
+    terminalLedgerEvidence?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateApproval?: undefined;
+    duplicateCompletion?: undefined;
+    duplicateStopped?: undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    suppressed: boolean;
+    duplicateApproval: boolean;
+    intentionalCleanupStop?: undefined;
+    terminalLedgerEvidence?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    duplicateCompletion?: undefined;
+    duplicateStopped?: undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    suppressed: boolean;
+    duplicateCompletion: boolean;
+    terminalLedgerEvidence: boolean;
+    intentionalCleanupStop?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    duplicateApproval?: undefined;
+    duplicateStopped?: undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    suppressed: boolean;
+    duplicateCompletion: boolean;
+    intentionalCleanupStop?: undefined;
+    terminalLedgerEvidence?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    duplicateApproval?: undefined;
+    duplicateStopped?: undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    suppressed: boolean;
+    duplicateStopped: boolean;
+    intentionalCleanupStop?: undefined;
+    terminalLedgerEvidence?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    duplicateApproval?: undefined;
+    duplicateCompletion?: undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    forwarded: number;
+    suppressed?: undefined;
+    intentionalCleanupStop?: undefined;
+    terminalLedgerEvidence?: undefined;
+    terminalLedgerKind?: undefined;
+    duplicateRefineTerminalEvent?: undefined;
+    duplicateApproval?: undefined;
+    duplicateCompletion?: undefined;
+    duplicateStopped?: undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string;
+};
+export declare function setupMeshEventForwarding(components: DaemonComponents): void;

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

@@ -0,0 +1,45 @@
+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;
+}
+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 buildLongGeneratingCompletionReconciliation(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,47 @@
+import type { SessionRecoveryContext } from './mesh-ledger.js';
+export declare function readNonEmptyString(value: unknown): string;
+export declare function readRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function canonicalDaemonId(value: unknown): string;
+export declare function sameDaemonId(a: unknown, b: unknown): boolean;
+/**
+ * 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;
+    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;
+} | 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;
+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;

package/dist/mesh/mesh-ledger-reconciliation.d.ts

@@ -1,4 +1,24 @@
-import type { AppendRemoteLedgerResult, MeshLedgerSlice, MeshLedgerSummary } from './mesh-ledger.js';
+import type { AppendRemoteLedgerResult, MeshLedgerSummary } from './mesh-ledger.js';
+/** Minimal ledger slice shape accepted by buildMeshLedgerReplicaEvidence. Covers both JSONL and SQLite slices. */
+export interface AnyLedgerSlice {
+    entries: Array<{
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId?: string | null;
+        sessionId?: string | null;
+        providerType?: string | null;
+        payload: unknown;
+    }>;
+    cursor: {
+        afterId: string | null;
+        nextAfterId: string | null;
+        limit: number;
+        hasMore: boolean;
+    };
+    summary?: MeshLedgerSummary;
+}
 export type MeshLedgerReplicaStatus = 'local' | 'queried' | 'imported' | 'failed';
 export interface MeshLedgerReplicaEvidence {
     nodeId: string;
@@ -22,7 +42,7 @@ export interface MeshLedgerReconciliationEvidence {
     meshId: string;
     generatedAt: string;
     sourceOfTruth: {
-        kind: 'coordinator_local_jsonl';
+        kind: 'coordinator_local_sqlite';
         p2pOnly: true;
         cloudD1LedgerSync: false;
         notes: string;
@@ -47,7 +67,7 @@ export declare function buildMeshLedgerReplicaEvidence(args: {
     nodeId: string;
     daemonId?: string;
     transport: 'local' | 'p2p_datachannel';
-    slice?: MeshLedgerSlice;
+    slice?: AnyLedgerSlice;
     importResult?: AppendRemoteLedgerResult;
     status?: MeshLedgerReplicaStatus;
     error?: string;

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

@@ -13,7 +13,8 @@
  * Safety:  mode 0o600, atomic append via appendFileSync
  */
 import { EventEmitter } from 'events';
-export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'session_launched' | 'session_auto_launch' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled';
+import { MeshRuntimeStore } from './mesh-runtime-store.js';
+export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | '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' | 'delivery_unroutable' | 'direct_dispatch_pruned';
 export interface MeshLedgerEntry {
     id: string;
     meshId: string;
@@ -25,6 +26,40 @@ export interface MeshLedgerEntry {
     payload: Record<string, unknown>;
 }
 export declare function isIntentionalCleanupStopEntry(entry: Pick<MeshLedgerEntry, 'kind' | 'payload'>): boolean;
+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';
@@ -38,6 +73,7 @@ export interface MeshTaskCompletionEvidence {
         providerSessionId?: string;
         finalSummaryAvailable: boolean;
     };
+    workerResult: MeshWorkerResultArtifact;
     git: {
         status: 'deferred';
         reason: string;
@@ -59,6 +95,7 @@ export interface BuildTaskCompletionEvidenceOptions {
     providerType?: string;
     providerSessionId?: string;
     finalSummary?: string;
+    workerResult?: Record<string, unknown>;
     completedAt?: string;
 }
 export interface MeshLedgerSummary {
@@ -115,6 +152,27 @@ export interface AppendRemoteLedgerResult {
 }
 export declare const MAX_LEDGER_SLICE_LIMIT = 500;
 export declare function getLedgerDir(): string;
+/**
+ * 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 declare function buildWorkerTaskFooter(): string;
+/**
+ * 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 declare function compactLedger(meshId: string): {
+    archivedCount: number;
+    retainedCount: number;
+};
+export declare function normalizeMeshWorkerResult(input?: Record<string, unknown>, source?: MeshWorkerResultArtifact['source']): MeshWorkerResultArtifact;
 export declare function buildTaskCompletionEvidence(opts: BuildTaskCompletionEvidenceOptions): MeshTaskCompletionEvidence;
 /**
  * Append a new entry to the mesh ledger.
@@ -127,8 +185,16 @@ export declare function appendLedgerEntry(meshId: string, partial: Omit<MeshLedg
  * This skips deduplicated entries and rejects malformed/cross-mesh entries.
  */
 export declare function appendRemoteLedgerEntries(meshId: string, entries: MeshLedgerEntry[]): AppendRemoteLedgerResult;
+/**
+ * Test helper: clear all runtime ledger state for a mesh — SQLite rows, read
+ * cache, and the one-time import flag. JSONL files are the caller's concern.
+ */
+export declare function __clearMeshLedgerForTests(meshId: string): void;
 /**
  * Read ledger entries with optional filtering.
+ * G2: SQLite (mesh_event_ledger) is the primary read path; legacy JSONL is
+ * imported once per store instance and otherwise retained as an
+ * export/import/debug artifact only.
  */
 export declare function readLedgerEntries(meshId: string, opts?: ReadLedgerOptions): MeshLedgerEntry[];
 /**
@@ -137,6 +203,16 @@ export declare function readLedgerEntries(meshId: string, opts?: ReadLedgerOptio
  * remote daemons on demand without Cloud/D1 becoming a ledger data-plane.
  */
 export declare function readLedgerSlice(meshId: string, opts?: ReadLedgerSliceOptions): MeshLedgerSlice;
+/**
+ * G4: Read a bounded ledger slice from the SQLite mesh_event_ledger table.
+ * This is the preferred P2P reconcile read path; JSONL files are retained as
+ * export/import/debug/legacy artifacts only.
+ *
+ * Returns a shape structurally compatible with MeshLedgerSlice (minus the
+ * JSONL-specific `summary` and `sourceOfTruth.path` fields) so callers can
+ * pass it to buildMeshLedgerReplicaEvidence without modification.
+ */
+export declare function readLedgerSliceFromStore(meshId: string, opts?: ReadLedgerSliceOptions): ReturnType<typeof MeshRuntimeStore.prototype.readLedgerSlice>;
 /**
  * Get a summary of mesh activity from the ledger.
  */