agent-inspect 6.19.0 → 6.20.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 6.20.0
+
+### Minor Changes
+
+- 43a4481: Flexible deterministic contracts: selectable `requiredOrderMode` (`first-occurrence` | `happens-before` | `all-occurrences`), one-level `alternatives.anyOf`, and `lintTraceContract` / `explainTraceContract` helpers. Includes MCP expected-rejection and local Promptfoo use-together recipes.
+
+## 6.19.1
+
+### Patch Changes
+
+- e23b94b: 6.19.1 trust restoration: redact free-text credentials in persisted error messages before disk, refresh shipped docs to match 6.19.0 reality, and enforce all 18 fixed-group package READMEs (including root `agent-inspect`) via `package-readmes:check`.
+
 ## 6.19.0
 
 ### Minor Changes

package/README.md

@@ -33,6 +33,8 @@
   <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js 20 or newer"></a>
 </p>
 
+**Support level:** Stable — see [SUPPORT-LEVELS.md](docs/SUPPORT-LEVELS.md). Network behavior: [NETWORK-BEHAVIOR.md](docs/NETWORK-BEHAVIOR.md).
+
 ```bash
 npm install agent-inspect
 ```
@@ -210,7 +212,7 @@ The root package is enough for custom capture, the CLI, checks, and Evidence wor
 
 ## Status and documentation
 
-**Current published baseline:** **6.19.0** · persisted schema `1.0` · Node.js `>=20` · MIT.
+**Current published baseline:** **6.20.0** · persisted schema `1.0` · Node.js `>=20` · MIT.
 
 Legacy v0.1 and v0.2 traces remain readable. Check the npm badge and [changelog](CHANGELOG.md) for the current published version.
 

package/SECURITY.md

@@ -82,6 +82,8 @@ For a practical pre-share workflow, see `docs/SAFE-TRACE-SHARING.md`. For schema
 
 Pull requests run GitHub **Dependency review** (`.github/workflows/dependency-review.yml`) and fail on newly introduced **high** or **critical** advisory severity. Routine unit/typecheck/size CI also exercises redaction, path containment, and Evidence safety tests. These scanners do **not** replace manual review of share profiles or Evidence packages before you disclose traces.
 
+For synthetic fixtures, dynamic-import boundaries, and an explicit “what scanners verify vs not” table, see [docs/SECURITY-SCANNERS.md](docs/SECURITY-SCANNERS.md).
+
 ## Optional surfaces (v2.6)
 
 ### Local viewer (`agent-inspect serve`)

package/docs/ARCHITECTURE.md

@@ -1,27 +1,41 @@
 ## Architecture
 
-> **Adoption-focused overview:** see [TECHNICAL-GUIDE.md](./TECHNICAL-GUIDE.md) for a comprehensive technical guide (v3.5.5) suitable for blogs and outreach.
+> **Adoption-focused overview:** see [TECHNICAL-GUIDE.md](./TECHNICAL-GUIDE.md) for a comprehensive technical guide suitable for blogs and outreach.
 
-AgentInspect is a **local-first execution-tree debugger**: manual traces and log ingest produce inspectable step trees stored as JSONL on disk (default `.agent-inspect-runs/`), with a CLI for list/view/clean/logs/tail/export/diff workflows.
+AgentInspect is a **local-first execution-tree debugger and trajectory-test toolkit** for TypeScript AI agents: framework-native capture and manual traces produce inspectable step trees as local JSONL (default `.agent-inspect`), with CLI, TraceContract / TraceFacts checks, Evidence v2 packaging, and optional read-only MCP.
 
 ### Package layout
 
 | Package | Published? | Role |
 | -------- | ---------- | ---- |
 | `agent-inspect` | Yes | Public tarball: core tracing APIs + CLI (`agent-inspect` binary) |
-| `@agent-inspect/core` | No (private) | Tracing, storage, log parsing, export, diff |
+| `@agent-inspect/core` | No (private) | Tracing, storage, readers/writers, checks, export, diff |
 | `@agent-inspect/cli` | No (private) | Commander CLI implementation |
-| `@agent-inspect/langchain` | Yes (optional) | LangChain.js callback adapter (experimental) |
-| `@agent-inspect/tui` | Yes (optional) | Ink/React terminal viewer (experimental) |
-
-Root `agent-inspect` uses **conditional exports** for ESM/CJS TypeScript consumers (`import.types` / `require.types`). Heavy dependencies (LangChain, Ink/React) stay in optional packages.
+| `@agent-inspect/redact` | Yes | Standalone redaction engine (also used by CLI `redact`) |
+| `@agent-inspect/ai-sdk` | Yes (optional) | Vercel AI SDK telemetry integration |
+| `@agent-inspect/openai-agents` | Yes (optional) | OpenAI Agents JS `setTraceProcessors()` adapter |
+| `@agent-inspect/langchain` | Yes (optional) | LangChain.js / LangGraph callback adapter |
+| `@agent-inspect/mcp` | Yes (optional) | MCP client `tools/list` / `tools/call` tracing |
+| `@agent-inspect/adapter-sdk` | Yes (optional) | Shared adapter helpers / plugin surface |
+| `@agent-inspect/vitest` / `@agent-inspect/jest` | Yes (optional) | Test reporters and TraceContract matchers |
+| `@agent-inspect/eval` | Yes (optional) | Deterministic local eval heuristics |
+| `@agent-inspect/guardrails` / `@agent-inspect/circuit` | Yes (optional) | Local guardrail and circuit utilities |
+| `@agent-inspect/harness` | Yes (optional) | Lightweight local harness helpers |
+| `@agent-inspect/viewer` | Yes (optional) | Local HTML/viewer surface |
+| `@agent-inspect/tui` | Yes (optional) | Ink/React terminal viewer |
+| `@agent-inspect/mcp-server` | Yes (optional) | Read-only local MCP server over traces |
+| `@agent-inspect/index-sqlite` | Yes (optional) | Optional local SQLite metadata index |
+| `@agent-inspect/studio` | Yes (optional) | Local studio CLI / ingest surfaces |
+
+Root `agent-inspect` uses **conditional exports** for ESM/CJS TypeScript consumers (`import.types` / `require.types`). Heavy framework dependencies stay in optional packages.
 
 ### Event model and schema
 
-- Manual traces use **`schemaVersion: "0.1"`** JSONL events (`run_started`, `step_started`, `step_completed`, `run_completed`).
-- Failures use `step_completed` with `status: "error"` — there is no `step_failed` event.
+- Manual global helpers (`inspectRun()` / `step()`) still write **`schemaVersion: "0.1"`** JSONL for compatibility (`run_started`, `step_started`, `step_completed`, `run_completed`).
+- Failures use `step_completed` / `run_completed` with `status: "error"` — there is no `step_failed` event.
+- **Persisted writer/runtime output targets schema 1.0.** `createInspector()` with built-in writers emits schema **1.0** persisted rows; v0.1 and v0.2 remain readable.
 - Log-derived runs use confidence labels (`explicit`, `correlated`, `heuristic`, `unknown`) and conservative tree-building rules.
-- **v1.2.0 persisted-event foundation (released):** source-agnostic `PersistedInspectEvent` helpers (`schemaVersion: "0.2"`) — types, validators, converters, and in-memory tree bridge. Existing **`TreeBuilder`** remains the canonical tree builder. v0.2 bridge works **in memory only**; storage dual-read and CLI integration are v1.3+ / post-foundation work. See [proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md](./proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md) and [implementation/V1.3.0-RELEASE-TRAIN.md](./implementation/V1.3.0-RELEASE-TRAIN.md).
+- Migration is explicit (`agent-inspect migrate …`); AgentInspect does not rewrite old traces in place.
 
 See [SCHEMA.md](./SCHEMA.md) for field reference and [API.md](./API.md) for public surfaces (stable vs experimental).
 
@@ -29,21 +43,19 @@ See [SCHEMA.md](./SCHEMA.md) for field reference and [API.md](./API.md) for publ
 
 - Instrumentation must **not throw into user code**; trace safety failures degrade gracefully.
 - **Manual metadata** is redacted before disk by default; `redact: false` opts out.
+- **Error messages** also run high-confidence free-text credential detectors before disk (provider keys, bearer tokens, JWTs, and related patterns), unless `redact: false`.
 - **Size bounds** cap persisted event and metadata size.
 - Log ingest: JSON first-class; log4js best-effort; no `eval` or JS object-literal parsing.
 
 See [SECURITY.md](../SECURITY.md) and [LIMITATIONS.md](./LIMITATIONS.md).
 
-### Optional adapters
-
-- **`@agent-inspect/langchain`**: in-memory by default; `persist: true` writes local JSONL. Experimental.
-- **`@agent-inspect/tui`**: interactive viewer; isolated from root deps. Experimental.
+### Optional adapters and surfaces
 
-See [ADAPTERS.md](./ADAPTERS.md).
+Official adapters (`@agent-inspect/ai-sdk`, `@agent-inspect/openai-agents`, `@agent-inspect/langchain`) share a bounded preview-capture contract. MCP client tracing, reporters, eval, redact, viewer/TUI, studio, and read-only MCP are separate optional packages — see [ADAPTERS.md](./ADAPTERS.md) and [SUPPORT-LEVELS.md](./SUPPORT-LEVELS.md).
 
 ### Architecture proposals
 
-Maintainer-owned RFCs and planning proposals are indexed in [proposals/README.md](./proposals/README.md). The active post-v1.5 roadmap is [implementation/ROADMAP-V1.6-TO-V3.md](./implementation/ROADMAP-V1.6-TO-V3.md).
+Maintainer-owned RFCs and planning proposals are indexed in [proposals/README.md](./proposals/README.md). The active roadmap is [implementation/ROADMAP.md](./implementation/ROADMAP.md).
 
 ### Where to read next
 

package/docs/KNOWN-ISSUES.md

@@ -28,10 +28,10 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 ## Integrations
 
 - **Vendor sinks** (hosted dashboards, Langfuse/Braintrust/New Relic/Datadog native uploads, OTLP gRPC streaming, etc.) are **not implemented** in the core packages described here.
-- **AI SDK adapter** (`@agent-inspect/ai-sdk`) is experimental and metadata-first. It depends on explicit AI SDK telemetry configuration and requires `recordInputs: false` / `recordOutputs: false` for the documented safe path.
-- **OpenAI Agents JS adapter** (`@agent-inspect/openai-agents`) is experimental and metadata-first. Runtime metadata mapping is local-only; the safe install path is `setTraceProcessors()` rather than `addTraceProcessor()`. The v1.9 package publication retry is pending maintainer-side npm auto-publish setup and is separate from v2 contract work.
+- **AI SDK adapter** (`@agent-inspect/ai-sdk`) is Supported and metadata-first by default. It depends on explicit AI SDK telemetry configuration and requires `recordInputs: false` / `recordOutputs: false` for the documented safe path. Opt-in `capture: "preview"` uses the shared bounded preview helper.
+- **OpenAI Agents JS adapter** (`@agent-inspect/openai-agents`) is Supported and metadata-first. Runtime metadata mapping is local-only; the safe install path is `setTraceProcessors()` rather than `addTraceProcessor()`. Bounded `capture: "preview"` parity ships with the other official adapters.
 - **LangGraph support** is currently a documented boundary through `@agent-inspect/langchain`, not a dedicated package.
-- **LangChain adapter** captures **metadata-oriented** signals by default; it does not replace full framework observability.
+- **LangChain adapter** (`@agent-inspect/langchain`) is Supported; it captures **metadata-oriented** signals by default and shares the same preview contract when `capture: "preview"` is set.
 - **LangChain `stream: true`** records chunk counts and timing only — not a full token replay. Per-token JSONL events are not emitted.
 - **Deep swarm / nested RunnableSequence (6.14.2+):** capture resolves parents before registering child indexes and rejects `parentId === stepId`. Legacy traces that still contain self-parent edges are normalized in logical projection (`AI_LOGICAL_SELF_PARENT_REMOVED`) and rendered with visibility-first, cycle-safe trees so nested LLM/tool steps remain visible.
 - **Correlation metadata** (`correlationId`, `requestId`, `decisionId`, `groupId`) is written on `run_started` but **CLI list/view does not filter by correlation fields** yet.

package/docs/LIMITATIONS.md

@@ -13,10 +13,10 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **`list` / `view` / `export`** do not filter by correlation fields yet — `stats --correlation-id` / `--group-id` and `search` provide targeted read paths; full CLI filtering remains incremental.
 
-## Persisted event model (v1.2.0 foundation)
+## Persisted event model
 
 - **Manual global tracing remains v0.1.** `inspectRun()` / `step()` still write `schemaVersion: "0.1"` JSONL for compatibility.
-- **Persisted writer/runtime output targets schema 1.0.** `createInspector()` with built-in writers emits schema 1.0 persisted rows; v0.2 remains a readable compatibility foundation.
+- **Persisted writer/runtime output targets schema 1.0.** `createInspector()` with built-in writers emits schema 1.0 persisted rows; v0.1 and v0.2 remain readable.
 - **Migration is explicit, not automatic.** `agent-inspect migrate <input> --to 1.0 --dry-run` reports what would change, and `--output <file>` writes a separate file. AgentInspect does not rewrite old traces in place.
 
 ## Runtime writers and universal readers (v1.6)
@@ -32,7 +32,7 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **AI SDK integration is explicit telemetry wiring.** Use `@agent-inspect/ai-sdk` through AI SDK `experimental_telemetry.integrations`; AgentInspect does not wrap providers, patch fetch, or enable telemetry globally.
 - **AI SDK privacy settings are caller-owned.** Examples set `recordInputs: false` and `recordOutputs: false`; leaving those enabled in user code can cause the AI SDK telemetry layer to include richer data before AgentInspect receives events.
-- **OpenAI Agents JS support is experimental.** `@agent-inspect/openai-agents` maps metadata-only runtime spans through the safe `setTraceProcessors()` boundary and does not capture raw payloads by default. The v1.9 package publication retry is a separate maintainer npm automation task, not part of the v2 contract work.
+- **OpenAI Agents JS support is Supported (metadata-first).** `@agent-inspect/openai-agents` maps runtime spans through the safe `setTraceProcessors()` boundary and does not capture raw payloads by default. Bounded `capture: "preview"` is available through the shared adapter capture contract.
 - **LangGraph support is a boundary decision, not a separate package.** Initial support is expected through `@agent-inspect/langchain` callbacks unless no-network fixtures prove a separate package is needed.
 - **No root/core adapter dependencies.** AI SDK, OpenAI Agents, LangGraph, OpenTelemetry, and LangChain remain outside the root/core runtime dependency graph.
 - **Preview capture is bounded, not sanitized.** `capture: "preview"` persists truncated, key-redacted previews of framework-provided input/output fields. Key-based redaction cannot detect a secret embedded in free text, and there is no full-content capture mode. Fields the framework never exposes are reported as `AI_CAPTURE_FIELD_UNAVAILABLE` rather than reconstructed.
@@ -53,7 +53,8 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **Redaction profiles** (`local`, `share`, `strict`) are key-based presets — not compliance-grade PII detection. Review exports before sharing even with `--redaction-profile strict`.
 - **`@agent-inspect/redact` and `agent-inspect redact` create redacted copies.** They do not encrypt source traces, mutate originals, certify compliance, or guarantee every sensitive value is detected.
-- **Default metadata redaction** covers common sensitive keys only (exact key match, case-insensitive). Custom secret field names are not redacted unless you add rules via `redact: { rules: [...] }`.
+- **Default metadata redaction** covers common sensitive keys (exact key match, case-insensitive). Custom secret field names are not redacted unless you add rules via `redact: { rules: [...] }`.
+- **Error-message free text** also runs high-confidence credential detectors before disk (provider API keys, bearer tokens, JWTs, GitHub tokens, PEM private keys, and high-confidence `key=value` secrets). This is still not compliance-grade detection; `redact: false` opts out.
 - **Metadata truncation** applies to string values and nested structures; very large metadata may be replaced with a truncation marker when `maxEventBytes` is exceeded (default 64 KiB per JSONL line).
 - **Redaction is not encryption.** Local trace files remain readable on disk; treat `.agent-inspect-runs/` like any developer artifact that may contain operational data.
 

package/docs/PERFORMANCE.md

@@ -30,7 +30,7 @@ npx agent-inspect stats --dir fixtures/performance
 
 All three are validated by `pnpm fixtures:check` and small enough for git (the largest is well under 1 MB).
 
-## Comfortable ranges (v3.4)
+## Comfortable ranges
 
 | Workload | Comfortable | Warning | Not designed for |
 | -------- | ----------- | ------- | ---------------- |

package/docs/SUPPORT-LEVELS.md

@@ -49,7 +49,8 @@ shows). `pnpm package-readmes:check` enforces the agreement and runs as part of
 To promote or demote a surface:
 
 1. Edit the row in the matrix above.
-2. Edit the `**Support level:**` line in each affected `packages/*/README.md`.
+2. Edit the `**Support level:**` line in the affected public README: `README.md`
+   for the root `agent-inspect` package, or `packages/*/README.md` for scoped packages.
 3. Run `pnpm package-readmes:check`.
 
 The check also reports packages whose level is **unenforced** — those the matrix

package/docs/TRACE-CONTRACTS.md

@@ -10,6 +10,9 @@ Contracts compile to deterministic check rules for common cases:
 
 - run status / completion / max duration
 - tool required / forbidden / allowed / maxCalls / order (`requiredTools` / `forbiddenTools` aliases)
+- selectable `requiredOrderMode` (`first-occurrence` | `happens-before` | `all-occurrences`)
+- `alternatives.anyOf` for one level of legitimate alternate paths
+- `lintTraceContract` / `explainTraceContract` for brittle-contract diagnostics
 - LLM maxCalls / maxTotalTokens / allowedModels
 - evidence-bearing findings on failures
 - evaluation over **logical** TraceFacts (raw events remain available)
@@ -24,13 +27,14 @@ Contracts compile to deterministic check rules for common cases:
 → contract.tool.order.1: B before C
 ```
 
-Each pair compares the **first occurrence** (start/encounter order in the evaluated event stream):
+`requiredOrderMode` selects one ordering relation for every generated pair:
 
 - unlisted intermediate tools are allowed;
-- later repetitions do not invalidate an earlier valid first-occurrence order;
 - TraceContract `requiredOrder` **implies presence** — every listed name is added to the effective required-tool set;
-- this is **not** causal happens-before; overlapping intervals emit a non-failing `tool.order.overlap` warning;
-- combine ordering with `maxCalls` or custom rules when repeated calls matter.
+- `first-occurrence` (default when omitted) compares first occurrences in start/encounter order; later repetitions do not invalidate an earlier valid order, and interval overlap emits a non-failing `tool.order.overlap` warning;
+- `happens-before` requires the first `before` occurrence to finish before the first `after` occurrence starts;
+- `all-occurrences` requires every `before` occurrence to finish before every `after` occurrence starts (`max(before.end) <= min(after.start)`);
+- causal modes fail when a required interval boundary cannot be resolved instead of falling back to encounter order.
 
 Examples for `requiredOrder: ["retrieve", "generate"]`:
 
@@ -38,12 +42,16 @@ Examples for `requiredOrder: ["retrieve", "generate"]`:
 | --- | --- |
 | `retrieve → generate` | PASS |
 | `retrieve → rerank → generate` | PASS |
-| `retrieve → generate → retrieve` | PASS (first-occurrence) |
+| `retrieve → generate → retrieve` | PASS under omitted / `first-occurrence`; FAIL under `all-occurrences` |
 | `generate → retrieve` | FAIL (order) |
 | `cache_lookup → generate` | FAIL (missing `retrieve` via implied presence) |
 
 Low-level `createToolOrderingRule({ before, after })` alone may still pass when an endpoint is missing (compositional). TraceContract `requiredOrder` does not.
 
+For overlapping first calls, omitted / `first-occurrence` warns while `happens-before` fails.
+
+Immediate or positional `all-pairs` matching is not implemented.
+
 ### Experimental Vitest / Jest matchers (shipped)
 
 | Package | Export | Matchers |
@@ -55,7 +63,7 @@ These are **Experimental** — API names may evolve. There is no `expectTrace(..
 
 See [API.md](./API.md), [TRACE-FACTS.md](./TRACE-FACTS.md), and `packages/core/src/checks/contract.ts`.
 
-## Rule kinds (shipped vs planned)
+## Rule kinds
 
 TraceContract rules fall into distinct categories. Mixing them incorrectly is a common source of false failures (see GitHub #308 and #309).
 
@@ -65,65 +73,68 @@ Unconditional path invariant: every named tool must appear **at least once** in
 
 - Use when the tool is always part of a valid execution path.
 - **Do not** use for steps that legitimate shortcuts may skip (for example cache hits that bypass `retrieve`).
-- When a shortcut is valid but you still need evidence of the outcome, prefer `observations.required` until `alternatives.anyOf` ships (6.20.0).
+- Prefer `alternatives.anyOf` or `observations.required` when a shortcut is valid.
 
-### `tools.requiredOrder` (shipped — first-occurrence / start-encounter)
+### `tools.requiredOrder` (shipped — selectable ordering modes)
 
-Legacy first-start / encounter ordering. The evaluator walks the trace and checks that each listed tool's **first occurrence** appears after the previous tool's first occurrence.
+The evaluator expands each list into adjacent pairs and applies one `requiredOrderMode` to every pair.
 
 - TraceContract `requiredOrder` **implies presence** of every listed tool (unioned into `tools.required`).
-- Default mode is **first-occurrence** start/encounter order — **not** causal happens-before.
-- Overlapping intervals that still satisfy start order emit a non-failing overlap warning.
-- **Planned (6.20.0, GitHub #308):**
-  - `requiredOrderMode: "happens-before"` — first before must **end** before first after **starts**
-  - `requiredOrderMode: "all-occurrences"` — every before must end before every after starts
-
-### `observations.required` (shipped)
-
-Requires externally observed or effect evidence (for example HTTP status, file write, cache key) rather than a specific tool call. Prefer this when the invariant is about **outcome** rather than **which tool ran**.
-
-### Planned (6.20.0 — not shipped)
-
-Document only; **do not** use these fields in contracts today:
+- `requiredOrderMode: "first-occurrence"` is the default first-occurrence start/encounter relation; overlapping intervals emit a non-failing warning.
+- `requiredOrderMode: "happens-before"` requires the first before to **end** before the first after **starts**; overlap fails.
+- `requiredOrderMode: "all-occurrences"` requires every before to end before every after starts; any cross-boundary overlap or later before fails.
+- Missing interval boundaries fail closed in the two causal modes.
+
+### `alternatives.anyOf` (shipped)
+
+One level of named deterministic branches. Base rules always apply. At least one complete branch must pass.
+
+```ts
+defineTraceContract({
+  run: { requireCompleted: true },
+  tools: { required: ["generate"] },
+  alternatives: {
+    anyOf: [
+      {
+        id: "cache-hit",
+        contract: {
+          tools: { required: ["cache_lookup"], forbidden: ["retrieve"] },
+          observations: { required: ["cache-hit-valid"] },
+        },
+      },
+      {
+        id: "retrieve",
+        contract: {
+          tools: { required: ["retrieve"], requiredOrder: ["retrieve", "generate"] },
+          observations: { required: ["retrieval-context-valid"] },
+        },
+      },
+    ],
+  },
+});
+```
 
-| Planned field | Purpose | GitHub |
-|---------------|---------|--------|
-| `alternatives.anyOf` | One of several deterministic valid paths (one level, no nested groups, no predicates) | #309 |
-| `requiredOrderMode: "happens-before"` | Causal completion-before-start ordering | #308 |
-| `requiredOrderMode: "all-occurrences"` | Strict ordering across all tool occurrences | #308 |
+Constraints:
 
-API shape for both requires maintainer approval before external PR lands. @HsienW volunteered on #308 for `requiredOrderMode` implementation.
+- unique branch ids
+- no nested `alternatives`
+- no predicates / runtime DSL
+- unused failed branches do not fail the contract when another branch passes
+- if none pass → `contract.alternatives.none-satisfied`
 
-## Workaround until 6.20.0
+### `observations.required` (shipped)
 
-When a legitimate shortcut skips a tool you would otherwise require:
+Requires externally observed or effect evidence (for example HTTP status, file write, cache key) rather than a specific tool call. Prefer this when the invariant is about **outcome** rather than **which tool ran**.
 
-1. **Remove** unconditional `tools.required` for that step.
-2. **Express** the verified outcome via `observations.required` when possible.
-3. **Document** the cache-hit or alternate path in contract comments for reviewers.
+### Lint and explain (shipped)
 
-Example matching GitHub #309 (cache hit skips second `retrieve`):
+```ts
+import { lintTraceContract, explainTraceContract } from "agent-inspect/checks";
 
-```yaml
-contract:
-  tools:
-    required: [generate] # not retrieve — cache may skip it
-    requiredOrder: [generate] # ordering only among tools that ran
-  observations:
-    required: [cache_hit_or_retrieve_evidence]
+lintTraceContract(contract);   // brittle / invalid shape diagnostics
+explainTraceContract(contract); // human-readable intent lines
 ```
 
-With first-occurrence ordering, `retrieve → generate → retrieve` still **passes** when both retrieves are present (see worked example below).
-
-## What is not shipped (yet)
-
-Do **not** document these as available:
-
-- `expectTrace(...).toSatisfyTraceContract` (different API shape than the shipped matchers)
-- Full workflow handoff / approval / MCP protocol contract rules
-- Per-tool argument schema / regex validators on the contract surface
-- Every structure rule (orphan/cycle/depth) exposed on the contract API (many exist as standalone check rules)
-
 ## CLI relationship
 
 ```bash
@@ -137,3 +148,4 @@ Suites and gates can consume check results; see [SUITES-COHORTS-GATES.md](./SUIT
 - Experimental/Beta API — may evolve in minors
 - Contract tests are smoke-level; prefer check-engine tests for deep rule coverage
 - Always review findings before treating a green check as product proof
+- No nested alternatives, all-pairs matching, or general temporal DSL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.19.0",
+  "version": "6.20.0",
   "license": "MIT",
   "type": "module",
   "description": "Local evidence debugger and trajectory-test toolkit for TypeScript AI agents — execution trees, TraceContract checks, Evidence v2, and read-only MCP",
@@ -243,7 +243,8 @@
     "public-truth:check": "node scripts/validate-public-truth.mjs",
     "ai-assets:check": "node scripts/validate-ai-assets.mjs",
     "package-readmes:check": "node scripts/validate-package-readmes.mjs",
-    "docs:check": "pnpm run docs:commands && pnpm run docs:links && pnpm run public-truth:check && pnpm run ai-assets:check && pnpm run package-readmes:check && pnpm run repo:health && pnpm run build:cli && pnpm run demo:verify",
+    "actions:check": "node scripts/check-github-actions-pins.mjs",
+    "docs:check": "pnpm run docs:commands && pnpm run docs:links && pnpm run public-truth:check && pnpm run ai-assets:check && pnpm run package-readmes:check && pnpm run repo:health && pnpm run actions:check && pnpm run build:cli && pnpm run demo:verify",
     "build:cli": "pnpm exec tsup --config tsup.cli.config.ts",
     "repo:health": "node scripts/validate-repo-health.mjs",
     "demo:generate": "node scripts/demo-generate.mjs",

package/packages/cli/dist/{chunk-R7Y5SGH5.mjs → chunk-QPRJUVLH.mjs}

@@ -1714,9 +1714,63 @@ async function extractMetadata(filePath, _quickScan) {
     createdAt: stats.birthtime
   };
 }
+var ROOT_STEP_DEPTH = 0;
+var MAX_RUN_SUMMARY_DEPTH = 1e3;
 function isNonNegativeFiniteNumber(value) {
   return typeof value === "number" && Number.isFinite(value) && value >= 0;
 }
+function resolveParentStepId(step, steps) {
+  const parentId = step.parentId;
+  if (typeof parentId !== "string" || parentId.trim() === "") {
+    return void 0;
+  }
+  return steps.has(parentId) ? parentId : void 0;
+}
+function computeStepDepth(stepId, steps, depthCache) {
+  const cached = depthCache.get(stepId);
+  if (cached !== void 0) return cached;
+  const ancestry = [];
+  const ancestryIndexes = /* @__PURE__ */ new Map();
+  let currentStepId = stepId;
+  let resolvedDepth;
+  while (resolvedDepth === void 0) {
+    const cachedDepth = depthCache.get(currentStepId);
+    if (cachedDepth !== void 0) {
+      resolvedDepth = cachedDepth;
+      continue;
+    }
+    const cycleStart = ancestryIndexes.get(currentStepId);
+    if (cycleStart !== void 0) {
+      const cycleStepIds = ancestry.splice(cycleStart);
+      for (const cycleStepId of cycleStepIds) {
+        depthCache.set(cycleStepId, ROOT_STEP_DEPTH);
+      }
+      resolvedDepth = ROOT_STEP_DEPTH;
+      continue;
+    }
+    const currentStep = steps.get(currentStepId);
+    if (!currentStep) {
+      resolvedDepth = ROOT_STEP_DEPTH;
+      continue;
+    }
+    ancestryIndexes.set(currentStepId, ancestry.length);
+    ancestry.push(currentStepId);
+    const parentStepId = resolveParentStepId(currentStep, steps);
+    if (parentStepId === void 0) {
+      ancestry.pop();
+      depthCache.set(currentStepId, ROOT_STEP_DEPTH);
+      resolvedDepth = ROOT_STEP_DEPTH;
+      continue;
+    }
+    currentStepId = parentStepId;
+  }
+  ancestry.reverse();
+  for (const ancestorStepId of ancestry) {
+    resolvedDepth = Math.min(MAX_RUN_SUMMARY_DEPTH, resolvedDepth + 1);
+    depthCache.set(ancestorStepId, resolvedDepth);
+  }
+  return depthCache.get(stepId) ?? ROOT_STEP_DEPTH;
+}
 function buildRunSummary(events) {
   const started = events.find(
     (e) => e.event === "run_started"
@@ -1770,27 +1824,13 @@ function buildRunSummary(events) {
   let stepsWithKnownTotal = 0;
   let hasCachedTokens = false;
   const depthCache = /* @__PURE__ */ new Map();
-  const computeDepth = (stepId) => {
-    const cached = depthCache.get(stepId);
-    if (cached !== void 0) return cached;
-    const node = steps.get(stepId);
-    if (!node) return 0;
-    const parent = node.parentId;
-    if (typeof parent !== "string" || parent.trim() === "" || !steps.has(parent)) {
-      depthCache.set(stepId, 0);
-      return 0;
-    }
-    const d = Math.min(1e3, computeDepth(parent) + 1);
-    depthCache.set(stepId, d);
-    return d;
-  };
   for (const [id, s] of steps.entries()) {
     totalSteps += 1;
     if (s.type === "llm") llmSteps += 1;
     else if (s.type === "tool") toolSteps2 += 1;
     else logicSteps += 1;
     if (s.status === "error") errorSteps += 1;
-    const depth = computeDepth(id);
+    const depth = computeStepDepth(id, steps, depthCache);
     if (depth > maxDepth) maxDepth = depth;
     if (typeof s.durationMs === "number" && Number.isFinite(s.durationMs)) {
       if (!longestStep || s.durationMs > longestStep.durationMs) {
@@ -11741,5 +11781,5 @@ function renderGateReport(result, options = {}) {
 }
 
 export { COHORT_METRIC_IDS, DEFAULT_SUITE_ARTIFACTS_DIR, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, Redactor, TraceDirectory, TraceReadError, TreeBuilder, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, applyProfileMetadataCaps, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceHtmlShell, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compactAttributes, createBaselineRegressionRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRunDepthRule, createRunDurationRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolUsageRule, defaultBundleOutputPath, defaultSuiteConfigTemplate, diffRuns, diffTraceEvents, enrichSessionRunRecord, escapeHtml, escapeMarkdown, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatStepLabel, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, inferEvidenceFileRole, isAgentInspectTrace, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, manualTraceEventsToComparableRun, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToTraceEvents, renderActivitySummaryHuman, renderCohortReport, renderErrorLine, renderGateReport, renderObservedOutcomesHtml, renderObservedOutcomesMarkdown, renderRunDiff, renderRunWhat, renderStepLine, renderSuiteReport, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, runTraceChecks, safeString, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sha256Hex, stableJson, summarizeObservedOutcomes, summarizeSemanticParity, traceEventToPersistedInspectEvent, truncateName, truncateStringForProfile, validateEvent, validateSuiteConfig, verifyEvidenceDirectory, zeroKinds };
-//# sourceMappingURL=chunk-R7Y5SGH5.mjs.map
-//# sourceMappingURL=chunk-R7Y5SGH5.mjs.map
+//# sourceMappingURL=chunk-QPRJUVLH.mjs.map
+//# sourceMappingURL=chunk-QPRJUVLH.mjs.map