@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

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

@@ -0,0 +1,128 @@
+/**
+ * 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. suggest + write `.adhdev/change-impact.json`     (change-impact classification)
+ *   4. recommend a node providerPriority from the installed CLI providers
+ *
+ * mesh_init now covers all THREE repo-committed `.adhdev/*` config families that
+ * carry a suggest→validate→write engine (refine + worktree_bootstrap +
+ * change-impact). `.adhdev/mesh.json` (coordinator prompt + operating notes) has
+ * its own dedicated export/write path (export_mesh_json_config / write_mesh_json_config).
+ *
+ * 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 ChangeImpactConfig } from '../git/change-impact-config.js';
+import type { MagiKindPanelMap } from '@adhdev/mesh-shared';
+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 declare const MESH_INIT_CHANGE_IMPACT_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 | ChangeImpactConfig;
+}
+/**
+ * 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;
+}
+/**
+ * A snapshot of the currently-saved config for each domain, so the coordinator can
+ * render a current-vs-suggested diff to the user before an init/reinit overwrite.
+ * This is READ-ONLY echo — every field is what is on disk / machine-local right now,
+ * never a suggestion. Absent domains are reported as `undefined` config.
+ */
+export interface MeshInitCurrentConfigEcho {
+    /** Currently-saved `.adhdev/refine.json` (repo-committed) — undefined when absent/invalid. */
+    refine?: RepoMeshRefineConfig;
+    /** Currently-saved `.adhdev/worktree_bootstrap.json` (repo-committed). */
+    worktreeBootstrap?: RepoMeshWorktreeBootstrapConfig;
+    /** Currently-saved `.adhdev/change-impact.json` (repo-committed). */
+    changeImpact?: ChangeImpactConfig;
+    /** Per-domain source type so the coordinator can tell "absent" from "invalid". */
+    sourceTypes: {
+        refine: string;
+        worktreeBootstrap: string;
+        changeImpact: string;
+    };
+    /**
+     * Currently-configured MAGI kind→panel slot bindings (machine-local
+     * ~/.adhdev/meshes.json). Empty object when none configured. This is a
+     * machine-local echo — the coordinator labels it as such vs. the repo files.
+     */
+    magiKindPanels: MagiKindPanelMap;
+}
+export interface RunMeshInitResult {
+    success: true;
+    workspace: string;
+    dryRun: boolean;
+    refine: MeshInitConfigFileResult;
+    worktreeBootstrap: MeshInitConfigFileResult;
+    changeImpact: MeshInitConfigFileResult;
+    providers: {
+        providerPriority: string[];
+        installedProviders: Array<{
+            id: string;
+            displayName: string;
+            version?: string;
+        }>;
+    };
+    /**
+     * Read-only snapshot of the currently-saved config per domain (repo files +
+     * machine-local kind panels). Lets the coordinator present a current-vs-suggested
+     * diff to the user before any overwrite. Always populated (dry-run and write).
+     */
+    currentConfig: MeshInitCurrentConfigEcho;
+    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,9 +42,8 @@ export interface MeshLedgerReconciliationEvidence {
     meshId: string;
     generatedAt: string;
     sourceOfTruth: {
-        kind: 'coordinator_local_jsonl';
+        kind: 'coordinator_local_sqlite';
         p2pOnly: true;
-        cloudD1LedgerSync: false;
         notes: string;
     };
     replicas: MeshLedgerReplicaEvidence[];
@@ -47,7 +66,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,9 @@
  * 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_joined' | 'node_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled';
+import { MeshRuntimeStore } from './mesh-runtime-store.js';
+import { type MeshLedgerOriginatingCoordinatorV2 } from './contracts.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' | 'event_held' | 'event_held_requeued' | 'task_reclaimed' | 'coordinator_operating_note' | 'coordinator_operating_note_tombstone' | 'mission_created' | 'mission_status_changed' | 'mission_goal_updated' | 'magi_dispatched' | 'magi_synthesis';
 export interface MeshLedgerEntry {
     id: string;
     meshId: string;
@@ -25,6 +27,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' | 'parseable_answer' | 'default';
+}
 export interface MeshTaskCompletionEvidence {
     source: 'agent_status_event';
     event: 'agent:generating_completed' | 'agent:ready';
@@ -38,6 +74,7 @@ export interface MeshTaskCompletionEvidence {
         providerSessionId?: string;
         finalSummaryAvailable: boolean;
     };
+    workerResult: MeshWorkerResultArtifact;
     git: {
         status: 'deferred';
         reason: string;
@@ -59,6 +96,7 @@ export interface BuildTaskCompletionEvidenceOptions {
     providerType?: string;
     providerSessionId?: string;
     finalSummary?: string;
+    workerResult?: Record<string, unknown>;
     completedAt?: string;
 }
 export interface MeshLedgerSummary {
@@ -77,6 +115,12 @@ export interface ReadLedgerOptions {
     tail?: number;
     since?: string;
     kind?: MeshLedgerKind[];
+    /**
+     * Filter to entries whose nodeId is equivalent to this daemon id. Matched via
+     * daemonIdsEquivalent (not raw ===) so caller-supplied identifiers in any form
+     * (mach_X vs daemon_mach_X) resolve correctly — see the canon-identity defect class.
+     */
+    node?: string;
 }
 export interface ReadLedgerSliceOptions {
     /** Return entries strictly after this entry id. If not found, starts from the beginning of the filtered set. */
@@ -114,21 +158,105 @@ export interface AppendRemoteLedgerResult {
     entries: MeshLedgerEntry[];
 }
 export declare const MAX_LEDGER_SLICE_LIMIT = 500;
+export declare const OPERATING_NOTE_KIND: MeshLedgerKind;
+export declare const OPERATING_NOTE_TOMBSTONE_KIND: MeshLedgerKind;
+export declare const OPERATING_NOTE_DEDUPE_WINDOW = 40;
+export declare const OPERATING_NOTE_KEEP_LATEST = 100;
 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;
+/**
+ * Build the v2 originating-coordinator stamp for a task_dispatched ledger entry
+ * (B2a / design decision §2). This is the source of truth from which a worker's
+ * completion emit later restores `dispatchedBy` — it records which coordinator
+ * dispatched the task, so the terminal event can be routed (unicast) back to it.
+ *
+ * Nested under `payload.originatingCoordinator`; additive, so existing readers
+ * of the task_dispatched payload are unaffected. Returns undefined when no
+ * coordinator daemon id is known (the pre-v2 path) so the caller omits the stamp
+ * entirely rather than writing a malformed identity — those entries stay v1 and
+ * are broadcast-treated during rollout.
+ */
+export declare function buildLedgerOriginatingCoordinatorStamp(fields: {
+    coordinatorDaemonId?: string | null;
+    coordinatorRunId?: string | null;
+    coordinatorSessionId?: string | null;
+}): MeshLedgerOriginatingCoordinatorV2 | undefined;
 /**
  * Append a new entry to the mesh ledger.
  * Handles file creation, rotation on size overflow, and atomic writes.
  */
 export declare const meshLedgerEvents: EventEmitter<[never]>;
 export declare function appendLedgerEntry(meshId: string, partial: Omit<MeshLedgerEntry, 'id' | 'meshId' | 'timestamp'>): MeshLedgerEntry;
+/** True if the operating note is retracted by any tombstone in `tombstones`. */
+export declare function isOperatingNoteTombstoned(entry: Pick<MeshLedgerEntry, 'id' | 'payload'>, tombstones: {
+    ids: Set<string>;
+    fingerprints: Set<string>;
+}): boolean;
+/**
+ * Fix (2) supersede/remove: append a tombstone that retracts a coordinator
+ * operating note. Targets by note id and/or by exact trimmed text (a text target
+ * retracts every note with that text). History is preserved — the notes stay in
+ * the ledger but readers filter them out. Returns how many currently-live notes
+ * the tombstone will hide.
+ */
+export declare function tombstoneOperatingNote(meshId: string, target: {
+    noteId?: string;
+    text?: string;
+    reason?: string;
+}): {
+    tombstone: MeshLedgerEntry;
+    matched: number;
+};
+/**
+ * Read live operating notes (tombstoned notes filtered out), oldest→newest.
+ * `tail` bounds the number of live notes returned (the freshest N).
+ */
+export declare function readOperatingNotes(meshId: string, opts?: {
+    tail?: number;
+}): MeshLedgerEntry[];
+/**
+ * Fix (3) keep-latest-N prune for coordinator_operating_note. Removes, from the
+ * store, (a) every note retracted by a tombstone, and (b) the oldest live notes
+ * beyond `keepLatest`. Tombstone entries themselves are retained as an audit trail
+ * of what was forgotten. Returns the number of note entries removed.
+ */
+export declare function pruneOperatingNotes(meshId: string, keepLatest?: number): number;
 /**
  * Append entries received over local-first/P2P ledger replication to the local ledger.
  * 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 +265,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.
  */

package/dist/mesh/mesh-magi-status.d.ts

@@ -0,0 +1,63 @@
+import type { MeshLedgerEntry } from './mesh-ledger.js';
+import type { MagiGitSkew } from '@adhdev/mesh-shared';
+export type MeshMagiActivityStatus = 'running' | 'synthesized';
+/** A bounded needs_verification preview item (claim text + category only). */
+export interface MeshMagiNeedsVerificationItem {
+    claim: string;
+    category: string;
+}
+export interface MeshMagiActivitySummary {
+    consensusGroupId: string;
+    status: MeshMagiActivityStatus;
+    missionId?: string;
+    panel?: string;
+    question?: string;
+    replicaCount?: number;
+    answered?: number;
+    missing?: number;
+    staleReplicas?: number;
+    needsVerificationCount?: number;
+    agreedCount?: number;
+    independenceBanner?: string | null;
+    gitSkew?: MagiGitSkew;
+    /** Bounded sample of the needs_verification clusters (claim + category). */
+    needsVerification?: MeshMagiNeedsVerificationItem[];
+    openQuestions?: string[];
+    lastLedgerKind?: string;
+    lastUpdatedAt?: string;
+}
+/** Cap on inlined needs_verification preview items per group (keeps the payload bounded). */
+export declare const MAGI_NEEDS_VERIFICATION_PREVIEW_CAP = 8;
+/**
+ * Reconstruct per-consensusGroup MAGI activity from a ledger window. The newest
+ * `magi_synthesis` for a group supplies the synthesis fields; a `magi_dispatched`
+ * with no later synthesis stays `running`. Deduped by consensusGroupId, newest first.
+ */
+export declare function buildMeshMagiActivity(args: {
+    meshId?: string;
+    ledgerEntries?: MeshLedgerEntry[];
+}): MeshMagiActivitySummary[];
+/** Synthesized groups older than this (relative to the newest activity in the set) are
+ *  folded out of the active list — already-resolved historical runs that should not keep
+ *  inflating mesh_status. 6h covers a long working session. */
+export declare const STALE_MAGI_WINDOW_MS: number;
+/** Cap on recent synthesized groups kept in the active list even if all are fresh. */
+export declare const RECENT_MAGI_CAP = 6;
+export interface MeshMagiActivitySummaryFold {
+    total: number;
+    byStatus: Record<string, number>;
+    /** Synthesized groups dropped from the active list as stale historical residue. */
+    staleSynthesized: number;
+    /** Bounded set of recent/active groups (running first, then recent synthesized). */
+    groups: MeshMagiActivitySummary[];
+}
+/**
+ * Bound the MAGI activity list for mesh_status: running groups are always kept; synthesized
+ * groups are kept only when recent (within STALE_MAGI_WINDOW_MS of the newest activity AND
+ * among the RECENT_MAGI_CAP most-recent). Freshness is measured relative to the newest group
+ * (not wall-clock) so the result is deterministic for a given input. Mirrors
+ * summarizeMeshAsyncRefineJobs.
+ */
+export declare function summarizeMeshMagiActivity(activity: MeshMagiActivitySummary[]): MeshMagiActivitySummaryFold;
+/** Latest persisted synthesis activity for one consensusGroupId, or undefined. */
+export declare function getMeshMagiActivityByGroup(ledgerEntries: MeshLedgerEntry[], consensusGroupId: string): MeshMagiActivitySummary | undefined;