open-multi-agent-kit 0.95.2 → 0.96.1

package/docs/provider-resilience.md

@@ -1,87 +1,74 @@
-# 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` | Blocks interactive and automatic activation of models known to produce sticky false-positive safety stops. The catalog still lists them; set this to `false` to use an interactive or saved selection. |
+| `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 }
-```
+An explicit `--model` or `--provider`/`--model` pin keeps automatic resilience from replacing that model. A later manual model selection can still change it.
+Safety-stop failover and sticky-model eject do not run on a pinned model.
+Claude Fable, Opus, and Sonnet also stay on-model after a content/safety stop,
+even without `--model` and even when skills are loaded. Those refusals are not
+retried on DeepSeek or Kimi.
 
-## Code
+## Failover behavior
 
-| 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 |
+For a safety stop or recognized quota/billing error, OMK:
 
-## How Fable is neutralized (not "jailbroken")
+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.
 
-Server-side content/safety stops cannot be removed by OAuth RE or local patches.
-OMK **deletes Fable from the operational surface**:
+A content/safety stop gets at most one automatic retry, including a retry that switches model, regardless of the larger transport retry budget. Other transient failures keep the configured retry policy and backoff. Plain authentication errors remain non-retryable and do not trigger failover.
 
-| 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 |
+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.
 
-**You don't fight Fable. You never load it.**
+The default candidate order is:
 
-## Operator
+1. `kimi-coding/k3`
+2. `modelstudio-maas/qwen3.8-max-preview`
+3. `xai/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`
 
-```
-# after rebuild — restart OMK session (required)
+## Retry and termination events
 
-/model k3          # if still on a bad model
-/new               # if transcript is corrupted (orphan tool ids)
+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.
 
-# 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

@@ -18,16 +18,19 @@ Use `/login` in interactive mode, then select a provider:
 - ChatGPT Plus/Pro (Codex)
 - Claude Pro/Max
 - GitHub Copilot
+- xAI Grok subscription OAuth
 
 Run `/login` and choose a configured subscription provider to open its account picker. Select an existing account by its ChatGPT, Claude, or Google email when available, or choose **Add another account** to sign in with a new one. OMK keeps and refreshes each account independently, pins the provider to the account you select, and does not silently fail over to another subscription. `/model` remains dedicated to model selection.
 
 Use `/logout` to clear all stored accounts for a provider. Tokens are stored in `~/.omk/agent/auth.json` and auto-refresh when expired.
 
-When the status sidebar is pinned, its **USAGE** section lists every configured subscription provider, with the active provider first. OMK reads quota windows from fixed provider endpoints for Codex, Claude, Kimi Code, and GLM/ZAI Coding Plan, caches the result, and displays each percentage and reset countdown separately. Claude also passively merges the official `anthropic-ratelimit-unified-*` response headers used by Claude Code. If Anthropic's usage endpoint is rate limited and no complete recent snapshot exists, OMK mirrors Claude Code's own startup quota check with one fixed-endpoint Haiku request capped at one output token, no more than once per OAuth credential per hour. This fallback consumes a small amount of Claude plan quota.
+When the status sidebar is pinned, its **USAGE** section lists every configured subscription provider, with the active provider first. OMK reads quota windows from fixed provider endpoints for Codex, Claude, Kimi Code, GLM/ZAI Coding Plan, and native xAI SuperGrok, caches the result, and displays each percentage and reset countdown separately. Claude also passively merges the official `anthropic-ratelimit-unified-*` response headers used by Claude Code. If Anthropic's usage endpoint is rate limited and no complete recent snapshot exists, OMK mirrors Claude Code's own startup quota check with one fixed-endpoint Haiku request capped at one output token, no more than once per OAuth credential per hour. This fallback consumes a small amount of Claude plan quota.
 
 Codex streaming passively merges `x-codex-primary-*`, `x-codex-secondary-*`, and `codex.rate_limits` signals through the non-blocking `StreamOptions.onRateLimit` observer. These signals supplement missing polling windows only when the Codex service returns them; OMK does not infer a missing 5-hour value from a 7-day value.
 
-Alibaba Model Studio Token Plan is recognized as **QWEN TOKEN PLAN** but shows `console-only quota`. Its [official usage page](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=plan&commonbuy=1&orderType=buy#/efm/subscription/token-plan) obtains `per5HourPercentage`, `per5HourResetTime`, `per1WeekPercentage`, and `per1WeekResetTime` through an authenticated Alibaba Cloud console gateway. The plan-specific `sk-sp-*` key does not authorize that console endpoint, and compatible-mode model responses expose token counts but no quota headers. OMK therefore does not copy browser cookies or estimate quota from token counts. Qwen OAuth and Grok remain explicit `quota API unavailable`.
+Alibaba Model Studio Token Plan is recognized as **QWEN TOKEN PLAN** but shows `console-only quota`. Its [official usage page](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=plan&commonbuy=1&orderType=buy#/efm/subscription/token-plan) obtains `per5HourPercentage`, `per5HourResetTime`, `per1WeekPercentage`, and `per1WeekResetTime` through an authenticated Alibaba Cloud console gateway. The plan-specific `sk-sp-*` key does not authorize that console endpoint, and compatible-mode model responses expose token counts but no quota headers. OMK therefore does not copy browser cookies or estimate quota from token counts. Qwen OAuth remains explicit `quota API unavailable`.
+
+With a stored native `xai` OAuth credential, OMK reads `GET https://cli-chat-proxy.grok.com/v1/billing?format=credits` and shows the weekly SuperGrok pool from `config.creditUsagePercent` plus its reset from `config.currentPeriod.end`. `XAI_API_KEY` is a separate API-billing credential and does not authorize this subscription endpoint.
 
 ### OpenAI Codex
 
@@ -49,9 +52,11 @@ Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party h
 - Press Enter for github.com, or enter your GitHub Enterprise Server domain
 - If you get "model not supported", enable it in VS Code: Copilot Chat → model selector → select model → "Enable"
 
-### Grok harness presets
+### xAI Grok
+
+Both authentication modes use the built-in `xai` provider. Run `/login` for subscription OAuth, or set `XAI_API_KEY` for xAI Platform API billing. Do not configure a second Grok provider.
 
-For `grok-oauth-proxy` project presets, Composer routing, and Imagine tool guidance, see [Grok harness](grok-harness.md).
+For project presets, Imagine guidance, and the exact `grok-4.6`, `grok-4.5`, and `grok-4.3` thinking mappings, see [Grok harness](grok-harness.md).
 
 ## API Keys
 
@@ -99,6 +104,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,104 @@
+# 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.
+
+## Durable goal lifecycle
+
+A durable goal is working-directory state, not a session-file field or a `TaskSpec`. `/goal <objective>` creates or edits `.omk/goals/current.json`; `/goal` without arguments shows its status and round count.
+
+Goals created by `/goal` use an eight-round cap. The controller queues another turn only while the goal is active, no message is pending, and the cap has not been reached. Reaching the cap stops automatic continuation; the controller does not infer or mark completion.
+
+For programmatic lifecycle control, import `createDurableGoal`, `parseDurableGoalSnapshot`, `applyDurableGoalCommand`, and `DurableGoalStore` from `open-multi-agent-kit`. The reducer supports edit, pause, resume, block, round advancement, evidence attachment, completion, and clear transitions.
+
+Every mutation consumes the current revisioned `GoalRef`; stale revisions are rejected. Editing the objective or round limit, or advancing a round, starts a new semantic generation and invalidates earlier completion evidence. Completion requires lowercase SHA-256 evidence captured during the current generation.
+
+### Seam checkpoints
+
+A durable goal can carry one bounded `Goal / Core / Verified / Open / Next` seam checkpoint. The checkpoint is another revision in `.omk/goals/current.json`, not a separate state tree. It is bound to the goal generation and referenced evidence IDs, forced-redacted before persistence, and correlated by a content digest. The digest is unkeyed: it detects accidental mismatch but does not authenticate workspace state against a same-user editor.
+
+Use the interactive command with strict JSON:
+
+```text
+/goal checkpoint {"core":["Keep deterministic gates authoritative"],"verified":["focused-tests"],"open":["Historical calibration"],"next":"Run the package checks"}
+```
+
+`verified` may name only fresh evidence already attached to the current goal generation. A round advance carries the checkpoint record forward but does not make its evidence current-round proof. The built-in controller injects checkpoint prose only when the user recorded it through `/goal checkpoint` in the current process. A checkpoint loaded from mutable workspace state is noted by digest and its prose is not promoted to user authority. Editing the objective or round limit clears it. The session stores only a `goal_checkpoint` entry containing the goal ID, revision, and checkpoint digest; complete content remains in the existing durable-goal journal.
+
+Programmatic callers use the `record-checkpoint` command with `applyDurableGoalCommand()` or `DurableGoalStore.transition()`. `parseDurableGoalCheckpointCommand()` parses the interactive JSON shape; `formatDurableGoalCheckpoint()` renders the five fields.
+
+## 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.
+
+### Advisory best-of-N judge
+
+`chooseWithAdvisoryJudge()` is an optional selection sidecar, not a protocol verdict producer. It validates each `EvaluationResult`, admits only candidates whose semantic verdict is `pass`, and lets a judge score only that eligible set. Zero eligible candidates produce no selection; one skips the model; multiple candidates use weighted 0–4 rubric scores.
+
+Candidate material, the task goal, and rubric descriptions are forced-redacted and bounded before the judge receives them. The model adapter uses a tool-free prompt, treats candidate text as untrusted data, disables retries and cache retention, and accepts only a complete matrix of known candidate and criterion IDs. A provider error, timeout, malformed JSON, unknown ID, or incomplete score matrix selects the existing deterministic first choice and reports a sanitized fallback reason.
+
+The sidecar never creates an `Observation`, changes `EvaluationResult.semanticVerdict`, supplies independent-verifier evidence, waives a claim, or changes `RuntimeDecision`. Run fresh tests, integrity checks, security gates, and evidence freshness checks after applying the selected candidate.
+
+## 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.

package/docs/sdk.md

@@ -14,6 +14,19 @@ The SDK provides programmatic access to omk's agent capabilities. Use it to embe
 
 See [examples/sdk/](../examples/sdk/) for working examples from minimal to full control.
 
+## Inspect persisted sessions from the CLI
+
+Use `omk sdk session` to inspect or append to stored JSONL sessions without starting the TUI:
+
+```bash
+omk sdk session status [id] [--cwd <path>] [--session-dir <path>] [--json]
+omk sdk session tail [id] [--cwd <path>] [--session-dir <path>] [--limit <n>]
+omk sdk session inspect [id] [--cwd <path>] [--session-dir <path>]
+omk sdk session send <id> "<message>" [--cwd <path>] [--session-dir <path>]
+```
+
+`status` without an ID lists sessions for the selected working directory. `tail` and `inspect` without an ID select the most recently modified session; `tail` defaults to 20 entries. `send` requires an exact ID, appends a user-message entry only when the session has no active owner, and does not wake or execute an agent. `status` is human-readable unless `--json` is passed; the other actions emit JSON. Exit codes are `0` for success, `1` when no target exists or the session is active, and `2` for invalid usage.
+
 ## Quick Start
 
 ```typescript
@@ -134,6 +147,20 @@ interface AgentSession {
 
 Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
 
+### AgentSession policy seams
+
+The package root exports focused policy helpers for custom runtimes and tests:
+
+| Exports | Purpose |
+| --- | --- |
+| `shouldSkipCompactionCheck`, `isSessionModelOverflow` | Compaction eligibility and overflow ownership |
+| `isRetryableAssistantError`, `nextRetryAttempt`, `computeRetryDelayMs`, `isFailoverTriggerError`, `failoverModelKey` | Retry and failover decisions |
+| `computePromptTokenBudget`, `computeResponseReserveTokens` | Prompt and response token budgets |
+| `classifyPromptCacheTransition` | Cache establishment, reuse, change, or bypass |
+| `assembleSessionSystemPrompt` | System-prompt options, text, and cache boundary |
+
+The decision and arithmetic helpers perform no I/O. `assembleSessionSystemPrompt()` delegates to the system-prompt planner, which incorporates the current date and installation paths.
+
 ### createAgentSessionRuntime() and AgentSessionRuntime
 
 Use the runtime API when you need to replace the active session and rebuild cwd-bound runtime state.
@@ -216,6 +243,8 @@ const executor = new VerifiedEvidenceExecutor({ store, ledger });
 
 `transcript_repaired`, `tool_timeout`, `tool_late_settlement`, and `workspace_mutation` use that ledger. A receipt at or before a later relevant workspace mutation is blocked by `EvidenceGate`.
 
+New replay events declare `payloadHashAlgorithm: "jcs-rfc8785-v2"`; payload keys are canonicalized with RFC 8785 before SHA-256 hashing, and the algorithm identifier is part of the event-hash commitment. Existing events with no algorithm are verified with the original `json-stringify-v1` contract. Loading, appending to, replaying, or exporting a mixed ledger does not rewrite or relabel those legacy events. Unknown declared algorithms fail closed.
+
 ### Prompting and Message Queueing
 
 `PromptOptions` controls prompt expansion, queueing behavior while streaming, and prompt preflight notifications:
@@ -374,6 +403,8 @@ session.subscribe((event) => {
 });
 ```
 
+`session_termination` is emitted per provider attempt, not only when the outer `prompt()` call stops. If `auto_retry_start` follows a retryable termination, wait for the recovered attempt; `session.lastTermination` is updated to the later `completed` result on success.
+
 ## Options Reference
 
 ### Directories
@@ -530,10 +561,12 @@ The `edit` tool returns `details.diff` for OMK's TUI display and `details.patch`
 
 The `diagnostics` tool runs the project's own checkers and normalizes the result — `tsc --noEmit` for TypeScript, `pyright`/`ruff` for Python, `go vet` for Go, `cargo check` for Rust. Missing checkers or project markers are reported as `skipped` in the tool result instead of failing. Output is capped at 50 diagnostics and cached for 5 s.
 
+With default OMP seams, truncated `read` output does not create a sidecar. With `OMK_OMP_SEAMS=0`, legacy truncation may write the selected window to `<absolute-source-path>.omk-spill.txt`; `ReadToolDetails.fullOutputPath` reports the path when present. A first line that alone exceeds the byte cap is clipped without a sidecar. The exported `spillTruncatedOutput()` helper provides the preview-plus-path contract for custom tools.
+
 ```typescript
 import { createAgentSession } from "open-multi-agent-kit";
 
-// Read-only mode
+// Enable inspection tools; legacy read mode may create a spill sidecar
 const { session } = await createAgentSession({
   tools: ["read", "grep", "find", "ls"],
 });
@@ -1155,9 +1188,11 @@ Execution-bound evidence records a declared verification command and reported ou
 
 **Default path (opt-out):** when an AgentSession has a replay ledger (persisted sessions create one automatically), LLM-callable `bash` and interactive/RPC `executeBash` bind through `executeVerifiedBash` with `executor: "bash-tool"` and receipts under `<sessionFile>.evidence/receipts` (or `cwd/.omk/session-evidence/<goalId>/receipts` for ephemeral sessions). Session workspace scope is git-aware: inside a worktree, the receipt binds the toplevel plus up to 32 sorted dirty file paths (1 s TTL). Git status expands ordinary untracked directories to files; untracked nested repositories remain outside the parent scope. Set `OMK_VERIFIED_BASH=0` to restore the legacy unverified path. Custom `createBashTool()` calls stay unverified unless the caller wraps operations with `createVerifiedBashOperations()`. CI still runs release-consistency through `executeVerifiedLocalBash()` with `executor: "ci-runner"`.
 
-**Default sandbox (opt-out):** session bash defaults to `enforce`. Every built-in local spawn is wrapped by macOS `sandbox-exec` or Linux `bwrap`, writes are limited to the session workspace and OS temp directory, and network access is disabled. If the platform is unsupported or the backend is unavailable, the spawn fails closed with `sandbox.backend_missing`. Set `OMK_BASH_SANDBOX=audit` only for an unwrapped compatibility path that records each decision as a `sandbox_audit` replay event; set `OMK_BASH_SANDBOX=0` to disable the preflight entirely. Unknown values resolve to `enforce`.
+**Default AgentSession sandbox (opt-out):** built-in local bash defaults to `enforce`. Local spawns use macOS `sandbox-exec` or Linux `bwrap`, writes are limited to the session workspace and OS temp directory, and network access is disabled. Unsupported platforms and unavailable backends fail closed with `sandbox.backend_missing`. Explicit `audit` keeps the unwrapped ledger-only path; `0` or `off` disables the preflight. Unknown values resolve to `enforce`.
 
-This boundary applies to AgentSession's built-in local bash operations. Custom `createBashTool()` calls remain unsandboxed unless they receive a `sandboxPolicy`, and injected or remote `BashOperations` own their own isolation. The default workspace-write profile is not a read-confidentiality boundary or whole-process container; use [Containerization](containerization.md) when every tool and extension must be isolated.
+Automatic backend probing is lazy and cached. An AgentSession probes at most once during its lifetime; each `createLocalBashOperations({ sandboxPolicy })` instance also probes at most once when its preflight omits `backend`. The denial reason identifies missing `bwrap` or `sandbox-exec`, disabled user namespaces, both Linux failures, or an unsupported platform.
+
+This boundary applies only to AgentSession's built-in local bash operations. Custom `createBashTool()` calls remain unsandboxed unless they receive a `sandboxPolicy`; injected or remote `BashOperations` own their isolation. The profile is not read-confidentiality or whole-process containment. `executeVerifiedLocalBash()` remains an evidence adapter, not an OS sandbox. See [Containerization](containerization.md).
 
 ### Recorded and invoked inputs
 
@@ -1212,9 +1247,72 @@ Ledger and receipt publication are fail-closed but not one filesystem transactio
 - **Ledger**: `ReplayLedgerManager` verifies an existing ledger on construction (sequence order, prev-hash chain, payload hash, event hash) and **fails closed** on any violation.
 - **Store**: `EvidenceReceiptStore` uses an owner-only directory, symlink rejection, no-overwrite hard-link publication, and identity rechecks to detect observed path replacement. These checks assume same-UID path mutation is quiescent; they are **not** filesystem sandbox isolation.
 
+### Protocol-first semantic evaluation
+
+New integrations should use `TaskSpec`, `ExecutionAttempt`, `Observation`, `EvaluationResult`, `RuntimeDecision`, and `WaiverRecord` from `omk-protocol`. `evaluateTask()` derives the semantic verdict from current observations; `reduceRuntimeDecision()` derives the next runtime action. See [Run Protocol v1](run-protocol.md) for the rules and current migration boundary.
+
+`evidenceReceiptToObservation(receipt, attemptId)` validates the receipt core digest and emits immutable execution facts for protocol evaluation. It does not replace ledger, attestation, freshness, or sandbox checks.
+
+### Advisory best-of-N selection
+
+Use the advisory judge only after deterministic evaluation. `chooseWithAdvisoryJudge()` validates every `EvaluationResult` and excludes `fail` and `inconclusive` candidates before any model call. The judge cannot revive them or alter protocol, evidence, loop, or security gates.
+
+```typescript
+import {
+  chooseWithAdvisoryJudge,
+  createModelAdvisoryJudge,
+} from "open-multi-agent-kit";
+
+const model = modelRegistry.find("xai", "grok-4.5");
+if (!model) throw new Error("judge model is not registered");
+
+const judge = createModelAdvisoryJudge({ model, modelRegistry });
+const decision = await chooseWithAdvisoryJudge({
+  taskGoal: task.goal,
+  judgeId: "reviewer-v1",
+  judge,
+  rubric: [
+    { id: "correctness", description: "Satisfies required behavior and evidence", weight: 3 },
+    { id: "safety", description: "Preserves security and deterministic gates", weight: 2 },
+  ],
+  candidates: [
+    { id: "attempt-a", deterministicRank: 0, material: outputA, evaluation: evaluationA },
+    { id: "attempt-b", deterministicRank: 1, material: outputB, evaluation: evaluationB },
+  ],
+});
+```
+
+The sidecar makes no call when zero or one candidate passes. For multiple passing candidates it sends only bounded, forced-redacted material through a tool-free request and requires a complete 0–4 score matrix. Invalid output or provider failure returns `status: "fallback"` with the deterministic first candidate and a sanitized reason. It never persists model prose. Re-run fresh deterministic gates after applying the selected result.
+
+`createModelAdvisoryJudge()` resolves current auth through `ModelRegistry` for each explicit call, uses no cache retention, and performs no model retry. Tests can inject `AdvisoryJudgeCompletion`; production defaults to `completeSimple()`.
+
+### Durable-goal seam checkpoints
+
+Use the existing durable-goal journal for `Goal / Core / Verified / Open / Next` continuity:
+
+```typescript
+const current = await goalStore.current();
+if (!current) throw new Error("durable goal is missing");
+
+const now = new Date().toISOString();
+const checkpointed = await goalStore.transition({
+  kind: "record-checkpoint",
+  ref: current.ref,
+  checkpoint: {
+    core: ["Keep the protocol verdict authoritative"],
+    verifiedEvidenceIds: ["focused-tests"],
+    open: ["Historical calibration"],
+    next: "Run the full package checks",
+    capturedAt: now,
+  },
+}, now);
+```
+
+The reducer rejects stale refs and evidence outside the current generation. Text is bounded and forced-redacted before persistence; the checkpoint digest correlates its content and generation but is unkeyed and does not authenticate a same-user workspace. `/goal checkpoint {"core":[],"verified":[],"open":[],"next":"..."}` exposes the same transition interactively. The built-in controller carries prose into the next round only for a checkpoint explicitly recorded through that command in the current process. On resume, mutable workspace checkpoint prose is not promoted to user authority; only its digest is noted. Editing the goal definition clears the checkpoint. No `.jspace/` or second state system is created.
+
 ### Receipt policy
 
-`EvidenceGate` (default `receiptMode: "prefer"`) gates a `TaskContract` against its satisfied receipts. Pass `executor.createGateOptions()` so the gate resolves receipts, ledger events, and workspace fingerprints from the same store and ledger.
+`EvidenceGate` (default `receiptMode: "prefer"`) gates the legacy `TaskContract` against its satisfied receipts. Pass `executor.createGateOptions()` so the gate resolves receipts, ledger events, and workspace fingerprints from the same store and ledger.
 
 | Mode | Soft missing data | Tamper-grade mismatch | Legacy `hash` / `command` |
 | ------ | ------------------- | ----------------------- | ---------------------------- |
@@ -1228,7 +1326,9 @@ Tamper-grade mismatches include: receipt ID, goal, or claim mismatch; schema ver
 
 `createGateOptions()` returns three resolvers bound to the executor's own store and ledger: `resolveReceipt` (read a stored receipt), `resolveLedgerEvent` (find a chain event by `seq`), and `captureWorkspaceFingerprint` (snapshot the selected artifact set). The gate validates every returned value.
 
-### Integration example
+### Legacy gate integration example
+
+This compatibility path still uses mutable `TaskContract` evidence status and verdict fields. `TaskContractBuilder.setVerdict()` and `updateEvidenceStatus()` are deprecated for new integrations.
 
 ```typescript
 import {
@@ -1324,11 +1424,17 @@ createContextCacheInvalidationSnapshot, serializeContextCacheSnapshot,
 CONTEXT_BUDGET_POLICY_VERSION_V2
 computeReservedTokenBudget, estimateToolResultReserve, ReservedTokenBudgetError
 
+// Advisory selection and durable goals
+chooseWithAdvisoryJudge, createModelAdvisoryJudge, AdvisoryJudgeInputError, AdvisoryJudgeModelError
+createDurableGoal, applyDurableGoalCommand, parseDurableGoalSnapshot, DurableGoalStore
+createDurableGoalCheckpoint, parseDurableGoalCheckpoint, formatDurableGoalCheckpoint
+
 // Run journal and session termination
 RunJournalStore, appendRunJournalRecordDurably, writeQuarantineBytesDurably,
 classifySessionTermination, formatSessionTermination, SessionTerminationError
 
 // Execution-bound evidence (optional, application-driven verification receipts)
+evidenceReceiptToObservation
 EvidenceReceiptStore
 ReplayLedgerManager
 EvidenceGate

package/docs/security.md

@@ -1,12 +1,12 @@
-# Extension Full-Access Threat Model
+# Extension Runtime Threat Model
 
-> **Scope**: This document analyzes the security implications of OMK extensions that request `full-access` permissions. It applies to the OMK (Open Multi-Agent Kit) coding agent CLI and its extension runtime.
+> **Scope**: This document covers every OMK extension. OMK does not currently provide extension permission tiers or an extension-specific OS sandbox.
 >
-> **Version**: 0.80.3
+> **Version**: 0.96.1
 
 ## 1. Overview
 
-OMK extensions can operate at different permission levels. The `full-access` level grants an extension unrestricted access to the OMK runtime, including the ability to:
+Extensions execute as trusted code inside the OMK process with the host user's permissions. Treat every loaded extension as capable of:
 
 - Read and modify the agent's configuration (`~/.omk/agent/`)
 - Intercept and mutate tool calls and their results
@@ -23,20 +23,20 @@ This document outlines the threat model for such extensions and provides guidanc
 | Malicious Extension Author | Data exfiltration, credential theft, supply-chain compromise | Distributes a seemingly benign extension with hidden malicious logic |
 | Compromised Extension Dependency | Indirect compromise via a dependency of a legitimate extension | Injects malicious code into a trusted extension's dependency tree |
 | Insider Threat | Espionage, sabotage, unauthorized data access | Installs or modifies an extension on a target's machine |
-| User (Self-Inflicted) | Accidental misconfiguration | Grants `full-access` to an untrusted extension without review |
+| User (Self-Inflicted) | Accidental misconfiguration | Loads an untrusted extension without review |
 
 ## 3. Attack Scenarios
 
 ### 3.1 Configuration Exfiltration
 
-A `full-access` extension can read `~/.omk/agent/auth.json`, which contains API keys and OAuth tokens for LLM providers (e.g., `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`).
+An extension can read `~/.omk/agent/auth.json`, which contains API keys and OAuth tokens for LLM providers.
 
 **Impact**: Credential theft leading to unauthorized LLM API usage, financial loss, or data leakage through the compromised API account.
 
 **Mitigation**:
 - Store auth credentials in OS keychain or encrypted vault rather than plaintext `auth.json` where possible.
-- Audit extensions before granting `full-access`.
-- Run extensions with restricted permissions if full access is not strictly required.
+- Audit extensions before loading them.
+- Run the whole OMK process inside an isolated environment when the extension is not fully trusted.
 
 ### 3.2 Session Hijacking
 
@@ -51,7 +51,7 @@ A malicious extension can intercept session `.jsonl` files in `~/.omk/agent/sess
 
 ### 3.3 Tool Call Interception and Mutation
 
-Extensions with `full-access` can wrap built-in tools (e.g., `bash`, `read`, `write`). A malicious wrapper could:
+Extensions can wrap built-in tools (e.g., `bash`, `read`, `write`). A malicious wrapper could:
 - Log all `bash` commands and their outputs to a remote server.
 - Modify `write` tool calls to inject backdoors into source files.
 - Block `read` operations on sensitive files to hide evidence of tampering.
@@ -59,19 +59,19 @@ Extensions with `full-access` can wrap built-in tools (e.g., `bash`, `read`, `wr
 **Impact**: Supply-chain compromise, data integrity loss, covert surveillance.
 
 **Mitigation**:
-- Use the `--no-extensions` flag when working with highly sensitive codebases.
+- Use `--no-extensions` to disable discovered third-party extensions when working with highly sensitive codebases.
 - Pin extension versions and review diffs on updates.
 - Run extensions in an isolated environment (container, VM) where feasible.
 
 ### 3.4 Privilege Escalation via Custom Tools
 
-A `full-access` extension can register new tools that appear in the agent's tool list. These tools execute with the same privileges as the OMK process.
+An extension can register new tools that appear in the agent's tool list. These tools execute with the same privileges as the OMK process.
 
 **Impact**: Arbitrary code execution, system compromise if the agent process has elevated privileges.
 
 **Mitigation**:
 - Never run OMK as root or with sudo.
-- Use OS-level sandboxing (e.g., `sandbox-exec` on macOS, `seccomp` on Linux) for the OMK process.
+- Run the whole OMK process in a container, VM, or other verified OS sandbox when containment is required.
 - Review the full source code of any extension before installation.
 
 ### 3.5 Telemetry and Data Leakage
@@ -83,40 +83,30 @@ Extensions can silently exfiltrate data via DNS queries, HTTP requests, or by wr
 **Mitigation**:
 - Block outbound network access for the OMK process using a firewall or network namespace.
 - Monitor DNS and network traffic for anomalies.
-- Use offline mode (`--offline`) when extensions are not required to fetch remote resources.
+- Do not treat `--offline` as a network sandbox; it disables OMK startup network operations, not arbitrary extension traffic.
 
-## 4. Default Sandbox Path
+## 4. Actual Isolation Boundary
 
-OMK provides a default sandbox path for extensions that do not explicitly request `full-access`. This path restricts the extension to:
+OMK does not sandbox extension JavaScript separately. Extension code, extension tools, custom code, and the OMK process run with the host user's permissions.
 
-- A dedicated subdirectory under `~/.omk/agent/extensions/<extension-name>/`
-- Read-only access to the project workspace (current working directory)
-- No access to `~/.omk/agent/auth.json`, `~/.omk/agent/mcp.json`, or session files
-- No network access (unless explicitly granted via extension manifest)
-
-**Default Sandbox Directory**: `~/.omk/agent/extensions/<extension-id>/`
-
-Extensions operating within this sandbox cannot:
-- Access files outside the project workspace and their own extension directory.
-- Intercept tool calls from other extensions or the core agent.
-- Read or write global agent configuration.
+AgentSession's built-in local bash sandbox wraps only built-in local bash child processes. It does not contain extension callbacks, custom tools, OMK file tools, or the OMK process. For broader isolation, run the whole process inside a container or VM, or route every relevant tool through an isolated backend. See [Containerization](containerization.md).
 
 ## 5. Security Checklist for Users
 
-Before installing or upgrading a `full-access` extension, verify:
+Before installing or upgrading an extension, verify:
 
 - [ ] The extension source code is available and has been reviewed.
 - [ ] The extension is from a trusted author or has been audited by a third party.
 - [ ] The extension's `package.json` or manifest does not include unexpected dependencies.
-- [ ] The extension's network permissions (if any) are justified by its functionality.
+- [ ] The extension's network behavior is justified by its functionality.
 - [ ] You have a backup of `~/.omk/agent/` (especially `auth.json` and sessions).
 - [ ] You have considered running the extension in a sandboxed environment.
 
 ## 6. Security Checklist for Extension Developers
 
-When building a `full-access` extension, adhere to:
+When building an extension, adhere to:
 
-- [ ] **Principle of Least Privilege**: Only request `full-access` if absolutely necessary. Use the default sandbox for everything else.
+- [ ] **Principle of Least Privilege**: Keep the extension's file, process, network, and credential access to the minimum required, even though OMK does not enforce a per-extension tier.
 - [ ] **No Credential Access**: Never read `auth.json` or environment variables containing API keys unless the extension's core purpose is authentication management.
 - [ ] **Transparent Logging**: Log all file system and network operations to a user-visible location.
 - [ ] **Minimal Dependencies**: Keep the dependency tree small to reduce supply-chain risk.
@@ -125,7 +115,7 @@ When building a `full-access` extension, adhere to:
 
 ## 7. Incident Response
 
-If a malicious or compromised `full-access` extension is suspected:
+If a malicious or compromised extension is suspected:
 
 1. **Immediately revoke** any exposed API keys (check `auth.json` and provider dashboards).
 2. **Remove** the extension directory from `~/.omk/agent/extensions/`.
@@ -142,4 +132,4 @@ If a malicious or compromised `full-access` extension is suspected:
 
 ---
 
-*Last updated: 2026-06-25*
+*Last updated: 2026-08-19*