open-multi-agent-kit 0.95.1 → 0.96.0

package/docs/mcp.md

@@ -0,0 +1,97 @@
+# MCP
+
+OMK speaks the [Model Context Protocol](https://modelcontextprotocol.io) as a
+**client**: it starts configured servers, lists their tools, and exposes those
+tools to the model alongside the built-in ones.
+
+Two separate surfaces exist, and they are easy to confuse:
+
+| Surface | Module | What it does |
+| --- | --- | --- |
+| Inventory / health | `core/mcp-inventory.ts` | Reads configuration read-only for `omk doctor` and the MCP health view. **Never starts a server.** Env *values* are stripped. |
+| Runtime client | `core/mcp/` | Starts servers, performs the handshake, and registers their tools for a session. |
+
+## Configuration
+
+Servers are read from three files, later wins on a name collision:
+
+1. `~/.kimi/mcp.json`
+2. `~/.omk/mcp.json`
+3. `<cwd>/.omk/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+      "startup_timeout_sec": 60
+    },
+    "serena": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/oraios/serena", "serena"],
+      "env": { "SERENA_LOG_LEVEL": "error" }
+    },
+    "retired": { "command": "npx", "args": ["-y", "old-server"], "disabled": true }
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `command`, `args` | Executable to spawn. **Required** — entries with only a `url` are skipped, since stdio is the supported transport. |
+| `env` | Extra environment for the child. Merged over the parent environment. Values are runtime-only and are never rendered or logged. |
+| `cwd` | Working directory. Defaults to the session's cwd. |
+| `disabled` / `enabled: false` | Skip without deleting the entry. |
+| `startup_timeout_sec` | Handshake deadline. Raise it for `npx -y …@latest` servers whose first run downloads a package. |
+
+## Using it
+
+```ts
+const status = await session.attachMcpServers();
+// [{ name: "playwright", state: "ready", toolCount: 24, serverVersion: "1.62.0" }]
+
+session.getToolDefinition("playwright__navigate");
+```
+
+- **Nothing is spawned until `attachMcpServers()` is called.** A workspace can
+  configure 25 servers without paying for them at startup.
+- Tools are exposed as `<server>__<tool>`, truncated to 64 characters with the
+  server prefix preserved.
+- A built-in tool always wins a name collision; MCP can never shadow `bash`.
+- Calling `attachMcpServers()` again replaces the previous MCP tools rather than
+  duplicating them.
+- `session.dispose()` terminates every server it started.
+
+### Failure behavior
+
+Failures are isolated by design, because one broken server must not cost a
+session:
+
+| Failure | Result |
+| --- | --- |
+| Server exits during startup | That server is `failed` with its stderr tail; every other server still contributes tools. |
+| Handshake exceeds `startup_timeout_sec` | Same — reported as a timeout, session unaffected. |
+| Server dies mid-session | In-flight requests reject; later calls to its tools return a tool-level error instead of throwing. |
+| Tool returns an MCP error | Surfaces as a normal tool result with `isError: true`, so the model sees the server's own message. |
+| Server emits a non-JSON line | The line is dropped and decoding resynchronizes at the next newline. |
+
+## Checking your configuration
+
+```bash
+node scripts/mcp-smoke.mjs                       # connect everything, print status
+node scripts/mcp-smoke.mjs github playwright     # only these
+OMK_MCP_SMOKE_HANDSHAKE_MS=120000 node scripts/mcp-smoke.mjs   # override slow handshakes
+```
+
+The script prints server state, tool counts, and versions. It never prints env
+values.
+
+## Scope
+
+Implemented: `initialize`, `notifications/initialized`, `tools/list`,
+`tools/call` over stdio.
+
+Not implemented: HTTP/SSE transports, resources, prompts, sampling, and
+server-initiated requests. Every OMK-configured server today is stdio, and
+adding a surface nothing calls would be dead weight.

package/docs/metrics.md

@@ -0,0 +1,87 @@
+# Turn metrics
+
+OMK records one JSON line per agent turn so harness changes can be measured
+instead of guessed.
+
+This is separate from the two things that already existed:
+
+| Surface | Purpose |
+| --- | --- |
+| `core/run-journal.ts` | Hash-chained **integrity** log (run started/finished/recovered, tool timeout). Answers "was this run tampered with or abandoned". |
+| `core/telemetry.ts` | Install-time opt-in flag. Nothing else. |
+| `core/turn-metrics.ts` | **Performance and quality**: cost, latency, tool failure rates, cache effectiveness. |
+
+## Where it goes
+
+`<cwd>/.omk/metrics/turns.jsonl`, append-only, rotated once past 8 MB
+(`turns.jsonl.1`), file mode `600`.
+
+| Variable | Effect |
+| --- | --- |
+| `OMK_TURN_METRICS=0` | Disable recording entirely. |
+| `OMK_TURN_METRICS_DIR` | Write somewhere else. |
+
+## Reading it
+
+```bash
+omk stats                    # aggregate report for the current project
+omk stats --dir <path>       # a different metrics directory
+omk stats --json             # machine-readable summary
+```
+
+```text
+Turn metrics — 412 turns across 27 session(s)
+  models        anthropic/claude-sonnet-4-5
+  turn duration p50 4.2s · p95 31.8s
+  input 91,204 · output 22,880 · cacheRead 1,904,551 · cacheWrite 88,100
+  cache read share 95.4% of prompt-side usage
+  cost          $4.8812
+  compactions 6 · failovers 1 · ctx plan hit 41.2%
+
+  tool                 calls   fail%     p50     p95    total
+  bash                   688    4.2%   210ms    3.1s     4.1m
+  edit                   201    9.0%    38ms   140ms    12.4s
+```
+
+## What is recorded
+
+Counts, durations, ids, and error *classes*:
+
+```json
+{
+  "schemaVersion": "omk-turn-metrics-1",
+  "sessionId": "…", "turnIndex": 12,
+  "provider": "anthropic", "model": "claude-sonnet-4-5",
+  "startedAtEpochMs": 1, "endedAtEpochMs": 2, "durationMs": 1,
+  "usage": { "input": 100, "output": 20, "cacheRead": 900, "cacheWrite": 10, "costUsd": 0.0125 },
+  "stopReason": "toolUse",
+  "toolCalls": [{ "name": "bash", "durationMs": 120, "ok": false, "error": "exit 1" }],
+  "toolCallCount": 1, "toolFailureCount": 1
+}
+```
+
+**Never recorded:** prompt text, tool arguments, tool output, file contents, or
+environment values. Tool error strings are whitespace-collapsed and truncated to
+200 characters — enough to tell failure modes apart, too short to carry a
+payload.
+
+Metrics are advisory. A failed write is counted and dropped; it can never make a
+turn fail.
+
+## Capability baseline
+
+Runtime metrics tell you what a session cost, not whether the harness can solve
+tasks. For that, `scripts/tb-mini-suite.mjs` selects a deterministic,
+difficulty-balanced Terminal-Bench 2.1 subset so scores are comparable across
+runs:
+
+```bash
+node scripts/tb-mini-suite.mjs             # human-readable selection
+node scripts/tb-mini-suite.mjs --json      # feed a runner
+node scripts/tb-mini-suite.mjs --seed 7    # a different fixed subset
+```
+
+Selection is a pure function of (tasks directory, seed, size): the same inputs
+always produce the same task list, which is the whole point of using it as a
+regression gate. The scoring run itself requires Docker, `harbor`, and real
+model spend — it is deliberately not wired into `npm run check`.

package/docs/models.md

@@ -4,6 +4,7 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.omk/a
 
 ## Table of Contents
 
+- [Built-in NVIDIA GLM-5.2](#built-in-nvidia-glm-52)
 - [Minimal Example](#minimal-example)
 - [Full Example](#full-example)
 - [Supported APIs](#supported-apis)
@@ -14,6 +15,10 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.omk/a
 - [Anthropic Messages Compatibility](#anthropic-messages-compatibility)
 - [OpenAI Compatibility](#openai-compatibility)
 
+## Built-in NVIDIA GLM-5.2
+
+With `NVIDIA_API_KEY` configured, `nvidia/z-ai/glm-5.2` supports OMK thinking levels through NVIDIA NIM. Its generated metadata explicitly enables `reasoning_effort`, so `/thinking max` is sent as `reasoning_effort: "max"`. Other NVIDIA models do not inherit that capability automatically.
+
 ## Minimal Example
 
 For local models (Ollama, LM Studio, vLLM), only `id` is required per model:
@@ -146,22 +151,29 @@ Set `api` at provider level (default for all models) or model level (override pe
 The `apiKey` and `headers` fields support command execution, environment interpolation, and literals:
 
 - **Shell command:** `"!command"` at the start executes the whole value as a command and uses stdout
+
   ```json
   "apiKey": "!security find-generic-password -ws 'anthropic'"
   "apiKey": "!op read 'op://vault/item/credential'"
   ```
+
 - **Environment interpolation:** `"$ENV_VAR"` or `"${ENV_VAR}"` uses the value of the named variable. Interpolation works inside larger literals.
+
   ```json
   "apiKey": "$MY_API_KEY"
   "apiKey": "${KEY_PREFIX}_${KEY_SUFFIX}"
   ```
+
   `$FOO_BAR` is the variable `FOO_BAR`; use `${FOO}_BAR` when `BAR` is literal text. Missing environment variables make the value unresolved.
 - **Escapes:** `"$$"` emits a literal `"$"`; `"$!"` emits a literal `"!"` without triggering command execution.
+
   ```json
   "apiKey": "$$literal-dollar-prefix"
   "apiKey": "$!literal-bang-prefix"
   ```
+
 - **Literal value:** Used directly
+
   ```json
   "apiKey": "sk-..."
   ```

package/docs/packages.md

@@ -2,11 +2,12 @@
 
 # OMK Packages
 
-OMK packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in `package.json` under the `omk` key, or use conventional directories.
+OMK packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in `package.json` under `omk` or the compatible `pi` key, or use conventional directories.
 
 ## Table of Contents
 
 - [Install and Manage](#install-and-manage)
+- [Pi Compatibility and Package Doctor](#pi-compatibility-and-package-doctor)
 - [Package Sources](#package-sources)
 - [Creating a OMK Package](#creating-a-omk-package)
 - [Package Structure](#package-structure)
@@ -28,6 +29,7 @@ omk install ./relative/path/to/package
 
 omk remove npm:@foo/bar
 omk list                     # show installed packages from settings
+omk package doctor npm:@foo/bar@1.0.0  # static compatibility report as JSON
 omk update                   # update omk, update packages, and reconcile pinned git refs
 omk update --extensions      # update packages and reconcile pinned git refs only
 omk update --self            # update omk only
@@ -47,6 +49,24 @@ omk -e npm:@foo/bar
 omk -e git:github.com/user/repo
 ```
 
+## Pi Compatibility and Package Doctor
+
+OMK reads package manifests in strict priority order: `omk`, then `pi`, then conventional directories. The first present manifest is authoritative. If it is malformed, OMK reports the error instead of silently falling back. When both keys exist, `omk` wins and the doctor reports that `pi` was shadowed.
+
+A Pi extension directory entry such as `"extensions": ["./"]` resolves to its `index.ts`, `index.js`, `index.mjs`, or `index.cjs`. It is not recursively treated as a directory of independent extensions.
+
+Inspect a local, npm, or git source before installing it:
+
+```bash
+omk package doctor ./local-package
+omk package doctor npm:@scope/package@1.2.3 > package-doctor.json
+omk package doctor git:github.com/user/repo@v1
+```
+
+The command emits a versioned JSON report and returns `0` when no compatibility error is found, `1` for an incompatible package or inspection failure, and `2` for invalid CLI usage. It checks manifest precedence, declared resources, legacy Pi runtime imports, `.pi` storage paths, lifecycle event names, headless UI guards, and resume signals.
+
+The doctor never imports extension modules. For npm sources it downloads the registry tarball with `npm pack --ignore-scripts` and extracts bounded regular files without installing dependencies. Git inspection clones without running `npm install`. These static checks are advisory and do not make third-party code trusted.
+
 ## Package Sources
 
 OMK accepts three source types in settings and `omk install`.
@@ -91,6 +111,7 @@ ssh://git@github.com/user/repo@v1
 - When reconciliation changes the checkout, omk resets and cleans the clone, then runs `npm install` if `package.json` exists.
 
 **SSH examples:**
+
 ```bash
 # git@host:path shorthand (requires git: prefix)
 omk install git:git@github.com:user/repo
@@ -113,7 +134,7 @@ Local paths point to files or directories on disk and are added to settings with
 
 ## Creating a OMK Package
 
-Add a `omk` manifest to `package.json` or use conventional directories. Include the `omk-package` keyword for discoverability.
+Add an `omk` manifest to `package.json` or use conventional directories. OMK also reads a Pi-compatible `pi` manifest when `omk` is absent. Include the `omk-package` keyword for discoverability.
 
 ```json
 {
@@ -155,7 +176,7 @@ If both are set, video takes precedence.
 
 ### Convention Directories
 
-If no `omk` manifest is present, omk auto-discovers resources from these directories:
+If neither an `omk` nor a `pi` manifest is present, omk auto-discovers resources from these directories:
 
 - `extensions/` loads `.ts` and `.js` files
 - `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
@@ -164,7 +185,7 @@ If no `omk` manifest is present, omk auto-discovers resources from these directo
 
 ## Dependencies
 
-Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When omk installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
+Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. Normal npm and git installation installs runtime dependencies automatically. `omk package doctor` is different: it does not install dependencies or execute lifecycle scripts.
 
 OMK bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `omk-ai`, `omk-agent-core`, `open-multi-agent-kit`, `omk-tui`, `typebox`.
 

package/docs/provider-resilience.md

@@ -1,87 +1,68 @@
-# Provider resilience (root-level)
+# Provider Resilience
 
-Built into OMK core — not an optional extension.
+OMK can recover an agent turn from provider failures that are unlikely to succeed unchanged:
 
-## What it does
+- content or safety stops reported as errors
+- billing-cycle or quota exhaustion
+- orphaned `tool_call_id` protocol errors
+- transient transport and server failures
 
-1. **Blocks sticky safety models** (e.g. `claude-fable-5`) from being selected as the session chat model.
-2. **Ejects** them at prompt time if a resumed session still has one loaded.
-3. On **content/safety stop** (`stop_reason=refusal`), **auto-failovers** to `k3 → grok-4.5 → deepseek` before retry.
-4. Works with message sanitize (`transform-messages` orphan `tool_call_id` drop) so K3 protocol 400s can heal on retry.
+This is availability behavior, not a safety bypass. Provider safety policy and the user's configured model access remain authoritative.
 
-This is session survival engineering, not a jailbreak.
+## Settings
 
-## Settings (`~/.omk/agent/settings.json`)
+Configure resilience in `~/.omk/agent/settings.json` or `.omk/settings.json`:
 
 ```json
 {
-  "defaultProvider": "kimi-coding",
-  "defaultModel": "k3",
   "providerResilience": {
     "blockStickySafetyModels": true,
     "autoFailoverOnSafetyStop": true,
     "failoverCandidates": [
       { "provider": "kimi-coding", "id": "k3" },
-      { "provider": "grok-oauth-proxy", "id": "grok-4.5" },
-      { "provider": "deepseek", "id": "deepseek-v4-pro" }
+      { "provider": "modelstudio-maas", "id": "qwen3.8-max-preview" }
     ]
   }
 }
 ```
 
-| Key | Default | Meaning |
-|---|---|---|
-| `blockStickySafetyModels` | `true` | Refuse `setModel` / initial pick of Fable-class ids |
-| `autoFailoverOnSafetyStop` | `true` | Switch model before auto-retry on safety stop |
-| `failoverCandidates` | k3→grok→deepseek… | Ordered targets |
+| Setting | Default | Behavior |
+|---|---:|---|
+| `blockStickySafetyModels` | `true` | Rejects models known to produce sticky false-positive safety stops. |
+| `autoFailoverOnSafetyStop` | `true` | Enables failover for safety stops and quota/billing exhaustion. |
+| `failoverCandidates` | built-in chain | Ordered models considered before an automatic retry. |
 
-Disable only if you intentionally want Fable:
+Automatic recovery also requires `retry.enabled: true` and available retry budget.
 
-```json
-"providerResilience": { "blockStickySafetyModels": false, "autoFailoverOnSafetyStop": false }
-```
+## Failover behavior
 
-## Code
+For a safety stop or recognized quota/billing error, OMK:
 
-| Module | Role |
-|---|---|
-| `src/core/provider-resilience.ts` | Shared detectors + failover pick |
-| `src/core/agent-session.ts` | eject / failover / retry wiring |
-| `src/core/model-resolver.ts` | skip sticky on initial model pick |
-| `src/core/settings-manager.ts` | `providerResilience` settings |
-| `packages/ai/.../transform-messages.ts` | drop orphan tool results |
+1. classifies the failed provider attempt;
+2. excludes the current model and models already failed during this retry sequence;
+3. selects the first non-sticky candidate that exists and has configured authentication;
+4. switches models before retrying with a short delay.
 
-## How Fable is neutralized (not "jailbroken")
+If no candidate qualifies, the normal same-model retry policy and backoff apply. Plain authentication errors remain non-retryable and do not trigger failover.
 
-Server-side content/safety stops cannot be removed by OAuth RE or local patches.
-OMK **deletes Fable from the operational surface**:
+Recognized quota shapes include billing-cycle usage limits, `insufficient_quota`, exhausted balances, `GoUsageLimitError`, `FreeUsageLimitError`, and out-of-budget responses. These are classified as `provider.rate_limit`, even when a provider wraps them in HTTP 403.
 
-| Layer | Kill switch |
-|---|---|
-| `models.json` | `claude-fable-5` removed from anthropic catalog |
-| `model-registry.loadModels` | `/fable/i` filtered unless `OMK_ALLOW_STICKY_SAFETY_MODELS=1` |
-| `model-resolver` | sticky skipped; k3 preferred |
-| `setModel` | throws if sticky + block on |
-| `cycleModel` (scoped + available) | sticky filtered; goes through `setModel` |
-| prompt boundary | ejects leftover Fable session model → k3 |
-| safety-stop retry | failover chain before continue |
+The default candidate order is:
 
-**You don't fight Fable. You never load it.**
+1. `kimi-coding/k3`
+2. `modelstudio-maas/qwen3.8-max-preview`
+3. `grok-oauth-proxy/grok-4.5`
+4. `deepseek/deepseek-v4-pro`
+5. `deepseek/deepseek-v4-flash`
+6. `modelstudio-maas/deepseek-v4-pro`
+7. `kimi-coding/kimi-for-coding`
 
-## Operator
+## Retry and termination events
 
-```
-# after rebuild — restart OMK session (required)
+Each provider attempt is journaled separately and emits `session_termination`. A retryable failure is attempt-level when an `auto_retry_start` event follows it. A recovered retry later emits a `completed` termination; an exhausted retry budget leaves the last provider failure as the final termination.
 
-/model k3          # if still on a bad model
-/new               # if transcript is corrupted (orphan tool ids)
-
-# emergency re-enable Fable (not recommended)
-OMK_ALLOW_STICKY_SAFETY_MODELS=1 omk
-# and settings: providerResilience.blockStickySafetyModels=false
-```
+See [Sessions](sessions.md#retries-and-termination-events) for consumer guidance.
 
-## arXiv note (2026-07)
+## Protocol recovery
 
-Recent cs.CL hits on refusal/jailbreak are mostly attack-ASR / weight-edit / prefill studies.
-No immediate ops patch beyond routing+sanitize already in-tree. Skip theory-only papers.
+For orphaned `tool_call_id` errors, OMK removes the failed assistant message from the live retry context. The standard message transform then drops tool results whose originating call is absent. Persisted session history remains unchanged for auditability.

package/docs/providers.md

@@ -33,7 +33,7 @@ Alibaba Model Studio Token Plan is recognized as **QWEN TOKEN PLAN** but shows `
 
 - Requires ChatGPT Plus or Pro subscription
 - Officially endorsed by OpenAI: [Codex for OSS](https://developers.openai.com/community/codex-for-oss)
-- `gpt-5.6-moa` is a tool-free virtual model that runs bounded GPT-5.6 Sol and Terra advisers concurrently, then streams a Sol synthesis. It performs three inference calls per turn, caps adviser/synthesis output independently, and is intended for analysis, review, and answer synthesis; use Sol or Terra directly when tools are required.
+- `gpt-5.6-moa` runs bounded, tool-free GPT-5.6 Sol and Terra advisers concurrently, then streams a Sol synthesis with the active tools and tool history. Synthesis tool calls enter the normal agent loop; each follow-up model turn repeats the three-call workflow. Adviser and synthesis output remain independently capped.
 - The Codex backend accepts `xhigh` as its highest literal reasoning effort. OMK's `max` and `ultra` tiers map to `xhigh`; `ultra` on the MoA model additionally represents the Sol/Terra delegation workflow.
 
 ```bash
@@ -99,6 +99,10 @@ omk
 
 Reference for environment variables and `auth.json` keys: [`const envMap`](https://github.com/dmae97/omk/blob/main/packages/ai/src/env-api-keys.ts) in [`packages/ai/src/env-api-keys.ts`](https://github.com/dmae97/omk/blob/main/packages/ai/src/env-api-keys.ts).
 
+#### NVIDIA NIM
+
+Set `NVIDIA_API_KEY` and select an NVIDIA model with `/model`. The built-in `nvidia/z-ai/glm-5.2` entry sends `reasoning_effort`, including the `max` level. Other NVIDIA models keep conservative compatibility defaults unless their model metadata explicitly enables reasoning effort.
+
 #### Zyloo
 
 Zyloo is an OpenAI-compatible unified API gateway. Set `ZYLOO_API_KEY` and use any Zyloo-hosted model:

package/docs/run-protocol.md

@@ -0,0 +1,72 @@
+# OMK Run Protocol v1
+
+The OMK Run Protocol defines one versioned contract for task execution and evaluation:
+
+```text
+TaskSpec -> ExecutionAttempt -> Observation -> EvaluationResult -> RuntimeDecision
+```
+
+`omk-protocol` owns these records and the pure reducers that connect them. Tool execution, persistence, scheduling, routing, and topology remain outside the package.
+
+## Implemented scope
+
+The first v1 slice is available under `packages/protocol` with schema version `omk.run.v1`.
+
+| Contract | Purpose |
+| --- | --- |
+| `TaskSpec` | Goal and required or advisory `ClaimPredicate` records |
+| `ExecutionAttempt` | One completed initial, retry, failover, or resumed execution |
+| `Observation` | Immutable facts tied to a task and attempt |
+| `ClaimEvaluation` | Derived `satisfied`, `violated`, or `inconclusive` claim result |
+| `EvaluationResult` | Claim evaluations plus one semantic `pass`, `fail`, or `inconclusive` verdict |
+| `RuntimeDecision` | Pure `continue`, `retry`, `failover`, or `stop` decision |
+| `WaiverRecord` | Explicit, scoped, attributable, and optionally expiring exception |
+
+Every top-level record carries `schemaVersion`. Parsers reject unsupported versions, malformed timestamps, duplicate claim IDs, invalid JSON facts, and empty logical conditions.
+
+## Evaluation model
+
+`evaluateTask()` is a pure `TaskSpec + ExecutionAttempt + Observation[] + WaiverRecord[] -> EvaluationResult` reducer. It does not mutate its inputs or stored evidence.
+
+An observation condition selects facts by observation kind and task or attempt scope. Its expected facts are a recursive object subset; arrays match exactly.
+
+- no candidate observation: `inconclusive`
+- candidate with matching facts: `satisfied`
+- candidates present but none match: `violated`
+- `all`, `any`, and `not` compose conditions without adding evaluator state
+
+Required, unwaived violations reduce to `fail`. Required, unwaived missing observations reduce to `inconclusive`. Otherwise the semantic verdict is `pass`. Advisory claims are reported but do not block. A task with no required claims is `inconclusive`.
+
+`reduceRuntimeDecision()` then maps the semantic verdict through an explicit runtime policy. `pass` always stops successfully; fail and inconclusive behavior is supplied as `onFail` and `onInconclusive`. Retry and failover counters are not fields: consumers derive them from `ExecutionAttempt` records.
+
+## Waivers
+
+A waiver names one task and claim, the approver, approval time, rationale, and evidence references. It may be limited to one attempt and may expire. Evaluation fails closed for cross-task, unknown-claim, future-approved, expired, duplicate, or advisory-claim waivers. The underlying claim result remains visible; `waiverId` records why it did not block.
+
+## EvidenceReceipt v3 bridge
+
+`EvidenceReceipt v3` remains the integrity layer. `evidenceReceiptToObservation()` from `open-multi-agent-kit` validates the immutable core digest, then projects only execution facts into an `Observation`:
+
+- receipt schema version and claim text
+- exit code, timeout flag, and abort flag
+- duration and executor
+- a digest-bound receipt reference
+
+The adapter deliberately omits the legacy mutable evidence status. Receipt digest validation does not prove ledger membership, trusted attestation, runner honesty, freshness, or OS isolation; apply those checks separately before trusting the observation.
+
+```typescript
+import { evaluateTask, reduceRuntimeDecision } from "omk-protocol";
+import { evidenceReceiptToObservation } from "open-multi-agent-kit";
+```
+
+The legacy `TaskContract`, `EvidenceStatus`, `TaskContractBuilder.setVerdict()`, and `updateEvidenceStatus()` remain for compatibility and are deprecated. New code should append observations and recompute evaluation.
+
+## Authority boundaries
+
+This slice does not change runtime ownership:
+
+- the coding-agent still owns provider retry and failover execution;
+- AdaptOrch WPL still owns its existing work-packet state machine and adjudication types;
+- scheduler and router separation, topology validation, background-task durability, and algorithm-isolation work remain follow-up migrations.
+
+Those components should consume `omk-protocol` rather than define new task, attempt, observation, or semantic-verdict types.