agent-inspect 6.29.5 → 6.30.0

package/packages/cli/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { ATTRIBUTION_CONFIDENCES, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createSafetyOversizedAttributeRule, resolveTraceDir, parseDuration, buildSessionIndex, resolveBundleRunIds, getTraceFilePath, openTrace, sha256Hex, collectTraceSchemaVersions, aggregateBundleSafeStatus, bundleFailsOnSafety, bundleRunAssetRelativePath, buildPlaceholderArtifact, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceHtmlShell, buildEvidenceProvenanceViewHtml, EVIDENCE_FORMAT_VERSION, inferEvidenceFileRole, buildEvidenceSafetyViewHtml, buildEvidenceDiffViewHtml, buildEvidenceCircuitViewHtml, buildEvidenceOutcomesViewHtml, buildEvidenceContractsViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceCausalFailureViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceTreeViewHtml, buildEvidenceManifest, serializeEvidenceManifest, buildZipArchive, assertBundlePathContained, enrichSessionRunRecord, normalizeBundleOutputPath, sanitizeBundleRunId, defaultBundleOutputPath, runTraceChecks, assertEvidenceRelativePath, TraceDirectory, loadTraceMetadataList, loadSessionRunRecords, TraceReadError, resolveRedactionProfile, applyProfileMetadataCaps, Redactor, flattenTree, escapeHtml, safeString, compactAttributes, stableJson, escapeMarkdown, truncateStringForProfile, extractMetadata, filterTraces, truncateName, buildRunSummary, formatDuration, formatTimestamp, renderErrorLine, isAgentInspectTrace, filterMetasBySessionScope, aggregateSessionCheckResults, createBaselineRegressionRule, summarizeSemanticParity, buildEvidenceCiPackage, verifyEvidenceDirectory, diffTraceEvents, renderRunDiff, buildRunTimeline, renderTimeline, buildTraceStats, renderTraceStats, parseDurationFilter, searchTraces, formatStepLabel, buildActivitySummary, renderActivitySummaryHuman, buildRunWhatSummary, renderRunWhat, buildLocalExplanation, resolveSuiteTemplate, defaultSuiteConfigTemplate, loadSuiteConfig, validateSuiteConfig, runSuite, renderSuiteReport, analyzeCohort, renderCohortReport, gateHasThresholds, runGate, renderGateReport, persistedInspectEventsToTraceEvents, renderStepLine, getIndent, TreeBuilder, zeroKinds, validateEvent, traceEventToPersistedInspectEvent, isPersistedInspectEvent, createRunStatusRule, createStructureOrphanRule, createStructureCycleRule, createRunDurationRule, createMaxStepDurationRule, createRequireCompletedRule, createStallDetectionRule, createObservedOutcomeRule, createRunDepthRule, createToolUsageRule, createLlmUsageRule, createStructureRelationshipRule, createStructureParallelWidthRule, projectLogicalEvents, summarizeObservedOutcomes, extractOutcomesFromTraceEvents, renderObservedOutcomesMarkdown, renderObservedOutcomesHtml, DEFAULT_SUITE_ARTIFACTS_DIR, parseCohortMetricList, COHORT_METRIC_IDS, parseGateList, nanoid, isAttributionConfidence, diffRuns, manualTraceEventsToComparableRun } from './chunk-XWQEHKGB.mjs';
+import { ATTRIBUTION_CONFIDENCES, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createSafetyOversizedAttributeRule, resolveTraceDir, parseDuration, buildSessionIndex, resolveBundleRunIds, getTraceFilePath, openTrace, sha256Hex, collectTraceSchemaVersions, aggregateBundleSafeStatus, bundleFailsOnSafety, bundleRunAssetRelativePath, buildPlaceholderArtifact, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceHtmlShell, buildEvidenceProvenanceViewHtml, EVIDENCE_FORMAT_VERSION, inferEvidenceFileRole, buildEvidenceSafetyViewHtml, buildEvidenceDiffViewHtml, buildEvidenceCircuitViewHtml, buildEvidenceOutcomesViewHtml, buildEvidenceContractsViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceCausalFailureViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceTreeViewHtml, buildEvidenceManifest, serializeEvidenceManifest, buildZipArchive, assertBundlePathContained, enrichSessionRunRecord, normalizeBundleOutputPath, sanitizeBundleRunId, defaultBundleOutputPath, runTraceChecks, assertEvidenceRelativePath, TraceDirectory, loadTraceMetadataList, loadSessionRunRecords, TraceReadError, resolveRedactionProfile, applyProfileMetadataCaps, Redactor, flattenTree, escapeHtml, safeString, compactAttributes, stableJson, escapeMarkdown, truncateStringForProfile, extractMetadata, filterTraces, truncateName, buildRunSummary, formatDuration, formatTimestamp, renderErrorLine, isAgentInspectTrace, defineTraceContract, filterMetasBySessionScope, evaluateTraceContract, aggregateSessionCheckResults, createBaselineRegressionRule, summarizeSemanticParity, buildEvidenceCiPackage, verifyEvidenceDirectory, diffTraceEvents, renderRunDiff, buildRunTimeline, renderTimeline, buildTraceStats, renderTraceStats, parseDurationFilter, searchTraces, formatStepLabel, buildActivitySummary, renderActivitySummaryHuman, buildRunWhatSummary, renderRunWhat, buildLocalExplanation, resolveSuiteTemplate, defaultSuiteConfigTemplate, loadSuiteConfig, validateSuiteConfig, runSuite, renderSuiteReport, analyzeCohort, renderCohortReport, gateHasThresholds, runGate, renderGateReport, persistedInspectEventsToTraceEvents, renderStepLine, getIndent, TreeBuilder, zeroKinds, validateEvent, traceEventToPersistedInspectEvent, isPersistedInspectEvent, createRunStatusRule, createStructureOrphanRule, createStructureCycleRule, createRunDurationRule, createMaxStepDurationRule, createRequireCompletedRule, createStallDetectionRule, createObservedOutcomeRule, createRunDepthRule, createToolUsageRule, createLlmUsageRule, createStructureRelationshipRule, createStructureParallelWidthRule, projectLogicalEvents, summarizeObservedOutcomes, extractOutcomesFromTraceEvents, renderObservedOutcomesMarkdown, renderObservedOutcomesHtml, DEFAULT_SUITE_ARTIFACTS_DIR, parseCohortMetricList, COHORT_METRIC_IDS, parseGateList, nanoid, isAttributionConfidence, diffRuns, manualTraceEventsToComparableRun } from './chunk-BDRJENLM.mjs';
 import { realpathSync, constants as constants$1, existsSync, readFileSync } from 'fs';
 import path19 from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
@@ -13,7 +13,7 @@ import { createServer } from 'http';
 import { createRequire } from 'module';
 
 // package.json
-var version = "6.29.5";
+var version = "6.30.0";
 
 // packages/cli/src/trace-dir-scale.ts
 var TRACE_COUNT_WARN = 1e3;
@@ -3397,7 +3397,7 @@ async function newestTraceMtimeMs(traceDir) {
 }
 async function loadSessionRuns(traceDir) {
   try {
-    const mod = await import('./src-XNC4EUN3.mjs');
+    const mod = await import('./src-ZUGAUXY6.mjs');
     const dbPath = mod.resolveIndexDbPath(traceDir);
     const status = mod.indexStatus(dbPath);
     if (!status.healthy) {
@@ -5855,7 +5855,8 @@ async function writeLocalEvidence(input3) {
     redactionProfile: profile,
     assessmentStatus,
     checkResultsJson: input3.checkResultsJson,
-    ...input3.summaryText !== void 0 ? { summaryText: input3.summaryText } : {}
+    ...input3.summaryText !== void 0 ? { summaryText: input3.summaryText } : {},
+    ...input3.contractPackage !== void 0 ? { contractPackage: input3.contractPackage } : {}
   });
   const files = [
     ["evidence.html", evidencePackage["evidence.html"]],
@@ -5863,6 +5864,10 @@ async function writeLocalEvidence(input3) {
     ["check-results.json", evidencePackage["check-results.json"]],
     ["trace.jsonl", evidencePackage["trace.jsonl"]]
   ];
+  const resolvedContract = evidencePackage["contract.resolved.json"];
+  if (resolvedContract !== void 0) {
+    files.push(["contract.resolved.json", resolvedContract]);
+  }
   const expected = createEvidenceCiArtifacts({
     redactionProfile: profile
   }).map((a) => a.path);
@@ -6824,6 +6829,131 @@ function asStringArray(value) {
   return value;
 }
 var CHECKS_KEYS = /* @__PURE__ */ new Set(["select", "run", "tool", "llm", "structure", "safety"]);
+var ROOT_CONFIG_KEYS = /* @__PURE__ */ new Set(["checks", "contract"]);
+var CONTRACT_KEYS = /* @__PURE__ */ new Set([
+  "run",
+  "tools",
+  "llm",
+  "observations",
+  "scope",
+  "alternatives",
+  "controls",
+  "retry"
+]);
+var CONTRACT_BODY_KEYS = /* @__PURE__ */ new Set([
+  "run",
+  "tools",
+  "llm",
+  "observations",
+  "controls",
+  "retry"
+]);
+var CONTRACT_SCOPE_KEYS = /* @__PURE__ */ new Set([
+  "runId",
+  "subAgentId",
+  "groupId",
+  "workflowStep",
+  "rootEventId"
+]);
+var CONTRACT_RUN_KEYS = /* @__PURE__ */ new Set(["requireCompleted", "allowedStatuses", "maxDurationMs"]);
+var CONTRACT_TOOLS_KEYS = /* @__PURE__ */ new Set([
+  "required",
+  "requiredTools",
+  "forbidden",
+  "forbiddenTools",
+  "allowed",
+  "maxCalls",
+  "requiredOrder",
+  "requiredOrderMode",
+  "arguments",
+  "orderRules",
+  "defaultOccurrenceMode"
+]);
+var CONTRACT_LLM_KEYS = /* @__PURE__ */ new Set(["maxCalls", "maxTotalTokens", "allowedModels"]);
+var CONTRACT_OBSERVATION_KEYS = /* @__PURE__ */ new Set(["required", "failOn", "requireProvenance"]);
+var CONTRACT_PROVENANCE_KEYS = /* @__PURE__ */ new Set(["method", "evidence", "sameRunEventReference"]);
+var CONTRACT_CONTROLS_KEYS = /* @__PURE__ */ new Set([
+  "declaredTools",
+  "enforcedTools",
+  "declaredToolsAttribute",
+  "enforcedToolsAttribute",
+  "requireDeclaredMatchesEnforced",
+  "requireObservedWithinEnforced",
+  "requireObservedWithinDeclared",
+  "requiredStages"
+]);
+var CONTRACT_CONTROL_STAGES = /* @__PURE__ */ new Set([
+  "declared",
+  "presented",
+  "validated",
+  "enforced",
+  "observed",
+  "accepted"
+]);
+var CONTRACT_CONTROL_STAGE_KEYS = /* @__PURE__ */ new Set(["stage", "observation"]);
+var CONTRACT_RETRY_KEYS = /* @__PURE__ */ new Set([
+  "maxAttempts",
+  "requireTerminalResult",
+  "fallbackOnlyAfterFailure",
+  "nonIdempotentTools",
+  "requireIdempotencyEvidenceForRetry",
+  "requireRecoveredFailureVisible",
+  "operations"
+]);
+var CONTRACT_OPERATION_KEYS = /* @__PURE__ */ new Set([
+  "tool",
+  "maxAttempts",
+  "retryableErrors",
+  "requireFailureBeforeRetry",
+  "requireSameArguments",
+  "requireTerminalSuccess",
+  "requireRecoveredFailureVisible",
+  "successfulResultDependency",
+  "sideEffectClass"
+]);
+var CONTRACT_RETRYABLE_ERRORS_KEYS = /* @__PURE__ */ new Set(["codes"]);
+var CONTRACT_RESULT_DEP_KEYS = /* @__PURE__ */ new Set(["consumerKind", "requireExplicitReference"]);
+var CONTRACT_ALT_KEYS = /* @__PURE__ */ new Set(["anyOf"]);
+var CONTRACT_ALT_BRANCH_KEYS = /* @__PURE__ */ new Set(["id", "description", "contract"]);
+var CONTRACT_ORDER_RULE_KEYS = /* @__PURE__ */ new Set([
+  "before",
+  "after",
+  "occurrenceMode",
+  "requireEndpoints"
+]);
+var CONTRACT_ARGUMENT_KEYS = /* @__PURE__ */ new Set([
+  "tool",
+  "path",
+  "operator",
+  "occurrence",
+  "expected",
+  "oneOf",
+  "type"
+]);
+var CONTRACT_ARGUMENT_OPERATORS = /* @__PURE__ */ new Set(["exists", "type", "equals", "oneOf"]);
+var CONTRACT_ARGUMENT_OCCURRENCES = /* @__PURE__ */ new Set(["first", "last", "any", "all"]);
+var CONTRACT_ARGUMENT_TYPES = /* @__PURE__ */ new Set([
+  "string",
+  "number",
+  "boolean",
+  "object",
+  "array",
+  "null"
+]);
+var CONTRACT_ORDER_MODES = /* @__PURE__ */ new Set([
+  "first-occurrence",
+  "happens-before",
+  "all-occurrences"
+]);
+var CONTRACT_FAIL_ON = /* @__PURE__ */ new Set(["failed", "unknown", "skipped"]);
+var CONTRACT_SIDE_EFFECT_CLASSES = /* @__PURE__ */ new Set(["read", "write"]);
+var CONTRACT_MAX_STRING_LIST = 64;
+var CONTRACT_MAX_ARGUMENTS = 32;
+var CONTRACT_MAX_ORDER_RULES = 32;
+var CONTRACT_MAX_ANY_OF = 16;
+var CONTRACT_MAX_OPERATIONS = 32;
+var CONTRACT_MAX_REQUIRED_STAGES = 16;
+var CONTRACT_MAX_ONE_OF = 32;
 var RUN_KEYS = /* @__PURE__ */ new Set(["expected", "allowIncomplete", "maxDurationMs", "maxDepth"]);
 var TOOL_KEYS = /* @__PURE__ */ new Set(["required", "forbidden", "allowed", "minCount", "maxCount"]);
 var LLM_KEYS = /* @__PURE__ */ new Set([
@@ -6930,6 +7060,49 @@ function requireBoolean(value, pathPrefix) {
   }
   return value;
 }
+function requireNonEmptyString(value, pathPrefix) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new CheckConfigError(
+      "AI_CHECK_CONFIG_INVALID_VALUE",
+      `${pathPrefix} must be a non-empty string.`
+    );
+  }
+  return value;
+}
+function requireBoundedArray(value, pathPrefix, max) {
+  if (!Array.isArray(value)) {
+    throw new CheckConfigError(
+      "AI_CHECK_CONFIG_INVALID_VALUE",
+      `${pathPrefix} must be an array.`
+    );
+  }
+  if (value.length > max) {
+    throw new CheckConfigError(
+      "AI_CHECK_CONFIG_INVALID_VALUE",
+      `${pathPrefix} exceeds bound of ${max} items.`
+    );
+  }
+  return value;
+}
+function requireBoundedStringArray(value, pathPrefix, max = CONTRACT_MAX_STRING_LIST) {
+  const items = requireBoundedArray(value, pathPrefix, max);
+  if (items.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw new CheckConfigError(
+      "AI_CHECK_CONFIG_INVALID_VALUE",
+      `${pathPrefix} must be an array of non-empty strings.`
+    );
+  }
+  return items;
+}
+function requireOrderMode(value, pathPrefix) {
+  if (typeof value !== "string" || !CONTRACT_ORDER_MODES.has(value)) {
+    throw new CheckConfigError(
+      "AI_CHECK_CONFIG_INVALID_VALUE",
+      `${pathPrefix} must be one of: "first-occurrence", "happens-before", "all-occurrences".`
+    );
+  }
+  return value;
+}
 function parseRunSection(value) {
   const record = requireObject(value, "checks.run");
   rejectUnknownKeys(record, RUN_KEYS, "checks.run");
@@ -7062,6 +7235,7 @@ function sectionHasEffect(section) {
   return Object.keys(section).length > 0;
 }
 function checkConfigHasEffect(config) {
+  if (contractConfigHasEffect(config.contract)) return true;
   const checks2 = config.checks;
   if (checks2 === void 0) return false;
   if ((checks2.select?.length ?? 0) > 0) return true;
@@ -7072,43 +7246,587 @@ function checkConfigHasEffect(config) {
   if (sectionHasEffect(checks2.safety)) return true;
   return false;
 }
+function contractConfigHasEffect(contract) {
+  if (contract === void 0) return false;
+  if (sectionHasEffect(contract.run)) return true;
+  if (sectionHasEffect(contract.tools)) return true;
+  if (sectionHasEffect(contract.llm)) return true;
+  if (sectionHasEffect(contract.observations)) {
+    return true;
+  }
+  if (sectionHasEffect(contract.controls)) return true;
+  if (sectionHasEffect(contract.retry)) return true;
+  if ((contract.alternatives?.anyOf?.length ?? 0) > 0) return true;
+  return false;
+}
+function parseContractRunSection(value, pathPrefix = "contract.run") {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_RUN_KEYS, pathPrefix);
+  const out = {};
+  if (record.requireCompleted !== void 0) {
+    out.requireCompleted = requireBoolean(
+      record.requireCompleted,
+      `${pathPrefix}.requireCompleted`
+    );
+  }
+  if (record.allowedStatuses !== void 0) {
+    out.allowedStatuses = requireBoundedStringArray(
+      record.allowedStatuses,
+      `${pathPrefix}.allowedStatuses`
+    );
+  }
+  if (record.maxDurationMs !== void 0) {
+    out.maxDurationMs = requireNonNegativeNumber(
+      record.maxDurationMs,
+      `${pathPrefix}.maxDurationMs`
+    );
+  }
+  return out;
+}
+function parseToolArgumentCheck(value, pathPrefix) {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_ARGUMENT_KEYS, pathPrefix);
+  const tool = requireNonEmptyString(record.tool, `${pathPrefix}.tool`);
+  if (typeof record.path !== "string") {
+    throw new CheckConfigError(
+      "AI_CHECK_CONFIG_INVALID_VALUE",
+      `${pathPrefix}.path must be a string JSON Pointer ("" or start with "/").`
+    );
+  }
+  const pathValue = record.path;
+  if (typeof record.operator !== "string" || !CONTRACT_ARGUMENT_OPERATORS.has(record.operator)) {
+    throw new CheckConfigError(
+      "AI_CHECK_CONFIG_INVALID_VALUE",
+      `${pathPrefix}.operator must be one of: "exists", "type", "equals", "oneOf".`
+    );
+  }
+  const operator = record.operator;
+  const out = { tool, path: pathValue, operator };
+  if (record.occurrence !== void 0) {
+    if (typeof record.occurrence !== "string" || !CONTRACT_ARGUMENT_OCCURRENCES.has(record.occurrence)) {
+      throw new CheckConfigError(
+        "AI_CHECK_CONFIG_INVALID_VALUE",
+        `${pathPrefix}.occurrence must be one of: "first", "last", "any", "all".`
+      );
+    }
+    out.occurrence = record.occurrence;
+  }
+  if (record.expected !== void 0) {
+    out.expected = record.expected;
+  }
+  if (record.oneOf !== void 0) {
+    out.oneOf = requireBoundedArray(record.oneOf, `${pathPrefix}.oneOf`, CONTRACT_MAX_ONE_OF);
+  }
+  if (record.type !== void 0) {
+    if (typeof record.type !== "string" || !CONTRACT_ARGUMENT_TYPES.has(record.type)) {
+      throw new CheckConfigError(
+        "AI_CHECK_CONFIG_INVALID_VALUE",
+        `${pathPrefix}.type must be one of: "string", "number", "boolean", "object", "array", "null".`
+      );
+    }
+    out.type = record.type;
+  }
+  return out;
+}
+function parseOrderRule(value, pathPrefix) {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_ORDER_RULE_KEYS, pathPrefix);
+  const out = {
+    before: requireNonEmptyString(record.before, `${pathPrefix}.before`),
+    after: requireNonEmptyString(record.after, `${pathPrefix}.after`)
+  };
+  if (record.occurrenceMode !== void 0) {
+    out.occurrenceMode = requireOrderMode(record.occurrenceMode, `${pathPrefix}.occurrenceMode`);
+  }
+  if (record.requireEndpoints !== void 0) {
+    out.requireEndpoints = requireBoolean(
+      record.requireEndpoints,
+      `${pathPrefix}.requireEndpoints`
+    );
+  }
+  return out;
+}
+function parseContractToolsSection(value, pathPrefix = "contract.tools") {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_TOOLS_KEYS, pathPrefix);
+  const out = {};
+  if (record.required !== void 0) {
+    out.required = requireBoundedStringArray(record.required, `${pathPrefix}.required`);
+  }
+  if (record.requiredTools !== void 0) {
+    out.requiredTools = requireBoundedStringArray(
+      record.requiredTools,
+      `${pathPrefix}.requiredTools`
+    );
+  }
+  if (record.forbidden !== void 0) {
+    out.forbidden = requireBoundedStringArray(record.forbidden, `${pathPrefix}.forbidden`);
+  }
+  if (record.forbiddenTools !== void 0) {
+    out.forbiddenTools = requireBoundedStringArray(
+      record.forbiddenTools,
+      `${pathPrefix}.forbiddenTools`
+    );
+  }
+  if (record.allowed !== void 0) {
+    out.allowed = requireBoundedStringArray(record.allowed, `${pathPrefix}.allowed`);
+  }
+  if (record.maxCalls !== void 0) {
+    out.maxCalls = requireNonNegativeNumber(record.maxCalls, `${pathPrefix}.maxCalls`);
+  }
+  if (record.requiredOrder !== void 0) {
+    out.requiredOrder = requireBoundedStringArray(
+      record.requiredOrder,
+      `${pathPrefix}.requiredOrder`
+    );
+  }
+  if (record.requiredOrderMode !== void 0) {
+    out.requiredOrderMode = requireOrderMode(
+      record.requiredOrderMode,
+      `${pathPrefix}.requiredOrderMode`
+    );
+  }
+  if (record.defaultOccurrenceMode !== void 0) {
+    out.defaultOccurrenceMode = requireOrderMode(
+      record.defaultOccurrenceMode,
+      `${pathPrefix}.defaultOccurrenceMode`
+    );
+  }
+  if (record.arguments !== void 0) {
+    const items = requireBoundedArray(
+      record.arguments,
+      `${pathPrefix}.arguments`,
+      CONTRACT_MAX_ARGUMENTS
+    );
+    out.arguments = items.map(
+      (item, index) => parseToolArgumentCheck(item, `${pathPrefix}.arguments[${index}]`)
+    );
+  }
+  if (record.orderRules !== void 0) {
+    const items = requireBoundedArray(
+      record.orderRules,
+      `${pathPrefix}.orderRules`,
+      CONTRACT_MAX_ORDER_RULES
+    );
+    out.orderRules = items.map(
+      (item, index) => parseOrderRule(item, `${pathPrefix}.orderRules[${index}]`)
+    );
+  }
+  return out;
+}
+function parseContractLlmSection(value, pathPrefix = "contract.llm") {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_LLM_KEYS, pathPrefix);
+  const out = {};
+  if (record.maxCalls !== void 0) {
+    out.maxCalls = requireNonNegativeNumber(record.maxCalls, `${pathPrefix}.maxCalls`);
+  }
+  if (record.maxTotalTokens !== void 0) {
+    out.maxTotalTokens = requireNonNegativeNumber(
+      record.maxTotalTokens,
+      `${pathPrefix}.maxTotalTokens`
+    );
+  }
+  if (record.allowedModels !== void 0) {
+    out.allowedModels = requireBoundedStringArray(
+      record.allowedModels,
+      `${pathPrefix}.allowedModels`
+    );
+  }
+  return out;
+}
+function parseRequireProvenance(value, pathPrefix) {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_PROVENANCE_KEYS, pathPrefix);
+  const out = {};
+  if (record.method !== void 0) {
+    out.method = requireBoolean(record.method, `${pathPrefix}.method`);
+  }
+  if (record.evidence !== void 0) {
+    out.evidence = requireBoolean(record.evidence, `${pathPrefix}.evidence`);
+  }
+  if (record.sameRunEventReference !== void 0) {
+    out.sameRunEventReference = requireBoolean(
+      record.sameRunEventReference,
+      `${pathPrefix}.sameRunEventReference`
+    );
+  }
+  return out;
+}
+function parseContractObservationsSection(value, pathPrefix = "contract.observations") {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_OBSERVATION_KEYS, pathPrefix);
+  const out = {};
+  if (record.required !== void 0) {
+    out.required = requireBoundedStringArray(record.required, `${pathPrefix}.required`);
+  }
+  if (record.failOn !== void 0) {
+    const items = requireBoundedArray(record.failOn, `${pathPrefix}.failOn`, CONTRACT_MAX_STRING_LIST);
+    for (const item of items) {
+      if (typeof item !== "string" || !CONTRACT_FAIL_ON.has(item)) {
+        throw new CheckConfigError(
+          "AI_CHECK_CONFIG_INVALID_VALUE",
+          `${pathPrefix}.failOn values must be "failed", "unknown", or "skipped".`
+        );
+      }
+    }
+    out.failOn = items;
+  }
+  if (record.requireProvenance !== void 0) {
+    out.requireProvenance = parseRequireProvenance(
+      record.requireProvenance,
+      `${pathPrefix}.requireProvenance`
+    );
+  }
+  return out;
+}
+function parseControlRequiredStage(value, pathPrefix) {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_CONTROL_STAGE_KEYS, pathPrefix);
+  if (typeof record.stage !== "string" || !CONTRACT_CONTROL_STAGES.has(record.stage)) {
+    throw new CheckConfigError(
+      "AI_CHECK_CONFIG_INVALID_VALUE",
+      `${pathPrefix}.stage must be one of: declared, presented, validated, enforced, observed, accepted.`
+    );
+  }
+  const out = {
+    stage: record.stage
+  };
+  if (record.observation !== void 0) {
+    out.observation = requireNonEmptyString(record.observation, `${pathPrefix}.observation`);
+  }
+  return out;
+}
+function parseContractControlsSection(value, pathPrefix = "contract.controls") {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_CONTROLS_KEYS, pathPrefix);
+  const out = {};
+  if (record.declaredTools !== void 0) {
+    out.declaredTools = requireBoundedStringArray(
+      record.declaredTools,
+      `${pathPrefix}.declaredTools`
+    );
+  }
+  if (record.enforcedTools !== void 0) {
+    out.enforcedTools = requireBoundedStringArray(
+      record.enforcedTools,
+      `${pathPrefix}.enforcedTools`
+    );
+  }
+  if (record.declaredToolsAttribute !== void 0) {
+    out.declaredToolsAttribute = requireNonEmptyString(
+      record.declaredToolsAttribute,
+      `${pathPrefix}.declaredToolsAttribute`
+    );
+  }
+  if (record.enforcedToolsAttribute !== void 0) {
+    out.enforcedToolsAttribute = requireNonEmptyString(
+      record.enforcedToolsAttribute,
+      `${pathPrefix}.enforcedToolsAttribute`
+    );
+  }
+  if (record.requireDeclaredMatchesEnforced !== void 0) {
+    out.requireDeclaredMatchesEnforced = requireBoolean(
+      record.requireDeclaredMatchesEnforced,
+      `${pathPrefix}.requireDeclaredMatchesEnforced`
+    );
+  }
+  if (record.requireObservedWithinEnforced !== void 0) {
+    out.requireObservedWithinEnforced = requireBoolean(
+      record.requireObservedWithinEnforced,
+      `${pathPrefix}.requireObservedWithinEnforced`
+    );
+  }
+  if (record.requireObservedWithinDeclared !== void 0) {
+    out.requireObservedWithinDeclared = requireBoolean(
+      record.requireObservedWithinDeclared,
+      `${pathPrefix}.requireObservedWithinDeclared`
+    );
+  }
+  if (record.requiredStages !== void 0) {
+    const items = requireBoundedArray(
+      record.requiredStages,
+      `${pathPrefix}.requiredStages`,
+      CONTRACT_MAX_REQUIRED_STAGES
+    );
+    out.requiredStages = items.map(
+      (item, index) => parseControlRequiredStage(item, `${pathPrefix}.requiredStages[${index}]`)
+    );
+  }
+  return out;
+}
+function parseRecoveryOperation(value, pathPrefix) {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_OPERATION_KEYS, pathPrefix);
+  const out = {
+    tool: requireNonEmptyString(record.tool, `${pathPrefix}.tool`)
+  };
+  if (record.maxAttempts !== void 0) {
+    out.maxAttempts = requireNonNegativeNumber(record.maxAttempts, `${pathPrefix}.maxAttempts`);
+  }
+  if (record.retryableErrors !== void 0) {
+    const errors = requireObject(record.retryableErrors, `${pathPrefix}.retryableErrors`);
+    rejectUnknownKeys(errors, CONTRACT_RETRYABLE_ERRORS_KEYS, `${pathPrefix}.retryableErrors`);
+    const retryableErrors = {};
+    if (errors.codes !== void 0) {
+      retryableErrors.codes = requireBoundedStringArray(
+        errors.codes,
+        `${pathPrefix}.retryableErrors.codes`
+      );
+    }
+    out.retryableErrors = retryableErrors;
+  }
+  if (record.requireFailureBeforeRetry !== void 0) {
+    out.requireFailureBeforeRetry = requireBoolean(
+      record.requireFailureBeforeRetry,
+      `${pathPrefix}.requireFailureBeforeRetry`
+    );
+  }
+  if (record.requireSameArguments !== void 0) {
+    if (record.requireSameArguments === true || record.requireSameArguments === false) {
+      out.requireSameArguments = record.requireSameArguments;
+    } else if (record.requireSameArguments === "structured-or-digest") {
+      out.requireSameArguments = "structured-or-digest";
+    } else {
+      throw new CheckConfigError(
+        "AI_CHECK_CONFIG_INVALID_VALUE",
+        `${pathPrefix}.requireSameArguments must be a boolean or "structured-or-digest".`
+      );
+    }
+  }
+  if (record.requireTerminalSuccess !== void 0) {
+    out.requireTerminalSuccess = requireBoolean(
+      record.requireTerminalSuccess,
+      `${pathPrefix}.requireTerminalSuccess`
+    );
+  }
+  if (record.requireRecoveredFailureVisible !== void 0) {
+    out.requireRecoveredFailureVisible = requireBoolean(
+      record.requireRecoveredFailureVisible,
+      `${pathPrefix}.requireRecoveredFailureVisible`
+    );
+  }
+  if (record.successfulResultDependency !== void 0) {
+    const dep = requireObject(
+      record.successfulResultDependency,
+      `${pathPrefix}.successfulResultDependency`
+    );
+    rejectUnknownKeys(dep, CONTRACT_RESULT_DEP_KEYS, `${pathPrefix}.successfulResultDependency`);
+    if (dep.consumerKind !== "LLM") {
+      throw new CheckConfigError(
+        "AI_CHECK_CONFIG_INVALID_VALUE",
+        `${pathPrefix}.successfulResultDependency.consumerKind must be "LLM".`
+      );
+    }
+    const dependency = { consumerKind: "LLM" };
+    if (dep.requireExplicitReference !== void 0) {
+      dependency.requireExplicitReference = requireBoolean(
+        dep.requireExplicitReference,
+        `${pathPrefix}.successfulResultDependency.requireExplicitReference`
+      );
+    }
+    out.successfulResultDependency = dependency;
+  }
+  if (record.sideEffectClass !== void 0) {
+    if (typeof record.sideEffectClass !== "string" || !CONTRACT_SIDE_EFFECT_CLASSES.has(record.sideEffectClass)) {
+      throw new CheckConfigError(
+        "AI_CHECK_CONFIG_INVALID_VALUE",
+        `${pathPrefix}.sideEffectClass must be "read" or "write".`
+      );
+    }
+    out.sideEffectClass = record.sideEffectClass;
+  }
+  return out;
+}
+function parseContractRetrySection(value, pathPrefix = "contract.retry") {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_RETRY_KEYS, pathPrefix);
+  const out = {};
+  if (record.maxAttempts !== void 0) {
+    out.maxAttempts = requireNonNegativeNumber(record.maxAttempts, `${pathPrefix}.maxAttempts`);
+  }
+  if (record.requireTerminalResult !== void 0) {
+    out.requireTerminalResult = requireBoolean(
+      record.requireTerminalResult,
+      `${pathPrefix}.requireTerminalResult`
+    );
+  }
+  if (record.fallbackOnlyAfterFailure !== void 0) {
+    out.fallbackOnlyAfterFailure = requireBoolean(
+      record.fallbackOnlyAfterFailure,
+      `${pathPrefix}.fallbackOnlyAfterFailure`
+    );
+  }
+  if (record.nonIdempotentTools !== void 0) {
+    out.nonIdempotentTools = requireBoundedStringArray(
+      record.nonIdempotentTools,
+      `${pathPrefix}.nonIdempotentTools`
+    );
+  }
+  if (record.requireIdempotencyEvidenceForRetry !== void 0) {
+    out.requireIdempotencyEvidenceForRetry = requireBoolean(
+      record.requireIdempotencyEvidenceForRetry,
+      `${pathPrefix}.requireIdempotencyEvidenceForRetry`
+    );
+  }
+  if (record.requireRecoveredFailureVisible !== void 0) {
+    out.requireRecoveredFailureVisible = requireBoolean(
+      record.requireRecoveredFailureVisible,
+      `${pathPrefix}.requireRecoveredFailureVisible`
+    );
+  }
+  if (record.operations !== void 0) {
+    const items = requireBoundedArray(
+      record.operations,
+      `${pathPrefix}.operations`,
+      CONTRACT_MAX_OPERATIONS
+    );
+    out.operations = items.map(
+      (item, index) => parseRecoveryOperation(item, `${pathPrefix}.operations[${index}]`)
+    );
+  }
+  return out;
+}
+function parseContractScopeSection(value) {
+  const record = requireObject(value, "contract.scope");
+  rejectUnknownKeys(record, CONTRACT_SCOPE_KEYS, "contract.scope");
+  const out = {};
+  if (record.runId !== void 0) {
+    out.runId = requireNonEmptyString(record.runId, "contract.scope.runId");
+  }
+  if (record.subAgentId !== void 0) {
+    out.subAgentId = requireNonEmptyString(record.subAgentId, "contract.scope.subAgentId");
+  }
+  if (record.groupId !== void 0) {
+    out.groupId = requireNonEmptyString(record.groupId, "contract.scope.groupId");
+  }
+  if (record.workflowStep !== void 0) {
+    out.workflowStep = requireNonEmptyString(
+      record.workflowStep,
+      "contract.scope.workflowStep"
+    );
+  }
+  if (record.rootEventId !== void 0) {
+    out.rootEventId = requireNonEmptyString(record.rootEventId, "contract.scope.rootEventId");
+  }
+  return out;
+}
+function parseContractBodySection(value, pathPrefix) {
+  const record = requireObject(value, pathPrefix);
+  rejectUnknownKeys(record, CONTRACT_BODY_KEYS, pathPrefix);
+  const out = {};
+  if (record.run !== void 0) out.run = parseContractRunSection(record.run, `${pathPrefix}.run`);
+  if (record.tools !== void 0) {
+    out.tools = parseContractToolsSection(record.tools, `${pathPrefix}.tools`);
+  }
+  if (record.llm !== void 0) out.llm = parseContractLlmSection(record.llm, `${pathPrefix}.llm`);
+  if (record.observations !== void 0) {
+    out.observations = parseContractObservationsSection(
+      record.observations,
+      `${pathPrefix}.observations`
+    );
+  }
+  if (record.controls !== void 0) {
+    out.controls = parseContractControlsSection(record.controls, `${pathPrefix}.controls`);
+  }
+  if (record.retry !== void 0) {
+    out.retry = parseContractRetrySection(record.retry, `${pathPrefix}.retry`);
+  }
+  return out;
+}
+function parseContractAlternativesSection(value) {
+  const record = requireObject(value, "contract.alternatives");
+  rejectUnknownKeys(record, CONTRACT_ALT_KEYS, "contract.alternatives");
+  if (record.anyOf === void 0) {
+    throw new CheckConfigError(
+      "AI_CHECK_CONFIG_INVALID_VALUE",
+      "contract.alternatives.anyOf is required."
+    );
+  }
+  const items = requireBoundedArray(
+    record.anyOf,
+    "contract.alternatives.anyOf",
+    CONTRACT_MAX_ANY_OF
+  );
+  const anyOf = items.map((item, index) => {
+    const pathPrefix = `contract.alternatives.anyOf[${index}]`;
+    const branch = requireObject(item, pathPrefix);
+    rejectUnknownKeys(branch, CONTRACT_ALT_BRANCH_KEYS, pathPrefix);
+    const id = requireNonEmptyString(branch.id, `${pathPrefix}.id`);
+    if (branch.contract === void 0) {
+      throw new CheckConfigError(
+        "AI_CHECK_CONFIG_INVALID_VALUE",
+        `${pathPrefix}.contract is required.`
+      );
+    }
+    const out = {
+      id,
+      contract: parseContractBodySection(branch.contract, `${pathPrefix}.contract`)
+    };
+    if (branch.description !== void 0) {
+      out.description = requireNonEmptyString(branch.description, `${pathPrefix}.description`);
+    }
+    return out;
+  });
+  return { anyOf };
+}
+function parseContractSection(value) {
+  const record = requireObject(value, "contract");
+  rejectUnknownKeys(record, CONTRACT_KEYS, "contract");
+  const bodyOnly = {};
+  for (const key of Object.keys(record)) {
+    if (CONTRACT_BODY_KEYS.has(key)) bodyOnly[key] = record[key];
+  }
+  const out = { ...parseContractBodySection(bodyOnly, "contract") };
+  if (record.scope !== void 0) out.scope = parseContractScopeSection(record.scope);
+  if (record.alternatives !== void 0) {
+    out.alternatives = parseContractAlternativesSection(record.alternatives);
+  }
+  return out;
+}
 function parseCheckConfig(value) {
   if (value === void 0 || value === null) return {};
   if (typeof value !== "object" || Array.isArray(value)) {
     throw new CheckConfigError("AI_CHECK_CONFIG_INVALID_VALUE", "Config must export an object.");
   }
   const root = value;
-  if ("contract" in root) {
-    throw new CheckConfigError(
-      "AI_CHECK_CONFIG_UNKNOWN_KEY",
-      'Top-level "contract" is not supported by `agent-inspect check --config`. Use the TraceContract TypeScript API (`defineTraceContract` / `evaluateTraceContract` from `agent-inspect/checks`), or express tool/run/llm rules under `checks`.'
-    );
-  }
   const rootKeys = Object.keys(root);
   for (const key of rootKeys) {
-    if (key === "checks") continue;
-    const suggestion = closestKey(key, ["checks"]);
+    if (ROOT_CONFIG_KEYS.has(key)) continue;
+    const suggestion = closestKey(key, [...ROOT_CONFIG_KEYS]);
     const hint = suggestion ? ` Did you mean "${suggestion}"?` : "";
     throw new CheckConfigError(
       "AI_CHECK_CONFIG_UNKNOWN_KEY",
-      `Unknown top-level check config key "${key}". Allowed: checks.${hint}`
+      `Unknown top-level check config key "${key}". Allowed: checks, contract.${hint}`
     );
   }
-  if (!("checks" in root)) return {};
-  const checksRecord = requireObject(root.checks, "checks");
-  rejectUnknownKeys(checksRecord, CHECKS_KEYS, "checks");
-  const checks2 = {};
-  if (checksRecord.select !== void 0) {
-    checks2.select = requireStringArray(checksRecord.select, "checks.select");
+  const out = {};
+  if ("checks" in root) {
+    const checksRecord = requireObject(root.checks, "checks");
+    rejectUnknownKeys(checksRecord, CHECKS_KEYS, "checks");
+    const checks2 = {};
+    if (checksRecord.select !== void 0) {
+      checks2.select = requireStringArray(checksRecord.select, "checks.select");
+    }
+    if (checksRecord.run !== void 0) checks2.run = parseRunSection(checksRecord.run);
+    if (checksRecord.tool !== void 0) checks2.tool = parseToolSection(checksRecord.tool);
+    if (checksRecord.llm !== void 0) checks2.llm = parseLlmSection(checksRecord.llm);
+    if (checksRecord.structure !== void 0) {
+      checks2.structure = parseStructureSection(checksRecord.structure);
+    }
+    if (checksRecord.safety !== void 0) checks2.safety = parseSafetySection(checksRecord.safety);
+    out.checks = checks2;
   }
-  if (checksRecord.run !== void 0) checks2.run = parseRunSection(checksRecord.run);
-  if (checksRecord.tool !== void 0) checks2.tool = parseToolSection(checksRecord.tool);
-  if (checksRecord.llm !== void 0) checks2.llm = parseLlmSection(checksRecord.llm);
-  if (checksRecord.structure !== void 0) {
-    checks2.structure = parseStructureSection(checksRecord.structure);
+  if ("contract" in root) {
+    out.contract = parseContractSection(root.contract);
+  }
+  if (out.contract !== void 0 && contractConfigHasEffect(out.contract) && checkConfigHasEffect({ checks: out.checks })) {
+    throw new CheckConfigError(
+      "AI_CHECK_CONFIG_INVALID_VALUE",
+      'Config cannot combine top-level "checks" and "contract". Use one vocabulary per config file.'
+    );
   }
-  if (checksRecord.safety !== void 0) checks2.safety = parseSafetySection(checksRecord.safety);
-  return { checks: checks2 };
+  return out;
 }
 async function loadConfig(configPath) {
   if (configPath === void 0) return {};
@@ -7436,6 +8154,7 @@ async function checkCommand(target, options = {}, stdin = process.stdin) {
   let evidenceRead;
   let evidenceRunIds = [];
   let evidenceSourceContents;
+  let evidenceContract;
   const sessionId = options.session?.trim();
   const groupId = options.group?.trim();
   const useSessionScope = Boolean(sessionId || groupId);
@@ -7444,7 +8163,7 @@ async function checkCommand(target, options = {}, stdin = process.stdin) {
     if (options.config !== void 0 && !checkConfigHasEffect(config)) {
       result = errorResult(
         "AI_CHECK_CONFIG_NO_EFFECTIVE_RULES",
-        "Explicit --config has no effective check rules. Configure checks.select, checks.run, checks.tool, checks.llm, checks.structure, or checks.safety."
+        "Explicit --config has no effective check rules. Configure checks.select, checks.run, checks.tool, checks.llm, checks.structure, checks.safety, or contract."
       );
       if (options.json) printJson2(result);
       else printHuman2(result, options);
@@ -7452,7 +8171,11 @@ async function checkCommand(target, options = {}, stdin = process.stdin) {
       return;
     }
     let effectiveOptions = options;
-    const resolved = resolvePreset(options.preset, {
+    const useContract = config.contract !== void 0 && contractConfigHasEffect(config.contract);
+    if (useContract) {
+      evidenceContract = defineTraceContract(config.contract);
+    }
+    const resolved = useContract ? void 0 : resolvePreset(options.preset, {
       hasToolRules: hasToolRulesConfigured(config, options)
     });
     if (resolved !== void 0) {
@@ -7460,7 +8183,7 @@ async function checkCommand(target, options = {}, stdin = process.stdin) {
       config = applied.config;
       effectiveOptions = applied.options;
     }
-    const built = buildRules(config, effectiveOptions, resolved?.select ?? []);
+    const built = useContract ? { rules: [], select: [], diagnostics: [] } : buildRules(config, effectiveOptions, resolved?.select ?? []);
     if (built.diagnostics.some((item) => item.severity === "error")) {
       result = errorResult("AI_CHECK_INVALID_CONFIG", "Invalid check configuration.");
       result.diagnostics = [...built.diagnostics];
@@ -7482,6 +8205,7 @@ async function checkCommand(target, options = {}, stdin = process.stdin) {
       });
       const perRun = [];
       const sourceContents = /* @__PURE__ */ new Map();
+      const definedContract = evidenceContract;
       for (const meta of scoped.metas) {
         const read = await openTrace(
           { type: "file", path: meta.filePath },
@@ -7498,23 +8222,20 @@ async function checkCommand(target, options = {}, stdin = process.stdin) {
 `
           );
         }
+        const base = definedContract ? evaluateTraceContract({ read }, definedContract, { runId: meta.runId }) : runTraceChecks(
+          { read },
+          {
+            rules: built.rules,
+            select: built.select,
+            runId: meta.runId
+          }
+        );
         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 } : {},
-              runId: meta.runId
-            }
-          )
+          mergeSafetyExtensions(base, read, {
+            ...options.guardrails ? { guardrails: options.guardrails } : {},
+            ...options.circuit ? { circuits: options.circuit } : {},
+            runId: meta.runId
+          })
         );
       }
       evidenceRunIds = scoped.runIds;
@@ -7553,22 +8274,25 @@ async function checkCommand(target, options = {}, stdin = process.stdin) {
           ])
         );
       }
-      result = mergeSafetyExtensions(
-        runTraceChecks(
-          { read },
-          {
-            rules: built.rules,
-            select: built.select,
-            ...options.run !== void 0 ? { runId: options.run } : {}
-          }
-        ),
-        read,
+      const base = useContract && evidenceContract !== void 0 ? evaluateTraceContract(
+        { read },
+        evidenceContract,
+        {
+          ...options.run !== void 0 ? { runId: options.run } : {}
+        }
+      ) : runTraceChecks(
+        { read },
         {
-          ...options.guardrails ? { guardrails: options.guardrails } : {},
-          ...options.circuit ? { circuits: options.circuit } : {},
+          rules: built.rules,
+          select: built.select,
           ...options.run !== void 0 ? { runId: options.run } : {}
         }
       );
+      result = mergeSafetyExtensions(base, read, {
+        ...options.guardrails ? { guardrails: options.guardrails } : {},
+        ...options.circuit ? { circuits: options.circuit } : {},
+        ...options.run !== void 0 ? { runId: options.run } : {}
+      });
     }
   } catch (error) {
     if (phase === "config") {
@@ -7612,7 +8336,15 @@ async function checkCommand(target, options = {}, stdin = process.stdin) {
         checkResultsJson: checkResultToEvidenceJson(result, runIds),
         summaryText: `Check status: ${result.status}`,
         redactionProfile,
-        format: evidenceFormat
+        format: evidenceFormat,
+        ...evidenceContract !== void 0 ? {
+          contractPackage: {
+            engineVersion: "",
+            source: "file",
+            contract: evidenceContract,
+            ...options.config !== void 0 ? { path: options.config } : {}
+          }
+        } : {}
       });
       if (!options.json) {
         console.log(`Evidence: ${written}`);
@@ -12173,7 +12905,7 @@ function isModuleNotFound4(e) {
 }
 async function loadIndexSqlite() {
   try {
-    return await import('./src-XNC4EUN3.mjs');
+    return await import('./src-ZUGAUXY6.mjs');
   } catch (e) {
     if (isModuleNotFound4(e)) {
       console.error(
@@ -13123,7 +13855,7 @@ function createCliProgram() {
     "add run.maxStepDuration (e.g. 30s, 5m)"
   ).option("--require-completed", "add run.requireCompleted").option("--detect-stalls", "add run.stall for running or incomplete events").option(
     "--fail-on-observation <status>",
-    "fail when observed outcomes match status (passed, failed, unknown, skipped; comma-separated)"
+    "outcome gate: require \u22651 OUTCOME and fail when status matches (passed,failed,unknown,skipped; comma-separated). Does not invent outcomes from tool/LLM/run success; use --preset trajectory for structural checks"
   ).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"
@@ -13136,7 +13868,7 @@ function createCliProgram() {
     "run optional circuit rules (repeatable): same-tool-repetition, max-retries, ...",
     (value, previous = []) => [...previous, value]
   ).addOption(
-    new Option("--preset <name>", "additive check preset").choices(["trajectory", "safety", "comprehensive", "behavioral-session"])
+    new Option("--preset <name>", "additive check preset (trajectory=structure only; safety=share checks; not interchangeable)").choices(["trajectory", "safety", "comprehensive", "behavioral-session"])
   ).addOption(
     new Option(
       "--evidence-on <mode>",