@adhdev/daemon-core 0.9.82-rc.47 → 0.9.82-rc.470

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_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;

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

@@ -0,0 +1,226 @@
+/**
+ * M3: Mission persistence (minimal form).
+ *
+ * A mission is a persistent record of a multi-task goal so the plan lives in
+ * the system rather than in the coordinator LLM's context. Coordinator
+ * sessions can die or compact; a new coordinator reads the mission back at
+ * launch and continues.
+ *
+ * Explicit non-goals (see docs/mesh-product-plan-v2.md Phase M3): this is not
+ * a workflow engine and there is no automatic takeover daemon. Progress is
+ * never stored — it is derived from queue task statuses (mission_id) at
+ * query time.
+ */
+import { type MeshMissionStats } from './mesh-task-stats.js';
+export type MeshMissionStatus = 'active' | 'paused' | 'completed' | 'abandoned';
+export declare const MESH_MISSION_STATUSES: MeshMissionStatus[];
+/**
+ * Provenance of a mission. `magi` marks an inline mission auto-created by a
+ * mesh_magi_review fan-out (one per cross-verification run). `coordinator` (the
+ * default semantic for an unstamped/legacy mission) marks a coordinator- or
+ * user-authored mission. Used to bound the accumulation of completed MAGI missions
+ * out of the default mesh_mission_list surface — see listMeshMissionSummaries.
+ */
+export type MeshMissionSource = 'magi' | 'coordinator';
+export interface MeshMissionRecord {
+    id: string;
+    meshId: string;
+    title: string;
+    goal: string;
+    status: MeshMissionStatus;
+    /**
+     * Optional provenance tag. Absent on missions created before this field existed
+     * and on coordinator/user missions that don't bother stamping it — both are
+     * treated as coordinator missions (never auto-hidden). Only explicit `magi`
+     * missions are bounded out of the default list once completed.
+     */
+    source?: MeshMissionSource;
+    /**
+     * G3: idempotency marker for the mission_close_candidate nudge. ISO timestamp of
+     * the last emit; absent/undefined when the mission has not (or no longer) been in a
+     * fully-terminal state. Owned by maybeEmitMissionCloseCandidate — never set by a
+     * regular upsert. See summarizeMissionTasks / maybeEmitMissionCloseCandidate.
+     */
+    closeCandidateEmittedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MeshMissionTaskAggregate {
+    total: number;
+    pending: number;
+    assigned: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    /** Pending tasks held back by a dependency failure (blockedReason set). */
+    blocked: number;
+    /** Latest updatedAt across the mission's tasks, or null with no tasks. */
+    lastActivityAt: string | null;
+}
+export interface MeshMissionSummary extends MeshMissionRecord {
+    tasks: MeshMissionTaskAggregate;
+    /**
+     * Operational rollup (durations / attempts) derived from the ledger via
+     * computeMeshMissionStats. Optional: only populated by surfaces that opt in
+     * (e.g. mesh_status), since the rollup scans a bounded ledger tail per
+     * mission. Absent on the lightweight task-aggregate-only summaries.
+     */
+    stats?: MeshMissionStats;
+}
+/**
+ * Slim mission summary for the mesh_status compact (default) surface. Drops the
+ * full `goal` text — which can be hundreds of chars per mission and is repeated
+ * for every mission on every status call — keeping only a short preview plus a
+ * `goalTruncated` flag when the original was longer. The stored goal is never
+ * mutated; this is an output-only projection. Coordinators that need the full
+ * goal call mesh_status with verbose=true, or read the mission directly via
+ * mesh_mission_upsert / getMeshMission.
+ */
+export interface MeshMissionSlimSummary extends Omit<MeshMissionSummary, 'goal'> {
+    /** Short preview of the goal (≤ GOAL_PREVIEW_MAX chars), '' when goal empty. */
+    goalPreview: string;
+    /** True when the stored goal was longer than the preview (full text elided). */
+    goalTruncated: boolean;
+}
+/** Max chars of goal text retained in the slim (compact) mission summary. */
+export declare const GOAL_PREVIEW_MAX = 120;
+/**
+ * Shorter goal preview used by the mesh_status compact (LLM coordinator) surface.
+ * The coordinator only needs to recognize a mission, not read its full goal, and
+ * mesh_status repeats every live mission on every poll — so the status preview is
+ * tighter than the dashboard / mesh_mission_list preview (GOAL_PREVIEW_MAX).
+ */
+export declare const COMPACT_STATUS_GOAL_PREVIEW_MAX = 80;
+export declare function upsertMeshMission(meshId: string, input: {
+    id?: string;
+    title: string;
+    goal?: string;
+    status?: string;
+    source?: MeshMissionSource;
+}): MeshMissionRecord;
+export declare function getMeshMissions(meshId: string, statuses?: MeshMissionStatus[]): MeshMissionRecord[];
+export declare function getMeshMission(meshId: string, missionId: string): MeshMissionRecord | null;
+/** Aggregate task statuses for a mission at query time (no stored progress). */
+export declare function summarizeMissionTasks(meshId: string, missionId: string): MeshMissionTaskAggregate;
+export declare function summarizeMeshMission(meshId: string, mission: MeshMissionRecord): MeshMissionSummary;
+/**
+ * G3 — all-tasks-terminal detection: true when a mission has at least one task and
+ * every task has reached a terminal status (no pending, no assigned). This is the
+ * derived signal (never a stored flag) that a mission has no more work in flight and
+ * is a candidate for the coordinator to close. A mission with zero tasks is NOT a
+ * candidate — an empty mission is a freshly-created plan, not a finished one.
+ */
+export declare function isMissionAllTasksTerminal(aggregate: MeshMissionTaskAggregate): boolean;
+/**
+ * G3 (step ①) — emit a `mission_close_candidate` coordinator nudge the first time an
+ * ACTIVE mission's tasks all become terminal, and reset the idempotency marker when a
+ * mission leaves the terminal state. Call this after any task-status mutation that can
+ * change a mission's aggregate (completion / failure / cancel / dependency-failure /
+ * new task). Fire-and-forget and fully best-effort — a throw here must never break the
+ * task mutation that triggered it.
+ *
+ * Design invariants (docs/MESH_PROMPT_ARCH_REVIEW_2026-07.md §9-1 G3):
+ *  - NEVER transitions the mission status. This only publishes a "consider closing"
+ *    hint; the coordinator/human decides via mesh_mission_upsert.
+ *  - Idempotent per all-terminal EDGE. The mission's close_candidate_emitted_at marker
+ *    guarantees exactly one emit per terminal transition; while the mission stays
+ *    all-terminal, subsequent calls no-op (no per-tick spam). When the mission returns
+ *    to non-terminal (a new/re-opened task), the marker is cleared so a later
+ *    re-completion nudges again.
+ *  - Only ACTIVE missions nudge. A paused/completed/abandoned mission is never a
+ *    close candidate (already decided, or intentionally on hold).
+ *
+ * Returns true iff an event was emitted on this call.
+ */
+export declare function maybeEmitMissionCloseCandidate(meshId: string, missionId: string): boolean;
+/** Active mission summaries for mesh_status / coordinator prompt injection. */
+export declare function getActiveMeshMissionSummaries(meshId: string): MeshMissionSummary[];
+/**
+ * Mission summaries for the mesh_status dashboard surface: every active/paused
+ * mission plus a capped, newest-first slice of completed/abandoned history so
+ * the dashboard can render a collapsible "history" section without unbounded
+ * payload growth. Returned newest-first within each group (active/paused first,
+ * then history), so the frontend can split on `status` directly.
+ *
+ * Compact mode (the default) elides each mission's full `goal` text — which is
+ * repeated verbatim on every status poll and dominates the payload when a mesh
+ * has many missions — returning only a short `goalPreview` + `goalTruncated`
+ * flag. Pass `verbose: true` to get the full `goal` text per mission. The stored
+ * goal is untouched in both modes; this is an output-only projection.
+ */
+export declare function getMeshStatusMissionSummaries(meshId: string, options?: {
+    historyLimit?: number;
+    verbose?: boolean;
+    withStats?: boolean;
+}): MeshMissionSummary[] | MeshMissionSlimSummary[];
+/** Folded completed/abandoned history for the mesh_status compact surface. */
+export interface MeshStatusMissionsHistoryFold {
+    /** Total completed + abandoned missions. */
+    count: number;
+    /** Count by lifecycle status (e.g. { completed, abandoned }). */
+    byStatus: Record<string, number>;
+    /** Newest-first id list (capped) so each folded mission stays addressable. */
+    missionIds: string[];
+    note: string;
+}
+/** Compact mesh_status mission projection: live detail + folded history. */
+export interface MeshStatusMissionsCompact {
+    /**
+     * Active + paused missions, goal-elided to COMPACT_STATUS_GOAL_PREVIEW_MAX and
+     * WITHOUT the operational `stats` rollup — the `tasks` aggregate already carries
+     * progress, and stats (durations/retries) is a verbose/dashboard concern.
+     */
+    live: MeshMissionSlimSummary[];
+    /** Completed + abandoned missions folded to counts + ids; null when none. */
+    historyFold: MeshStatusMissionsHistoryFold | null;
+}
+/**
+ * Mission projection for the mesh_status COMPACT (LLM coordinator) surface.
+ *
+ * Unlike getMeshStatusMissionSummaries (which emits every live mission plus a
+ * capped slice of full-detail history, each carrying a stats rollup), this keeps
+ * per-mission detail ONLY for live (active/paused) missions and folds the whole
+ * completed/abandoned history into a counts + id-list summary. Combined with the
+ * tighter goal preview and dropped stats, this is what keeps the compact
+ * mesh_status payload bounded as a mesh accumulates missions — the missions
+ * section previously dominated the payload (full goalPreview + tasks + stats per
+ * mission, for every live mission and up to 10 history missions, on every poll).
+ *
+ * The stored missions are untouched; this is an output-only projection. Full
+ * mission detail (goal text + stats + history) stays available via
+ * mesh_status verbose=true or mesh_mission_list.
+ */
+export declare function getMeshStatusMissionsCompact(meshId: string, options?: {
+    previewMax?: number;
+    historyIdLimit?: number;
+}): MeshStatusMissionsCompact;
+/**
+ * Read-only mission listing for the mesh_mission_list tool. Returns summaries
+ * (record + live task aggregate) for missions matching `statuses` — or every
+ * mission when `statuses` is omitted/empty — newest-first by updatedAt. Unlike
+ * getMeshStatusMissionSummaries this does NOT cap or group by lifecycle, so a
+ * coordinator can deliberately surface paused/abandoned/completed missions that
+ * the live status view would hide or truncate.
+ *
+ * MAGI bounding: by default this EXCLUDES completed MAGI missions (source==='magi'
+ * && status==='completed') — a mesh_magi_review fan-out auto-creates one inline
+ * mission per run and auto-closes it on collection, so without this they accumulate
+ * unbounded and drown out coordinator missions in the list. In-progress MAGI missions
+ * (active/paused) are still shown so a running cross-verification stays visible. Pass
+ * `includeMagi: true` to return every mission including completed MAGI ones. A mission
+ * with no `source` (legacy / coordinator) is never affected.
+ *
+ * Compact (the default) elides each goal to a capped preview + goalTruncated
+ * flag; verbose returns the full goal text. The stored goal is never mutated.
+ */
+export declare function listMeshMissionSummaries(meshId: string, options?: {
+    statuses?: MeshMissionStatus[];
+    verbose?: boolean;
+    includeMagi?: boolean;
+}): MeshMissionSummary[] | MeshMissionSlimSummary[];
+/**
+ * M3-3: render active missions as a prompt section for {{mission}}.
+ * Empty string when no active mission — the prompt stays byte-identical to
+ * the pre-M3 output in that case (regression guarantee).
+ */
+export declare function buildMissionPromptSection(meshId: string): string;