crumbtrail-node 0.1.0 → 0.2.1

package/dist/index.cjs

@@ -123,6 +123,7 @@ __export(index_exports, {
   cloudWatchEvidenceProvider: () => cloudWatchEvidenceProvider,
   cloudflareEvidenceProvider: () => cloudflareEvidenceProvider,
   compareSessions: () => compareSessions,
+  comparisonTitle: () => comparisonTitle,
   createCrumbtrailExpressErrorMiddleware: () => createCrumbtrailExpressErrorMiddleware,
   createCrumbtrailExpressMiddleware: () => createCrumbtrailExpressMiddleware,
   createServer: () => createServer,
@@ -172,6 +173,7 @@ __export(index_exports, {
   renderProviderReadme: () => renderProviderReadme,
   resolveDbRequestContext: () => resolveDbRequestContext,
   sentryEvidenceProvider: () => sentryEvidenceProvider,
+  sessionRefLabel: () => sessionRefLabel,
   signSigV4: () => signSigV4,
   splunkEvidenceProvider: () => splunkEvidenceProvider,
   splunkSearchDeepLink: () => splunkSearchDeepLink,
@@ -1298,21 +1300,139 @@ function inferIntent(evidence, commits) {
 var FUSION_SCHEMA_VERSION = "fusion.v1";
 function assembleBundle(input) {
   const evidence = rankEvidence(input.symptom, input.evidence);
-  const hypotheses = classifyHypotheses(
+  const classified = classifyHypotheses(
     input.symptom,
     input.evidence,
     input.intent
   );
   const gaps = input.gaps ?? [];
+  const located = input.located;
+  const hypotheses = classified.map((hypothesis) => {
+    const verification = deriveVerification(hypothesis, evidence);
+    return verification.length > 0 ? { ...hypothesis, verification } : hypothesis;
+  });
+  const contextCompleteness = deriveContextCompleteness(
+    evidence,
+    gaps,
+    hypotheses,
+    located
+  );
+  const escalation = deriveEscalation(contextCompleteness, hypotheses);
   return {
     schemaVersion: FUSION_SCHEMA_VERSION,
     symptom: input.symptom,
     evidence,
     opinion: { stance: "advisory", hypotheses },
     gaps,
-    directives: suggestCaptureDirectives(input.symptom, input.evidence, gaps)
+    directives: suggestCaptureDirectives(input.symptom, input.evidence, gaps),
+    contextCompleteness,
+    escalation,
+    ...located ? { located } : {}
   };
 }
+function clamp01(value) {
+  if (Number.isNaN(value)) return 0;
+  return Math.max(0, Math.min(1, value));
+}
+var COMPLETENESS_LANES = [
+  "network",
+  "db",
+  "flow",
+  "browser",
+  "env"
+];
+function deriveContextCompleteness(evidence, gaps, hypotheses, located) {
+  const lanesPresent = new Set(evidence.map((item) => item.lane));
+  const informativePresent = COMPLETENESS_LANES.filter(
+    (lane) => lanesPresent.has(lane)
+  );
+  const breadth = Math.min(1, informativePresent.length / 3);
+  const volume = Math.min(1, evidence.length / 5);
+  const top = hypotheses[0];
+  const hypothesisStrength = !top || top.kind === "inconclusive" ? 0 : top.confidence;
+  let score = 0.4 * breadth + 0.25 * volume + 0.35 * hypothesisStrength;
+  if (located) {
+    score = located.outcome === "matched" ? 0.85 * score + 0.15 * clamp01(located.confidence) : score * 0.6;
+  }
+  const hardGaps = gaps.filter((gap) => gap.kind === "source-unavailable").length;
+  const softGaps = gaps.length - hardGaps;
+  const gapPenalty = Math.min(0.5, softGaps * 0.1 + hardGaps * 0.3);
+  score = clamp01(score - gapPenalty);
+  const level = score < 0.34 ? "low" : score < 0.67 ? "medium" : "high";
+  const reasons = [];
+  const missingLanes = COMPLETENESS_LANES.filter(
+    (lane) => !lanesPresent.has(lane)
+  );
+  if (informativePresent.length === 0) {
+    reasons.push("no network/db/flow/browser/env evidence captured");
+  } else if (missingLanes.length > 0) {
+    reasons.push(`missing evidence lanes: ${missingLanes.join(", ")}`);
+  }
+  if (evidence.length > 0 && evidence.length < 3) {
+    reasons.push(`thin evidence (${evidence.length} item(s))`);
+  }
+  if (hardGaps > 0) reasons.push(`source unavailable for ${hardGaps} lane(s)`);
+  if (softGaps > 0) reasons.push(`${softGaps} evidence gap(s)`);
+  if (located?.outcome === "inconclusive") {
+    reasons.push("incident location inconclusive");
+  }
+  if (!top || top.kind === "inconclusive") {
+    reasons.push("no distinguishing hypothesis");
+  }
+  return { score, level, reasons };
+}
+function pkString(pk) {
+  return Object.keys(pk).sort().map((key) => `${key}=${String(pk[key])}`).join(", ");
+}
+function deriveVerification(hypothesis, evidence) {
+  if (hypothesis.kind === "inconclusive") return [];
+  const cited = new Set(hypothesis.evidenceIds);
+  const out = [];
+  for (const item of evidence) {
+    if (!cited.has(item.id)) continue;
+    const ref = item.ref;
+    if (item.lane === "db" && ref.table && ref.pk && Object.keys(ref.pk).length > 0) {
+      out.push({
+        observation: `row in ${ref.table} (${pkString(ref.pk)}) matches the intended post-fix state`,
+        evidenceIds: [item.id],
+        how: "db"
+      });
+    } else if (ref.requestId) {
+      const sigPart = ref.sig ? ` for signature ${ref.sig}` : "";
+      out.push({
+        observation: `request ${ref.requestId} succeeds${sigPart} on a fresh run (no error response)`,
+        evidenceIds: [item.id],
+        how: "request"
+      });
+    } else if (ref.sig) {
+      out.push({
+        observation: `error signature ${ref.sig} no longer appears in a fresh session over the same route`,
+        evidenceIds: [item.id],
+        how: "session"
+      });
+    }
+  }
+  return out;
+}
+function deriveEscalation(completeness, hypotheses) {
+  const allInconclusive = hypotheses.length > 0 && hypotheses.every((hypothesis) => hypothesis.kind === "inconclusive");
+  const recommended = completeness.level === "low" || allInconclusive;
+  if (!recommended) return { recommended: false, when: [] };
+  const when = [
+    "if you cannot reproduce the symptom via the anchored request or session, stop and request human triage \u2014 do not widen the search"
+  ];
+  if (completeness.level === "low") {
+    when.push(
+      "context is thin: confirm the missing evidence lanes before acting on the top hypothesis"
+    );
+  }
+  if (allInconclusive) {
+    when.push(
+      "no hypothesis is distinguished; treat the listed causes as equally unproven"
+    );
+  }
+  return { recommended, when };
+}
 var LANE_PRIOR = {
   db: 0.2,
   network: 0.2,
@@ -3081,6 +3201,7 @@ var SentryError = class extends Error {
     this.status = status;
     this.name = "SentryError";
   }
+  status;
 };
 function sanitizeUrl2(u) {
   try {
@@ -3494,6 +3615,8 @@ var CloudWatchError = class extends Error {
     this.target = target;
     this.name = "CloudWatchError";
   }
+  status;
+  target;
 };
 function isTransient2(error) {
   if (error instanceof CloudWatchError) {
@@ -3906,6 +4029,7 @@ var SplunkError = class extends Error {
     this.status = status;
     this.name = "SplunkError";
   }
+  status;
 };
 function sanitizeUrl3(u) {
   try {
@@ -4256,6 +4380,7 @@ var DatadogError = class extends Error {
     this.status = status;
     this.name = "DatadogError";
   }
+  status;
 };
 function sanitizeUrl4(u) {
   try {
@@ -4619,6 +4744,7 @@ var PostHogError = class extends Error {
     this.status = status;
     this.name = "PostHogError";
   }
+  status;
 };
 function sanitizeUrl5(u) {
   try {
@@ -5009,6 +5135,8 @@ var CloudflareError = class extends Error {
     this.op = op;
     this.name = "CloudflareError";
   }
+  status;
+  op;
 };
 function isTransient6(error) {
   if (error instanceof CloudflareError) {
@@ -5811,7 +5939,7 @@ function timeProximity(now, candidateTime) {
   const decay = Math.pow(0.5, ageMs / TIME_PROXIMITY_HALF_LIFE_MS);
   return { boost: TIME_PROXIMITY_WEIGHT * decay, recent: decay >= 0.5 };
 }
-function clamp01(value) {
+function clamp012(value) {
   return Math.min(1, Math.max(0, value));
 }
 function locateIncident(symptom, store, opts = {}) {
@@ -5840,7 +5968,7 @@ function locateIncident(symptom, store, opts = {}) {
       candidates.push({
         sessionId: id,
         bugId: bug.bugId,
-        confidence: clamp01(base.score + time.boost + releaseBoost),
+        confidence: clamp012(base.score + time.boost + releaseBoost),
         reasons,
         bug
       });
@@ -5986,7 +6114,20 @@ async function locateAndAssemble(symptom, store, opts = {}) {
   const adapter = await gatherAdapterEvidence(symptom, located, opts);
   const evidence = [...located.evidence, ...adapter.items];
   const gaps = located.evidence.length === 0 ? [NO_LOCATED_SESSION_GAP, ...adapter.gaps] : [...adapter.gaps];
-  const bundle = assembleBundle({ symptom, evidence, intent: [], gaps });
+  const located_ = {
+    outcome: located.match.outcome,
+    confidence: located.match.confidence,
+    method: "fuzzy",
+    ...located.match.sessionId ? { sessionId: located.match.sessionId } : {},
+    reasons: located.match.reasons
+  };
+  const bundle = assembleBundle({
+    symptom,
+    evidence,
+    intent: [],
+    gaps,
+    located: located_
+  });
   return { bundle, match: located.match, sources: adapter.sources };
 }
 
@@ -11027,6 +11168,8 @@ var AudioProcessingError = class extends Error {
     this.cause = cause;
     this.name = "AudioProcessingError";
   }
+  phase;
+  cause;
 };
 var AudioTranscriptionUnavailableError = class extends Error {
   constructor() {
@@ -12777,12 +12920,12 @@ var import_node_fs10 = __toESM(require("fs"), 1);
 // package.json
 var package_default = {
   name: "crumbtrail-node",
-  version: "0.1.0",
+  version: "0.2.1",
   description: "Local Crumbtrail server, MCP evidence tools, Express middleware, and CLI for self-hosted debugging sessions.",
   license: "MIT",
   repository: {
     type: "git",
-    url: "https://github.com/oshabana/crumbtrail.git",
+    url: "git+https://github.com/crumbtrail-dev/crumbtrail-js.git",
     directory: "packages/node"
   },
   keywords: [
@@ -12835,6 +12978,10 @@ var package_default = {
     "@types/node": "^25.5.0",
     express: "^5.2.1",
     typescript: "^5.7.0"
+  },
+  homepage: "https://github.com/crumbtrail-dev/crumbtrail-js/tree/main/packages/node#readme",
+  bugs: {
+    url: "https://github.com/crumbtrail-dev/crumbtrail-js/issues"
   }
 };
 
@@ -13485,6 +13632,10 @@ var RequestValidationError = class extends Error {
     this.retryable = retryable;
     this.name = "RequestValidationError";
   }
+  status;
+  publicMessage;
+  code;
+  retryable;
 };
 function serveStatic(res, staticDir, urlPath) {
   const resolved = resolveStaticPath(staticDir, urlPath);
@@ -14214,6 +14365,7 @@ var BoundedTraceSessionCache = class {
   constructor(maxEntries) {
     this.maxEntries = maxEntries;
   }
+  maxEntries;
   entries = /* @__PURE__ */ new Map();
   get(traceId) {
     const existing = this.entries.get(traceId);
@@ -14912,6 +15064,20 @@ function createServer(config) {
     });
     server.on("close", () => sweeper.stop());
   }
+  if (config.ai?.enabled && config.ai.backfillOnStart) {
+    const sessionDirs = sessions.listSummaries().map((summary) => sessions.getExistingSessionDir(summary.id)).filter((dir) => dir !== void 0);
+    const timer = setTimeout(() => {
+      void backfillAiDiagnoses(
+        sessionDirs,
+        config.ai
+      ).then(
+        (result) => config.ai?.log?.(
+          `Crumbtrail AI diagnosis backfill complete: ${JSON.stringify(result)}`
+        )
+      );
+    }, 0);
+    server.on("close", () => clearTimeout(timer));
+  }
   if (fastFinalizer) {
     server.on("close", () => fastFinalizer.stop());
   }
@@ -14961,6 +15127,7 @@ var FixContextError = class extends Error {
     this.code = code2;
     this.name = "FixContextError";
   }
+  code;
 };
 function buildFixContext(sessionDirOrId, opts = {}) {
   const sessionDir = resolveSessionDir(sessionDirOrId, opts);
@@ -16020,16 +16187,85 @@ function diffEnvironment(a, b, rules, disabled) {
       addSuppressedRules(rules, beforeRules, afterRules, disabled);
     return [];
   }
+  const envDelta = buildEnvDiff(a, b, disabled);
   return [
     {
       plane: "env",
       kind: "env.snapshot",
       before: a,
       after: b,
-      brief: "feature flag, config, release, or build snapshot changed between sessions"
+      brief: envBrief(envDelta),
+      envDelta
     }
   ];
 }
+function buildEnvDiff(a, b, disabled) {
+  const delta = {
+    flags: channelDelta(recordField(a.flags), recordField(b.flags), disabled),
+    config: channelDelta(
+      recordField(a.config),
+      recordField(b.config),
+      disabled
+    )
+  };
+  const releaseBefore = stringOrUndefined(a.release);
+  const releaseAfter = stringOrUndefined(b.release);
+  if (releaseBefore !== releaseAfter) {
+    delta.release = {
+      ...releaseBefore !== void 0 ? { before: releaseBefore } : {},
+      ...releaseAfter !== void 0 ? { after: releaseAfter } : {}
+    };
+  }
+  const buildBefore = stringOrUndefined(a.build);
+  const buildAfter = stringOrUndefined(b.build);
+  if (buildBefore !== buildAfter) {
+    delta.build = {
+      ...buildBefore !== void 0 ? { before: buildBefore } : {},
+      ...buildAfter !== void 0 ? { after: buildAfter } : {}
+    };
+  }
+  return delta;
+}
+function recordField(value) {
+  return isRecord14(value) ? value : {};
+}
+function channelDelta(a, b, disabled) {
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const key of Object.keys(a).sort()) {
+    if (!(key in b)) {
+      removed.push({ key, before: a[key] });
+    } else if (envValuesDiffer(a[key], b[key], disabled)) {
+      changed.push({ key, before: a[key], after: b[key] });
+    }
+  }
+  for (const key of Object.keys(b).sort()) {
+    if (!(key in a)) added.push({ key, after: b[key] });
+  }
+  return { added, removed, changed };
+}
+function envValuesDiffer(before, after, disabled) {
+  const beforeRules = /* @__PURE__ */ new Set();
+  const afterRules = /* @__PURE__ */ new Set();
+  if (canonicalize(before, beforeRules) !== canonicalize(after, afterRules))
+    return true;
+  const rawDiffers = stableStringify(before) !== stableStringify(after);
+  return rawDiffers && hasDisabledRule(beforeRules, afterRules, disabled);
+}
+function envBrief(delta) {
+  const counts = delta.flags.added.length + delta.flags.removed.length + delta.flags.changed.length + delta.config.added.length + delta.config.removed.length + delta.config.changed.length + (delta.release ? 1 : 0) + (delta.build ? 1 : 0);
+  const parts = [];
+  const flagCount = delta.flags.added.length + delta.flags.removed.length + delta.flags.changed.length;
+  const configCount = delta.config.added.length + delta.config.removed.length + delta.config.changed.length;
+  if (flagCount > 0) parts.push(`${flagCount} flag(s)`);
+  if (configCount > 0) parts.push(`${configCount} config value(s)`);
+  if (delta.release) parts.push("release");
+  if (delta.build) parts.push("build");
+  if (counts === 0 || parts.length === 0)
+    return "feature flag, config, release, or build snapshot changed between sessions";
+  return `environment delta between sessions: ${parts.join(", ")} changed`;
+}
 function confidenceFor(divergences) {
   if (divergences.length === 0) return "high";
   if (divergences.some(
@@ -16056,6 +16292,9 @@ async function compareSessions(aDir, bDir, options = {}) {
     ...diffDb(a.dbWrites, b.dbWrites, rules, disabled),
     ...diffEnvironment(a.environment, b.environment, rules, disabled)
   ];
+  const envDelta = divergences.find(
+    (divergence) => divergence.kind === "env.snapshot"
+  )?.envDelta;
   return {
     schemaVersion: SESSION_COMPARE_SCHEMA_VERSION,
     verdict: divergences.length > 0 ? "regression" : "clean",
@@ -16078,20 +16317,187 @@ async function compareSessions(aDir, bDir, options = {}) {
     divergences,
     noise: { suppressedCount: rules.size, rules: [...rules].sort() },
     evidence: divergencesToEvidence(divergences),
-    intent: []
+    intent: [],
+    ...envDelta ? { envDelta } : {}
   };
 }
 
 // src/compare/regression-context.ts
 var import_node_fs13 = __toESM(require("fs"), 1);
 var import_node_path13 = __toESM(require("path"), 1);
+
+// src/compare/report.ts
+var PLANE_ORDER = ["flow", "network", "db", "env"];
+var PLANE_LABELS = {
+  flow: "Flow steps",
+  network: "Network calls",
+  db: "Database rows",
+  env: "Environment and flags"
+};
+function renderCompareReport(comparison) {
+  const lines = [];
+  const regressed = comparison.verdict === "regression";
+  lines.push(
+    `# Session comparison - ${formatSessionRef(comparison.a)} vs ${formatSessionRef(comparison.b)}`
+  );
+  lines.push("");
+  lines.push(
+    regressed ? `> **Verdict: REGRESSION** (confidence: ${comparison.confidence}) - recorded behavior changed between these sessions.` : `> **Verdict: CLEAN** (confidence: ${comparison.confidence}) - the recorded sessions show no behavioral divergence.`
+  );
+  lines.push("");
+  lines.push(
+    "A is the baseline session; B is the candidate release/build. Every row below is grounded in the recorded evidence of both sessions."
+  );
+  lines.push("");
+  lines.push("## Aligned flow");
+  lines.push("");
+  const { matchedSteps, unmatchedA, unmatchedB } = comparison.alignment;
+  lines.push(
+    `${matchedSteps} step(s) matched by component identity \xB7 ${unmatchedA} only in A \xB7 ${unmatchedB} only in B`
+  );
+  lines.push("");
+  if (comparison.divergences.length > 0) {
+    lines.push("| Plane | Kind | Component | Divergence |");
+    lines.push("|---|---|---|---|");
+    for (const d of comparison.divergences) {
+      const component = d.sig ? `\`${escapeCell(d.sig)}\`` : "\u2014";
+      lines.push(
+        `| **${d.plane}** | \`${d.kind}\` | ${component} | ${escapeCell(d.brief)} |`
+      );
+    }
+    lines.push("");
+  }
+  for (const plane of PLANE_ORDER) {
+    const planeDivergences = comparison.divergences.filter(
+      (d) => d.plane === plane
+    );
+    if (planeDivergences.length === 0) continue;
+    lines.push(`## ${PLANE_LABELS[plane]}`);
+    lines.push("");
+    for (const d of planeDivergences) {
+      lines.push(`### \`${d.kind}\` - ${escapeCell(d.brief)}`);
+      lines.push("");
+      if (d.sig) lines.push(`- Component: \`${d.sig}\``);
+      if (d.requestId) lines.push(`- Request: \`${d.requestId}\``);
+      if (d.table)
+        lines.push(
+          `- Table: \`${d.table}\`${d.pk ? ` \xB7 pk \`${JSON.stringify(d.pk)}\`` : ""}`
+        );
+      lines.push("");
+      if (d.envDelta) {
+        lines.push(...renderEnvDelta(d.envDelta));
+      } else {
+        lines.push("```diff");
+        lines.push(`- before: ${JSON.stringify(d.before)}`);
+        lines.push(`+ after:  ${JSON.stringify(d.after)}`);
+        lines.push("```");
+      }
+      lines.push("");
+    }
+  }
+  lines.push("---");
+  lines.push("");
+  lines.push(
+    comparison.noise.suppressedCount > 0 ? `*${comparison.noise.suppressedCount} expected-variance difference(s) suppressed by the noise model (${comparison.noise.rules.join(", ")}).*` : "*No differences were suppressed by the noise model.*"
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+function formatComparisonSummary(comparison) {
+  const lines = [];
+  lines.push(
+    `crumbtrail-server compare - ${formatSessionRef(comparison.a)} vs ${formatSessionRef(comparison.b)}`
+  );
+  lines.push(`  Schema:      ${comparison.schemaVersion}`);
+  lines.push(
+    `  Verdict:     ${comparison.verdict.toUpperCase()} (confidence ${comparison.confidence})`
+  );
+  lines.push(
+    `  Alignment:   ${comparison.alignment.matchedSteps} matched \xB7 ${comparison.alignment.unmatchedA} only in A \xB7 ${comparison.alignment.unmatchedB} only in B`
+  );
+  lines.push(`  Divergences: ${comparison.divergences.length}`);
+  for (const d of comparison.divergences.slice(0, 5)) {
+    lines.push(`    [${d.plane}] ${d.kind} - ${d.brief}`);
+  }
+  if (comparison.divergences.length > 5) {
+    lines.push(
+      `    ... and ${comparison.divergences.length - 5} more (use --json or --report for the complete list)`
+    );
+  }
+  const rules = comparison.noise.rules.length > 0 ? ` (${comparison.noise.rules.join(", ")})` : "";
+  lines.push(
+    `  Noise:       ${comparison.noise.suppressedCount} suppressed${rules}`
+  );
+  return lines.join("\n");
+}
+function escapeCell(text3) {
+  return text3.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function sessionRefLabel(ref) {
+  return ref.release ?? ref.sessionId;
+}
+function comparisonTitle(comparison) {
+  return `${sessionRefLabel(comparison.a)} vs ${sessionRefLabel(comparison.b)}`;
+}
+function renderEnvDelta(delta) {
+  const lines = ["```diff"];
+  renderEnvChannel(lines, "flags", delta.flags);
+  renderEnvChannel(lines, "config", delta.config);
+  if (delta.release) {
+    lines.push(
+      `~ release: ${JSON.stringify(delta.release.before ?? null)} -> ${JSON.stringify(delta.release.after ?? null)}`
+    );
+  }
+  if (delta.build) {
+    lines.push(
+      `~ build: ${JSON.stringify(delta.build.before ?? null)} -> ${JSON.stringify(delta.build.after ?? null)}`
+    );
+  }
+  if (lines.length === 1) lines.push("  (no field-level changes)");
+  lines.push("```");
+  return lines;
+}
+function renderEnvChannel(lines, channel, delta) {
+  for (const change of delta.added) {
+    lines.push(
+      `+ ${channel}.${change.key}: ${JSON.stringify(change.after ?? null)}`
+    );
+  }
+  for (const change of delta.removed) {
+    lines.push(
+      `- ${channel}.${change.key}: ${JSON.stringify(change.before ?? null)}`
+    );
+  }
+  for (const change of delta.changed) {
+    lines.push(
+      `~ ${channel}.${change.key}: ${JSON.stringify(change.before ?? null)} -> ${JSON.stringify(change.after ?? null)}`
+    );
+  }
+}
+function formatSessionRef(ref) {
+  if (ref.release) {
+    const detail = [
+      `session ${ref.sessionId}`,
+      ref.build ? `build ${ref.build}` : void 0
+    ].filter(Boolean);
+    return `${ref.release} (${detail.join(", ")})`;
+  }
+  return ref.build ? `${ref.sessionId} (build ${ref.build})` : ref.sessionId;
+}
+
+// src/compare/regression-context.ts
 var REGRESSION_CONTEXT_SCHEMA_VERSION = "regression-context.v1";
 function buildRegressionContext(comparison, bDir) {
-  const requestIds = unique(comparison.divergences.map((d) => d.requestId).filter(isString));
-  const times = requestIds.flatMap((requestId) => requestTimesFromIndex(bDir, requestId));
+  const requestIds = unique(
+    comparison.divergences.map((d) => d.requestId).filter(isString)
+  );
+  const times = requestIds.flatMap(
+    (requestId) => requestTimesFromIndex(bDir, requestId)
+  );
   const firstSig = comparison.divergences.map((d) => d.sig).find(isString);
   return {
     schemaVersion: REGRESSION_CONTEXT_SCHEMA_VERSION,
+    title: comparisonTitle(comparison),
     comparison,
     divergent_interaction: firstSig ? interactionForSig(bDir, firstSig) : null,
     causal_window: requestIds.length > 0 ? {
@@ -16109,6 +16515,7 @@ function buildRegressionContext(comparison, bDir) {
       before: d.before,
       after: d.after
     })),
+    env_delta: comparison.envDelta ?? null,
     repro_hint: reproHint(bDir)
   };
 }
@@ -16153,7 +16560,8 @@ function collectRefTimes(value, times) {
   const start = isRecord15(value.start) ? value.start : void 0;
   const end = isRecord15(value.end) ? value.end : void 0;
   for (const candidate of [ref, start, end]) {
-    if (typeof candidate?.t === "number" && Number.isFinite(candidate.t)) times.push(candidate.t);
+    if (typeof candidate?.t === "number" && Number.isFinite(candidate.t))
+      times.push(candidate.t);
   }
 }
 function reproHint(sessionDir) {
@@ -17078,12 +17486,29 @@ var McpServer = class {
           "sha"
         ]))
           continue;
-        sessions.push(meta);
+        sessions.push(this.withReleaseBuild(meta));
       } catch {
       }
     }
     return textResult(sessions);
   }
+  /**
+   * Surfaces release/build as first-class list-row fields regardless of which
+   * alias the app used (release/releaseId/version, build/buildId/commit/sha), so
+   * an agent can label and group sessions by release without re-reading each
+   * meta. Additive: the raw meta keys are preserved.
+   */
+  withReleaseBuild(meta) {
+    const release = stringField5(meta.release ?? meta.releaseId ?? meta.version);
+    const build = stringField5(
+      meta.build ?? meta.buildId ?? meta.commit ?? meta.sha
+    );
+    return {
+      ...meta,
+      ...release !== void 0 ? { release } : {},
+      ...build !== void 0 ? { build } : {}
+    };
+  }
   sessionMetadataMatches(meta, expected, keys) {
     return keys.some((key) => meta[key] === expected);
   }
@@ -17487,6 +17912,7 @@ var McpServer = class {
     const currentSession = stringField5(args.currentSession);
     let evidence = [];
     let intent = [];
+    let locatedDecision;
     const adapterGaps = [];
     let sessionlessAdapterBundle = false;
     if (baselineSession && currentSession) {
@@ -17502,6 +17928,13 @@ var McpServer = class {
       try {
         const located = locateEvidence(symptom, this.recallStore());
         evidence = located.evidence;
+        locatedDecision = {
+          outcome: located.match.outcome,
+          confidence: located.match.confidence,
+          method: "fuzzy",
+          ...located.match.sessionId ? { sessionId: located.match.sessionId } : {},
+          reasons: located.match.reasons
+        };
         const adapter = await gatherAdapterEvidence(symptom, located, {
           sources: this.evidenceSources()
         });
@@ -17587,7 +18020,13 @@ var McpServer = class {
         }
       ] : []
     ];
-    const bundle = assembleBundle({ symptom, evidence, intent, gaps });
+    const bundle = assembleBundle({
+      symptom,
+      evidence,
+      intent,
+      gaps,
+      located: locatedDecision
+    });
     if (budget.maxTokens === void 0) return textResult(bundle);
     return this.budgetedTextResult(
       bundle,
@@ -20089,6 +20528,7 @@ var InspectError = class extends Error {
     this.code = code2;
     this.name = "InspectError";
   }
+  code;
 };
 function inspectSession(sessionDirOrId, opts = {}) {
   const sessionDir = resolveSessionDir2(sessionDirOrId, opts);
@@ -20715,117 +21155,6 @@ function isRecord21(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-// src/compare/report.ts
-var PLANE_ORDER = ["flow", "network", "db", "env"];
-var PLANE_LABELS = {
-  flow: "Flow steps",
-  network: "Network calls",
-  db: "Database rows",
-  env: "Environment and flags"
-};
-function renderCompareReport(comparison) {
-  const lines = [];
-  const regressed = comparison.verdict === "regression";
-  lines.push(
-    `# Session comparison - ${formatSessionRef(comparison.a)} vs ${formatSessionRef(comparison.b)}`
-  );
-  lines.push("");
-  lines.push(
-    regressed ? `> **Verdict: REGRESSION** (confidence: ${comparison.confidence}) - recorded behavior changed between these sessions.` : `> **Verdict: CLEAN** (confidence: ${comparison.confidence}) - the recorded sessions show no behavioral divergence.`
-  );
-  lines.push("");
-  lines.push(
-    "A is the baseline session; B is the candidate release/build. Every row below is grounded in the recorded evidence of both sessions."
-  );
-  lines.push("");
-  lines.push("## Aligned flow");
-  lines.push("");
-  const { matchedSteps, unmatchedA, unmatchedB } = comparison.alignment;
-  lines.push(
-    `${matchedSteps} step(s) matched by component identity \xB7 ${unmatchedA} only in A \xB7 ${unmatchedB} only in B`
-  );
-  lines.push("");
-  if (comparison.divergences.length > 0) {
-    lines.push("| Plane | Kind | Component | Divergence |");
-    lines.push("|---|---|---|---|");
-    for (const d of comparison.divergences) {
-      const component = d.sig ? `\`${escapeCell(d.sig)}\`` : "\u2014";
-      lines.push(
-        `| **${d.plane}** | \`${d.kind}\` | ${component} | ${escapeCell(d.brief)} |`
-      );
-    }
-    lines.push("");
-  }
-  for (const plane of PLANE_ORDER) {
-    const planeDivergences = comparison.divergences.filter(
-      (d) => d.plane === plane
-    );
-    if (planeDivergences.length === 0) continue;
-    lines.push(`## ${PLANE_LABELS[plane]}`);
-    lines.push("");
-    for (const d of planeDivergences) {
-      lines.push(`### \`${d.kind}\` - ${escapeCell(d.brief)}`);
-      lines.push("");
-      if (d.sig) lines.push(`- Component: \`${d.sig}\``);
-      if (d.requestId) lines.push(`- Request: \`${d.requestId}\``);
-      if (d.table)
-        lines.push(
-          `- Table: \`${d.table}\`${d.pk ? ` \xB7 pk \`${JSON.stringify(d.pk)}\`` : ""}`
-        );
-      lines.push("");
-      lines.push("```diff");
-      lines.push(`- before: ${JSON.stringify(d.before)}`);
-      lines.push(`+ after:  ${JSON.stringify(d.after)}`);
-      lines.push("```");
-      lines.push("");
-    }
-  }
-  lines.push("---");
-  lines.push("");
-  lines.push(
-    comparison.noise.suppressedCount > 0 ? `*${comparison.noise.suppressedCount} expected-variance difference(s) suppressed by the noise model (${comparison.noise.rules.join(", ")}).*` : "*No differences were suppressed by the noise model.*"
-  );
-  lines.push("");
-  return lines.join("\n");
-}
-function formatComparisonSummary(comparison) {
-  const lines = [];
-  lines.push(
-    `crumbtrail-server compare - ${formatSessionRef(comparison.a)} vs ${formatSessionRef(comparison.b)}`
-  );
-  lines.push(`  Schema:      ${comparison.schemaVersion}`);
-  lines.push(
-    `  Verdict:     ${comparison.verdict.toUpperCase()} (confidence ${comparison.confidence})`
-  );
-  lines.push(
-    `  Alignment:   ${comparison.alignment.matchedSteps} matched \xB7 ${comparison.alignment.unmatchedA} only in A \xB7 ${comparison.alignment.unmatchedB} only in B`
-  );
-  lines.push(`  Divergences: ${comparison.divergences.length}`);
-  for (const d of comparison.divergences.slice(0, 5)) {
-    lines.push(`    [${d.plane}] ${d.kind} - ${d.brief}`);
-  }
-  if (comparison.divergences.length > 5) {
-    lines.push(
-      `    ... and ${comparison.divergences.length - 5} more (use --json or --report for the complete list)`
-    );
-  }
-  const rules = comparison.noise.rules.length > 0 ? ` (${comparison.noise.rules.join(", ")})` : "";
-  lines.push(
-    `  Noise:       ${comparison.noise.suppressedCount} suppressed${rules}`
-  );
-  return lines.join("\n");
-}
-function escapeCell(text3) {
-  return text3.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
-}
-function formatSessionRef(ref) {
-  const tags = [
-    ref.release ? `release ${ref.release}` : void 0,
-    ref.build ? `build ${ref.build}` : void 0
-  ].filter(Boolean);
-  return tags.length > 0 ? `${ref.sessionId} (${tags.join(", ")})` : ref.sessionId;
-}
-
 // src/ticket/comment.ts
 var REASON_PHRASES = {
   semantic: "wording overlap with the captured incident",
@@ -21276,6 +21605,7 @@ function bounded(value, max) {
   cloudWatchEvidenceProvider,
   cloudflareEvidenceProvider,
   compareSessions,
+  comparisonTitle,
   createCrumbtrailExpressErrorMiddleware,
   createCrumbtrailExpressMiddleware,
   createServer,
@@ -21325,6 +21655,7 @@ function bounded(value, max) {
   renderProviderReadme,
   resolveDbRequestContext,
   sentryEvidenceProvider,
+  sessionRefLabel,
   signSigV4,
   splunkEvidenceProvider,
   splunkSearchDeepLink,