@adhdev/daemon-core 0.9.82-rc.43 → 0.9.82-rc.430

package/src/mesh/mesh-magi-status.ts

@@ -0,0 +1,223 @@
+// MAGI (Multi-Agent Ground-truth Insight) activity reconstruction for mesh_status.
+//
+// MAGI cross-verification runs are persisted in the mesh ledger as `magi_dispatched`
+// (fan-out enqueued) and `magi_synthesis` (collected + synthesized) entries, keyed by
+// consensusGroupId. This module reconstructs the latest per-group activity from a
+// ledger window and folds it into a BOUNDED mesh_status section so a coordinator (and
+// the web dashboard's extractMagiActivity) can read the synthesis fields — the
+// needs_verification counts, independence banner, and git skew — without re-running
+// collection. Mirrors mesh-refine-status.ts (buildMeshAsyncRefineJobs / summarize…).
+//
+// Pure: operates on a ledger-entry array. No I/O, no Node/DOM APIs.
+
+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;
+}
+
+function readString(value: unknown): string | undefined {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value as Record<string, unknown>
+        : undefined;
+}
+
+function readNumber(value: unknown): number | undefined {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+/** Cap on inlined needs_verification preview items per group (keeps the payload bounded). */
+export const MAGI_NEEDS_VERIFICATION_PREVIEW_CAP = 8;
+
+function summarizeNeedsVerification(synthesis: Record<string, unknown> | undefined): MeshMagiNeedsVerificationItem[] | undefined {
+    const list = Array.isArray(synthesis?.needsVerification) ? synthesis!.needsVerification : undefined;
+    if (!list) return undefined;
+    const items: MeshMagiNeedsVerificationItem[] = [];
+    for (const raw of list.slice(0, MAGI_NEEDS_VERIFICATION_PREVIEW_CAP)) {
+        const r = readRecord(raw);
+        const claim = readString(r?.claim);
+        if (!claim) continue;
+        items.push({ claim, category: readString(r?.category) || 'needs_verification' });
+    }
+    return items;
+}
+
+function mergeGroup(
+    groups: Map<string, MeshMagiActivitySummary>,
+    patch: Partial<MeshMagiActivitySummary> & { consensusGroupId?: string },
+): void {
+    const consensusGroupId = readString(patch.consensusGroupId);
+    if (!consensusGroupId) return;
+    const previous = groups.get(consensusGroupId);
+    // synthesized is terminal-ish and must not be downgraded back to running by an
+    // out-of-order dispatch entry.
+    const status: MeshMagiActivityStatus = patch.status === 'synthesized' || previous?.status === 'synthesized'
+        ? 'synthesized'
+        : 'running';
+    const definedPatch = Object.fromEntries(
+        Object.entries(patch).filter(([, v]) => v !== undefined),
+    ) as Partial<MeshMagiActivitySummary>;
+    groups.set(consensusGroupId, { ...previous, ...definedPatch, consensusGroupId, status });
+}
+
+/**
+ * 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 function buildMeshMagiActivity(args: {
+    meshId?: string;
+    ledgerEntries?: MeshLedgerEntry[];
+}): MeshMagiActivitySummary[] {
+    const groups = new Map<string, MeshMagiActivitySummary>();
+
+    for (const entry of args.ledgerEntries || []) {
+        const payload = readRecord(entry.payload);
+        if (payload?.source !== 'magi') continue;
+        const consensusGroupId = readString(payload.consensusGroupId);
+        if (!consensusGroupId) continue;
+
+        if (entry.kind === 'magi_synthesis') {
+            const synthesis = readRecord(payload.synthesis);
+            mergeGroup(groups, {
+                consensusGroupId,
+                status: 'synthesized',
+                missionId: readString(payload.missionId),
+                panel: readString(payload.panel),
+                question: readString(payload.question),
+                replicaCount: readNumber(synthesis?.replicasExpected) ?? readNumber(payload.replicaCount),
+                answered: readNumber(synthesis?.replicasAnswered),
+                missing: readNumber(synthesis?.replicasMissing),
+                staleReplicas: readNumber(payload.staleReplicas) ?? readNumber(synthesis?.staleReplicas),
+                needsVerificationCount: Array.isArray(synthesis?.needsVerification) ? synthesis!.needsVerification.length : undefined,
+                agreedCount: Array.isArray(synthesis?.agreed) ? synthesis!.agreed.length : undefined,
+                independenceBanner: synthesis && 'independenceBanner' in synthesis ? (synthesis.independenceBanner as string | null) : undefined,
+                gitSkew: readRecord(synthesis?.gitSkew) as unknown as MagiGitSkew | undefined,
+                needsVerification: summarizeNeedsVerification(synthesis),
+                openQuestions: Array.isArray(synthesis?.openQuestions) ? (synthesis!.openQuestions as string[]).slice(0, 10) : undefined,
+                lastLedgerKind: entry.kind,
+                lastUpdatedAt: entry.timestamp,
+            });
+        } else if (entry.kind === 'magi_dispatched') {
+            mergeGroup(groups, {
+                consensusGroupId,
+                status: 'running',
+                missionId: readString(payload.missionId),
+                panel: readString(payload.panel),
+                question: readString(payload.question),
+                replicaCount: readNumber(payload.replicaCount),
+                lastLedgerKind: entry.kind,
+                lastUpdatedAt: entry.timestamp,
+            });
+        }
+    }
+
+    return Array.from(groups.values()).sort((a, b) => {
+        const at = new Date(a.lastUpdatedAt || '').getTime();
+        const bt = new Date(b.lastUpdatedAt || '').getTime();
+        return (Number.isFinite(bt) ? bt : 0) - (Number.isFinite(at) ? at : 0);
+    });
+}
+
+/** 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 const STALE_MAGI_WINDOW_MS = 6 * 60 * 60 * 1000;
+
+/** Cap on recent synthesized groups kept in the active list even if all are fresh. */
+export 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[];
+}
+
+function activityTime(g: MeshMagiActivitySummary): number {
+    const t = new Date(g.lastUpdatedAt || '').getTime();
+    return Number.isFinite(t) ? t : 0;
+}
+
+/**
+ * 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 function summarizeMeshMagiActivity(
+    activity: MeshMagiActivitySummary[],
+): MeshMagiActivitySummaryFold {
+    const running: MeshMagiActivitySummary[] = [];
+    const synthesized: MeshMagiActivitySummary[] = [];
+    for (const g of activity) {
+        if (g.status === 'synthesized') synthesized.push(g);
+        else running.push(g);
+    }
+
+    let newest = 0;
+    for (const g of activity) newest = Math.max(newest, activityTime(g));
+    const cutoff = newest - STALE_MAGI_WINDOW_MS;
+
+    const synthesizedByRecency = [...synthesized].sort((a, b) => activityTime(b) - activityTime(a));
+    const freshSynthesized = synthesizedByRecency
+        .filter(g => activityTime(g) >= cutoff)
+        .slice(0, RECENT_MAGI_CAP);
+
+    const byStatus: Record<string, number> = {};
+    for (const g of [...running, ...freshSynthesized]) {
+        byStatus[g.status] = (byStatus[g.status] ?? 0) + 1;
+    }
+
+    // Running first (most actionable), then recent synthesized — both newest-first.
+    const runningByRecency = [...running].sort((a, b) => activityTime(b) - activityTime(a));
+    return {
+        total: running.length + freshSynthesized.length,
+        byStatus,
+        staleSynthesized: synthesized.length - freshSynthesized.length,
+        groups: [...runningByRecency, ...freshSynthesized],
+    };
+}
+
+/** Latest persisted synthesis activity for one consensusGroupId, or undefined. */
+export function getMeshMagiActivityByGroup(
+    ledgerEntries: MeshLedgerEntry[],
+    consensusGroupId: string,
+): MeshMagiActivitySummary | undefined {
+    const key = readString(consensusGroupId);
+    if (!key) return undefined;
+    return buildMeshMagiActivity({ ledgerEntries }).find(g => g.consensusGroupId === key);
+}

package/src/mesh/mesh-missions.ts

@@ -0,0 +1,449 @@
+/**
+ * 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 { randomUUID } from 'crypto';
+import { MeshRuntimeStore } from './mesh-runtime-store.js';
+import { getQueue } from './mesh-work-queue.js';
+import { computeMeshMissionStats, type MeshMissionStats } from './mesh-task-stats.js';
+import { appendLedgerEntry } from './mesh-ledger.js';
+
+/**
+ * Max chars of mission goal text written into a ledger entry payload. Mission
+ * goals can be hundreds–thousands of chars; the ledger is an append-only audit
+ * stream, so we store a bounded summary (+ a length/truncated flag) rather than
+ * the full text to keep the ledger from bloating on repeated goal rewrites.
+ */
+const LEDGER_GOAL_SUMMARY_MAX = 200;
+
+function summarizeGoalForLedger(goal: string): string {
+    return goal.length > LEDGER_GOAL_SUMMARY_MAX ? goal.slice(0, LEDGER_GOAL_SUMMARY_MAX) : goal;
+}
+
+export type MeshMissionStatus = 'active' | 'paused' | 'completed' | 'abandoned';
+
+export const MESH_MISSION_STATUSES: MeshMissionStatus[] = ['active', 'paused', 'completed', 'abandoned'];
+
+/**
+ * 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;
+    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 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 const COMPACT_STATUS_GOAL_PREVIEW_MAX = 80;
+
+function normalizeMissionStatus(value: unknown): MeshMissionStatus {
+    return MESH_MISSION_STATUSES.includes(value as MeshMissionStatus)
+        ? value as MeshMissionStatus
+        : 'active';
+}
+
+function normalizeMissionSource(value: unknown): MeshMissionSource | undefined {
+    return value === 'magi' || value === 'coordinator' ? value : undefined;
+}
+
+export function upsertMeshMission(meshId: string, input: {
+    id?: string;
+    title: string;
+    goal?: string;
+    status?: string;
+    source?: MeshMissionSource;
+}): MeshMissionRecord {
+    const title = typeof input.title === 'string' ? input.title.trim() : '';
+    if (!title) throw new Error('mission_title_required: a mission needs a non-empty title');
+    if (input.status !== undefined && !MESH_MISSION_STATUSES.includes(input.status as MeshMissionStatus)) {
+        throw new Error(`invalid_mission_status: '${input.status}' (valid: ${MESH_MISSION_STATUSES.join(', ')})`);
+    }
+    const id = typeof input.id === 'string' && input.id.trim() ? input.id.trim() : randomUUID();
+    const store = MeshRuntimeStore.getInstance();
+    const existing = store.getMission(meshId, id);
+    const prevStatus = existing ? normalizeMissionStatus(existing.status) : null;
+    const prevGoal = existing?.goal ?? '';
+    const record = {
+        id,
+        meshId,
+        title,
+        goal: typeof input.goal === 'string' ? input.goal : existing?.goal ?? '',
+        status: normalizeMissionStatus(input.status ?? existing?.status),
+        // source is write-once: only forwarded when the caller supplies one. The
+        // store COALESCEs it against the existing value, so a later status/goal
+        // upsert that omits source never clears a previously-stamped tag.
+        ...(input.source ? { source: input.source } : {}),
+    };
+    store.upsertMission(record);
+    const saved = store.getMission(meshId, id)!;
+    const result: MeshMissionRecord = {
+        ...saved,
+        status: normalizeMissionStatus(saved.status),
+        source: normalizeMissionSource(saved.source),
+    };
+
+    // Mission audit trail: record this mutation in the mesh ledger so mission
+    // lifecycle (create, goal rewrite, status transition) is auditable alongside
+    // task events and survives a coordinator restart. Best-effort: a ledger
+    // failure must never break the primary mission write.
+    appendMissionLedgerEntries(meshId, {
+        isCreate: !existing,
+        record: result,
+        prevStatus,
+        prevGoal,
+    });
+
+    return result;
+}
+
+/**
+ * Append the relevant ledger entries for a mission upsert. Emits at most one
+ * entry per distinct change:
+ *  - new mission                       → mission_created
+ *  - status differs from prior         → mission_status_changed
+ *  - goal text differs from prior      → mission_goal_updated (no-op rewrites skipped)
+ */
+function appendMissionLedgerEntries(
+    meshId: string,
+    args: { isCreate: boolean; record: MeshMissionRecord; prevStatus: MeshMissionStatus | null; prevGoal: string },
+): void {
+    const { isCreate, record, prevStatus, prevGoal } = args;
+    try {
+        if (isCreate) {
+            const goal = record.goal ?? '';
+            appendLedgerEntry(meshId, {
+                kind: 'mission_created',
+                payload: {
+                    missionId: record.id,
+                    title: record.title,
+                    goalSummary: summarizeGoalForLedger(goal),
+                    goalLength: goal.length,
+                    goalTruncated: goal.length > LEDGER_GOAL_SUMMARY_MAX,
+                    status: record.status,
+                },
+            });
+            return;
+        }
+        if (prevStatus !== null && prevStatus !== record.status) {
+            appendLedgerEntry(meshId, {
+                kind: 'mission_status_changed',
+                payload: {
+                    missionId: record.id,
+                    title: record.title,
+                    fromStatus: prevStatus,
+                    toStatus: record.status,
+                },
+            });
+        }
+        const nextGoal = record.goal ?? '';
+        if (nextGoal !== prevGoal) {
+            appendLedgerEntry(meshId, {
+                kind: 'mission_goal_updated',
+                payload: {
+                    missionId: record.id,
+                    title: record.title,
+                    prevGoalSummary: summarizeGoalForLedger(prevGoal),
+                    nextGoalSummary: summarizeGoalForLedger(nextGoal),
+                    prevGoalLength: prevGoal.length,
+                    nextGoalLength: nextGoal.length,
+                    goalTruncated: prevGoal.length > LEDGER_GOAL_SUMMARY_MAX || nextGoal.length > LEDGER_GOAL_SUMMARY_MAX,
+                },
+            });
+        }
+    } catch { /* audit trail is best-effort; never break the mission write */ }
+}
+
+export function getMeshMissions(meshId: string, statuses?: MeshMissionStatus[]): MeshMissionRecord[] {
+    return MeshRuntimeStore.getInstance().getMissions(meshId, statuses)
+        .map(m => ({ ...m, status: normalizeMissionStatus(m.status), source: normalizeMissionSource(m.source) }));
+}
+
+export function getMeshMission(meshId: string, missionId: string): MeshMissionRecord | null {
+    const record = MeshRuntimeStore.getInstance().getMission(meshId, missionId);
+    return record ? { ...record, status: normalizeMissionStatus(record.status), source: normalizeMissionSource(record.source) } : null;
+}
+
+/** Aggregate task statuses for a mission at query time (no stored progress). */
+export function summarizeMissionTasks(meshId: string, missionId: string): MeshMissionTaskAggregate {
+    const tasks = getQueue(meshId).filter(task => task.missionId === missionId);
+    const aggregate: MeshMissionTaskAggregate = {
+        total: tasks.length,
+        pending: 0,
+        assigned: 0,
+        completed: 0,
+        failed: 0,
+        cancelled: 0,
+        blocked: 0,
+        lastActivityAt: null,
+    };
+    for (const task of tasks) {
+        if (task.status === 'pending') aggregate.pending += 1;
+        else if (task.status === 'assigned') aggregate.assigned += 1;
+        else if (task.status === 'completed') aggregate.completed += 1;
+        else if (task.status === 'failed') aggregate.failed += 1;
+        else if (task.status === 'cancelled') aggregate.cancelled += 1;
+        if (task.status === 'pending' && task.blockedReason) aggregate.blocked += 1;
+        if (task.updatedAt && (!aggregate.lastActivityAt || task.updatedAt > aggregate.lastActivityAt)) {
+            aggregate.lastActivityAt = task.updatedAt;
+        }
+    }
+    return aggregate;
+}
+
+export function summarizeMeshMission(meshId: string, mission: MeshMissionRecord): MeshMissionSummary {
+    return { ...mission, tasks: summarizeMissionTasks(meshId, mission.id) };
+}
+
+/** Active mission summaries for mesh_status / coordinator prompt injection. */
+export function getActiveMeshMissionSummaries(meshId: string): MeshMissionSummary[] {
+    return getMeshMissions(meshId, ['active']).map(mission => summarizeMeshMission(meshId, mission));
+}
+
+/** Project a full mission summary down to the slim (goal-elided) shape. */
+function slimMissionSummary(summary: MeshMissionSummary, previewMax: number = GOAL_PREVIEW_MAX): MeshMissionSlimSummary {
+    const goal = typeof summary.goal === 'string' ? summary.goal : '';
+    const goalTruncated = goal.length > previewMax;
+    const { goal: _omitGoal, ...rest } = summary;
+    return {
+        ...rest,
+        goalPreview: goalTruncated ? goal.slice(0, previewMax) : goal,
+        goalTruncated,
+    };
+}
+
+/**
+ * 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 function getMeshStatusMissionSummaries(
+    meshId: string,
+    options?: { historyLimit?: number; verbose?: boolean; withStats?: boolean },
+): MeshMissionSummary[] | MeshMissionSlimSummary[] {
+    const historyLimit = Math.max(0, options?.historyLimit ?? 10);
+    const all = getMeshMissions(meshId);
+    const live = all.filter(m => m.status === 'active' || m.status === 'paused');
+    const history = all
+        .filter(m => m.status === 'completed' || m.status === 'abandoned')
+        .sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''))
+        .slice(0, historyLimit);
+    let full = [...live, ...history].map(mission => summarizeMeshMission(meshId, mission));
+    // Operational stats (durations / attempts) are an opt-in projection: each
+    // mission's rollup scans a bounded ledger tail, so we only compute it for
+    // the bounded set we are about to return (live + capped history), not for
+    // every mission in the mesh. The dashboard graph opts in so mission detail
+    // can show wall-clock / retries without a second round trip.
+    if (options?.withStats) {
+        full = full.map(summary => ({ ...summary, stats: computeMeshMissionStats(meshId, summary.id) }));
+    }
+    return options?.verbose ? full : full.map(summary => slimMissionSummary(summary));
+}
+
+/** 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 function getMeshStatusMissionsCompact(
+    meshId: string,
+    options?: { previewMax?: number; historyIdLimit?: number },
+): MeshStatusMissionsCompact {
+    const previewMax = Math.max(0, options?.previewMax ?? COMPACT_STATUS_GOAL_PREVIEW_MAX);
+    const historyIdLimit = Math.max(0, options?.historyIdLimit ?? 20);
+    const all = getMeshMissions(meshId);
+    const live = all
+        .filter(m => m.status === 'active' || m.status === 'paused')
+        .map(mission => slimMissionSummary(summarizeMeshMission(meshId, mission), previewMax));
+    const history = all
+        .filter(m => m.status === 'completed' || m.status === 'abandoned')
+        .sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''));
+    let historyFold: MeshStatusMissionsHistoryFold | null = null;
+    if (history.length > 0) {
+        const byStatus: Record<string, number> = {};
+        for (const m of history) byStatus[m.status] = (byStatus[m.status] ?? 0) + 1;
+        historyFold = {
+            count: history.length,
+            byStatus,
+            missionIds: history.slice(0, historyIdLimit).map(m => m.id),
+            note: 'Completed/abandoned missions are folded to counts + ids in compact mesh_status. Use mesh_mission_list or mesh_status verbose=true for their goal/task detail.',
+        };
+    }
+    return { live, historyFold };
+}
+
+/**
+ * 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 function listMeshMissionSummaries(
+    meshId: string,
+    options?: { statuses?: MeshMissionStatus[]; verbose?: boolean; includeMagi?: boolean },
+): MeshMissionSummary[] | MeshMissionSlimSummary[] {
+    const statuses = options?.statuses && options.statuses.length > 0 ? options.statuses : undefined;
+    const includeMagi = options?.includeMagi === true;
+    const missions = getMeshMissions(meshId, statuses)
+        // Bound completed-MAGI accumulation by default. Only a mission EXPLICITLY
+        // tagged source==='magi' AND completed is hidden — coordinator/legacy
+        // (source undefined) missions and in-progress MAGI missions always pass.
+        .filter(m => includeMagi || !(m.source === 'magi' && m.status === 'completed'))
+        .sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''));
+    const full = missions.map(mission => summarizeMeshMission(meshId, mission));
+    return options?.verbose ? full : full.map(summary => slimMissionSummary(summary));
+}
+
+/**
+ * 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 function buildMissionPromptSection(meshId: string): string {
+    const summaries = getActiveMeshMissionSummaries(meshId);
+    if (summaries.length === 0) return '';
+    const lines: string[] = ['## Active Mission' + (summaries.length > 1 ? 's' : '')];
+    for (const mission of summaries) {
+        const t = mission.tasks;
+        lines.push(
+            `- **${mission.title}** (id: \`${mission.id}\`)`
+            + (mission.goal ? `\n  Goal: ${mission.goal}` : '')
+            + `\n  Tasks: ${t.total} total — ${t.pending} pending (${t.blocked} blocked), ${t.assigned} assigned, ${t.completed} completed, ${t.failed} failed, ${t.cancelled} cancelled`
+            + (t.lastActivityAt ? `\n  Last activity: ${t.lastActivityAt}` : ''),
+        );
+    }
+    lines.push(
+        'Continue this mission from its current task state. Do not re-enqueue tasks that already exist — check mesh_view_queue first. '
+        + 'Update the mission with mesh_mission_upsert when its goal changes or it reaches a terminal state (completed/abandoned).',
+    );
+    return lines.join('\n');
+}