recallnest 1.4.1

package/src/version-manager.ts

@@ -0,0 +1,172 @@
+/**
+ * Version Manager — Tier 3.3
+ *
+ * Replaces the "archive loser" SUPERSEDE model with version coexistence:
+ * - Entries that would have been merged are instead grouped by version_group
+ * - Each version has a rank (confidence × log1p(accessCount + 1))
+ * - During retrieval, only the top-ranked version per group is returned
+ * - All versions remain in DB for history/audit
+ *
+ * Brain science inspiration: Imprint Competition — competing memory traces
+ * can coexist; the stronger one dominates recall but the weaker remains
+ * available for re-evaluation.
+ */
+
+import type { MemoryEntry, MemoryStore } from "./store.js";
+import { logInfo } from "./stderr-log.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface VersionGroupMetadata {
+  /** Shared UUID for all versions in this group */
+  version_group: string;
+  /** Rank within group (higher = preferred for retrieval) */
+  version_rank: number;
+  /** When this version was created/grouped */
+  version_created: string;
+}
+
+// ============================================================================
+// Core Functions
+// ============================================================================
+
+/**
+ * Create a version group from two entries that would otherwise be merged.
+ * Instead of archiving the weaker one, both get tagged with the same group.
+ *
+ * @param store      Memory store
+ * @param canonical  The stronger entry (higher canonicalScore)
+ * @param member     The weaker entry
+ * @param scope      Scope filter for updates
+ * @returns The version_group ID
+ */
+export async function createVersionGroup(
+  store: MemoryStore,
+  canonical: MemoryEntry,
+  member: MemoryEntry,
+  scope: string,
+): Promise<string> {
+  // Check if canonical already has a version_group
+  const canonMeta = parseMetadata(canonical.metadata);
+  const existingGroup = typeof canonMeta.version_group === "string" ? canonMeta.version_group : null;
+  const groupId = existingGroup ?? generateGroupId();
+  const now = new Date().toISOString();
+
+  // Update canonical
+  const canonRank = computeVersionRank(canonical);
+  canonMeta.version_group = groupId;
+  canonMeta.version_rank = canonRank;
+  if (!canonMeta.version_created) canonMeta.version_created = now;
+  await store.update(canonical.id, { metadata: JSON.stringify(canonMeta) }, [scope]);
+
+  // Update member
+  const memberMeta = parseMetadata(member.metadata);
+  const memberRank = computeVersionRank(member);
+  memberMeta.version_group = groupId;
+  memberMeta.version_rank = memberRank;
+  memberMeta.version_created = now;
+  await store.update(member.id, { metadata: JSON.stringify(memberMeta) }, [scope]);
+
+  logInfo(
+    `[INFO] Version group ${groupId.slice(0, 8)}: ` +
+    `${canonical.id.slice(0, 8)} (rank=${canonRank.toFixed(2)}) + ` +
+    `${member.id.slice(0, 8)} (rank=${memberRank.toFixed(2)})`,
+  );
+
+  return groupId;
+}
+
+/**
+ * Compute version rank for an entry.
+ * Formula: (0.5 * importance + 0.5 * confidence) × (1 + log1p(accessCount))
+ * Combines both importance (from extraction) and confidence (from user feedback)
+ * with access frequency to determine which version wins.
+ * Higher = preferred for retrieval.
+ */
+export function computeVersionRank(entry: MemoryEntry): number {
+  const meta = parseMetadata(entry.metadata);
+  const confidence = typeof meta.confidence === "number" ? meta.confidence : 0.7;
+  const accessCount = typeof meta.accessCount === "number" ? meta.accessCount : 0;
+  const importance = typeof entry.importance === "number" ? entry.importance : 0.5;
+  const quality = 0.5 * importance + 0.5 * confidence;
+  return quality * (1 + Math.log1p(accessCount));
+}
+
+/**
+ * Deduplicate retrieval results by version group.
+ * For each version_group, keep only the entry with the highest version_rank.
+ * Entries without a version_group pass through unchanged.
+ *
+ * @param results  Array of retrieval results (must have entry.metadata)
+ * @returns Filtered array with at most one entry per version group
+ */
+export function deduplicateByVersionGroup<T extends { entry: MemoryEntry; score: number }>(
+  results: T[],
+): T[] {
+  // First pass: find the best entry per version group
+  const groupBest = new Map<string, T>();
+
+  for (const r of results) {
+    const meta = parseMetadata(r.entry.metadata);
+    const group = typeof meta.version_group === "string" ? meta.version_group : null;
+    if (!group) continue;
+
+    const existing = groupBest.get(group);
+    if (!existing) {
+      groupBest.set(group, r);
+    } else {
+      const existingRank = getVersionRank(existing.entry);
+      const newRank = getVersionRank(r.entry);
+      if (newRank > existingRank) {
+        groupBest.set(group, r);
+      }
+    }
+  }
+
+  // Second pass: emit results preserving order, replacing groups with their winner
+  const groupWinnerIds = new Set([...groupBest.values()].map(r => r.entry.id));
+  const seenGroups = new Set<string>();
+  const output: T[] = [];
+
+  for (const r of results) {
+    const meta = parseMetadata(r.entry.metadata);
+    const group = typeof meta.version_group === "string" ? meta.version_group : null;
+
+    if (!group) {
+      // No version group → pass through
+      output.push(r);
+    } else if (!seenGroups.has(group) && groupWinnerIds.has(r.entry.id)) {
+      // First appearance of this group's winner
+      output.push(r);
+      seenGroups.add(group);
+    }
+    // Skip non-winners and duplicate group appearances
+  }
+
+  return output;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function getVersionRank(entry: MemoryEntry): number {
+  const meta = parseMetadata(entry.metadata);
+  return typeof meta.version_rank === "number" ? meta.version_rank : computeVersionRank(entry);
+}
+
+function parseMetadata(raw?: string): Record<string, unknown> {
+  try {
+    return JSON.parse(raw || "{}") as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+function generateGroupId(): string {
+  // Simple UUID v4-like (no crypto needed for grouping)
+  const hex = () => Math.random().toString(16).slice(2, 6);
+  return `vg-${hex()}${hex()}`;
+}

package/src/workflow-observation-engine.ts

@@ -0,0 +1,316 @@
+import { randomUUID } from "node:crypto";
+
+import type {
+  WorkflowEvidencePack,
+  WorkflowHealthDashboardItem,
+  WorkflowHealthReport,
+  WorkflowHealthWindow,
+  WorkflowObservationInput,
+  WorkflowObservationOutcome,
+  WorkflowObservationRecord,
+} from "./workflow-observation-schema.js";
+import { WorkflowObservationInputSchema, WorkflowObservationRecordSchema } from "./workflow-observation-schema.js";
+import type { WorkflowObservationStore } from "./workflow-observation-store.js";
+
+const DEFAULT_WINDOWS = [7, 30] as const;
+const MAX_OBSERVATIONS_FOR_ANALYSIS = 1000;
+const ISSUE_OUTCOMES: WorkflowObservationOutcome[] = ["failure", "corrected", "missed"];
+
+function pct(value: number): string {
+  return `${Math.round(value * 100)}%`;
+}
+
+function countBySignal(records: WorkflowObservationRecord[]): Array<{ signal: string; count: number }> {
+  const counts = new Map<string, number>();
+  for (const record of records) {
+    const key = record.signal?.trim();
+    if (!key) continue;
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([signal, count]) => ({ signal, count }))
+    .sort((a, b) => b.count - a.count || a.signal.localeCompare(b.signal))
+    .slice(0, 3);
+}
+
+function summarizeWindow(days: number, records: WorkflowObservationRecord[], nowMs: number): WorkflowHealthWindow {
+  const cutoff = nowMs - days * 24 * 60 * 60 * 1000;
+  const scoped = records.filter((record) => Date.parse(record.recordedAt) >= cutoff);
+  const total = scoped.length;
+  const successes = scoped.filter((record) => record.outcome === "success").length;
+  const failures = scoped.filter((record) => record.outcome === "failure").length;
+  const corrected = scoped.filter((record) => record.outcome === "corrected").length;
+  const missed = scoped.filter((record) => record.outcome === "missed").length;
+  const issueCount = failures + corrected + missed;
+  const latestAt = scoped[0]?.recordedAt;
+
+  return {
+    days,
+    total,
+    successes,
+    failures,
+    corrected,
+    missed,
+    issueCount,
+    successRate: total > 0 ? successes / total : 0,
+    issueRate: total > 0 ? issueCount / total : 0,
+    latestAt,
+    topSignals: countBySignal(scoped.filter((record) => ISSUE_OUTCOMES.includes(record.outcome))),
+  };
+}
+
+function deriveStatus(window30: WorkflowHealthWindow): WorkflowHealthReport["status"] {
+  if (window30.total === 0) return "no-data";
+  if (
+    window30.failures >= 1 ||
+    window30.missed >= 2 ||
+    window30.issueCount >= 3 ||
+    (window30.total >= 4 && window30.successRate < 0.5)
+  ) {
+    return "critical";
+  }
+  if (
+    window30.issueCount >= 1 ||
+    window30.successRate < 0.75
+  ) {
+    return "watch";
+  }
+  return "healthy";
+}
+
+function buildHealthSummary(workflowId: string, status: WorkflowHealthReport["status"], window30: WorkflowHealthWindow): string {
+  if (status === "no-data") {
+    return `No workflow observations recorded yet for ${workflowId}.`;
+  }
+  const signalText = window30.topSignals.length > 0
+    ? ` Top issues: ${window30.topSignals.map((item) => `${item.signal} (${item.count})`).join(", ")}.`
+    : "";
+  return `${workflowId} is ${status} over 30d: ${window30.total} observations, ${pct(window30.successRate)} success, ${window30.issueCount} issues.${signalText}`;
+}
+
+function uniqueStrings(values: string[]): string[] {
+  const deduped: string[] = [];
+  const seen = new Set<string>();
+  for (const value of values) {
+    const normalized = value.trim();
+    if (!normalized) continue;
+    const key = normalized.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(normalized);
+  }
+  return deduped;
+}
+
+function buildEvidenceSuggestions(
+  workflowId: string,
+  records: WorkflowObservationRecord[],
+  health: WorkflowHealthReport,
+): string[] {
+  const window30 = health.windows.find((window) => window.days === 30) || health.windows[health.windows.length - 1];
+  if (!window30 || window30.total === 0) {
+    return [
+      `Start recording ${workflowId} outcomes in real tasks before automating proactive alerts.`,
+    ];
+  }
+
+  const suggestions: string[] = [];
+  if (window30.missed > 0) {
+    suggestions.push("Tighten trigger coverage so this workflow fires before repo exploration or user correction.");
+  }
+  if (window30.corrected > 0) {
+    suggestions.push("Review recurring user corrections and turn them into explicit guardrails or narrower response rules.");
+  }
+  if (window30.failures > 0) {
+    suggestions.push("Add a regression test or smoke case that reproduces the failing path.");
+  }
+  if (window30.topSignals.some((item) => /repo-state|git status|checkpoint/i.test(item.signal))) {
+    suggestions.push("Keep volatile repo-state text out of saved checkpoints and handoff summaries unless this window verified it.");
+  }
+  if (workflowId === "resume_context" && window30.issueCount > 0) {
+    suggestions.push("Strengthen fresh-window continuity triggers and acceptance smoke for startup recovery.");
+  }
+  if (workflowId === "checkpoint_session" && window30.issueCount > 0) {
+    suggestions.push("Add end-of-window guards so checkpoint content is sanitized before it becomes the next handoff.");
+  }
+  if (window30.total < 4) {
+    suggestions.push("Collect a few more observations before changing thresholds or automating proactive advice.");
+  }
+
+  return uniqueStrings(suggestions).slice(0, 4);
+}
+
+export function resolveWorkflowObservationScope(input: Pick<WorkflowObservationInput, "scope">): string {
+  return input.scope || "global";
+}
+
+export function buildWorkflowObservationRecord(rawInput: unknown): WorkflowObservationRecord {
+  const input = WorkflowObservationInputSchema.parse(rawInput);
+  return WorkflowObservationRecordSchema.parse({
+    ...input,
+    observationId: randomUUID(),
+    resolvedScope: resolveWorkflowObservationScope(input),
+  });
+}
+
+export function summarizeWorkflowHealthRecords(
+  workflowId: string,
+  records: WorkflowObservationRecord[],
+  options: { scope?: string; now?: Date | number; windows?: number[] } = {},
+): WorkflowHealthReport {
+  const nowMs = options.now instanceof Date
+    ? options.now.getTime()
+    : typeof options.now === "number"
+      ? options.now
+      : Date.now();
+  const windows = (options.windows && options.windows.length > 0 ? options.windows : [...DEFAULT_WINDOWS])
+    .map((value) => Math.max(1, Math.trunc(value)));
+  const filtered = records
+    .filter((record) => record.workflowId === workflowId)
+    .filter((record) => !options.scope || record.resolvedScope === options.scope)
+    .sort((a, b) => Date.parse(b.recordedAt) - Date.parse(a.recordedAt));
+
+  const summarized = windows.map((days) => summarizeWindow(days, filtered, nowMs));
+  const primary = summarized.find((window) => window.days === 30) || summarized[summarized.length - 1];
+  const status = deriveStatus(primary);
+
+  return {
+    workflowId,
+    scope: options.scope,
+    status,
+    summary: buildHealthSummary(workflowId, status, primary),
+    latestObservationAt: filtered[0]?.recordedAt,
+    windows: summarized,
+  };
+}
+
+export function buildWorkflowHealthDashboard(
+  records: WorkflowObservationRecord[],
+  options: { scope?: string; limit?: number; now?: Date | number } = {},
+): WorkflowHealthDashboardItem[] {
+  const grouped = new Map<string, WorkflowObservationRecord[]>();
+  for (const record of records) {
+    if (options.scope && record.resolvedScope !== options.scope) continue;
+    const key = options.scope ? record.workflowId : `${record.resolvedScope}::${record.workflowId}`;
+    const bucket = grouped.get(key) || [];
+    bucket.push(record);
+    grouped.set(key, bucket);
+  }
+
+  const items = [...grouped.values()].map((bucket) => {
+    const workflowId = bucket[0].workflowId;
+    const scope = options.scope || bucket[0].resolvedScope;
+    const report = summarizeWorkflowHealthRecords(workflowId, bucket, {
+      scope,
+      now: options.now,
+    });
+    const primary = report.windows.find((window) => window.days === 30) || report.windows[report.windows.length - 1];
+    return {
+      workflowId,
+      scope,
+      status: report.status,
+      total: primary.total,
+      issueCount: primary.issueCount,
+      successRate: primary.successRate,
+      latestObservationAt: report.latestObservationAt,
+      summary: report.summary,
+    } satisfies WorkflowHealthDashboardItem;
+  });
+
+  const priority = { critical: 0, watch: 1, healthy: 2, "no-data": 3 } as const;
+  const limit = options.limit || 10;
+  return items
+    .sort((a, b) => {
+      const byStatus = priority[a.status] - priority[b.status];
+      if (byStatus !== 0) return byStatus;
+      const byIssues = b.issueCount - a.issueCount;
+      if (byIssues !== 0) return byIssues;
+      return (Date.parse(b.latestObservationAt || "1970-01-01T00:00:00.000Z") -
+        Date.parse(a.latestObservationAt || "1970-01-01T00:00:00.000Z"));
+    })
+    .slice(0, limit);
+}
+
+export function generateWorkflowEvidencePack(
+  workflowId: string,
+  records: WorkflowObservationRecord[],
+  options: { scope?: string; now?: Date | number; limit?: number } = {},
+): WorkflowEvidencePack {
+  const filtered = records
+    .filter((record) => record.workflowId === workflowId)
+    .filter((record) => !options.scope || record.resolvedScope === options.scope)
+    .sort((a, b) => Date.parse(b.recordedAt) - Date.parse(a.recordedAt));
+  const health = summarizeWorkflowHealthRecords(workflowId, filtered, {
+    scope: options.scope,
+    now: options.now,
+  });
+  const issues = filtered
+    .filter((record) => ISSUE_OUTCOMES.includes(record.outcome))
+    .slice(0, options.limit || 5)
+    .map((record) => ({
+      observationId: record.observationId,
+      outcome: record.outcome,
+      summary: record.summary,
+      signal: record.signal,
+      recordedAt: record.recordedAt,
+      task: record.task,
+    }));
+  const issueRecords = filtered.filter((record) => ISSUE_OUTCOMES.includes(record.outcome));
+  const suggestions = buildEvidenceSuggestions(workflowId, issueRecords, health);
+  const topSignals = countBySignal(issueRecords);
+  const summary = issues.length === 0
+    ? `No issue observations recorded yet for ${workflowId}.`
+    : `${workflowId} has ${issues.length} recent issue observation(s) ready for review.`;
+
+  return {
+    workflowId,
+    scope: options.scope,
+    generatedAt: new Date(
+      options.now instanceof Date
+        ? options.now.getTime()
+        : typeof options.now === "number"
+          ? options.now
+          : Date.now(),
+    ).toISOString(),
+    summary,
+    health,
+    topSignals,
+    recentIssues: issues,
+    suggestions,
+  };
+}
+
+export async function inspectWorkflowHealth(
+  store: WorkflowObservationStore,
+  params: { workflowId: string; scope?: string; now?: Date | number },
+): Promise<WorkflowHealthReport> {
+  const records = await store.listRecent({
+    workflowId: params.workflowId,
+    scope: params.scope,
+    limit: MAX_OBSERVATIONS_FOR_ANALYSIS,
+  });
+  return summarizeWorkflowHealthRecords(params.workflowId, records, params);
+}
+
+export async function inspectWorkflowDashboard(
+  store: WorkflowObservationStore,
+  params: { scope?: string; limit?: number; now?: Date | number } = {},
+): Promise<WorkflowHealthDashboardItem[]> {
+  const records = await store.listRecent({
+    scope: params.scope,
+    limit: MAX_OBSERVATIONS_FOR_ANALYSIS,
+  });
+  return buildWorkflowHealthDashboard(records, params);
+}
+
+export async function buildWorkflowEvidence(
+  store: WorkflowObservationStore,
+  params: { workflowId: string; scope?: string; limit?: number; now?: Date | number },
+): Promise<WorkflowEvidencePack> {
+  const records = await store.listRecent({
+    workflowId: params.workflowId,
+    scope: params.scope,
+    limit: MAX_OBSERVATIONS_FOR_ANALYSIS,
+  });
+  return generateWorkflowEvidencePack(params.workflowId, records, params);
+}

package/src/workflow-observation-managed.ts

@@ -0,0 +1,83 @@
+import type { ResumeContextRequest, ResumeContextResponse } from "./session-schema.js";
+import type { SessionCheckpointBuildResult } from "./session-engine.js";
+import type { WorkflowObservationInput } from "./workflow-observation-schema.js";
+
+const MANAGED_SOURCE = "managed";
+const MANAGED_TAGS = ["continuity", "managed"];
+
+function dedupeTags(tags: string[]): string[] {
+  const seen = new Set<string>();
+  const deduped: string[] = [];
+  for (const tag of tags) {
+    const normalized = tag.trim().toLowerCase();
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    deduped.push(normalized);
+  }
+  return deduped;
+}
+
+function resolveObservationScope(
+  request: Pick<ResumeContextRequest, "scope" | "sessionId">,
+  response?: Pick<ResumeContextResponse, "resolvedScope" | "latestCheckpoint">,
+): string | undefined {
+  return request.scope
+    || (request.sessionId ? `session:${request.sessionId}` : undefined)
+    || response?.resolvedScope
+    || response?.latestCheckpoint?.resolvedScope;
+}
+
+export function buildManagedResumeObservation(
+  request: Pick<ResumeContextRequest, "scope" | "sessionId" | "task">,
+  response: Pick<ResumeContextResponse, "stableContext" | "relevantPatterns" | "recentCases" | "latestCheckpoint" | "responseMode" | "resolvedScope">,
+): WorkflowObservationInput {
+  const stableCount = response.stableContext.length;
+  const patternCount = response.relevantPatterns.length;
+  const caseCount = response.recentCases.length;
+  const checkpointText = response.latestCheckpoint ? " plus the latest checkpoint" : "";
+  return {
+    workflowId: "resume_context",
+    outcome: "success",
+    summary: response.responseMode === "recall-only"
+      ? `Managed resume_context recovered ${stableCount} stable item(s) in recall-only mode${checkpointText}.`
+      : `Managed resume_context recovered ${stableCount} stable item(s), ${patternCount} pattern(s), and ${caseCount} case(s)${checkpointText}.`,
+    scope: resolveObservationScope(request, response),
+    source: MANAGED_SOURCE,
+    signal: response.responseMode === "recall-only" ? "managed-recall-resolved" : "managed-resume-resolved",
+    task: request.task,
+    tags: dedupeTags([
+      ...MANAGED_TAGS,
+      response.responseMode === "recall-only" ? "recall-only" : "startup-recovery",
+    ]),
+    tools: ["resume_context"],
+  };
+}
+
+function formatCheckpointFieldList(fields: string[]): string {
+  if (fields.length === 1) return fields[0];
+  if (fields.length === 2) return `${fields[0]} and ${fields[1]}`;
+  return `${fields.slice(0, -1).join(", ")}, and ${fields[fields.length - 1]}`;
+}
+
+export function buildManagedCheckpointObservation(
+  result: SessionCheckpointBuildResult,
+): WorkflowObservationInput {
+  const corrected = result.sanitization.changed;
+  const fieldText = formatCheckpointFieldList(result.sanitization.changedFields);
+  return {
+    workflowId: "checkpoint_session",
+    outcome: corrected ? "corrected" : "success",
+    summary: corrected
+      ? `Managed checkpoint_session sanitized repo-state text out of ${fieldText} before saving the handoff.`
+      : "Managed checkpoint_session saved a handoff without repo-state corrections.",
+    scope: result.record.resolvedScope,
+    source: MANAGED_SOURCE,
+    signal: corrected ? "repo-state-sanitized" : "checkpoint-saved",
+    task: result.record.task,
+    tags: dedupeTags([
+      ...MANAGED_TAGS,
+      corrected ? "sanitized" : "handoff-saved",
+    ]),
+    tools: ["checkpoint_session"],
+  };
+}

package/src/workflow-observation-output.ts

@@ -0,0 +1,86 @@
+import type {
+  WorkflowEvidencePack,
+  WorkflowHealthDashboardItem,
+  WorkflowHealthReport,
+  WorkflowObservationRecord,
+} from "./workflow-observation-schema.js";
+
+function pct(value: number): string {
+  return `${Math.round(value * 100)}%`;
+}
+
+export function formatWorkflowObservationSaved(record: WorkflowObservationRecord): string {
+  const lines = [
+    `Workflow observation ${record.observationId.slice(0, 8)}`,
+    `Workflow: ${record.workflowId}`,
+    `Outcome: ${record.outcome}`,
+    `Scope: ${record.resolvedScope}`,
+    `Source: ${record.source}`,
+    `Recorded: ${record.recordedAt}`,
+    `Summary: ${record.summary}`,
+  ];
+  if (record.signal) lines.push(`Signal: ${record.signal}`);
+  if (record.task) lines.push(`Task: ${record.task}`);
+  if (record.tools.length > 0) lines.push(`Tools: ${record.tools.join(", ")}`);
+  return lines.join("\n");
+}
+
+export function formatWorkflowHealthReport(report: WorkflowHealthReport): string {
+  const lines = [
+    `Workflow health: ${report.workflowId}`,
+    `Scope: ${report.scope || "all"}`,
+    `Status: ${report.status}`,
+    `Summary: ${report.summary}`,
+  ];
+  if (report.latestObservationAt) lines.push(`Latest: ${report.latestObservationAt}`);
+  for (const window of report.windows) {
+    lines.push(
+      `${window.days}d: total ${window.total}, success ${pct(window.successRate)}, issues ${window.issueCount} (${window.failures} failure / ${window.corrected} corrected / ${window.missed} missed)`,
+    );
+    if (window.topSignals.length > 0) {
+      lines.push(`Top signals: ${window.topSignals.map((item) => `${item.signal} (${item.count})`).join(", ")}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export function formatWorkflowHealthDashboard(items: WorkflowHealthDashboardItem[], scope?: string): string {
+  if (items.length === 0) {
+    return `No workflow observations found${scope ? ` in ${scope}` : ""}.`;
+  }
+  return [
+    `Workflow health dashboard${scope ? ` (${scope})` : ""}`,
+    ...items.map((item, index) =>
+      `${index + 1}. [${item.status}] ${item.workflowId}${item.scope ? ` @ ${item.scope}` : ""} — ${item.total} obs, ${pct(item.successRate)} success, ${item.issueCount} issues`,
+    ),
+  ].join("\n");
+}
+
+export function formatWorkflowEvidencePack(pack: WorkflowEvidencePack): string {
+  const lines = [
+    `Workflow evidence: ${pack.workflowId}`,
+    `Scope: ${pack.scope || "all"}`,
+    `Generated: ${pack.generatedAt}`,
+    `Summary: ${pack.summary}`,
+    `Health: ${pack.health.summary}`,
+  ];
+  if (pack.topSignals.length > 0) {
+    lines.push(`Top signals: ${pack.topSignals.map((item) => `${item.signal} (${item.count})`).join(", ")}`);
+  }
+  if (pack.recentIssues.length > 0) {
+    lines.push("Recent issues:");
+    for (const issue of pack.recentIssues) {
+      lines.push(
+        `- ${issue.recordedAt.slice(0, 10)} [${issue.outcome}] ${issue.signal ? `${issue.signal}: ` : ""}${issue.summary}`,
+      );
+    }
+  }
+  if (pack.suggestions.length > 0) {
+    lines.push("Suggestions:");
+    for (const suggestion of pack.suggestions) {
+      lines.push(`- ${suggestion}`);
+    }
+  }
+  return lines.join("\n");
+}
+