agent-inspect 5.0.0 → 5.2.0

package/packages/cli/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createSafetyOversizedAttributeRule, resolveTraceDir, parseDuration, buildSessionIndex, enrichSessionRunRecord, TraceDirectory, loadTraceMetadataList, loadSessionRunRecords, extractMetadata, filterTraces, truncateName, getTraceFilePath, buildRunSummary, formatDuration, formatTimestamp, isAgentInspectTrace, openTrace, TraceReadError, filterMetasBySessionScope, runTraceChecks, aggregateSessionCheckResults, createBaselineRegressionRule, resolveBundleRunIds, aggregateBundleSafeStatus, bundleFailsOnSafety, buildPlaceholderArtifact, buildBundleMetadata, buildBundleSummaryMarkdown, buildRunTimeline, renderTimeline, buildTraceStats, renderTraceStats, parseDurationFilter, searchTraces, buildActivitySummary, renderActivitySummaryHuman, buildRunWhatSummary, renderRunWhat, buildLocalExplanation, defaultSuiteConfigTemplate, loadSuiteConfig, validateSuiteConfig, runSuite, renderSuiteReport, persistedInspectEventsToTraceEvents, renderStepLine, renderErrorLine, getIndent, Redactor, TreeBuilder, validateEvent, traceEventToPersistedInspectEvent, isPersistedInspectEvent, createRunStatusRule, createStructureOrphanRule, createStructureCycleRule, createRunDurationRule, createMaxStepDurationRule, createRequireCompletedRule, createStallDetectionRule, createObservedOutcomeRule, createRunDepthRule, createToolUsageRule, createLlmUsageRule, createStructureRelationshipRule, createStructureParallelWidthRule, normalizeBundleOutputPath, defaultBundleOutputPath, summarizeObservedOutcomes, extractOutcomesFromTraceEvents, renderObservedOutcomesMarkdown, renderObservedOutcomesHtml, DEFAULT_SUITE_ARTIFACTS_DIR, nanoid, resolveRedactionProfile, applyProfileMetadataCaps, truncateStringForProfile } from './chunk-TB45H3QT.mjs';
+import { createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createSafetyOversizedAttributeRule, resolveTraceDir, parseDuration, buildSessionIndex, enrichSessionRunRecord, TraceDirectory, loadTraceMetadataList, loadSessionRunRecords, extractMetadata, filterTraces, truncateName, getTraceFilePath, buildRunSummary, formatDuration, formatTimestamp, isAgentInspectTrace, openTrace, TraceReadError, filterMetasBySessionScope, runTraceChecks, aggregateSessionCheckResults, createBaselineRegressionRule, resolveBundleRunIds, aggregateBundleSafeStatus, bundleFailsOnSafety, buildPlaceholderArtifact, buildBundleMetadata, buildBundleSummaryMarkdown, buildRunTimeline, renderTimeline, buildTraceStats, renderTraceStats, parseDurationFilter, searchTraces, buildActivitySummary, renderActivitySummaryHuman, buildRunWhatSummary, renderRunWhat, buildLocalExplanation, defaultSuiteConfigTemplate, loadSuiteConfig, validateSuiteConfig, runSuite, renderSuiteReport, analyzeCohort, renderCohortReport, gateHasThresholds, runGate, renderGateReport, persistedInspectEventsToTraceEvents, renderStepLine, renderErrorLine, getIndent, Redactor, TreeBuilder, zeroKinds, validateEvent, traceEventToPersistedInspectEvent, isPersistedInspectEvent, createRunStatusRule, createStructureOrphanRule, createStructureCycleRule, createRunDurationRule, createMaxStepDurationRule, createRequireCompletedRule, createStallDetectionRule, createObservedOutcomeRule, createRunDepthRule, createToolUsageRule, createLlmUsageRule, createStructureRelationshipRule, createStructureParallelWidthRule, normalizeBundleOutputPath, defaultBundleOutputPath, summarizeObservedOutcomes, extractOutcomesFromTraceEvents, renderObservedOutcomesMarkdown, renderObservedOutcomesHtml, escapeMarkdown, escapeHtml, DEFAULT_SUITE_ARTIFACTS_DIR, parseCohortMetricList, COHORT_METRIC_IDS, parseGateList, nanoid, resolveRedactionProfile, applyProfileMetadataCaps, flattenTree, safeString, compactAttributes, stableJson, truncateStringForProfile } from './chunk-SJ5R2XBE.mjs';
 import { realpathSync, constants as constants$1 } from 'fs';
 import path12 from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
@@ -11,7 +11,7 @@ import { createServer } from 'http';
 import { createRequire } from 'module';
 
 // package.json
-var version = "5.0.0";
+var version = "5.2.0";
 
 // packages/cli/src/trace-dir-scale.ts
 var TRACE_COUNT_WARN = 1e3;
@@ -923,7 +923,7 @@ function matchMapping(eventName, mappings) {
 function isFiniteNumber(v) {
   return typeof v === "number" && Number.isFinite(v);
 }
-function safeString(v) {
+function safeString2(v) {
   if (typeof v !== "string") return void 0;
   const t = v.trim();
   return t === "" ? void 0 : t;
@@ -973,7 +973,7 @@ var EventNormalizer = class {
     let runId;
     for (const k of cfg.runIdKeys) {
       const v = raw[k];
-      const s = safeString(v);
+      const s = safeString2(v);
       if (s) {
         runId = s;
         break;
@@ -989,7 +989,7 @@ var EventNormalizer = class {
         }
       };
     }
-    const eventName = safeString(raw[cfg.eventKey]);
+    const eventName = safeString2(raw[cfg.eventKey]);
     if (!eventName) {
       return {
         warning: {
@@ -1007,7 +1007,7 @@ var EventNormalizer = class {
     const timestamp = parsedTs ?? Date.now();
     const timestampMissing = parsedTs === void 0;
     const parentIdKey = cfg.parentIdKey;
-    const parentId = parentIdKey ? safeString(raw[parentIdKey]) : void 0;
+    const parentId = parentIdKey ? safeString2(raw[parentIdKey]) : void 0;
     let durationMs2;
     const durationKey = cfg.durationKey;
     if (durationKey) {
@@ -1018,7 +1018,7 @@ var EventNormalizer = class {
     }
     let status;
     const statusKey = cfg.statusKey;
-    const statusRaw = statusKey ? safeString(raw[statusKey]) : void 0;
+    const statusRaw = statusKey ? safeString2(raw[statusKey]) : void 0;
     if (statusRaw === "running" || statusRaw === "ok" || statusRaw === "error") {
       status = statusRaw;
     } else if (mapping?.status) {
@@ -1950,114 +1950,6 @@ function redactRunTreeForExport(tree, options) {
   return clone;
 }
 
-// packages/core/src/exporters/helpers.ts
-var REDACT_SUBSTRINGS = [
-  "authorization",
-  "cookie",
-  "token",
-  "apikey",
-  "password",
-  "secret",
-  "email"
-];
-function shouldRedactKey(key) {
-  const k = key.toLowerCase();
-  for (const s of REDACT_SUBSTRINGS) {
-    if (k.includes(s)) return true;
-  }
-  return false;
-}
-function safeString2(value, maxLength) {
-  if (value === null || value === void 0) return "";
-  let s;
-  if (typeof value === "string") s = value;
-  else if (typeof value === "number" || typeof value === "boolean") s = String(value);
-  else s = stableJson(value, false);
-  if (maxLength !== void 0 && maxLength >= 0 && s.length > maxLength) {
-    return `${s.slice(0, maxLength)}\u2026`;
-  }
-  return s;
-}
-function escapeMarkdown(value) {
-  return value.replace(/\|/g, "\\|").replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\n/g, " ");
-}
-function escapeHtml(value) {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-}
-function sortKeysDeep(input3) {
-  if (input3 === null || typeof input3 !== "object") return input3;
-  if (Array.isArray(input3)) return input3.map(sortKeysDeep);
-  const o = input3;
-  const out = {};
-  for (const k of Object.keys(o).sort()) {
-    out[k] = sortKeysDeep(o[k]);
-  }
-  return out;
-}
-function stableJson(value, pretty) {
-  const sorted = sortKeysDeep(value);
-  return pretty === true ? JSON.stringify(sorted, null, 2) : JSON.stringify(sorted);
-}
-function compactAttributes(attrs, options) {
-  if (attrs === void 0) return {};
-  const maxLen = options?.maxLength ?? 500;
-  const redacted = options?.redacted ?? true;
-  const out = {};
-  for (const key of Object.keys(attrs).sort()) {
-    if (redacted && shouldRedactKey(key)) {
-      out[key] = "[REDACTED]";
-      continue;
-    }
-    const v = attrs[key];
-    out[key] = compactValue(v, maxLen, redacted);
-  }
-  return out;
-}
-function compactValue(value, maxLen, redacted) {
-  if (value === null || typeof value !== "object") {
-    return typeof value === "string" ? safeString2(value, maxLen) : value;
-  }
-  if (Array.isArray(value)) {
-    const arr = value.slice(0, 20).map((x) => compactValue(x, maxLen, redacted));
-    if (value.length > 20) arr.push(`\u2026(+${value.length - 20} more)`);
-    return arr;
-  }
-  const o = value;
-  const inner = {};
-  for (const k of Object.keys(o)) {
-    if (redacted && shouldRedactKey(k)) inner[k] = "[REDACTED]";
-    else inner[k] = compactValue(o[k], maxLen, redacted);
-  }
-  return inner;
-}
-function flattenTree(tree) {
-  const out = [];
-  function walk(nodes) {
-    for (const n of nodes) {
-      out.push(n);
-      if (n.children.length > 0) walk(n.children);
-    }
-  }
-  walk(tree.children);
-  return out;
-}
-function zeroKinds() {
-  return {
-    RUN: 0,
-    AGENT: 0,
-    LLM: 0,
-    TOOL: 0,
-    CHAIN: 0,
-    RETRIEVER: 0,
-    DECISION: 0,
-    RESULT: 0,
-    ERROR: 0,
-    LOGIC: 0,
-    LOG: 0,
-    OUTCOME: 0
-  };
-}
-
 // packages/core/src/exporters/html-exporter.ts
 function renderTreeHtml(nodes, ulClass = "tree") {
   if (nodes.length === 0) return "";
@@ -2131,7 +2023,7 @@ function exportHtml(tree, options) {
   if (includeErrors && errors.length > 0) {
     errorsHtml += "<h2>Errors</h2><ul>";
     for (const n of errors) {
-      const msg = n.event.attributes && typeof n.event.attributes.error === "object" ? safeString2(
+      const msg = n.event.attributes && typeof n.event.attributes.error === "object" ? safeString(
         n.event.attributes.error.message,
         maxLen
       ) : "";
@@ -2280,7 +2172,7 @@ function exportMarkdown(tree, options) {
     lines.push("## Errors");
     lines.push("");
     for (const n of errors) {
-      const msg = n.event.attributes && typeof n.event.attributes.error === "object" ? safeString2(
+      const msg = n.event.attributes && typeof n.event.attributes.error === "object" ? safeString(
         n.event.attributes.error.message,
         maxLen
       ) : "";
@@ -3237,13 +3129,13 @@ function pairSteps(left, right) {
   return pairs;
 }
 function compareLeafSteps(L, R, segments, opts, out) {
-  const path19 = buildPath(segments);
+  const path21 = buildPath(segments);
   if (L.name !== R.name) {
     out.push({
       kind: "structure",
       severity: "warning",
       message: "Step name differs",
-      path: path19,
+      path: path21,
       left: L.name,
       right: R.name
     });
@@ -3253,7 +3145,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "step-type",
       severity: "warning",
       message: "Step type differs",
-      path: path19,
+      path: path21,
       left: L.type,
       right: R.type
     });
@@ -3263,7 +3155,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "step-status",
       severity: "warning",
       message: "Step status differs",
-      path: path19,
+      path: path21,
       left: L.status,
       right: R.status
     });
@@ -3275,7 +3167,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "error",
       severity: "error",
       message: "Step error message differs",
-      path: path19,
+      path: path21,
       left: le || void 0,
       right: re || void 0
     });
@@ -3293,7 +3185,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
         kind: "duration",
         severity: "info",
         message: "Step duration differs",
-        path: path19,
+        path: path21,
         left: ld,
         right: rd
       });
@@ -3306,7 +3198,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "metadata",
       severity: "info",
       message: "Step metadata differs",
-      path: path19,
+      path: path21,
       left: L.metadata,
       right: R.metadata
     });
@@ -3318,7 +3210,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "output",
       severity: "info",
       message: "Output preview differs",
-      path: path19,
+      path: path21,
       left: L.outputPreview,
       right: R.outputPreview
     });
@@ -3478,11 +3370,11 @@ function diffRuns(left, right, options) {
 }
 
 // packages/core/src/diff/renderer.ts
-function formatPath(path19) {
-  if (path19 === void 0 || path19.path.length === 0) {
+function formatPath(path21) {
+  if (path21 === void 0 || path21.path.length === 0) {
     return "(run)";
   }
-  return path19.path.map((s) => s.name).join(" > ");
+  return path21.path.map((s) => s.name).join(" > ");
 }
 function formatValue(v, verbose) {
   if (v === void 0) return "(undefined)";
@@ -3890,7 +3782,7 @@ async function newestTraceMtimeMs(traceDir) {
 }
 async function loadSessionRuns(traceDir) {
   try {
-    const mod = await import('./src-ZRFSYML6.mjs');
+    const mod = await import('./src-PK22BBMH.mjs');
     const dbPath = mod.resolveIndexDbPath(traceDir);
     const status = mod.indexStatus(dbPath);
     if (!status.healthy) {
@@ -4587,17 +4479,17 @@ function applyRule(rule, value, replacement) {
   }
   return value;
 }
-function childPath(path19, key) {
+function childPath(path21, key) {
   if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)) {
-    return path19 ? `${path19}.${key}` : key;
+    return path21 ? `${path21}.${key}` : key;
   }
-  return `${path19 || "$"}[${JSON.stringify(key)}]`;
+  return `${path21 || "$"}[${JSON.stringify(key)}]`;
 }
-function indexPath(path19, index) {
-  return `${path19 || "$"}[${index}]`;
+function indexPath(path21, index) {
+  return `${path21 || "$"}[${index}]`;
 }
-function makeFinding(path19, detector, action, matchKind, severity = "warning", preview) {
-  return preview === void 0 ? { path: path19, detector, action, severity, matchKind } : { path: path19, detector, action, severity, matchKind, preview };
+function makeFinding(path21, detector, action, matchKind, severity = "warning", preview) {
+  return preview === void 0 ? { path: path21, detector, action, severity, matchKind } : { path: path21, detector, action, severity, matchKind, preview };
 }
 function createRedactionProfile(profile = "local") {
   switch (profile) {
@@ -4666,11 +4558,11 @@ var Redactor2 = class {
   #recordFinding(state, finding) {
     if (this.#collectFindings) state.findings.push(finding);
   }
-  #redactValue(value, key, path19, depth, state) {
+  #redactValue(value, key, path21, depth, state) {
     if (depth > this.#maxDepth) {
       this.#recordFinding(
         state,
-        makeFinding(path19, "structure.maxDepth", "truncate", "value", "warning")
+        makeFinding(path21, "structure.maxDepth", "truncate", "value", "warning")
       );
       return "[Truncated]";
     }
@@ -4679,19 +4571,19 @@ var Redactor2 = class {
       if (rule) {
         this.#recordFinding(
           state,
-          makeFinding(path19, `key.${rule.key}`, actionForRule(rule), "key", "warning")
+          makeFinding(path21, `key.${rule.key}`, actionForRule(rule), "key", "warning")
         );
         return applyRule(rule, value, this.#replacement);
       }
     }
     for (const detector of this.#detectors) {
-      const detections = detector.detect({ path: path19, key, value });
+      const detections = detector.detect({ path: path21, key, value });
       for (const detection of detections) {
         const action = detection.action ?? "replace";
         this.#recordFinding(
           state,
           makeFinding(
-            path19,
+            path21,
             detector.id,
             action,
             detection.matchKind ?? detector.matchKind ?? "custom",
@@ -4709,7 +4601,7 @@ var Redactor2 = class {
       const out = [];
       state.seen.set(value, out);
       value.forEach((item, index) => {
-        out[index] = this.#redactValue(item, void 0, indexPath(path19, index), depth + 1, state);
+        out[index] = this.#redactValue(item, void 0, indexPath(path21, index), depth + 1, state);
       });
       return out;
     }
@@ -4721,7 +4613,7 @@ var Redactor2 = class {
         out[entryKey] = this.#redactValue(
           entryValue,
           entryKey,
-          childPath(path19 === "$" ? "" : path19, entryKey),
+          childPath(path21 === "$" ? "" : path21, entryKey),
           depth + 1,
           state
         );
@@ -5648,23 +5540,23 @@ function evaluatePromptInjection(text, options = {}) {
   }
   return fail(ruleId, `Matched ${evidence.length} injection pattern(s).`, evidence, "warning");
 }
-function validateSchemaField(value, field, path19, evidence) {
+function validateSchemaField(value, field, path21, evidence) {
   const ruleId = "guardrail.structured-output";
   if (field.type) {
     const actual = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
     if (actual !== field.type) {
-      evidence.push({ ruleId, path: path19, preview: `expected ${field.type}, got ${actual}` });
+      evidence.push({ ruleId, path: path21, preview: `expected ${field.type}, got ${actual}` });
       return;
     }
   }
   if (field.enum && !field.enum.some((item) => Object.is(item, value))) {
-    evidence.push({ ruleId, path: path19, preview: "value not in enum" });
+    evidence.push({ ruleId, path: path21, preview: "value not in enum" });
   }
   if (field.type === "object" && field.required && value && typeof value === "object" && !Array.isArray(value)) {
     const record = value;
     for (const key of field.required) {
       if (!(key in record)) {
-        evidence.push({ ruleId, path: `${path19}.${key}`, preview: "missing required key" });
+        evidence.push({ ruleId, path: `${path21}.${key}`, preview: "missing required key" });
       }
     }
   }
@@ -6165,10 +6057,10 @@ function printHuman(result) {
     console.log(`- ${diagnostic3.code}: ${diagnostic3.message}`);
   }
   for (const finding of result.findings) {
-    const path19 = finding.evidence[0]?.path;
+    const path21 = finding.evidence[0]?.path;
     const run = finding.evidence[0]?.runId;
     const runPrefix = run ? `[${run}] ` : "";
-    console.log(`- ${runPrefix}${finding.ruleId}: ${finding.message}${path19 ? ` (${path19})` : ""}`);
+    console.log(`- ${runPrefix}${finding.ruleId}: ${finding.message}${path21 ? ` (${path21})` : ""}`);
   }
 }
 function readErrorResult(error) {
@@ -6706,10 +6598,10 @@ async function evalRun(input3, options = {}) {
     diagnostics: []
   };
 }
-function evidenceForRun(run, path19) {
-  return [{ runId: run.runId, ...path19 !== void 0 ? { path: path19 } : {} }];
+function evidenceForRun(run, path21) {
+  return [{ runId: run.runId, ...path21 !== void 0 ? { path: path21 } : {} }];
 }
-function evidenceForEvent(event, path19) {
+function evidenceForEvent(event, path21) {
   return [
     {
       runId: event.runId,
@@ -6717,7 +6609,7 @@ function evidenceForEvent(event, path19) {
       ...event.parentId !== void 0 ? { parentId: event.parentId } : {},
       kind: event.kind,
       name: event.name,
-      ...path19 !== void 0 ? { path: path19 } : {}
+      ...path21 !== void 0 ? { path: path21 } : {}
     }
   ];
 }
@@ -6875,9 +6767,9 @@ function collectTextFields(nodes, keys, preferredKinds = []) {
 function tokenize(text) {
   return [...text.toLowerCase().matchAll(/[a-z0-9][a-z0-9'-]{2,}/g)].map((match) => match[0].replace(/^['-]+|['-]+$/g, "")).filter((token) => token.length > 2 && !STOP_WORDS.has(token));
 }
-function firstEvidence(fields, run, path19) {
+function firstEvidence(fields, run, path21) {
   const first = fields[0];
-  return first === void 0 ? evidenceForRun(run, path19) : evidenceForEvent(first.node.event, first.path);
+  return first === void 0 ? evidenceForRun(run, path21) : evidenceForEvent(first.node.event, first.path);
 }
 function collectSourceIds(nodes, keys) {
   const wanted = keySet(keys);
@@ -7254,8 +7146,8 @@ function renderEvalMarkdown(result) {
   if (result.findings.length > 0) {
     lines.push("", "## Findings");
     for (const finding of result.findings) {
-      const path19 = finding.evidence[0]?.path;
-      lines.push(`- ${finding.ruleId}: ${finding.message}${path19 ? ` (${path19})` : ""}`);
+      const path21 = finding.evidence[0]?.path;
+      lines.push(`- ${finding.ruleId}: ${finding.message}${path21 ? ` (${path21})` : ""}`);
     }
   }
   return `${lines.join("\n")}
@@ -7448,8 +7340,8 @@ function printHuman2(result) {
     console.log(`- ${diagnostic3.code}: ${diagnostic3.message}`);
   }
   for (const finding of result.findings) {
-    const path19 = finding.evidence[0]?.path;
-    console.log(`- ${finding.ruleId}: ${finding.message}${path19 ? ` (${path19})` : ""}`);
+    const path21 = finding.evidence[0]?.path;
+    console.log(`- ${finding.ruleId}: ${finding.message}${path21 ? ` (${path21})` : ""}`);
   }
 }
 function readErrorResult2(error) {
@@ -7687,8 +7579,8 @@ function printHuman3(result) {
     console.log(`- ${diagnostic3.code}: ${diagnostic3.message}`);
   }
   for (const finding of result.findings) {
-    const path19 = finding.evidence[0]?.path;
-    console.log(`- ${finding.ruleId}: ${finding.message}${path19 ? ` (${path19})` : ""}`);
+    const path21 = finding.evidence[0]?.path;
+    console.log(`- ${finding.ruleId}: ${finding.message}${path21 ? ` (${path21})` : ""}`);
   }
   console.log(`Note: ${result.note}`);
 }
@@ -7839,8 +7731,8 @@ function renderCheckSection(result) {
     `Diagnostics: ${result.diagnostics.length}`
   ];
   for (const finding of result.findings.slice(0, 10)) {
-    const path19 = finding.evidence[0]?.path ?? "(run)";
-    lines.push(`- ${finding.ruleId}: ${finding.message} (${path19})`);
+    const path21 = finding.evidence[0]?.path ?? "(run)";
+    lines.push(`- ${finding.ruleId}: ${finding.message} (${path21})`);
   }
   for (const diagnostic3 of result.diagnostics.slice(0, 10)) {
     lines.push(`- ${diagnostic3.code}: ${diagnostic3.message}`);
@@ -9794,7 +9686,7 @@ function isModuleNotFound3(e) {
 }
 async function loadIndexSqlite() {
   try {
-    return await import('./src-ZRFSYML6.mjs');
+    return await import('./src-PK22BBMH.mjs');
   } catch (e) {
     if (isModuleNotFound3(e)) {
       console.error(
@@ -10278,6 +10170,211 @@ async function suiteReportCommand(options = {}) {
     process.exitCode = 1;
   }
 }
+function normalizeMetrics(raw) {
+  const parsed = parseCohortMetricList(raw);
+  if (parsed.length === 0) return void 0;
+  const allowed = new Set(COHORT_METRIC_IDS);
+  return parsed.filter(
+    (item) => allowed.has(item)
+  );
+}
+async function writeArtifacts(result, outputDir) {
+  await mkdir(outputDir, { recursive: true });
+  const jsonPath = path12.join(outputDir, "cohort-results.json");
+  const markdownPath = path12.join(outputDir, "cohort-summary.md");
+  const htmlPath = path12.join(outputDir, "cohort-report.html");
+  await writeFile(jsonPath, `${renderCohortReport(result, { format: "json" })}
+`, "utf-8");
+  await writeFile(
+    markdownPath,
+    `${renderCohortReport(result, { format: "markdown" })}
+`,
+    "utf-8"
+  );
+  await writeFile(htmlPath, `${renderCohortReport(result, { format: "html" })}
+`, "utf-8");
+  return { jsonPath, markdownPath, htmlPath };
+}
+async function cohortCommand(options = {}) {
+  try {
+    const traceDir = resolveTraceDir({ dir: options.dir });
+    const { runs } = await loadSessionRuns(traceDir);
+    const result = await analyzeCohort(runs, {
+      traceDir,
+      baseline: options.baseline,
+      candidate: options.candidate,
+      cohortKey: options.cohortKey,
+      groupBy: options.groupBy,
+      metrics: normalizeMetrics(options.metric)
+    });
+    const format = options.format ?? (options.json ? "json" : "markdown");
+    let artifacts;
+    if (options.output !== void 0 && options.output.trim() !== "") {
+      artifacts = await writeArtifacts(result, path12.resolve(options.output.trim()));
+    }
+    if (options.json || format === "json") {
+      console.log(
+        JSON.stringify(
+          {
+            ...result,
+            artifacts: artifacts ?? null
+          },
+          null,
+          2
+        )
+      );
+    } else if (format === "html") {
+      console.log(renderCohortReport(result, { format: "html" }));
+      if (artifacts !== void 0) {
+        console.error(`Artifacts written to ${options.output}`);
+      }
+    } else {
+      console.log(renderCohortReport(result, { format: "markdown" }));
+      if (artifacts !== void 0) {
+        console.log("");
+        console.log(`Artifacts:`);
+        console.log(`- ${artifacts.jsonPath}`);
+        console.log(`- ${artifacts.markdownPath}`);
+        console.log(`- ${artifacts.htmlPath}`);
+      }
+    }
+    if (!result.ok) process.exitCode = 1;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (options.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    } else {
+      console.error(`[AgentInspect] cohort failed: ${message}`);
+    }
+    process.exitCode = 1;
+  }
+}
+var SUPPORTED_FORMATS = /* @__PURE__ */ new Set(["markdown", "json", "html", "junit", "github"]);
+function collectList(value) {
+  if (value === void 0) return [];
+  const items = Array.isArray(value) ? value : [value];
+  return items.flatMap((item) => parseGateList(item));
+}
+function parseRate(value) {
+  if (value === void 0 || value.trim() === "") return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Invalid --max-error-rate: ${value}`);
+  }
+  return parsed;
+}
+function parseDuration2(value) {
+  if (value === void 0 || value.trim() === "") return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Invalid --max-p95-duration: ${value}`);
+  }
+  return parsed;
+}
+async function writeArtifacts2(result, outputDir) {
+  await mkdir(outputDir, { recursive: true });
+  const paths = {
+    jsonPath: path12.join(outputDir, "gate-results.json"),
+    markdownPath: path12.join(outputDir, "gate-summary.md"),
+    htmlPath: path12.join(outputDir, "gate-report.html"),
+    junitPath: path12.join(outputDir, "junit.xml"),
+    githubPath: path12.join(outputDir, "github-step-summary.md")
+  };
+  await writeFile(
+    paths.jsonPath,
+    `${renderGateReport(result, { format: "json" })}
+`,
+    "utf-8"
+  );
+  await writeFile(
+    paths.markdownPath,
+    `${renderGateReport(result, { format: "markdown" })}
+`,
+    "utf-8"
+  );
+  await writeFile(
+    paths.htmlPath,
+    `${renderGateReport(result, { format: "html" })}
+`,
+    "utf-8"
+  );
+  await writeFile(
+    paths.junitPath,
+    `${renderGateReport(result, { format: "junit" })}
+`,
+    "utf-8"
+  );
+  await writeFile(
+    paths.githubPath,
+    `${renderGateReport(result, { format: "github" })}
+`,
+    "utf-8"
+  );
+  return paths;
+}
+async function gateCommand(options = {}) {
+  try {
+    const format = options.format ?? (options.json ? "json" : "markdown");
+    if (!SUPPORTED_FORMATS.has(format)) {
+      if (options.json) {
+        console.log(
+          JSON.stringify({ ok: false, exitCode: 4, error: `Unsupported format: ${format}` }, null, 2)
+        );
+      } else {
+        console.error(`[AgentInspect] Unsupported format: ${format}`);
+      }
+      process.exitCode = 4;
+      return;
+    }
+    const gateOptions = {
+      ...options.dir !== void 0 ? { traceDir: resolveTraceDir({ dir: options.dir }) } : {},
+      ...options.suite !== void 0 ? { suitePath: options.suite } : {},
+      ...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+      ...parseRate(options.maxErrorRate) !== void 0 ? { maxErrorRate: parseRate(options.maxErrorRate) } : {},
+      ...parseDuration2(options.maxP95Duration) !== void 0 ? { maxP95DurationMs: parseDuration2(options.maxP95Duration) } : {},
+      forbidTools: collectList(options.forbidTool),
+      requireObservations: collectList(options.requireObservation)
+    };
+    let runs = [];
+    const needsRuns = gateHasThresholds(gateOptions) || gateOptions.traceDir !== void 0 && gateOptions.suitePath === void 0;
+    if (needsRuns) {
+      const traceDir = gateOptions.traceDir ?? resolveTraceDir({ dir: options.dir });
+      const loaded = await loadSessionRuns(traceDir);
+      runs = loaded.runs;
+      gateOptions.traceDir = traceDir;
+    }
+    const result = await runGate(runs, gateOptions);
+    let artifacts;
+    if (options.output !== void 0 && options.output.trim() !== "") {
+      artifacts = await writeArtifacts2(result, path12.resolve(options.output.trim()));
+    }
+    if (options.json || format === "json") {
+      console.log(JSON.stringify({ ...result, artifacts: artifacts ?? null }, null, 2));
+    } else if (format === "html") {
+      console.log(renderGateReport(result, { format: "html" }));
+    } else if (format === "junit") {
+      console.log(renderGateReport(result, { format: "junit" }));
+    } else if (format === "github") {
+      console.log(renderGateReport(result, { format: "github" }));
+    } else {
+      console.log(renderGateReport(result, { format: "markdown" }));
+      if (artifacts !== void 0) {
+        console.log("");
+        console.log("Artifacts:");
+        for (const value of Object.values(artifacts)) console.log(`- ${value}`);
+      }
+    }
+    process.exitCode = result.exitCode;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (options.json) {
+      console.log(JSON.stringify({ ok: false, exitCode: 2, error: message }, null, 2));
+    } else {
+      console.error(`[AgentInspect] gate failed: ${message}`);
+    }
+    process.exitCode = 2;
+  }
+}
 
 // packages/cli/src/index.ts
 function runCommand(action) {
@@ -10712,6 +10809,21 @@ function createCliProgram() {
   suiteCmd.command("report").description("Render a report from a prior suite run artifact").option("--input <path>", "suite run JSON artifact").option("--format <format>", "markdown or json", "markdown").option("--json", "print JSON wrapper").action((opts) => {
     runCommand(() => suiteReportCommand(opts));
   });
+  program.command("cohort").description("Compare baseline/candidate trace cohorts for regressions (v5.1+)").option("--dir <path>", "trace directory").option("--baseline <label>", "baseline cohort label (metadata key)").option("--candidate <label>", "candidate cohort label (metadata key)").option("--cohort-key <key>", "metadata key for cohort labels", "cohort").option("--group-by <spec>", "model | session | group | metadata.<key>", "model").option(
+    "--metric <list>",
+    "comma-separated metrics (errorRate,duration,toolChoice,...)"
+  ).option("--format <format>", "markdown, json, or html", "markdown").option("-o, --output <dir>", "write cohort-results.json, cohort-summary.md, cohort-report.html").option("--json", "print deterministic JSON result").action((opts) => {
+    runCommand(() => cohortCommand(opts));
+  });
+  program.command("gate").description("Run deterministic CI quality gates over traces or suites (v5.2+)").option("--dir <path>", "trace directory for threshold checks").option("--suite <path>", "suite config path").option("--max-error-rate <percent>", "maximum allowed error rate percentage").option("--max-p95-duration <ms>", "maximum allowed p95 run duration in ms").option("--forbid-tool <name>", "forbidden tool name (repeatable or comma-separated)").option(
+    "--require-observation <name>",
+    "required passed observation (repeatable or comma-separated)"
+  ).option("--format <format>", "markdown, json, html, junit, or github", "markdown").option(
+    "-o, --output <dir>",
+    "write gate-results.json, gate-summary.md, gate-report.html, junit.xml, github-step-summary.md"
+  ).option("--json", "print deterministic JSON result").action((opts) => {
+    runCommand(() => gateCommand(opts));
+  });
   return program;
 }
 function isPrimaryModule() {