agent-inspect 2.3.0 → 2.5.0

package/packages/cli/dist/index.mjs

@@ -4,7 +4,7 @@ import path13 from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { Command, Option } from 'commander';
 import { AsyncLocalStorage } from 'async_hooks';
-import crypto, { webcrypto } from 'crypto';
+import crypto, { webcrypto, createHash } from 'crypto';
 import { unlink, stat, mkdir, writeFile, appendFile, readdir, readFile, access, open } from 'fs/promises';
 import os from 'os';
 import process2, { stdin, stdout } from 'process';
@@ -12,7 +12,7 @@ import tty from 'tty';
 import { createInterface } from 'readline';
 
 // package.json
-var version = "2.3.0";
+var version = "2.5.0";
 
 // packages/core/src/correlation-metadata.ts
 var TRACE_CORRELATION_KEYS = [
@@ -1429,18 +1429,18 @@ var proto = Object.defineProperties(() => {
     }
   }
 });
-var createStyler = (open2, close, parent) => {
+var createStyler = (open3, close, parent) => {
   let openAll;
   let closeAll;
   if (parent === void 0) {
-    openAll = open2;
+    openAll = open3;
     closeAll = close;
   } else {
-    openAll = parent.openAll + open2;
+    openAll = parent.openAll + open3;
     closeAll = close + parent.closeAll;
   }
   return {
-    open: open2,
+    open: open3,
     close,
     openAll,
     closeAll,
@@ -1505,15 +1505,15 @@ function getStatusIcon(status) {
   if (status === "error") return source_default.red("\u2716");
   return source_default.yellow("\u23F3");
 }
-function renderStepLine(name, durationMs, status, depth) {
+function renderStepLine(name, durationMs2, status, depth) {
   try {
     const nm = formatTerminalName(name);
     const ind = getIndent(depth ?? 0);
-    if (status === "running" && durationMs === void 0) {
+    if (status === "running" && durationMs2 === void 0) {
       return `${ind}${source_default.yellow("\u23F3")} ${nm}`;
     }
-    const hasDur = durationMs !== void 0 && Number.isFinite(durationMs);
-    const dur = hasDur ? formatDuration2(durationMs) : void 0;
+    const hasDur = durationMs2 !== void 0 && Number.isFinite(durationMs2);
+    const dur = hasDur ? formatDuration2(durationMs2) : void 0;
     if (status === "running") {
       return dur !== void 0 ? `${ind}${source_default.yellow("\u23F3")} ${nm} (${dur})` : `${ind}${source_default.yellow("\u23F3")} ${nm}`;
     }
@@ -1666,14 +1666,14 @@ async function extractMetadata(filePath, _quickScan) {
   } else {
     status = "unknown";
   }
-  const durationMs = explicitDurationMs ?? (startedAt !== void 0 && endedAt !== void 0 && Number.isFinite(startedAt) && Number.isFinite(endedAt) && endedAt >= startedAt ? endedAt - startedAt : void 0);
+  const durationMs2 = explicitDurationMs ?? (startedAt !== void 0 && endedAt !== void 0 && Number.isFinite(startedAt) && Number.isFinite(endedAt) && endedAt >= startedAt ? endedAt - startedAt : void 0);
   return {
     runId: resolvedRunId,
     name,
     status,
     startedAt,
     endedAt,
-    durationMs,
+    durationMs: durationMs2,
     eventCount: parsedTrace.sourceEventCount,
     filePath,
     fileSize: stats.size,
@@ -1694,7 +1694,7 @@ function buildRunSummary(events) {
   const runId = started?.runId ?? events.find((e) => typeof e.runId === "string")?.runId ?? "unknown-run";
   const name = typeof started?.name === "string" && started.name.trim() !== "" ? started.name : void 0;
   const status = lastCompleted ? lastCompleted.status : started ? "running" : "unknown";
-  const durationMs = lastCompleted && isFiniteNumber(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0;
+  const durationMs2 = lastCompleted && isFiniteNumber(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0;
   started && isFiniteNumber(started.startTime) ? started.startTime : void 0;
   const steps = /* @__PURE__ */ new Map();
   for (const e of events) {
@@ -1784,7 +1784,7 @@ function buildRunSummary(events) {
     runId,
     name,
     status,
-    durationMs,
+    durationMs: durationMs2,
     totalSteps,
     llmSteps,
     toolSteps,
@@ -2529,10 +2529,12 @@ async function searchTraces(metas, options) {
     durationFilter = parseDurationFilter(options.duration);
   }
   const limit = options.limit ?? 50;
+  const sessionId = options.session?.trim();
   const hasContentFilter = Boolean(
     options.status || stepTypeFilter || nameQuery || toolQuery || durationFilter
   );
   const results = [];
+  const sessionLabel = sessionId && sessionId !== "" ? sessionId : void 0;
   if (!hasContentFilter) {
     for (const m of filtered) {
       results.push({
@@ -2541,9 +2543,10 @@ async function searchTraces(metas, options) {
         runStatus: m.status,
         timestamp: m.startedAt,
         durationMs: m.durationMs,
-        matchReason: "trace in directory",
-        matchedFields: ["run"],
-        filePath: m.filePath
+        matchReason: sessionLabel ? `trace in session ${sessionLabel}` : "trace in directory",
+        matchedFields: sessionLabel ? ["run", "session"] : ["run"],
+        filePath: m.filePath,
+        ...sessionLabel ? { sessionId: sessionLabel } : {}
       });
     }
     return results.slice(0, limit);
@@ -2682,6 +2685,478 @@ async function loadTraceMetadataList(_traceDir, fileNames, getPath) {
   }
   return metas;
 }
+
+// packages/core/src/sessions/metadata.ts
+function isNonEmptyString3(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function finitePositiveInt(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+    return void 0;
+  }
+  return Math.trunc(value);
+}
+function extractSessionWorkflowMetadata(record) {
+  if (!record) return void 0;
+  const out = {};
+  let found = false;
+  const assignString = (key, value) => {
+    if (isNonEmptyString3(value)) {
+      out[key] = value.trim();
+      found = true;
+    }
+  };
+  assignString("sessionId", record.sessionId);
+  assignString("conversationId", record.conversationId);
+  assignString("groupId", record.groupId);
+  assignString("parentGroupId", record.parentGroupId);
+  assignString("retryOf", record.retryOf);
+  assignString("retryReason", record.retryReason);
+  assignString("handoffFrom", record.handoffFrom);
+  assignString("handoffTo", record.handoffTo);
+  assignString("subAgentId", record.subAgentId);
+  assignString("subAgentName", record.subAgentName);
+  assignString("jobId", record.jobId);
+  assignString("queueName", record.queueName);
+  assignString("workflowName", record.workflowName);
+  assignString("workflowStep", record.workflowStep);
+  assignString("toolCallId", record.toolCallId);
+  assignString("mcpToolCallId", record.mcpToolCallId);
+  assignString("linkedStepId", record.linkedStepId);
+  assignString("correlationId", record.correlationId);
+  assignString("requestId", record.requestId);
+  assignString("decisionId", record.decisionId);
+  const attempt = finitePositiveInt(record.attempt);
+  if (attempt !== void 0) {
+    out.attempt = attempt;
+    found = true;
+  }
+  return found ? out : void 0;
+}
+function sessionKeyForRun(meta, options) {
+  if (meta?.sessionId) return meta.sessionId;
+  if (options?.correlateByGroupId && meta?.groupId) {
+    return `group:${meta.groupId}`;
+  }
+  return void 0;
+}
+
+// packages/core/src/sessions/load.ts
+async function enrichSessionRunRecord(meta) {
+  let metadata;
+  try {
+    const events = await readTraceEventsFromFile(meta.filePath);
+    for (const event of events) {
+      if (event.event !== "run_started") continue;
+      if (event.metadata && typeof event.metadata === "object") {
+        metadata = event.metadata;
+      }
+      break;
+    }
+  } catch {
+  }
+  return {
+    runId: meta.runId,
+    name: meta.name,
+    status: meta.status,
+    startedAt: meta.startedAt,
+    endedAt: meta.endedAt,
+    durationMs: meta.durationMs,
+    filePath: meta.filePath,
+    metadata
+  };
+}
+async function loadSessionRunRecords(metas) {
+  const out = [];
+  for (const meta of metas) {
+    out.push(await enrichSessionRunRecord(meta));
+  }
+  return out;
+}
+
+// packages/core/src/sessions/scope.ts
+function filterMetasBySessionScope(metas, records, options) {
+  const sessionId = options.sessionId?.trim();
+  const groupId = options.groupId?.trim();
+  const warnings = [];
+  if (sessionId) {
+    const index = buildSessionIndex(records, {
+      correlateByGroupId: options.correlateByGroupId === true
+    });
+    warnings.push(...index.warnings);
+    const session = index.sessions.find((item) => item.sessionId === sessionId);
+    if (!session) {
+      return {
+        metas: [],
+        scopeLabel: sessionId,
+        scopeKind: "session",
+        runIds: [],
+        warnings,
+        notFound: true
+      };
+    }
+    const runIdSet = new Set(session.runIds);
+    const filtered = metas.filter((meta) => runIdSet.has(meta.runId));
+    return {
+      metas: filtered,
+      scopeLabel: sessionId,
+      scopeKind: "session",
+      runIds: session.runIds,
+      warnings,
+      notFound: false
+    };
+  }
+  if (groupId) {
+    const runIds = records.filter((run) => extractSessionWorkflowMetadata(run.metadata)?.groupId === groupId).map((run) => run.runId).sort();
+    if (runIds.length === 0) {
+      return {
+        metas: [],
+        scopeLabel: groupId,
+        scopeKind: "group",
+        runIds: [],
+        warnings,
+        notFound: true
+      };
+    }
+    const runIdSet = new Set(runIds);
+    return {
+      metas: metas.filter((meta) => runIdSet.has(meta.runId)),
+      scopeLabel: groupId,
+      scopeKind: "group",
+      runIds,
+      warnings,
+      notFound: false
+    };
+  }
+  return {
+    metas: [...metas],
+    scopeLabel: "",
+    scopeKind: "session",
+    runIds: [],
+    warnings,
+    notFound: false
+  };
+}
+
+// packages/core/src/sessions/checks.ts
+function emptySummary() {
+  return { passed: 0, failed: 0, warnings: 0, errors: 0 };
+}
+function mergeSummary(target, source) {
+  return {
+    passed: target.passed + source.passed,
+    failed: target.failed + source.failed,
+    warnings: target.warnings + source.warnings,
+    errors: target.errors + source.errors
+  };
+}
+function sessionDiagnostic(code, message) {
+  return { code, message, severity: "error" };
+}
+function aggregateSessionCheckResults(perRun, scope) {
+  if (scope.notFound) {
+    return {
+      ok: false,
+      status: "error",
+      format: perRun[0]?.format ?? "agent-inspect-jsonl",
+      scopeKind: scope.scopeKind,
+      scopeLabel: scope.scopeLabel,
+      runIds: [],
+      runResults: [],
+      summary: { ...emptySummary(), errors: 1 },
+      findings: [],
+      diagnostics: [
+        sessionDiagnostic(
+          "AI_CHECK_INVALID_ARGUMENTS",
+          `${scope.scopeKind} not found: ${scope.scopeLabel}`
+        )
+      ],
+      ...scope.sessionWarnings?.length ? { sessionWarnings: [...scope.sessionWarnings] } : {}
+    };
+  }
+  if (scope.empty || perRun.length === 0) {
+    return {
+      ok: false,
+      status: "error",
+      format: perRun[0]?.format ?? "agent-inspect-jsonl",
+      scopeKind: scope.scopeKind,
+      scopeLabel: scope.scopeLabel,
+      runIds: scope.runIds,
+      runResults: [],
+      summary: { ...emptySummary(), errors: 1 },
+      findings: [],
+      diagnostics: [
+        sessionDiagnostic(
+          "AI_CHECK_TRACE_UNREADABLE",
+          `No readable traces in ${scope.scopeKind}: ${scope.scopeLabel}`
+        )
+      ],
+      ...scope.sessionWarnings?.length ? { sessionWarnings: [...scope.sessionWarnings] } : {}
+    };
+  }
+  let summary = emptySummary();
+  const findings = [];
+  const diagnostics = [];
+  const runResults = [];
+  for (const result of perRun) {
+    summary = mergeSummary(summary, result.summary);
+    findings.push(...result.findings);
+    diagnostics.push(...result.diagnostics);
+    if (result.runId) {
+      runResults.push({ runId: result.runId, status: result.status });
+    }
+  }
+  runResults.sort((a, b) => a.runId.localeCompare(b.runId));
+  findings.sort((a, b) => {
+    const runCmp = (a.evidence[0]?.runId ?? "").localeCompare(
+      b.evidence[0]?.runId ?? ""
+    );
+    if (runCmp !== 0) return runCmp;
+    return a.ruleId.localeCompare(b.ruleId);
+  });
+  const hasErrors = diagnostics.some((item) => item.severity === "error");
+  const status = hasErrors ? "error" : summary.failed > 0 ? "fail" : "pass";
+  return {
+    ok: status === "pass",
+    status,
+    format: perRun[0]?.format ?? "agent-inspect-jsonl",
+    scopeKind: scope.scopeKind,
+    scopeLabel: scope.scopeLabel,
+    runIds: scope.runIds,
+    runResults,
+    summary,
+    findings,
+    diagnostics,
+    ...scope.sessionWarnings?.length ? { sessionWarnings: [...scope.sessionWarnings] } : {}
+  };
+}
+
+// packages/core/src/sessions/index.ts
+function compareRuns(a, b) {
+  const aStart = a.startedAt ?? 0;
+  const bStart = b.startedAt ?? 0;
+  if (aStart !== bStart) return aStart - bStart;
+  return a.runId.localeCompare(b.runId);
+}
+function buildGroups(runIds, metaByRunId) {
+  const byGroup = /* @__PURE__ */ new Map();
+  for (const runId of runIds) {
+    const groupId = metaByRunId.get(runId)?.groupId;
+    if (!groupId) continue;
+    const existing = byGroup.get(groupId);
+    if (existing) {
+      existing.runIds.push(runId);
+    } else {
+      byGroup.set(groupId, {
+        groupId,
+        parentGroupId: metaByRunId.get(runId)?.parentGroupId,
+        runIds: [runId]
+      });
+    }
+  }
+  return [...byGroup.values()].map((group) => ({
+    ...group,
+    runIds: [...group.runIds].sort((a, b) => a.localeCompare(b))
+  }));
+}
+function buildHandoffs(runIds, metaByRunId, warnings, sessionId) {
+  const edges = [];
+  const seen = /* @__PURE__ */ new Set();
+  const pushEdge = (edge) => {
+    const key = `${edge.from}->${edge.to}:${edge.confidence}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    edges.push(edge);
+  };
+  for (const runId of runIds) {
+    const meta = metaByRunId.get(runId);
+    if (!meta) continue;
+    if (meta.handoffFrom && meta.handoffTo) {
+      pushEdge({
+        from: meta.handoffFrom,
+        to: meta.handoffTo,
+        source: "manual",
+        confidence: "explicit"
+      });
+      continue;
+    }
+    if (meta.handoffFrom) {
+      pushEdge({
+        from: meta.handoffFrom,
+        to: runId,
+        source: "manual",
+        confidence: "explicit"
+      });
+    }
+    if (meta.handoffTo) {
+      pushEdge({
+        from: runId,
+        to: meta.handoffTo,
+        source: "manual",
+        confidence: "explicit"
+      });
+    }
+    if (meta.subAgentId && meta.parentGroupId && !meta.handoffFrom && !meta.handoffTo) {
+      pushEdge({
+        from: meta.parentGroupId,
+        to: meta.subAgentId,
+        source: "inferred",
+        confidence: "correlated"
+      });
+      warnings.push({
+        code: "ambiguous-handoff-endpoints",
+        message: "Handoff inferred from parentGroupId and subAgentId without explicit handoffFrom/handoffTo.",
+        runId,
+        sessionId
+      });
+    }
+  }
+  return edges.sort((a, b) => {
+    const from = a.from.localeCompare(b.from);
+    if (from !== 0) return from;
+    return a.to.localeCompare(b.to);
+  });
+}
+function buildRetries(runIds, metaByRunId, warnings, sessionId) {
+  const retries = [];
+  for (const runId of runIds) {
+    const meta = metaByRunId.get(runId);
+    if (!meta) continue;
+    if (meta.retryOf) {
+      retries.push({
+        runId,
+        retryOf: meta.retryOf,
+        attempt: meta.attempt,
+        source: "manual",
+        confidence: "explicit"
+      });
+      continue;
+    }
+    if (meta.attempt !== void 0 && meta.attempt > 1) {
+      retries.push({
+        runId,
+        attempt: meta.attempt,
+        source: "inferred",
+        confidence: "correlated"
+      });
+      warnings.push({
+        code: "ambiguous-retry-link",
+        message: "attempt > 1 without retryOf; retry link is correlated only.",
+        runId,
+        sessionId
+      });
+    }
+  }
+  return retries.sort((a, b) => a.runId.localeCompare(b.runId));
+}
+function buildCriticalPath(runs, handoffs) {
+  const runById = new Map(runs.map((run) => [run.runId, run]));
+  const explicitTargets = new Set(
+    handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.to)
+  );
+  const explicitSources = new Set(
+    handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.from)
+  );
+  const ordered = [...runs].sort(compareRuns);
+  const path15 = [];
+  const visited = /* @__PURE__ */ new Set();
+  const pushRun = (run, confidence, source) => {
+    if (visited.has(run.runId)) return;
+    visited.add(run.runId);
+    path15.push({
+      runId: run.runId,
+      name: run.name,
+      startedAt: run.startedAt,
+      durationMs: run.durationMs,
+      confidence,
+      source
+    });
+  };
+  for (const edge of handoffs) {
+    if (edge.confidence !== "explicit") continue;
+    const fromRun = [...runById.values()].find(
+      (run) => run.runId === edge.from || metaRunIdMatches(run, edge.from, runById)
+    );
+    const toRun = [...runById.values()].find(
+      (run) => run.runId === edge.to || metaRunIdMatches(run, edge.to, runById)
+    );
+    if (fromRun) pushRun(fromRun, "explicit", "manual");
+    if (toRun) pushRun(toRun, "explicit", "manual");
+  }
+  for (const run of ordered) {
+    if (visited.has(run.runId)) continue;
+    const confidence = explicitTargets.has(run.runId) || explicitSources.has(run.runId) ? "explicit" : "correlated";
+    pushRun(run, confidence, confidence === "explicit" ? "manual" : "inferred");
+  }
+  return path15;
+}
+function metaRunIdMatches(run, token, runById) {
+  const meta = extractSessionWorkflowMetadata(run.metadata);
+  return meta?.subAgentId === token || meta?.groupId === token || runById.has(token);
+}
+function buildSessionIndex(inputRuns, options = {}) {
+  const warnings = [];
+  const runs = [...inputRuns].sort(compareRuns);
+  const metaByRunId = /* @__PURE__ */ new Map();
+  for (const run of runs) {
+    metaByRunId.set(run.runId, extractSessionWorkflowMetadata(run.metadata));
+  }
+  const sessionsByKey = /* @__PURE__ */ new Map();
+  const unscopedRunIds = [];
+  for (const run of runs) {
+    const meta = metaByRunId.get(run.runId);
+    const key = sessionKeyForRun(meta, {
+      correlateByGroupId: options.correlateByGroupId === true
+    });
+    if (!key) {
+      unscopedRunIds.push(run.runId);
+      continue;
+    }
+    const bucket = sessionsByKey.get(key) ?? [];
+    bucket.push(run);
+    sessionsByKey.set(key, bucket);
+  }
+  const sessions = [...sessionsByKey.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([sessionId, sessionRuns]) => {
+    const runIds = sessionRuns.map((run) => run.runId).sort();
+    const handoffs = buildHandoffs(runIds, metaByRunId, warnings, sessionId);
+    const retries = buildRetries(runIds, metaByRunId, warnings, sessionId);
+    const groups = buildGroups(runIds, metaByRunId);
+    const criticalPath = buildCriticalPath(sessionRuns, handoffs);
+    const confidences = new Set(handoffs.map((edge) => edge.confidence));
+    if (confidences.has("explicit") && confidences.has("correlated")) {
+      warnings.push({
+        code: "mixed-confidence-group",
+        message: "Session aggregates explicit and correlated handoff edges.",
+        sessionId
+      });
+    }
+    return {
+      sessionId,
+      runIds,
+      groups,
+      handoffs,
+      retries,
+      criticalPath
+    };
+  });
+  if (sessions.length === 0 && runs.length > 0) {
+    warnings.push({
+      code: "missing-session-id",
+      message: "No sessionId (or correlated groupId) found on input runs."
+    });
+  }
+  warnings.sort((a, b) => {
+    const code = a.code.localeCompare(b.code);
+    if (code !== 0) return code;
+    return (a.runId ?? "").localeCompare(b.runId ?? "");
+  });
+  return {
+    runs,
+    sessions,
+    unscopedRunIds: unscopedRunIds.sort(),
+    warnings
+  };
+}
 var KNOWN_EVENTS = /* @__PURE__ */ new Set([
   "run_started",
   "run_completed",
@@ -2740,10 +3215,10 @@ function statusIcon(status) {
   if (status === "running") return "\u23F3";
   return "?";
 }
-function durationCell(status, durationMs) {
+function durationCell(status, durationMs2) {
   if (status === "running" || status === "unknown") return "-";
-  if (durationMs !== void 0 && Number.isFinite(durationMs)) {
-    return formatDuration2(durationMs);
+  if (durationMs2 !== void 0 && Number.isFinite(durationMs2)) {
+    return formatDuration2(durationMs2);
   }
   return "-";
 }
@@ -3400,7 +3875,7 @@ var TreeBuilder = class {
       const startedAt = sorted.length > 0 ? sorted[0].timestamp : void 0;
       const endedAt = sorted.length > 0 ? sorted[sorted.length - 1].timestamp : void 0;
       const status = computeRunStatus(sorted);
-      const durationMs = startedAt !== void 0 && endedAt !== void 0 && Number.isFinite(startedAt) && Number.isFinite(endedAt) && endedAt >= startedAt && status !== "running" ? endedAt - startedAt : void 0;
+      const durationMs2 = startedAt !== void 0 && endedAt !== void 0 && Number.isFinite(startedAt) && Number.isFinite(endedAt) && endedAt >= startedAt && status !== "running" ? endedAt - startedAt : void 0;
       const name = sorted.find((e) => e.kind === "RUN")?.name;
       out.push({
         runId,
@@ -3408,7 +3883,7 @@ var TreeBuilder = class {
         status,
         startedAt,
         endedAt: status === "running" ? void 0 : endedAt,
-        durationMs,
+        durationMs: durationMs2,
         children: roots,
         metadata: {
           totalEvents: sorted.length,
@@ -3703,13 +4178,13 @@ function persistedEventsForParsedTrace(parsed) {
 function isRecord8(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isNonEmptyString3(value) {
+function isNonEmptyString4(value) {
   return typeof value === "string" && value.trim() !== "";
 }
 function readStringField(record, keys) {
   for (const key of keys) {
     const value = record[key];
-    if (isNonEmptyString3(value)) return value;
+    if (isNonEmptyString4(value)) return value;
   }
   return void 0;
 }
@@ -3843,7 +4318,7 @@ function parseUnixNanoToIso(value) {
   return void 0;
 }
 function parseIsoTime(value) {
-  if (!isNonEmptyString3(value)) return void 0;
+  if (!isNonEmptyString4(value)) return void 0;
   const ms = Date.parse(value);
   if (!Number.isFinite(ms)) return void 0;
   return new Date(ms).toISOString();
@@ -4103,9 +4578,9 @@ function mapOpenInferenceSpan(span, index, version2) {
   if (endedAt !== void 0) {
     event.endedAt = endedAt;
   }
-  const durationMs = durationBetweenIso(startedAt, endedAt);
-  if (durationMs !== void 0) {
-    event.durationMs = durationMs;
+  const durationMs2 = durationBetweenIso(startedAt, endedAt);
+  if (durationMs2 !== void 0) {
+    event.durationMs = durationMs2;
   }
   if (tokenUsage !== void 0) {
     event.tokenUsage = tokenUsage;
@@ -4690,9 +5165,9 @@ function mapOtlpSpan(context) {
   if (endedAt !== void 0) {
     event.endedAt = endedAt;
   }
-  const durationMs = durationBetweenIso(startedAt, endedAt);
-  if (durationMs !== void 0) {
-    event.durationMs = durationMs;
+  const durationMs2 = durationBetweenIso(startedAt, endedAt);
+  if (durationMs2 !== void 0) {
+    event.durationMs = durationMs2;
   }
   if (tokenUsage !== void 0) {
     event.tokenUsage = tokenUsage;
@@ -5697,13 +6172,13 @@ var EventNormalizer = class {
     const timestampMissing = parsedTs === void 0;
     const parentIdKey = cfg.parentIdKey;
     const parentId = parentIdKey ? safeString(raw[parentIdKey]) : void 0;
-    let durationMs;
+    let durationMs2;
     const durationKey = cfg.durationKey;
     if (durationKey) {
       const v = raw[durationKey];
-      if (isFiniteNumber2(v)) durationMs = v;
+      if (isFiniteNumber2(v)) durationMs2 = v;
     } else if (isFiniteNumber2(raw.durationMs)) {
-      durationMs = raw.durationMs;
+      durationMs2 = raw.durationMs;
     }
     let status;
     const statusKey = cfg.statusKey;
@@ -5750,7 +6225,7 @@ var EventNormalizer = class {
       kind,
       timestamp,
       ...status ? { status } : {},
-      ...durationMs !== void 0 ? { durationMs } : {},
+      ...durationMs2 !== void 0 ? { durationMs: durationMs2 } : {},
       ...Object.keys(attributes).length > 0 ? { attributes } : {},
       confidence,
       source: {
@@ -7338,7 +7813,7 @@ function manualTraceEventsToRunTree(events) {
   }
   const startedAt = started.startTime;
   const endedAt = lastCompleted !== void 0 && runStatus !== "running" ? lastCompleted.endTime : void 0;
-  const durationMs = lastCompleted !== void 0 && Number.isFinite(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0;
+  const durationMs2 = lastCompleted !== void 0 && Number.isFinite(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0;
   const steps = /* @__PURE__ */ new Map();
   for (const e of events) {
     if (e.event !== "step_started") continue;
@@ -7427,7 +7902,7 @@ function manualTraceEventsToRunTree(events) {
     status: runStatus,
     startedAt,
     endedAt,
-    durationMs,
+    durationMs: durationMs2,
     children: roots,
     metadata: {
       totalEvents: inspectNodes.size,
@@ -7740,7 +8215,7 @@ function manualTraceEventsToComparableRun(events) {
   let runStatus;
   if (lastCompleted === void 0) runStatus = "running";
   else runStatus = lastCompleted.status;
-  const durationMs = lastCompleted !== void 0 && Number.isFinite(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0;
+  const durationMs2 = lastCompleted !== void 0 && Number.isFinite(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0;
   const steps = /* @__PURE__ */ new Map();
   let order = 0;
   for (const e of events) {
@@ -7811,7 +8286,7 @@ function manualTraceEventsToComparableRun(events) {
     runId,
     name: rs.name,
     status: runStatus,
-    durationMs,
+    durationMs: durationMs2,
     steps: roots
   };
 }
@@ -8397,11 +8872,29 @@ async function searchCommand(options = {}) {
       parseDurationFilter(options.duration);
     }
     const files = await td.list();
-    const metas = await loadTraceMetadataList(
+    let metas = await loadTraceMetadataList(
       traceDir,
       files,
       (f) => td.getPath(f)
     );
+    const sessionId = options.session?.trim();
+    if (sessionId) {
+      const records = await loadSessionRunRecords(metas);
+      const scoped = filterMetasBySessionScope(metas, records, {
+        sessionId,
+        correlateByGroupId: options.correlateGroup === true
+      });
+      if (scoped.notFound) {
+        if (options.json) {
+          console.log(JSON.stringify([], null, 2));
+        } else {
+          console.log(`Session not found: ${sessionId}`);
+          console.log(`Trace directory: ${traceDir}`);
+        }
+        return;
+      }
+      metas = scoped.metas;
+    }
     const status = options.status === "success" || options.status === "error" || options.status === "running" || options.status === "unknown" ? options.status : void 0;
     const results = await searchTraces(metas, {
       traceDir,
@@ -8412,7 +8905,9 @@ async function searchCommand(options = {}) {
       name: options.name,
       tool: options.tool,
       duration: options.duration,
-      limit: parseLimit2(options.limit)
+      limit: parseLimit2(options.limit),
+      ...sessionId ? { session: sessionId } : {},
+      ...options.correlateGroup ? { correlateGroup: true } : {}
     });
     if (options.json) {
       console.log(JSON.stringify(results, null, 2));
@@ -8440,6 +8935,184 @@ async function searchCommand(options = {}) {
   }
 }
 
+// packages/cli/src/sessions.ts
+async function loadSessionIndex(traceDir, correlateGroup) {
+  const td = new TraceDirectory({ dir: traceDir });
+  const files = await td.list();
+  const metas = await loadTraceMetadataList(
+    traceDir,
+    files,
+    (fileName) => td.getPath(fileName)
+  );
+  const runs = await loadSessionRunRecords(metas);
+  return buildSessionIndex(runs, { correlateByGroupId: correlateGroup === true });
+}
+function findSession(index, sessionId) {
+  return index.sessions.find((session) => session.sessionId === sessionId);
+}
+function renderSessionsHuman(index, traceDir) {
+  if (index.sessions.length === 0) {
+    console.log("No sessions found");
+    console.log(`Trace directory: ${traceDir}`);
+    if (index.unscopedRunIds.length > 0) {
+      console.log(
+        `Unscoped runs (no sessionId): ${index.unscopedRunIds.join(", ")}`
+      );
+    }
+    return;
+  }
+  console.log("Sessions:");
+  for (const session of index.sessions) {
+    const firstRun = index.runs.find(
+      (run) => session.runIds.includes(run.runId)
+    );
+    const workflowName = firstRun?.metadata && typeof firstRun.metadata.workflowName === "string" ? firstRun.metadata.workflowName : void 0;
+    const suffix = workflowName ? ` workflow=${workflowName}` : "";
+    console.log(
+      `  ${session.sessionId} (${session.runIds.length} run${session.runIds.length === 1 ? "" : "s"})${suffix}`
+    );
+  }
+  if (index.unscopedRunIds.length > 0) {
+    console.log("");
+    console.log(
+      `Unscoped runs (no sessionId): ${index.unscopedRunIds.join(", ")}`
+    );
+  }
+}
+function renderSessionHuman(session, index, options) {
+  console.log(`Session: ${session.sessionId}`);
+  console.log(`Runs: ${session.runIds.join(", ")}`);
+  if (session.handoffs.length > 0) {
+    console.log("");
+    console.log("Handoffs:");
+    for (const edge of session.handoffs) {
+      console.log(
+        `  ${edge.from} -> ${edge.to} (${edge.confidence}, ${edge.source})`
+      );
+    }
+  }
+  if (session.retries.length > 0) {
+    console.log("");
+    console.log("Retries:");
+    for (const retry of session.retries) {
+      const attempt = retry.attempt !== void 0 ? ` attempt=${retry.attempt}` : "";
+      const of = retry.retryOf !== void 0 ? ` retryOf=${retry.retryOf}` : "";
+      console.log(
+        `  ${retry.runId}${attempt}${of} (${retry.confidence})`
+      );
+    }
+  }
+  if (options.criticalPath && session.criticalPath.length > 0) {
+    console.log("");
+    console.log("Critical path:");
+    for (const step of session.criticalPath) {
+      const duration = step.durationMs !== void 0 ? ` ${step.durationMs}ms` : "";
+      console.log(
+        `  ${step.runId}${step.name ? ` (${step.name})` : ""}${duration} [${step.confidence}]`
+      );
+    }
+  }
+  if (options.diagnostics && index.warnings.length > 0) {
+    const scoped = index.warnings.filter(
+      (warning) => warning.sessionId === session.sessionId || !warning.sessionId
+    );
+    if (scoped.length > 0) {
+      console.log("");
+      console.log("Diagnostics:");
+      for (const warning of scoped) {
+        const run = warning.runId ? ` run=${warning.runId}` : "";
+        console.log(`  [${warning.code}]${run} ${warning.message}`);
+      }
+    }
+  }
+}
+async function sessionsCommand(options = {}) {
+  try {
+    const traceDir = resolveTraceDir({ dir: options.dir });
+    const index = await loadSessionIndex(traceDir, options.correlateGroup);
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            traceDir,
+            sessions: index.sessions,
+            unscopedRunIds: index.unscopedRunIds,
+            warnings: index.warnings
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    renderSessionsHuman(index, traceDir);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] sessions failed: ${msg}`);
+    process.exitCode = 1;
+  }
+}
+async function sessionCommand(sessionId, options = {}) {
+  const id = typeof sessionId === "string" && sessionId.trim() !== "" ? sessionId.trim() : "";
+  if (id === "") {
+    console.error("Session id is required");
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const traceDir = resolveTraceDir({ dir: options.dir });
+    const index = await loadSessionIndex(traceDir);
+    const session = findSession(index, id);
+    if (!session) {
+      console.log(`Session not found: ${id}`);
+      console.log(`Trace directory: ${traceDir}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (options.json) {
+      const timelines = {};
+      if (options.timeline) {
+        for (const runId of session.runIds) {
+          const result = await readRunTraceEvents(runId, traceDir);
+          if (result && result.events.length > 0) {
+            timelines[runId] = buildRunTimeline(result.events);
+          }
+        }
+      }
+      console.log(
+        JSON.stringify(
+          {
+            traceDir,
+            session,
+            warnings: index.warnings.filter(
+              (warning) => warning.sessionId === id || warning.sessionId === void 0
+            ),
+            ...options.timeline ? { timelines } : {}
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    renderSessionHuman(session, index, options);
+    if (options.timeline) {
+      for (const runId of session.runIds) {
+        const result = await readRunTraceEvents(runId, traceDir);
+        if (!result || result.events.length === 0) continue;
+        const timeline = buildRunTimeline(result.events);
+        console.log("");
+        console.log(`Timeline: ${runId}`);
+        console.log(renderTimeline(timeline));
+      }
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] session failed: ${msg}`);
+    process.exitCode = 1;
+  }
+}
+
 // packages/cli/src/what.ts
 async function whatCommand(runId, options = {}) {
   const id = typeof runId === "string" && runId.trim() !== "" ? runId.trim() : "";
@@ -9586,7 +10259,7 @@ function diagnostic(code, message, ruleId) {
     ...ruleId ? { ruleId } : {}
   };
 }
-function emptySummary() {
+function emptySummary2() {
   return {
     passed: 0,
     failed: 0,
@@ -9601,7 +10274,7 @@ function errorResult(input3, diagnostics, selectedRun) {
     format: input3.read.format,
     ...selectedRun ? { runId: selectedRun.runId } : {},
     summary: {
-      ...emptySummary(),
+      ...emptySummary2(),
       errors: diagnostics.filter((item) => item.severity === "error").length
     },
     findings: [],
@@ -10507,7 +11180,7 @@ function createSafetyRawContentRule(options = {}) {
 }
 function createSafetySecretPatternRule(options = {}) {
   const patterns = options.patterns ?? DEFAULT_SECRET_PATTERNS;
-  const maxStringLength = options.maxStringLength ?? 4096;
+  const maxStringLength2 = options.maxStringLength ?? 4096;
   return {
     id: "safety.secretPattern",
     category: "safety",
@@ -10517,7 +11190,7 @@ function createSafetySecretPatternRule(options = {}) {
       for (const event of context.events) {
         for (const entry of eventValueEntries(event, { includeSummaries: true, includeError: true })) {
           if (typeof entry.value !== "string") continue;
-          const sample = entry.value.slice(0, maxStringLength);
+          const sample = entry.value.slice(0, maxStringLength2);
           for (const pattern of patterns) {
             pattern.pattern.lastIndex = 0;
             if (!pattern.pattern.test(sample)) continue;
@@ -10773,6 +11446,621 @@ function runTraceChecks(input3, options = {}) {
     diagnostics
   };
 }
+var ALL_RULES = [
+  "circuit.same-tool-repetition",
+  "circuit.same-args-repetition",
+  "circuit.max-loop-iterations",
+  "circuit.max-retries",
+  "circuit.tool-timeout",
+  "circuit.runaway-llm-loop",
+  "circuit.excessive-branch-width"
+];
+function closed(ruleId, message) {
+  return { ruleId, status: "closed", severity: "info", message, evidence: [] };
+}
+function open2(ruleId, message, evidence, severity = "error") {
+  return {
+    ruleId,
+    status: severity === "warning" ? "warn" : "open",
+    severity,
+    message,
+    evidence
+  };
+}
+function isToolEvent(event) {
+  const name = event.name.toLowerCase();
+  return event.kind === "tool" || name.startsWith("tool:") || name.startsWith("function:") || name.includes(".tool.") || name.startsWith("mcp:");
+}
+function isLlmEvent(event) {
+  const name = event.name.toLowerCase();
+  return event.kind === "llm" || name.startsWith("llm:") || name.includes(".llm.") || name.includes("generation");
+}
+function toolLabel(event) {
+  const attrs = event.attributes ?? {};
+  const fromAttr = attrs.toolName ?? attrs.tool ?? attrs.function;
+  if (typeof fromAttr === "string" && fromAttr.length > 0) return fromAttr;
+  return event.name.replace(/^(tool:|function:|mcp:)/i, "");
+}
+function argsHash(toolName2, args) {
+  return createHash("sha256").update(`${toolName2}:${JSON.stringify(args ?? null)}`).digest("hex").slice(0, 16);
+}
+function toolArgs(event) {
+  const attrs = event.attributes ?? {};
+  return attrs.arguments ?? attrs.args ?? attrs.input ?? attrs.parameters;
+}
+function durationMs(event) {
+  if (typeof event.durationMs === "number") return event.durationMs;
+  const attrs = event.attributes ?? {};
+  const fromAttr = attrs.durationMs ?? attrs.duration;
+  return typeof fromAttr === "number" ? fromAttr : void 0;
+}
+function attemptNumber(event) {
+  const attrs = event.attributes ?? {};
+  const value = attrs.attempt ?? attrs.retryAttempt ?? attrs.retryCount;
+  return typeof value === "number" ? value : void 0;
+}
+function evaluateSameToolRepetition(events, maxRepeats) {
+  const ruleId = "circuit.same-tool-repetition";
+  const counts = /* @__PURE__ */ new Map();
+  for (const event of events.filter(isToolEvent)) {
+    const label = toolLabel(event);
+    counts.set(label, (counts.get(label) ?? 0) + 1);
+  }
+  const evidence = [];
+  for (const [toolName2, count] of counts) {
+    if (count > maxRepeats) {
+      evidence.push({ ruleId, toolName: toolName2, count, threshold: maxRepeats });
+    }
+  }
+  if (evidence.length === 0) {
+    return closed(ruleId, "Tool repetition within threshold.");
+  }
+  return open2(ruleId, "Same tool repeated beyond threshold.", evidence);
+}
+function evaluateSameArgsRepetition(events, maxRepeats) {
+  const ruleId = "circuit.same-args-repetition";
+  const counts = /* @__PURE__ */ new Map();
+  for (const event of events.filter(isToolEvent)) {
+    const label = toolLabel(event);
+    const hash = argsHash(label, toolArgs(event));
+    const key = `${label}:${hash}`;
+    const current = counts.get(key) ?? { toolName: label, count: 0 };
+    current.count += 1;
+    counts.set(key, current);
+  }
+  const evidence = [];
+  for (const entry of counts.values()) {
+    if (entry.count > maxRepeats) {
+      evidence.push({ ruleId, toolName: entry.toolName, count: entry.count, threshold: maxRepeats });
+    }
+  }
+  if (evidence.length === 0) {
+    return closed(ruleId, "Tool argument repetition within threshold.");
+  }
+  return open2(ruleId, "Same tool arguments repeated beyond threshold.", evidence);
+}
+function evaluateMaxLoopIterations(events, maxIterations) {
+  const ruleId = "circuit.max-loop-iterations";
+  const iterationEvents = events.filter((event) => {
+    const attrs = event.attributes ?? {};
+    return typeof attrs.iteration === "number" || event.name.toLowerCase().includes("loop");
+  });
+  const maxSeen = iterationEvents.reduce((max, event) => {
+    const attrs = event.attributes ?? {};
+    const iteration = typeof attrs.iteration === "number" ? attrs.iteration : max;
+    return Math.max(max, iteration);
+  }, iterationEvents.length);
+  if (maxSeen <= maxIterations) {
+    return closed(ruleId, "Loop iterations within threshold.");
+  }
+  return open2(ruleId, "Loop iterations exceeded threshold.", [
+    { ruleId, count: maxSeen, threshold: maxIterations }
+  ]);
+}
+function evaluateMaxRetries(events, maxRetries) {
+  const ruleId = "circuit.max-retries";
+  const attempts = events.map(attemptNumber).filter((value) => value !== void 0);
+  const maxAttempt = attempts.length > 0 ? Math.max(...attempts) : 0;
+  if (maxAttempt <= maxRetries) {
+    return closed(ruleId, "Retry count within threshold.");
+  }
+  return open2(ruleId, "Retry count exceeded threshold.", [
+    { ruleId, count: maxAttempt, threshold: maxRetries }
+  ]);
+}
+function evaluateToolTimeout(events, maxDurationMs) {
+  const ruleId = "circuit.tool-timeout";
+  const evidence = [];
+  for (const event of events.filter(isToolEvent)) {
+    const duration = durationMs(event);
+    if (duration !== void 0 && duration > maxDurationMs) {
+      evidence.push({
+        ruleId,
+        toolName: toolLabel(event),
+        count: duration,
+        threshold: maxDurationMs,
+        eventId: event.eventId
+      });
+    }
+  }
+  if (evidence.length === 0) {
+    return closed(ruleId, "Tool durations within timeout.");
+  }
+  return open2(ruleId, "Tool call exceeded configured timeout.", evidence, "warning");
+}
+function evaluateRunawayLlmLoop(events, maxLlmCalls) {
+  const ruleId = "circuit.runaway-llm-loop";
+  const llmCount = events.filter(isLlmEvent).length;
+  const hasTerminal = events.some((event) => {
+    const status = (event.status ?? event.attributes?.status ?? "").toString().toLowerCase();
+    return status === "ok" || status === "success" || status === "completed";
+  });
+  if (llmCount <= maxLlmCalls || hasTerminal) {
+    return closed(ruleId, "LLM call count within threshold or run completed.");
+  }
+  return open2(ruleId, "Runaway LLM loop detected.", [
+    { ruleId, count: llmCount, threshold: maxLlmCalls }
+  ]);
+}
+function evaluateExcessiveBranchWidth(events, maxWidth) {
+  const ruleId = "circuit.excessive-branch-width";
+  const children = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const parentId = event.parentId;
+    if (!parentId) continue;
+    children.set(parentId, (children.get(parentId) ?? 0) + 1);
+  }
+  const evidence = [];
+  for (const [parentId, count] of children) {
+    if (count > maxWidth) {
+      evidence.push({ ruleId, path: parentId, count, threshold: maxWidth });
+    }
+  }
+  if (evidence.length === 0) {
+    return closed(ruleId, "Branch width within threshold.");
+  }
+  return open2(ruleId, "Excessive parallel branch width detected.", evidence, "warning");
+}
+function runRule(ruleId, events, options) {
+  switch (ruleId) {
+    case "circuit.same-tool-repetition":
+      if (options.sameToolRepetition === void 0) return void 0;
+      return evaluateSameToolRepetition(events, options.sameToolRepetition.maxRepeats);
+    case "circuit.same-args-repetition":
+      if (options.sameArgsRepetition === void 0) return void 0;
+      return evaluateSameArgsRepetition(events, options.sameArgsRepetition.maxRepeats);
+    case "circuit.max-loop-iterations":
+      if (options.maxLoopIterations === void 0) return void 0;
+      return evaluateMaxLoopIterations(events, options.maxLoopIterations.maxIterations);
+    case "circuit.max-retries":
+      if (options.maxRetries === void 0) return void 0;
+      return evaluateMaxRetries(events, options.maxRetries.maxRetries);
+    case "circuit.tool-timeout":
+      if (options.toolTimeout === void 0) return void 0;
+      return evaluateToolTimeout(events, options.toolTimeout.maxDurationMs);
+    case "circuit.runaway-llm-loop":
+      if (options.runawayLlmLoop === void 0) return void 0;
+      return evaluateRunawayLlmLoop(events, options.runawayLlmLoop.maxLlmCalls);
+    case "circuit.excessive-branch-width":
+      if (options.excessiveBranchWidth === void 0) return void 0;
+      return evaluateExcessiveBranchWidth(events, options.excessiveBranchWidth.maxWidth);
+    default:
+      return void 0;
+  }
+}
+function runCircuits(events, options = {}) {
+  const selected = options.rules ?? ALL_RULES;
+  const results = [];
+  for (const ruleId of selected) {
+    const result = runRule(ruleId, events, options);
+    if (result) results.push(result);
+  }
+  const ok = !results.some((result) => result.status === "open" && result.severity === "error");
+  return { ok, results };
+}
+
+// packages/guardrails/src/rules.ts
+var DEFAULT_INJECTION_PATTERNS = [
+  "ignore previous instructions",
+  "ignore all prior",
+  "disregard your instructions",
+  "system prompt",
+  "you are now",
+  "jailbreak"
+];
+function pass(ruleId, message) {
+  return { ruleId, status: "pass", severity: "info", message, evidence: [] };
+}
+function fail(ruleId, message, evidence, severity = "error") {
+  return { ruleId, status: severity === "warning" ? "warn" : "fail", severity, message, evidence };
+}
+function boundedPreview(value, max = 80) {
+  if (value.length <= max) return value;
+  return `${value.slice(0, max - 3)}...`;
+}
+function evaluateBannedPhrase(text, options) {
+  const ruleId = "guardrail.banned-phrase";
+  const haystack = options.caseInsensitive !== false ? text.toLowerCase() : text;
+  const evidence = [];
+  for (const phrase of options.phrases) {
+    const needle = options.caseInsensitive !== false ? phrase.toLowerCase() : phrase;
+    if (needle.length > 0 && haystack.includes(needle)) {
+      evidence.push({ ruleId, match: phrase, preview: boundedPreview(text) });
+    }
+  }
+  if (evidence.length === 0) {
+    return pass(ruleId, "No banned phrases matched.");
+  }
+  return fail(ruleId, `Matched ${evidence.length} banned phrase(s).`, evidence);
+}
+var SEVERITY_RANK2 = { info: 0, warning: 1, error: 2 };
+function evaluatePiiLeak(value, options = {}) {
+  const ruleId = "guardrail.pii-leak";
+  const minSeverity = options.minSeverity ?? "warning";
+  const result = redact(value, { profile: options.profile ?? "share", collectFindings: true });
+  const findings = result.findings.filter(
+    (finding) => SEVERITY_RANK2[finding.severity] >= SEVERITY_RANK2[minSeverity]
+  );
+  if (findings.length === 0) {
+    return pass(ruleId, "No PII-style redaction findings.");
+  }
+  const evidence = findings.map((finding) => ({
+    ruleId,
+    path: finding.path,
+    detector: finding.detector,
+    preview: finding.preview
+  }));
+  return fail(ruleId, `Detected ${findings.length} PII-style finding(s).`, evidence);
+}
+function measureDepth(value) {
+  if (value === null || typeof value !== "object") return 0;
+  if (Array.isArray(value)) {
+    return 1 + Math.max(0, ...value.map((item) => measureDepth(item)));
+  }
+  const depths = Object.values(value).map((item) => measureDepth(item));
+  return 1 + (depths.length === 0 ? 0 : Math.max(...depths));
+}
+function maxStringLength(value) {
+  if (typeof value === "string") return value.length;
+  if (value === null || typeof value !== "object") return 0;
+  if (Array.isArray(value)) {
+    return Math.max(0, ...value.map((item) => maxStringLength(item)));
+  }
+  return Math.max(0, ...Object.values(value).map((item) => maxStringLength(item)));
+}
+function evaluateUnsafeToolArgs(toolName2, toolArgs2, options = {}) {
+  const ruleId = "guardrail.unsafe-tool-args";
+  const blocked = new Set((options.blockedTools ?? []).map((name) => name.toLowerCase()));
+  const evidence = [];
+  if (blocked.has(toolName2.toLowerCase())) {
+    evidence.push({ ruleId, preview: toolName2, match: toolName2 });
+  }
+  const maxDepth = options.maxDepth ?? 12;
+  const depth = measureDepth(toolArgs2);
+  if (depth > maxDepth) {
+    evidence.push({ ruleId, path: "args", preview: `depth=${depth}` });
+  }
+  const maxLen = options.maxStringLength ?? 16384;
+  const longest = maxStringLength(toolArgs2);
+  if (longest > maxLen) {
+    evidence.push({ ruleId, path: "args", preview: `maxStringLength=${longest}` });
+  }
+  if (evidence.length === 0) {
+    return pass(ruleId, "Tool arguments within configured bounds.");
+  }
+  return fail(ruleId, "Unsafe or oversized tool arguments detected.", evidence);
+}
+function evaluatePromptInjection(text, options = {}) {
+  const ruleId = "guardrail.prompt-injection";
+  const patterns = options.patterns ?? DEFAULT_INJECTION_PATTERNS;
+  const haystack = text.toLowerCase();
+  const evidence = [];
+  for (const pattern of patterns) {
+    const needle = pattern.toLowerCase();
+    if (needle.length > 0 && haystack.includes(needle)) {
+      evidence.push({ ruleId, match: pattern, preview: boundedPreview(text) });
+    }
+  }
+  if (evidence.length === 0) {
+    return pass(ruleId, "No prompt-injection patterns matched.");
+  }
+  return fail(ruleId, `Matched ${evidence.length} injection pattern(s).`, evidence, "warning");
+}
+function validateSchemaField(value, field, path15, 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: path15, preview: `expected ${field.type}, got ${actual}` });
+      return;
+    }
+  }
+  if (field.enum && !field.enum.some((item) => Object.is(item, value))) {
+    evidence.push({ ruleId, path: path15, 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: `${path15}.${key}`, preview: "missing required key" });
+      }
+    }
+  }
+}
+function evaluateStructuredOutput(value, options) {
+  const ruleId = "guardrail.structured-output";
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return fail(ruleId, "Structured output must be an object.", [
+      { ruleId, preview: typeof value }
+    ]);
+  }
+  const record = value;
+  const evidence = [];
+  for (const [key, field] of Object.entries(options.schema)) {
+    validateSchemaField(record[key], field, key, evidence);
+  }
+  if (evidence.length === 0) {
+    return pass(ruleId, "Structured output matches schema subset.");
+  }
+  return fail(ruleId, "Structured output schema violation.", evidence);
+}
+function evaluateOversizeOutput(value, options = {}) {
+  const ruleId = "guardrail.oversize-output";
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  const maxLength = options.maxLength ?? options.maxSerializedLength ?? 32768;
+  if (text.length <= maxLength) {
+    return pass(ruleId, "Output within size limits.");
+  }
+  return fail(ruleId, `Output exceeds max length (${text.length} > ${maxLength}).`, [
+    { ruleId, preview: `length=${text.length}` }
+  ]);
+}
+function evaluateRequiredJsonShape(value, options) {
+  const ruleId = "guardrail.required-json-shape";
+  let parsed = value;
+  if (typeof value === "string") {
+    try {
+      parsed = JSON.parse(value);
+    } catch {
+      return fail(ruleId, "Value is not valid JSON.", [{ ruleId, preview: boundedPreview(value) }]);
+    }
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return fail(ruleId, "JSON value must be an object.", [{ ruleId, preview: typeof parsed }]);
+  }
+  const record = parsed;
+  const evidence = [];
+  for (const key of options.requiredKeys) {
+    if (!(key in record)) {
+      evidence.push({ ruleId, path: key, preview: "missing required key" });
+    }
+  }
+  if (evidence.length === 0) {
+    return pass(ruleId, "Required JSON keys present.");
+  }
+  return fail(ruleId, "Missing required JSON keys.", evidence);
+}
+
+// packages/guardrails/src/run.ts
+var ALL_RULES2 = [
+  "guardrail.banned-phrase",
+  "guardrail.pii-leak",
+  "guardrail.unsafe-tool-args",
+  "guardrail.prompt-injection",
+  "guardrail.structured-output",
+  "guardrail.oversize-output",
+  "guardrail.required-json-shape"
+];
+function isErrorFailure(result) {
+  return result.status === "fail" && result.severity === "error";
+}
+function runRule2(ruleId, input3, options) {
+  switch (ruleId) {
+    case "guardrail.banned-phrase": {
+      if (!options.bannedPhrase || input3.text === void 0) return void 0;
+      return evaluateBannedPhrase(input3.text, options.bannedPhrase);
+    }
+    case "guardrail.pii-leak": {
+      if (input3.value === void 0 && input3.text === void 0) return void 0;
+      return evaluatePiiLeak(input3.value ?? input3.text, options.piiLeak);
+    }
+    case "guardrail.unsafe-tool-args": {
+      if (!input3.toolName) return void 0;
+      return evaluateUnsafeToolArgs(input3.toolName, input3.toolArgs ?? {}, options.unsafeToolArgs);
+    }
+    case "guardrail.prompt-injection": {
+      if (input3.text === void 0) return void 0;
+      return evaluatePromptInjection(input3.text, options.promptInjection);
+    }
+    case "guardrail.structured-output": {
+      if (!options.structuredOutput || input3.value === void 0) return void 0;
+      return evaluateStructuredOutput(input3.value, options.structuredOutput);
+    }
+    case "guardrail.oversize-output": {
+      if (input3.value === void 0 && input3.text === void 0) return void 0;
+      return evaluateOversizeOutput(input3.value ?? input3.text, options.oversizeOutput);
+    }
+    case "guardrail.required-json-shape": {
+      if (!options.requiredJsonShape || input3.value === void 0 && input3.text === void 0) return void 0;
+      return evaluateRequiredJsonShape(input3.value ?? input3.text, options.requiredJsonShape);
+    }
+    default:
+      return void 0;
+  }
+}
+function runGuardrails(input3, options = {}) {
+  const selected = options.rules ?? ALL_RULES2;
+  const results = [];
+  for (const ruleId of selected) {
+    const result = runRule2(ruleId, input3, options);
+    if (result) results.push(result);
+  }
+  const ok = !results.some(isErrorFailure);
+  return { ok, results };
+}
+
+// packages/cli/src/safety-extensions.ts
+var GUARDRAIL_ALIASES = {
+  "banned-phrase": "guardrail.banned-phrase",
+  "pii-leak": "guardrail.pii-leak",
+  "unsafe-tool-args": "guardrail.unsafe-tool-args",
+  "prompt-injection": "guardrail.prompt-injection",
+  "structured-output": "guardrail.structured-output",
+  "oversize-output": "guardrail.oversize-output",
+  "required-json-shape": "guardrail.required-json-shape"
+};
+var CIRCUIT_ALIASES = {
+  "same-tool-repetition": "circuit.same-tool-repetition",
+  "same-args-repetition": "circuit.same-args-repetition",
+  "max-loop-iterations": "circuit.max-loop-iterations",
+  "max-retries": "circuit.max-retries",
+  "tool-timeout": "circuit.tool-timeout",
+  "runaway-llm-loop": "circuit.runaway-llm-loop",
+  "excessive-branch-width": "circuit.excessive-branch-width"
+};
+function parseGuardrailRules(values) {
+  if (!values?.length) return void 0;
+  return values.map((value) => {
+    const rule = GUARDRAIL_ALIASES[value] ?? value;
+    return rule;
+  });
+}
+function parseCircuitRules(values) {
+  if (!values?.length) return void 0;
+  return values.map((value) => {
+    const rule = CIRCUIT_ALIASES[value] ?? value;
+    return rule;
+  });
+}
+function toSeverity(severity) {
+  return severity;
+}
+function guardrailFinding(result) {
+  return {
+    ruleId: result.ruleId,
+    severity: toSeverity(result.severity),
+    status: result.status === "pass" ? "pass" : result.status === "warn" ? "warning" : "fail",
+    message: result.message,
+    evidence: result.evidence.map(
+      (item) => ({
+        path: item.preview ? `${item.path ?? "value"} (${item.preview})` : item.path
+      })
+    )
+  };
+}
+function circuitFinding(result) {
+  return {
+    ruleId: result.ruleId,
+    severity: toSeverity(result.severity),
+    status: result.status === "closed" ? "pass" : result.status === "warn" ? "warning" : "fail",
+    message: result.message,
+    evidence: result.evidence.map(
+      (item) => ({
+        runId: item.runId,
+        eventId: item.eventId,
+        path: item.path,
+        name: item.toolName
+      })
+    ),
+    actual: result.evidence[0]?.count,
+    expected: result.evidence[0]?.threshold
+  };
+}
+function eventToCircuit(event) {
+  return {
+    eventId: event.eventId,
+    runId: event.runId,
+    name: event.name,
+    kind: event.kind,
+    parentId: event.parentId,
+    startedAt: event.startedAt,
+    endedAt: event.endedAt,
+    durationMs: event.durationMs,
+    attributes: event.attributes,
+    status: event.status
+  };
+}
+function collectGuardrailInputs(read) {
+  const inputs = [];
+  for (const event of read.events) {
+    const attrs = event.attributes ?? {};
+    for (const key of ["output", "answer", "text", "content", "message"]) {
+      const value = attrs[key];
+      if (typeof value === "string") inputs.push({ text: value });
+      else if (value !== void 0) inputs.push({ value });
+    }
+    if (event.kind === "TOOL" || event.name.startsWith("tool:")) {
+      inputs.push({
+        toolName: String(attrs.toolName ?? attrs.tool ?? event.name),
+        toolArgs: attrs.arguments ?? attrs.args ?? attrs.input
+      });
+    }
+  }
+  return inputs;
+}
+var DEFAULT_GUARDRAIL_OPTIONS = {
+  bannedPhrase: { phrases: ["delete all data", "ignore all instructions"] },
+  promptInjection: {},
+  piiLeak: { profile: "share" }
+};
+var DEFAULT_CIRCUIT_OPTIONS = {
+  sameToolRepetition: { maxRepeats: 3 },
+  sameArgsRepetition: { maxRepeats: 2 },
+  maxLoopIterations: { maxIterations: 20 },
+  maxRetries: { maxRetries: 3 },
+  toolTimeout: { maxDurationMs: 6e4 },
+  runawayLlmLoop: { maxLlmCalls: 12 },
+  excessiveBranchWidth: { maxWidth: 8 }
+};
+function mergeSafetyExtensions(result, read, options) {
+  const findings = [...result.findings];
+  let failed = result.summary.failed;
+  let warnings = result.summary.warnings;
+  let passed = result.summary.passed;
+  const guardrailRules = parseGuardrailRules(options.guardrails);
+  if (guardrailRules) {
+    for (const input3 of collectGuardrailInputs(read)) {
+      const run = runGuardrails(input3, {
+        ...DEFAULT_GUARDRAIL_OPTIONS,
+        rules: guardrailRules
+      });
+      for (const item of run.results) {
+        const finding = guardrailFinding(item);
+        findings.push(finding);
+        if (finding.status === "fail") failed += 1;
+        else if (finding.status === "warning") warnings += 1;
+        else passed += 1;
+      }
+    }
+  }
+  const circuitRules = parseCircuitRules(options.circuits);
+  if (circuitRules) {
+    const circuitRun = runCircuits(
+      read.events.map(eventToCircuit),
+      { ...DEFAULT_CIRCUIT_OPTIONS, rules: circuitRules }
+    );
+    for (const item of circuitRun.results) {
+      const finding = circuitFinding(item);
+      findings.push(finding);
+      if (finding.status === "fail") failed += 1;
+      else if (finding.status === "warning") warnings += 1;
+      else passed += 1;
+    }
+  }
+  const ok = failed === 0 && result.summary.errors === 0;
+  return {
+    ...result,
+    ok,
+    status: failed > 0 ? "fail" : result.status,
+    summary: {
+      passed,
+      failed,
+      warnings,
+      errors: result.summary.errors
+    },
+    findings
+  };
+}
 
 // packages/cli/src/check.ts
 var DEFAULT_SELECT = ["run.status"];
@@ -10942,6 +12230,13 @@ function printJson(result) {
   console.log(JSON.stringify(stable2(result), null, 2));
 }
 function printHuman(result) {
+  const scoped = result;
+  if (scoped.scopeLabel) {
+    console.log(`Scope: ${scoped.scopeKind} ${scoped.scopeLabel}`);
+    if (scoped.runIds?.length) {
+      console.log(`Runs: ${scoped.runIds.join(", ")}`);
+    }
+  }
   console.log(`Check status: ${result.status}`);
   console.log(`Format: ${result.format}`);
   if (result.runId !== void 0) console.log(`Run: ${result.runId}`);
@@ -10953,7 +12248,9 @@ function printHuman(result) {
   }
   for (const finding of result.findings) {
     const path15 = finding.evidence[0]?.path;
-    console.log(`- ${finding.ruleId}: ${finding.message}${path15 ? ` (${path15})` : ""}`);
+    const run = finding.evidence[0]?.runId;
+    const runPrefix = run ? `[${run}] ` : "";
+    console.log(`- ${runPrefix}${finding.ruleId}: ${finding.message}${path15 ? ` (${path15})` : ""}`);
   }
 }
 function readErrorResult(error) {
@@ -10969,24 +12266,84 @@ function readErrorResult(error) {
 async function checkCommand(target, options = {}, stdin = process.stdin) {
   let result;
   let phase = "config";
+  const sessionId = options.session?.trim();
+  const groupId = options.group?.trim();
+  const useSessionScope = Boolean(sessionId || groupId);
   try {
     const config = await loadConfig(options.config);
     const built = buildRules(config, options);
     if (built.diagnostics.some((item) => item.severity === "error")) {
       result = errorResult2("AI_CHECK_INVALID_CONFIG", "Invalid check configuration.");
       result.diagnostics = [...built.diagnostics];
+    } else if (useSessionScope) {
+      phase = "read";
+      const traceDir = resolveTraceDir({ dir: options.dir });
+      const td = new TraceDirectory({ dir: traceDir });
+      const files = await td.list();
+      const metas = await loadTraceMetadataList(
+        traceDir,
+        files,
+        (fileName) => td.getPath(fileName)
+      );
+      const records = await loadSessionRunRecords(metas);
+      const scoped = filterMetasBySessionScope(metas, records, {
+        ...sessionId ? { sessionId } : {},
+        ...groupId ? { groupId } : {},
+        correlateByGroupId: options.correlateGroup === true
+      });
+      const perRun = [];
+      for (const meta of scoped.metas) {
+        const read = await openTrace(
+          { type: "file", path: meta.filePath },
+          {
+            ...options.format !== void 0 ? { format: options.format } : {}
+          }
+        );
+        perRun.push(
+          mergeSafetyExtensions(
+            runTraceChecks(
+              { read },
+              {
+                rules: built.rules,
+                select: built.select,
+                runId: meta.runId
+              }
+            ),
+            read,
+            {
+              ...options.guardrails ? { guardrails: options.guardrails } : {},
+              ...options.circuit ? { circuits: options.circuit } : {}
+            }
+          )
+        );
+      }
+      result = aggregateSessionCheckResults(perRun, {
+        scopeKind: scoped.scopeKind,
+        scopeLabel: scoped.scopeLabel,
+        runIds: scoped.runIds,
+        sessionWarnings: scoped.warnings,
+        notFound: scoped.notFound,
+        empty: scoped.metas.length === 0
+      });
     } else {
       phase = "read";
       const input3 = await inputFromTarget(target, options, stdin);
       const read = await openTrace(input3, {
         ...options.format !== void 0 ? { format: options.format } : {}
       });
-      result = runTraceChecks(
-        { read },
+      result = mergeSafetyExtensions(
+        runTraceChecks(
+          { read },
+          {
+            rules: built.rules,
+            select: built.select,
+            ...options.run !== void 0 ? { runId: options.run } : {}
+          }
+        ),
+        read,
         {
-          rules: built.rules,
-          select: built.select,
-          ...options.run !== void 0 ? { runId: options.run } : {}
+          ...options.guardrails ? { guardrails: options.guardrails } : {},
+          ...options.circuit ? { circuits: options.circuit } : {}
         }
       );
     }
@@ -11190,7 +12547,7 @@ function evidenceForEvent(event, path15) {
     }
   ];
 }
-function fail(ruleId, message, evidence, expected, actual) {
+function fail2(ruleId, message, evidence, expected, actual) {
   return {
     ruleId,
     status: "fail",
@@ -11386,7 +12743,7 @@ var checks = {
       "eval.requireSuccess",
       "run",
       (context) => context.run.status === "ok" ? [] : [
-        fail(
+        fail2(
           "eval.requireSuccess",
           "Run did not complete successfully.",
           evidenceForRun(context.run, "status"),
@@ -11401,7 +12758,7 @@ var checks = {
     return createRule("eval.requiredTools", "tool", (context) => {
       const tools = new Set(nodeNames(context.nodes, "TOOL"));
       return expected.filter((name) => !tools.has(name)).map(
-        (name) => fail(
+        (name) => fail2(
           "eval.requiredTools",
           `Required tool ${name} did not appear.`,
           evidenceForRun(context.run, "children"),
@@ -11417,7 +12774,7 @@ var checks = {
       "eval.forbiddenTools",
       "tool",
       (context) => context.nodes.filter((node) => node.event.kind === "TOOL" && blocked.includes(node.event.name)).map(
-        (node) => fail(
+        (node) => fail2(
           "eval.forbiddenTools",
           `Forbidden tool ${node.event.name} appeared.`,
           evidenceForEvent(node.event, "name"),
@@ -11432,7 +12789,7 @@ var checks = {
       "eval.maxDurationMs",
       "run",
       (context) => context.run.durationMs !== void 0 && context.run.durationMs > maxDurationMs ? [
-        fail(
+        fail2(
           "eval.maxDurationMs",
           `Run duration exceeded ${maxDurationMs}ms.`,
           evidenceForRun(context.run, "durationMs"),
@@ -11449,7 +12806,7 @@ var checks = {
         void 0
       );
       return deepest !== void 0 && deepest.depth > maxDepth ? [
-        fail(
+        fail2(
           "eval.maxDepth",
           `Run tree depth exceeded ${maxDepth}.`,
           evidenceForEvent(deepest.event, "depth"),
@@ -11466,7 +12823,7 @@ var checks = {
       (context) => context.nodes.flatMap((node) => {
         const retries = numericAttribute(node, ["retryCount", "retries", "attempt"]);
         return retries !== void 0 && retries > maxRetries ? [
-          fail(
+          fail2(
             "eval.maxRetries",
             `Retry count exceeded ${maxRetries}.`,
             evidenceForEvent(node.event, "attributes.retryCount"),
@@ -11481,7 +12838,7 @@ var checks = {
     return createRule("eval.maxTotalTokens", "llm", (context) => {
       const total = totalTokenCount(context.events);
       return total > maxTotalTokens ? [
-        fail(
+        fail2(
           "eval.maxTotalTokens",
           `Total token usage exceeded ${maxTotalTokens}.`,
           evidenceForRun(context.run, "tokenUsage.total"),
@@ -11496,7 +12853,7 @@ var checks = {
       "eval.noFailedSteps",
       "run",
       (context) => context.nodes.filter((node) => node.event.status === "error" || node.event.kind === "ERROR").map(
-        (node) => fail(
+        (node) => fail2(
           "eval.noFailedSteps",
           "Run contains a failed step or error node.",
           evidenceForEvent(node.event, "status"),
@@ -11514,7 +12871,7 @@ var checks = {
         (node, index) => index < firstLlmIndex && node.event.kind === "RETRIEVER"
       );
       return retrievalIndex === -1 ? [
-        fail(
+        fail2(
           "eval.requiredRetrievalBeforeGeneration",
           "No retrieval step appeared before the first LLM generation.",
           evidenceForEvent(context.nodes[firstLlmIndex].event, "kind"),
@@ -11530,7 +12887,7 @@ var checks = {
       const decisions = context.nodes.filter((node) => node.event.kind === "DECISION");
       if (decisions.length === 0) {
         return [
-          fail(
+          fail2(
             "eval.requiredDecisionMetadata",
             "No decision node is available for required metadata.",
             evidenceForRun(context.run, "children"),
@@ -11541,7 +12898,7 @@ var checks = {
       }
       return decisions.flatMap(
         (node) => required.filter((key) => !hasAttribute(node, key)).map(
-          (key) => fail(
+          (key) => fail2(
             "eval.requiredDecisionMetadata",
             `Decision metadata ${key} is missing.`,
             evidenceForEvent(node.event, `attributes.${key}`),
@@ -11562,7 +12919,7 @@ var checks = {
       const contexts = collectTextFields(context.nodes, contextKeys, ["RETRIEVER", "TOOL"]);
       if (answers.length === 0 || contexts.length === 0) {
         return [
-          fail(
+          fail2(
             "eval.contextOverlap",
             "Answer and context text are required for overlap evaluation.",
             firstEvidence(answers.length > 0 ? answers : contexts, context.run, "children"),
@@ -11576,7 +12933,7 @@ var checks = {
       const sharedTerms = [...answerTerms].filter((term) => contextTerms.has(term)).length;
       const overlap = answerTerms.size === 0 ? 0 : sharedTerms / answerTerms.size;
       return sharedTerms < minSharedTerms || overlap < minOverlap ? [
-        fail(
+        fail2(
           "eval.contextOverlap",
           "Answer text did not sufficiently overlap retrieved context.",
           firstEvidence(answers, context.run, "attributes.answer"),
@@ -11604,7 +12961,7 @@ var checks = {
       const quotes = quotedSnippets(answerText, minQuoteLength);
       if (quotes.length === 0) {
         return requireQuote ? [
-          fail(
+          fail2(
             "eval.quoteOverlap",
             "Answer did not contain a quote for overlap evaluation.",
             firstEvidence(answers, context.run, "attributes.answer"),
@@ -11615,7 +12972,7 @@ var checks = {
       }
       const missing = quotes.filter((quote) => !contextText.includes(quote.toLowerCase()));
       return missing.length > 0 ? [
-        fail(
+        fail2(
           "eval.quoteOverlap",
           "Quoted answer text did not appear in retrieved context.",
           firstEvidence(answers, context.run, "attributes.answer"),
@@ -11633,7 +12990,7 @@ var checks = {
       const citations = collectTextFields(context.nodes, citationKeys);
       const count = citationCount(answers.map((field) => field.text).join(" "), citations);
       return count === 0 ? [
-        fail(
+        fail2(
           "eval.citationPresence",
           "Answer did not include citations or source references.",
           firstEvidence(answers, context.run, "attributes.answer"),
@@ -11651,7 +13008,7 @@ var checks = {
       const availableSet = new Set(available);
       const missing = expected.filter((id) => !availableSet.has(id));
       return missing.length > 0 ? [
-        fail(
+        fail2(
           "eval.requiredSourceIds",
           "Required source IDs were not present in trace context or citations.",
           evidenceForRun(context.run, "children"),
@@ -11671,7 +13028,7 @@ var checks = {
       const tooShort = options.minCharacters !== void 0 && characters < options.minCharacters || options.minWords !== void 0 && words < options.minWords;
       const tooLong = options.maxCharacters !== void 0 && characters > options.maxCharacters || options.maxWords !== void 0 && words > options.maxWords;
       return answer.length === 0 || tooShort || tooLong ? [
-        fail(
+        fail2(
           "eval.answerLengthBounds",
           "Answer length fell outside required bounds.",
           firstEvidence(answers, context.run, "attributes.answer"),
@@ -11694,7 +13051,7 @@ var checks = {
       const answer = answers.map((field) => field.text).join(" ").toLowerCase();
       const matches = banned.filter((phrase) => answer.includes(phrase));
       return matches.length > 0 ? [
-        fail(
+        fail2(
           "eval.bannedUnsupportedPhrases",
           "Answer contained banned unsupported-answer phrasing.",
           firstEvidence(answers, context.run, "attributes.answer"),
@@ -12072,7 +13429,7 @@ function invalidArgumentResult(command, error) {
   });
 }
 function buildSafetyRules(options) {
-  const maxStringLength = parseLimit3(options.maxStringLength, "--max-string-length") ?? DEFAULT_MAX_STRING_LENGTH;
+  const maxStringLength2 = parseLimit3(options.maxStringLength, "--max-string-length") ?? DEFAULT_MAX_STRING_LENGTH;
   const maxArrayLength = parseLimit3(options.maxArrayLength, "--max-array-length") ?? DEFAULT_MAX_ARRAY_LENGTH;
   const maxObjectKeys = parseLimit3(options.maxObjectKeys, "--max-object-keys") ?? DEFAULT_MAX_OBJECT_KEYS;
   const maxSerializedBytes = parseLimit3(options.maxSerializedBytes, "--max-serialized-bytes") ?? DEFAULT_MAX_SERIALIZED_BYTES;
@@ -12081,7 +13438,7 @@ function buildSafetyRules(options) {
     createSafetyRedactionRule(),
     createSafetySecretPatternRule(),
     createSafetyOversizedAttributeRule({
-      maxStringLength,
+      maxStringLength: maxStringLength2,
       maxArrayLength,
       maxObjectKeys,
       maxSerializedBytes
@@ -12962,7 +14319,18 @@ function createCliProgram() {
   ]).option("--allowed-model <model>", "allow an LLM model (repeatable)", (value, previous = []) => [
     ...previous,
     value
-  ]).option("--max-total-tokens <number>", "add llm.usage with a max total-token budget").action((target, opts) => {
+  ]).option("--max-total-tokens <number>", "add llm.usage with a max total-token budget").option("--session <id>", "check all runs in a workflow session (requires --dir)").option("--group <id>", "check all runs sharing a groupId (requires --dir)").option(
+    "--correlate-group",
+    "when using --session, also match synthetic group: session keys"
+  ).option(
+    "--guardrails <rule>",
+    "run optional guardrail rules (repeatable): banned-phrase, pii-leak, prompt-injection, ...",
+    (value, previous = []) => [...previous, value]
+  ).option(
+    "--circuit <rule>",
+    "run optional circuit rules (repeatable): same-tool-repetition, max-retries, ...",
+    (value, previous = []) => [...previous, value]
+  ).action((target, opts) => {
     runCommand(() => checkCommand(target, opts));
   });
   program.command("eval").description("Run deterministic local evals against a trace").argument("<trace-path-or-run-id>", "trace file, directory, stdin -, or run id").option("--dir <path>", "trace directory for run-id lookup").addOption(
@@ -13066,9 +14434,21 @@ function createCliProgram() {
   ).option("--kind <kind>", "filter by step kind/type (llm, tool, logic, \u2026)").option("--type <type>", "alias for --kind on manual trace step type").option("--name <query>", "substring match on run or step name").option("--tool <query>", "substring match on tool step name or metadata.toolName").option(
     "--duration <expr>",
     "duration filter on run or step (e.g. >5s, >=500ms)"
-  ).option("--limit <number>", "max results (default 50)").option("--json", "print results as JSON").action((opts) => {
+  ).option("--limit <number>", "max results (default 50)").option("--session <id>", "limit search to one workflow session").option(
+    "--correlate-group",
+    "when using --session, also match synthetic group: keys"
+  ).option("--json", "print results as JSON").action((opts) => {
     runCommand(() => searchCommand(opts));
   });
+  program.command("sessions").description("List workflow sessions grouped from local trace metadata (read-only)").option("--dir <path>", "trace directory").option(
+    "--correlate-group",
+    "treat shared groupId as a synthetic session when sessionId is absent"
+  ).option("--json", "print sessions index as JSON").action((opts) => {
+    runCommand(() => sessionsCommand(opts));
+  });
+  program.command("session").description("Inspect one workflow session: runs, handoffs, retries (read-only)").argument("<session-id>", "session id (from sessions output)").option("--dir <path>", "trace directory").option("--timeline", "include per-run timelines").option("--critical-path", "include critical path section").option("--diagnostics", "include ambiguity warnings").option("--json", "print session view as JSON").action((sessionId, opts) => {
+    runCommand(() => sessionCommand(sessionId, opts));
+  });
   program.command("what").description("Concise human-readable summary of a single run (local JSONL)").argument("<run-id>", "run id (e.g. from list output)").option("--dir <path>", "trace directory").option("--json", "print structured summary as JSON").option("--no-correlation", "omit correlation metadata from human output").action((runId, opts) => {
     runCommand(() => whatCommand(runId, opts));
   });