engineering-behavior-observatory 0.2.1

package/docs/harnesses/claude-agent-sdk.md

@@ -0,0 +1,61 @@
+# Claude Agent SDK
+
+EBO calls the TypeScript Agent SDK directly. It captures the native message
+stream, passive lifecycle hooks, exposed session identities, usage, telemetry
+receipt state, and a retained workspace outcome.
+
+## Run one task
+
+After [preparing and freezing a queue](../guides/operator-guide.md):
+
+```sh
+ebo agent-sdk run <bundle-root> <queue.json> <run-id> <output-root>
+```
+
+The adapter uses `@anthropic-ai/claude-agent-sdk@0.3.258`. It probes the
+installed SDK/CLI and records version-specific capabilities rather than
+assuming every hook is available. Runtime pins are implementation conditions,
+not assurances that a provider model route is accessible.
+
+Supply an approved Agent SDK authentication route through the environment.
+The opt-in OAuth proofs use `CLAUDE_CODE_OAUTH_TOKEN` with
+`ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` unset. Do not put credentials
+in packet or queue JSON. EBO does not establish entitlement to a model.
+
+The queue references five records: model, harness, native limits, tool policy,
+and capture profile. See the [configuration reference](../reference/agent-sdk-operational-runner.md)
+for accepted fields and examples. Tool permission settings can prevent a
+headless run from proceeding; review them before committing to a long task.
+
+## Read the capture
+
+| Evidence | What it establishes |
+| :--- | :--- |
+| Native SDK stream | Messages, tool-related content, result and session identities |
+| Passive hooks | Exposed lifecycle callback occurrences, including failures and compaction |
+| Telemetry | Received timing/resource signals, with gaps recorded independently |
+| Workspace evidence | Retained changes against the frozen starting tree |
+| Capture report | Structural validity, source capabilities, and missing evidence |
+
+A hook's occurrence is authoritative in callback evidence; a hook span is
+optional timing data. Hooks do not modify the agent's choices. Native reasoning
+may be present in restricted source data and is removed from portable exports.
+
+Tracing is beta; metrics/log events are separate capabilities. Content capture
+is opt-in. Short export intervals **and** clean shutdown reduce buffering loss,
+but collector receipt must still be checked. See [telemetry](../guides/telemetry.md).
+
+## Completion and interruption
+
+The command executes one queue entry, with a fresh attempt identity and output
+directory. It does not loop through the queue or silently retry. A valid
+captured stop or failure can return a successful CLI exit: inspect the summary
+and manifest to interpret the result.
+
+If workspace packaging fails, preserve the summary's
+`retainedWorkspacePath` for recovery. Missing outcome evidence cannot be
+called qualified completion. See [failure recovery](../guides/operator-guide.md#failure-recovery).
+
+Library operators can call `runAgentSdkQueueEntry` for queue execution or
+`captureClaudeAgentSdkRun` for an already-resolved attempt. The latter
+requires explicit workspace/lifecycle composition; it is not a task preparer.

package/docs/harnesses/codex-harness.md

@@ -0,0 +1,174 @@
+# Codex app-server harness
+
+EBO can execute one selected frozen queue entry through an owned
+`codex app-server --listen stdio://` child. The adapter is optional; the Claude
+Agent SDK remains EBO's primary Anthropic capture path. Codex native protocol
+records remain authoritative, OTLP is separately retained timing/resource
+evidence, and uniform events are a digest-checked projection after capture.
+
+The baseline is `codex-cli 0.153.4`. EBO rejects a different executable
+version, starts a new child for each attempt, and never connects to the desktop
+daemon or changes `~/.codex/config.toml`.
+
+Each child receives a temporary isolated `CODEX_HOME`, a controlled instruction
+file, and no copied user configuration. When the standard local login file is
+available, EBO references it with a temporary symlink so the supported login is
+reused without reading, copying, or retaining credential bytes. The temporary
+home and native Codex history are removed after `thread/read`; EBO retains only
+the captured protocol evidence.
+The child environment is an allowlist of basic process/locale keys with `HOME`
+and `CODEX_HOME` redirected to that temporary directory; caller secrets and
+Node preload settings are not inherited. Retained evidence records the key
+names, never their values.
+
+## Generated contract
+
+[`contracts/codex-app-server-0.153.4/manifest.json`](../../contracts/codex-app-server-0.153.4/manifest.json)
+pins the generated root digests and the small schema/type subset used by the
+adapter and its fixtures. Regenerate the source contracts with the pinned CLI:
+
+```sh
+codex app-server generate-ts --experimental --out /tmp/codex-types
+codex app-server generate-json-schema --experimental --out /tmp/codex-schema
+```
+
+The adapter uses the stable initialize/thread/turn lifecycle, plus generated
+leaf contracts for initialized, `thread/read`, `turn/interrupt`, and token usage.
+Unknown notifications are retained unchanged and listed as unmapped.
+
+The 0.153.4 refresh preserves the unchanged RPC, approval, sandbox, interruption
+and usage contracts. Initialization moved into the generated `v1` schema
+directory. The retained subset also includes thread/turn start parameters.
+New captures explicitly select legacy history; paginated or summary-only
+readback is retained with a gap instead of being claimed as complete history.
+The pinned runtime treats `writableRoots` as additional to the effective `cwd`
+and removes a redundant cwd entry. EBO verifies that cwd matches the requested
+workspace, rejects additional roots, and requires the requested network and
+temporary-directory restrictions. Initial thread effort and sandbox overrides
+match the explicit turn policy.
+
+Existing 0.150.1 bundles remain readable through their original normalization
+profile and dataset identity. The legacy contract snapshot stays checked in;
+a captured synthetic 0.150.1 bundle and its pre-upgrade normalized dataset test
+exact readback. New captures use the 0.153.4 profile. Frozen run configurations
+for the older executable are not rewritten: new execution requires fresh
+configuration references carrying the new runtime version and contract digest.
+
+## Queue configuration
+
+The queue keeps condition IDs path-safe; the digest-pinned model record carries
+the actual provider model and effort. A minimal observational configuration is:
+
+```json
+{ "schemaVersion": "ebo.codex-config/v1", "kind": "model", "provider": "openai", "model": "gpt-5.6-sol", "effort": "high" }
+{ "schemaVersion": "ebo.codex-config/v1", "kind": "harness", "adapter": "codex-app-server", "executable": "/opt/homebrew/bin/codex", "version": "0.153.4", "contractDigest": "sha256:e5f798fd1343c539f01fedea0e8a84a43c080fcca4615c80eb04a5edab4f7d0a" }
+{ "schemaVersion": "ebo.codex-config/v1", "kind": "native-limits", "shutdownGraceMs": 2000 }
+{ "schemaVersion": "ebo.codex-config/v1", "kind": "native-tool-policy", "approvalPolicy": "never", "sandbox": "workspace-write" }
+{ "schemaVersion": "ebo.codex-config/v1", "kind": "capture-profile", "telemetrySignals": ["logs", "traces", "metrics"], "workspaceOutcome": { "excludeDirectoryNames": ["node_modules"] } }
+```
+
+Each record is referenced by the existing experiment/queue contract. After task
+admission, freeze, and matrix compilation, execute exactly one entry:
+
+```sh
+ebo codex run \
+  <bundle-root> <queue.json> <run-id> <output-root> \
+  --workspace-root <disposable-workspace-parent>
+```
+
+`runCodexQueueEntry` is the equivalent library API. It does not iterate, retry,
+resume, or overwrite an existing attempt destination.
+
+## Lifecycle and evidence
+
+The client sends `initialize`, `initialized`, `thread/start`, and `turn/start`.
+Only `turn/completed` for the returned thread and turn ends the native attempt.
+After completion or interruption, `thread/read` with `includeTurns: true`
+retains persisted history separately from streamed item records. A request
+is considered full readback only when the thread reports `historyMode: legacy`
+and the owned turn reports `itemsView: full` with an items array. A request
+acknowledgement, final-looking message, idle state, or process exit is not
+completion.
+
+An approved synthetic smoke uses an already authenticated route:
+
+```sh
+EBO_LIVE_CODEX_CAPTURE_SMOKE=1 EBO_LIVE_CODEX_CAPTURE_MODEL='<existing-route>' \
+  node --test --test-name-pattern='approved existing-auth' dist/test/codex.test.js
+```
+
+The 0.153.4 validation created the exact synthetic file, retained full legacy
+history, and reported no capture gaps. Logs and traces arrived; metrics did not
+arrive within the bounded run and remained `missing`, not a fabricated receipt.
+
+On interruption EBO sends `turn/interrupt`, records its acknowledgement, waits
+briefly for matching terminal evidence, then tears down the owned child. There
+is no invented shutdown RPC. Requests, responses, server requests,
+notifications, unknown variants, completion evidence, stderr diagnostics, and
+process state append to `session.jsonl` with one receive/write sequence.
+Malformed frames, early exit, auth failure, and bounded teardown remain valid
+partial evidence. Workspace outcome capture runs independently and leaves the
+source workspace available when post-start packaging fails.
+
+The `ebo codex run` command turns scoped `SIGINT` and `SIGTERM` handlers into
+the run's abort signal, allowing interruption, history readback, process
+teardown, and partial-bundle finalization to complete before the CLI exits.
+Library callers receive the same two-second default shutdown grace at both the
+lifecycle and app-server boundaries unless they provide an explicit value.
+
+Unattended runs never fabricate human input or broaden permissions. Command and
+file approvals receive `decline`; MCP elicitation receives `decline`; dynamic
+tool calls fail without content; other unsupported server requests receive a
+recorded JSON-RPC error. Effective model/provider/effort, sandbox, approval
+policy, workspace, runtime identity, instruction sources, and material config
+remain in restricted evidence.
+
+## Native telemetry and usage
+
+When requested, EBO starts a bounded loopback OTLP/HTTP JSON receiver and passes
+the documented `otel.exporter`, `otel.trace_exporter`, and
+`otel.metrics_exporter` overrides to the owned child. `otel.log_user_prompt` is
+always false. Each signal is classified independently as `received`, `missing`,
+or `disabled`; configured export is never treated as receipt. Exported batches
+are retained without synthetic spans or time-based joins.
+The receiver accepts at most 256 records, 4 MiB per request, and 16 MiB total;
+rejected requests remain explicit receiver diagnostics.
+
+`thread/tokenUsage/updated` retains cumulative `total` and per-turn `last`
+values separately, including `totalTokens`, `inputTokens`,
+`cachedInputTokens`, `cacheWriteInputTokens`, `outputTokens`, and
+`reasoningOutputTokens` when emitted. EBO does not sum cumulative updates or
+turn cache/reasoning subsets into additional cost. Account quota and billing
+remain unavailable unless supplied by separate evidence.
+
+Restricted native session evidence retains Codex reasoning records unchanged.
+Partner and public derivatives remove `item/reasoning/textDelta` content,
+reasoning-item summary/content fields, and matching duplicated raw frames;
+portable readback fails closed if any of those content forms remain.
+
+## Uniform mapping
+
+| Native evidence | Uniform family | Rule |
+|---|---|---|
+| completed user/agent message item | `message` | completed item only |
+| completed command/MCP/dynamic/web-search item | `tool` | completed item only; starts and deltas stay native |
+| completed file-change item | `artifact` | content references the native item |
+| completed exposed collaboration item | `delegation` | no inferred child history |
+| turn plan or compaction notification | `context` | only when emitted |
+| token usage, reroute, or completed hook | `runtime` | native values only |
+| approval, permission, user-input, or elicitation request | `permission` | request and decision remain separate native records; other server requests stay unmapped |
+| matching `turn/completed` | `outcome` | terminal status is native |
+
+Model requests are deliberately unsupported: EBO does not infer an inference
+request from a turn, reroute, or model switch. Item starts, deltas, history
+readback, raw frames, and unknown methods remain unmapped rather than becoming
+duplicate tool/message counts. `describeAndValidateCodexDataset` runs the
+native-reference, digest, content-reference, capability, and coverage checks.
+
+Portable export uses the existing fail-closed sanitizer and readback. Native
+source bundles stay restricted; authentication/account material, local paths,
+environment values, and hidden reasoning are not approved portable fields.
+
+Protocol details follow the official [Codex app-server documentation](https://learn.chatgpt.com/docs/app-server).
+Exporter fields follow the official [advanced telemetry guidance](https://learn.chatgpt.com/docs/config-file/config-advanced#observability-and-telemetry)
+and [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).

package/docs/harnesses/cursor-sdk.md

@@ -0,0 +1,149 @@
+# Cursor TypeScript SDK harness
+
+EBO can execute one selected frozen queue entry through the first-party
+`@cursor/sdk` local-agent API. The integration pins SDK `1.0.31`, creates an
+attempt-owned `JsonlLocalAgentStore`, and retains stream messages, detailed
+callbacks, terminal `wait()` evidence, conversation history, billing readback,
+the official native store, and the final workspace before normalization.
+
+The SDK package version does not freeze Cursor's service, selected model, or
+separately deployed local runtime. The selected model must be an exact result
+from `Cursor.models.list()` at launch. SDK `1.0.31` does not expose a separate
+local-runtime version or SDK-local per-run OTLP configuration/receipt surface,
+so EBO records those capabilities as `not-exposed` and `unsupported` instead of
+inventing identities or spans.
+
+Cursor also offers a distinct [Enterprise OpenTelemetry Export](https://prod.cursor.com/docs/enterprise/opentelemetry-export)
+configured by a team admin. It runs server-side and pushes OTLP/HTTP protobuf
+metrics and logs to one public HTTPS collector; the [wire reference](https://prod.cursor.com/docs/enterprise/opentelemetry-export/wire)
+includes `sdk_ts` as an entrypoint. This adapter does not configure or receive that
+team export. Its metrics are aggregate deltas without conversation/request IDs,
+and although logs have dedupe IDs plus optional conversation/request/usage-event
+IDs, the public docs do not establish an exact join from those fields to this
+SDK's agent/run IDs. It provides no traces, prompt content, or historical
+backfill. EBO therefore records Enterprise export as `not-checked`, separately
+from the SDK-local `unsupported` result; future ingestion would require an
+approved admin destination and observed identity correlation evidence.
+
+## Safety policy
+
+Local tool execution is not an OS or container sandbox. EBO requires all of
+the following digest-pinned settings for every Cursor queue entry:
+
+- an explicit `sandbox.enabled` boolean; `true` can reject writes that require
+  interactive approval in a headless run, while `false` executes with the
+  invoking user's OS permissions and is not containment;
+- an explicit built-in tool allowlist and optional deny list;
+- `settingSources: []`, so candidate project files and unrelated user, team,
+  MDM, or plugin settings are not silently loaded;
+- `autoReview: false`, so instrumentation does not add a behavior-changing
+  classifier; and
+- `enableAgentRetries: false`, so a retained attempt is not silently replaced.
+
+SDK `1.0.31` treats an ancestor Git checkout as the local project root. EBO
+therefore rejects a materialized workspace nested under another `.git` path
+before starting the SDK. Use the default system temporary parent or pass a
+`--workspace-root` outside the invoking checkout; this prevents accidental
+ancestor-project routing but is not OS containment.
+
+No MCP servers, custom callback tools, subagents, cloud repositories, remote PR
+automation, or environment values are loaded from configuration. Supply
+`CURSOR_API_KEY` only in the process environment through the approved secret
+path; it is passed directly to the SDK and never written to an artifact. The
+SDK owns its child processes and does not expose a per-agent environment
+allowlist in this pin. During the deliberately single-entry SDK run, EBO keeps
+only platform/network variables and `CURSOR_API_KEY` in the process environment,
+records the allowed key names (never values), and restores the original
+environment after agent disposal. Concurrent in-process Cursor captures are
+rejected while that boundary is active.
+
+## Configuration records
+
+The queue points to five digest-pinned `ebo.cursor-sdk-config/v1` records. The
+minimal examples under [`examples/cursor-sdk`](../../examples/cursor-sdk/README.md) are
+caller inputs, not defaults. Replace the model placeholder with one exact
+catalog ID before computing digests and compiling a queue. The experiment's
+model-set key remains a path-safe condition ID; it need not duplicate a
+provider ID containing dots.
+
+```json
+{ "schemaVersion": "ebo.cursor-sdk-config/v1", "kind": "model", "provider": "cursor", "model": { "id": "<exact-catalog-model-id>" } }
+```
+
+```json
+{ "schemaVersion": "ebo.cursor-sdk-config/v1", "kind": "harness", "adapter": "cursor-sdk", "sdkVersion": "1.0.31" }
+```
+
+```json
+{ "schemaVersion": "ebo.cursor-sdk-config/v1", "kind": "native-limits", "shutdownGraceMs": 2000, "maxNativeRecordBytes": 16777216 }
+```
+
+```json
+{ "schemaVersion": "ebo.cursor-sdk-config/v1", "kind": "native-tool-policy", "tools": ["read", "edit", "grep", "glob", "ls"], "disallowedTools": ["shell", "task", "mcp", "webSearch", "webFetch"], "sandbox": { "enabled": false }, "settingSources": [], "autoReview": false, "enableAgentRetries": false }
+```
+
+```json
+{ "schemaVersion": "ebo.cursor-sdk-config/v1", "kind": "capture-profile", "nativeOtlp": "unsupported", "workspaceOutcome": { "excludeDirectoryNames": ["node_modules"] } }
+```
+
+Use the existing packet admission, freeze, matrix compilation, and queue
+validation commands from the [operator guide](../guides/operator-guide.md). Then run one
+persisted entry:
+
+```sh
+# After injecting CURSOR_API_KEY through the approved secret environment:
+ebo cursor run \
+  <bundle-root> <queue.json> <run-id> <output-root> \
+  --workspace-root <workspace-parent>
+```
+
+The output destination is never replaced. Interrupting the command cancels the
+owned run within the configured shutdown grace. Provider, stream, history,
+recorder, store, workspace, and cleanup failures retain a partial attempt and
+cannot produce qualified-complete capture.
+
+## Evidence and overlap policy
+
+| Channel | Retained role | Normalized role |
+|---|---|---|
+| `run.stream()` | lifecycle, messages, tools, per-turn usage | authoritative message/tool/usage projection |
+| `onDelta` / `onStep` | lower-level deltas, nested updates, step snapshots | retained as overlap evidence; not counted again |
+| `run.wait()` | owned terminal status, duration, cumulative usage | authoritative outcome; cumulative usage is not re-added |
+| `run.conversation()` | durable conversation readback before disposal | retained as history; not counted again |
+| `agent.getUsage()` | eventually consistent billing scope/read time | separate billing evidence; absence does not invalidate semantic capture |
+| `JsonlLocalAgentStore` | agents, runs, run events, checkpoints | authoritative native persistence; not counted again |
+
+Every callback value is JSON-snapshotted at receipt and writes are serialized.
+Unknown tool payloads remain in restricted native evidence. Portable export
+recursively removes thinking/reasoning content and checkpoint blob bytes, then
+redacts secrets, local identifiers, paths, and source correlations. Restricted
+source artifacts are unchanged.
+
+## Capability matrix
+
+| Capability | Status | Basis |
+|---|---|---|
+| messages | available | SDK stream user/assistant records |
+| tools | available | SDK stream `tool_call` identity/status/args/result |
+| context | partial | detailed summaries/nested updates retained, not reconstructed |
+| delegation | partial | task tool retained without invented subagent lifecycle |
+| artifacts | unsupported | tool names retain intent only; verified workspace outcome remains separate and authoritative |
+| usage | available | per-turn stream increments; cumulative/billing channels remain separate |
+| terminal outcome | available | exact owned `run.wait()` result |
+| parentage/native time | partial | exposed identities and adapter receipt order only |
+| SDK-local OTLP configuration/receipt | unsupported | no public SDK `1.0.31` per-run API |
+| Enterprise team OTLP export | not checked | server-side metrics/logs exist, but no destination or exact SDK run correlation was verified |
+| OS containment | unsupported | SDK sandbox policy is not an OS/container boundary |
+
+Run the deterministic contract proof with:
+
+```sh
+npm run build
+node --test dist/test/cursor-sdk.test.js
+```
+
+That fixture covers frozen queue execution through workspace retention,
+qualification, export/readback, observations, existing judge evidence,
+comparison/aggregation, and Atlas drilldown. It is not proof of live provider
+authentication. A live smoke must use an exact currently available catalog
+model and one bounded synthetic local workspace edit through the same command.

package/docs/harnesses/deepseek-harness.md

@@ -0,0 +1,134 @@
+# DeepSeek Harness adapter
+
+EBO drives DeepSeek Harness out of process through the pinned public package
+roots `@deepseek-ai/dsh-sdk-client@0.1.1-rc.2` and
+`@deepseek-ai/dsh-sdk-protocol@0.1.1-rc.2`. It does not import source modules,
+embed the agent loop, or implement JSON-RPC framing, correlation,
+subscriptions, or process teardown.
+
+The upstream contracts are the official
+[TypeScript client](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/sdk/client/README.md),
+[wire protocol](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/sdk/protocol/README.md),
+[server plugin](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/sdk/server/README.md),
+[session log](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md),
+and [session telemetry](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session-telemetry.md).
+
+## Live verification
+
+The September 9 release audit ran the installed `@deepseek-ai/dsh@0.1.1-rc.2`
+runtime with matching `dsh-sdk-jsonrpc-server` and `dsh-llm-pi-ai` packages.
+The npm CLI at that version has no shipped `sdk` profile. A custom profile's
+`package.json` selected `dsh.profile.bundles: ["@deepseek-ai/dsh-base"]`;
+its patch mounted the official JSON-RPC server and configured the existing
+`llm-pi-ai` plugin. No agent loop or protocol implementation was added to EBO.
+
+The provider configuration used `api: openai-completions`,
+`baseURL: https://api.z.ai/api/coding/paas/v4`, `apiKeyEnv: ZAI_API_KEY`,
+and model `glm-5.3-flash`. The key was supplied only through the recorded child
+environment allowlist. The permission preset explicitly paired workspace-write
+sandboxing with unattended approval; module reload, generated session titles,
+and native telemetry were disabled for this smoke.
+
+The run wrote `done` to the requested file in 12 seconds and retained 206
+client observations, including 196 native session notifications. All 35
+sequenced events in the persisted session log matched delivered native events;
+the stream also carries chunk events stored compactly by the runtime.
+Receipt-to-idle completion and client-owned process teardown passed.
+Capture qualification and validation of 202 projected events passed after
+expanding the uniform relation bound to preserve large native source sets.
+
+This proves the tested Z.ai composition, not every provider or plugin choice.
+The runtime reported server version `0.0.1`; installed npm package versions
+and the runtime/configuration digests identify the actual software. Native
+telemetry was disabled and is not live-verified by this smoke. Capture/judge
+and release checks do not turn a successful file-write smoke into a quality score.
+
+## Runtime composition
+
+`ebo.deepseek-runtime-composition/v1` records the exact Node command and
+arguments, process and workspace directories, named profile, ordered Cordis
+patches, provider/model route, pinned client/protocol versions, plugin names,
+an ordered digest-bearing reference for every Cordis patch and plugin
+configuration, the launched runtime artifact, environment policy, and telemetry
+selection. Every referenced configuration and runtime digest is rechecked
+before the process starts.
+Environment values are not recorded. The adapter passes a replacement child
+environment to the official client and rejects keys outside the recorded
+allowlist; configured secret values are redacted from retained error and stderr
+tails. When a Harness home is selected, the child `DSH_HOME` is set from that
+retained path and any caller-supplied value must match it.
+
+Two fixtures demonstrate configuration-only swaps:
+
+- `test/fixtures/deepseek/compositions/minimal` disables native telemetry.
+- `test/fixtures/deepseek/compositions/telemetry` composes the telemetry plugin
+  and records its separate artifact reference.
+
+The adapter code is identical for both compositions. Runtime and plugin choices
+remain configuration, not EBO runner branches.
+
+## Native evidence
+
+`HarnessClient` owns the child and JSON-RPC transport. EBO calls only its public
+`start`, `initialize`, `prompt`, `subscribeSessionTree`, and `close` methods.
+The native JSONL evidence records:
+
+- the selected composition and capability report;
+- typed initialize, prompt receipt, notification, error, and shutdown
+  observations in observed order;
+- every delivered `session.event` envelope verbatim, including its native
+  `seq`, `time`, surface metadata, and source-specific fields;
+- root and child session identities from each native notification, with the
+  declared session tree used during bundle qualification;
+- whole-agent `session.status` and available subagent notifications; and
+- bounded, redacted diagnostics only when the official client attributes them
+  to the child stderr tail.
+
+Stdout remains exclusively owned by the official JSON-RPC transport. EBO does
+not attach a console exporter or stdout logger. The controlled-runtime test
+parses every emitted evidence line and forces a contaminated runtime to fail
+while retaining its stderr diagnostic and partial observations.
+
+## Completion and limitations
+
+`session/prompt` returns only the durable queued message ID. Completion requires
+the matching native `agent/inbox/spliced` event followed by the root session
+whole-agent `session.status: idle`. Those two observation sequences are retained
+as the activity boundary. They do not claim that an assistant message was
+caused by the prompt, and `finalResponse` is not treated as a prompt result.
+
+The capability report keeps these current protocol limitations explicit:
+
+- protocol-version negotiation: unsupported;
+- prompt cancellation: unsupported;
+- per-session close: unsupported;
+- true per-prompt result: unsupported; and
+- native spans: available, unsupported, or not checked according to the named
+  telemetry composition.
+
+The official client owns graceful `shutdown`, stdin EOF, SIGTERM, and SIGKILL
+escalation. An interruption, activity timeout, transport exit, or protocol
+failure closes through that same ladder. Delivered notifications and stderr
+remain valid partial evidence.
+
+## Normalization
+
+Normalization begins only when the capture retains the selected composition,
+capabilities, successful initialize and prompt receipts, and at least one
+durable session event. A completed capture additionally requires the exact
+receipt-to-idle boundary and successful official-client close/reap evidence.
+The client does not expose whether its best-effort protocol shutdown request or
+a later EOF/signal step ended the process, so EBO does not invent a shutdown
+response.
+
+The capture report persists the required semantic-evidence kinds and related
+session IDs. Later qualification treats that declaration as authoritative and
+rejects caller overrides that would weaken or replace it.
+
+Mapped events retain a `line:N` native reference into the authoritative DeepSeek
+JSONL. Session events use their native session-local sequence/time; EBO client
+observations use a separate observation-order domain. Large message, tool,
+compaction, request, validation, and artifact bodies remain behind content
+references. Unknown source events remain explicitly unmapped rather than being
+dropped or forced into a convenience family. Optional telemetry stays a
+separate timing/resource artifact and never replaces semantic session events.