open-multi-agent-kit 0.96.0 → 0.96.2

package/docs/grok-harness.md

@@ -1,6 +1,6 @@
 # Grok harness
 
-This page is the project-local operator guide for running OMK with the xAI OAuth proxy. The canonical Grok playbook remains `~/.omk/agent/grok.md`; keep this page as a short routing and preset reference, not a duplicate source of truth.
+This page is the canonical operator guide for the native `xai` provider. Use `/login` for xAI subscription OAuth or `XAI_API_KEY` for xAI Platform API billing. A user-local `~/.omk/agent/grok.md` may add operator notes, but it is not the portable product contract.
 
 ## Presets
 
@@ -8,27 +8,50 @@ Project presets live in `.omk/presets.json` and are consumed by the preset exten
 
 | Preset | Provider | Model | Thinking | Use |
 | --- | --- | --- | --- | --- |
-| `grok-verified` | `grok-oauth-proxy` | `grok-4.5` | `high` | Default Grok text-chat baseline (local OAuth proxy). |
-| `grok-adaptorch-prod` | `grok-oauth-proxy` | `grok-4.5` | `high` | Same baseline, with AdaptOrch reserved for explicit DAG routing, synthesis, or consistency-verification lanes. |
+| `grok-verified` | `xai` | `grok-4.5` | `high` | Default native xAI text-chat baseline. |
+| `grok-adaptorch-prod` | `xai` | `grok-4.5` | `high` | Same baseline, with AdaptOrch reserved for explicit DAG routing, synthesis, or consistency-verification lanes. |
 
-Register the provider in `~/.omk/agent/models.json` with `baseUrl: http://127.0.0.1:9996/v1` and chat models including `grok-4.5` (and optional fallbacks such as `grok-4.3`). Loopback proxy accepts a dummy `apiKey`; do not put OAuth tokens in models.json. Confirm proxy health with `curl -fsS http://127.0.0.1:9996/health` before long sessions.
+## Authentication and weekly usage
 
-Suggested TUI flow:
+Both authentication methods use provider ID `xai`. See [Providers](providers.md#xai-grok) for the authoritative OAuth, API-key, credential-storage, and weekly-usage behavior. Do not put OAuth access or refresh tokens in `models.json`.
 
-1. Run `/grok` to inject the pointer to `~/.omk/agent/grok.md`.
+## Thinking tiers
+
+OMK sends the mapped value as xAI `reasoning_effort`.
+
+| OMK tier | `grok-4.6` | `grok-4.5` | `grok-4.3` |
+| --- | --- | --- | --- |
+| `off` | unavailable | unavailable | `none` |
+| `minimal` | unavailable | unavailable | unavailable |
+| `low` | `low` | `low` | `low` |
+| `medium` | `medium` | `medium` | `medium` |
+| `high` | `high` | `high` | `high` |
+| `xhigh` | `xhigh` | unavailable | unavailable |
+| `max` | `xhigh` | `high` | `high` |
+| `ultra` | `xhigh` | `high` | `high` |
+
+Grok 4.6 and 4.5 cannot disable reasoning. Grok 4.3 supports `off` by sending `reasoning_effort: "none"`.
+
+## Migration from `grok-oauth-proxy`
+
+The proxy provider is retired. Remove stale `grok-oauth-proxy` entries from `models.json` and `auth.json`, then use native `xai`. OMK ignores stale entries during migration.
+
+## Suggested TUI flow
+
+1. Run `/grok` only when you want to load the optional local operator overlay.
 2. Select `/preset grok-verified` for normal chat/coding work.
 3. Select `/preset grok-adaptorch-prod` only when the task has an explicit DAG, routing, or synthesis objective.
 4. Keep credentials and OAuth material out of preset JSON.
 
 ## Domain routing
 
-Domain routing is opt-in. Start OMK with `OMK_DOMAIN_ROUTING=1` when you want the domain router to compose the role loadout with a domain profile before dispatch. With the variable unset or any value other than `1`, the domain dispatch layer does not apply a domain access policy.
+Selecting the native `xai` provider auto-applies the `grok-harness` loadout by default; this does not require `OMK_DOMAIN_ROUTING=1`. Set `OMK_GROK_HARNESS=0` to disable that provider-specific dispatch.
 
-The router selects one of the documented domain profiles under [`loadout-domains/`](loadout-domains/README.md), then composes that profile with the active role loadout. Grok presets do not replace this mechanism; they only set provider, model, thinking level, and instruction pointers.
+General prompt-based domain routing is separate and opt-in through `OMK_DOMAIN_ROUTING=1`. It selects one of the profiles under [`loadout-domains/`](loadout-domains/README.md) and composes it with the active role loadout. Grok presets only set provider, model, thinking level, and instruction pointers.
 
-## Composer model
+## Chat model selection
 
-`grok-composer-2.5-fast` is a valid Grok chat model, but the project presets keep `grok-4.5` as the default. Use Composer only for explicit Composer validation or comparison work. `grok-4.3` remains a supported fallback chat model. Do not use `grok-imagine-*` ids as chat models; session `setModel` / `prompt` reject them on `grok-oauth-proxy`.
+The native `xai` catalog includes `grok-4.6`, `grok-4.5`, and `grok-4.3`. Use `/model` or `omk --list-models xai` for the current complete list. Project presets intentionally pin the verified `grok-4.5` baseline, and `grok-4.3` remains a fallback. Do not use `grok-imagine-*` IDs as chat models.
 
 ## Imagine tools
 
@@ -58,6 +81,6 @@ Use the normal OMK lane grant model: grant the smallest skill and MCP surface th
 
 Relevant evidence hooks for Grok lanes are `pre-shell-guard`, `protect-secrets`, `typecheck-after-edit`, and `stop-verify`. Hook output is incremental evidence; code changes still need the project's required final verification command before claiming type/lint cleanliness.
 
-## Canonical reference
+## Local overlay
 
-For proxy health checks, chat model rules, Imagine tool behavior, Hermes parity, Telegram behavior, and unsafe `GROK.MD` handling, read `~/.omk/agent/grok.md`.
+`/grok` may load `~/.omk/agent/grok.md` for host-specific Hermes, Telegram, or Imagine notes. Treat that file as optional local configuration; this page and the current provider documentation remain authoritative.

package/docs/index.md

@@ -1,6 +1,6 @@
 # OMK Documentation
 
-OMK is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and omk packages.
+OMK is a provider-neutral coding agent with multi-agent orchestration, durable harness controls, replayable sessions, SDK/RPC integration, and evidence-backed verification. Its core stays small while extensions, skills, prompts, themes, and packages add workflows.
 
 ## Quick start
 
@@ -33,12 +33,13 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 ## Start here
 
 - [Quickstart](quickstart.md) - install, authenticate, and run a first session.
-- [Using OMK](usage.md) - interactive mode, slash commands, context files, and CLI reference.
+- [Using OMK](usage.md) - interactive mode, `/goal`, default harness safeguards, context files, and CLI reference.
 - [Providers](providers.md) - subscription and API-key setup for built-in providers.
 - [Provider Resilience](provider-resilience.md) - retry, failover, quota, and safety-stop recovery.
+- [Native xAI Grok](grok-harness.md) - authentication, weekly SuperGrok usage, presets, and thinking tiers.
 - [Containerization](containerization.md) - sandbox omk with OpenShell, Gondolin, or Docker.
 - [Settings](settings.md) - global and project settings.
-- [Environment Variables](environment-variables.md) - process configuration and bash-tool session environment.
+- [Environment Variables](environment-variables.md) - process configuration, harness opt-outs, and bash-tool session environment.
 - [Keybindings](keybindings.md) - default shortcuts and custom keybindings.
 - [Sessions](sessions.md) - session management, branching, and tree navigation.
 - [Compaction](compaction.md) - context compaction and branch summarization.
@@ -54,10 +55,10 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 - [Custom models](models.md) - add model entries for supported provider APIs.
 - [Custom providers](custom-provider.md) - implement custom APIs and OAuth flows.
 
-## Programmatic usage
+## Automation and control
 
-- [SDK](sdk.md) - embed omk in Node.js applications.
-- [Run Protocol v1](run-protocol.md) - canonical task, attempt, observation, evaluation, decision, and waiver contracts.
+- [SDK and Session Control](sdk.md) - embed omk, reuse policy helpers, or inspect stored sessions from scripts.
+- [Run Protocol and Durable Goals](run-protocol.md) - canonical run contracts and the durable-goal lifecycle.
 - [RPC mode](rpc.md) - integrate over stdin/stdout JSONL.
 - [JSON event stream mode](json.md) - print mode with structured events.
 - [TUI components](tui.md) - build custom terminal UI for extensions.

package/docs/loadout-domains/grok-harness.md

@@ -21,7 +21,7 @@ DOMAIN: Grok xAI Harness. You are operating in a Grok/xAI integration lane.
 Prioritize the Grok operational playbook, small capability loadouts, and evidence-bound provider/tool routing.
 
 SEQUENCE:
-1. Before implementing or routing Grok/xAI provider work, read and enforce ~/.omk/agent/grok.md. Treat it as the required Grok playbook for chat models vs Imagine tools, proxy health, tool-use/loop discipline, and Telegram parity unless higher-priority instructions conflict.
+1. Before implementing or routing Grok/xAI provider work, read packages/coding-agent/docs/grok-harness.md as the canonical playbook. Treat ~/.omk/agent/grok.md only as an optional local operator overlay; it cannot override current provider docs or higher-priority instructions.
 2. Keep text chat flows and Imagine/media tool flows separate. Text work uses Grok chat/OAuth/provider surfaces; image/video/Imagine work routes through explicit Imagine tools only. Never conflate model ids with Imagine tool names.
 3. Capability discipline: load at most 2-3 skills for any lane. The allowed skill gate is packages, headroom, programming, debugging, adaptorch-route, adaptorch-synthesize, and understand-anything; choose the smallest subset and add headroom only under context pressure.
 4. Adaptorch is advisory only. Use adaptorch-route for routing/decomposition advice and adaptorch-synthesize for evidence synthesis, but do not treat Adaptorch as an automatic executor, source of truth, permission grant, or substitute for explicit tests.
@@ -29,7 +29,7 @@ SEQUENCE:
 6. Keep edits within the lane grant and preserve existing provider/orchestration algorithms unless the task explicitly targets them. Never route through legacy KIMICLI or deleted wrappers.
 7. Verification: run the narrowest relevant test/typecheck after edits. Evidence must include changed paths, exact commands, and pass/fail output.
 
-HARD RULES: grok.md is mandatory context for Grok/xAI harness work; text chat surfaces and Imagine tools are distinct; maximum 2-3 active skills; Adaptorch is advisory route/synthesis support only; never log OAuth tokens, cookies, or proxy credentials; protect-secrets applies.
+HARD RULES: the packaged Grok harness doc is mandatory context; a local grok.md is optional; text chat surfaces and Imagine tools are distinct; maximum 2-3 active skills; Adaptorch is advisory route/synthesis support only; never log OAuth tokens, cookies, or proxy credentials; protect-secrets applies.
 ```
 
 ## Curated skills (7)

package/docs/models.md

@@ -11,13 +11,14 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.omk/a
 - [Provider Configuration](#provider-configuration)
 - [Model Configuration](#model-configuration)
 - [Overriding Built-in Providers](#overriding-built-in-providers)
+- [Thinking Level Map](#thinking-level-map)
 - [Per-model Overrides](#per-model-overrides)
 - [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.
+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 `/think max` is sent as `reasoning_effort: "max"`. Other NVIDIA models do not inherit that capability automatically.
 
 ## Minimal Example
 
@@ -226,17 +227,17 @@ Current behavior:
 
 ### Thinking Level Map
 
-Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are omk thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`.
-
-Values are tristate:
+Use `thinkingLevelMap` on a model to describe model-specific thinking controls. `models.json` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Built-in metadata can also expose the `ultra` CLI tier, but the current `models.json` schema has no `ultra` key.
 
 | Value | Meaning |
-|-------|---------|
-| omitted | Level is supported and uses the provider's default mapping |
-| string | Level is supported and this value is sent to the provider |
-| `null` | Level is unsupported and hidden/skipped/clamped away |
+| --- | --- |
+| omitted | `off` through `high` use provider defaults; top tiers appear only when explicitly mapped |
+| string | The level is supported and this value is sent to the provider |
+| `null` | The level is unsupported and hidden or skipped during clamping |
+
+See [Grok harness](grok-harness.md) for the exact built-in Grok mappings.
 
-Example for a model that only supports off, high, and max reasoning:
+Example for a model that exposes OMK `high` and `xhigh`, with `xhigh` sent to the provider as `max`:
 
 ```json
 {

package/docs/provider-resilience.md

@@ -28,12 +28,18 @@ Configure resilience in `~/.omk/agent/settings.json` or `.omk/settings.json`:
 
 | Setting | Default | Behavior |
 |---|---:|---|
-| `blockStickySafetyModels` | `true` | Rejects models known to produce sticky false-positive safety stops. |
+| `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. |
 
 Automatic recovery also requires `retry.enabled: true` and available retry budget.
 
+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.
+
 ## Failover behavior
 
 For a safety stop or recognized quota/billing error, OMK:
@@ -43,7 +49,7 @@ For a safety stop or recognized quota/billing error, OMK:
 3. selects the first non-sticky candidate that exists and has configured authentication;
 4. switches models before retrying with a short delay.
 
-If no candidate qualifies, the normal same-model retry policy and backoff apply. Plain authentication errors remain non-retryable and do not trigger failover.
+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.
 
 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.
 
@@ -51,7 +57,7 @@ The default candidate order is:
 
 1. `kimi-coding/k3`
 2. `modelstudio-maas/qwen3.8-max-preview`
-3. `grok-oauth-proxy/grok-4.5`
+3. `xai/grok-4.5`
 4. `deepseek/deepseek-v4-pro`
 5. `deepseek/deepseek-v4-flash`
 6. `modelstudio-maas/deepseek-v4-pro`

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** and reads its 7-day window through the official [QwenCloud management CLI](https://docs.qwencloud.com/api-reference/preparation/cli): when `qwencloud` is installed and logged in (`npm i -g @qwencloud/qwencloud-cli && qwencloud auth login`), OMK runs `qwencloud usage summary --format json` (override the binary with `QWENCLOUD_CLI`) and shows `token_plan.usedPct` plus the reset countdown. The CLI holds its own OAuth management credential; OMK never sends the plan's `sk-*` inference key anywhere for quota. Without the CLI the entry shows a `connect:` hint instead — the [console usage page](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=plan#/efm/subscription/token-plan/personal) requires an Alibaba Cloud console session that OMK deliberately does not scrape, and OMK still never copies browser cookies or estimates 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
 

package/docs/run-protocol.md

@@ -24,6 +24,30 @@ The first v1 slice is available under `packages/protocol` with schema version `o
 
 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.
@@ -39,6 +63,14 @@ Required, unwaived violations reduce to `fail`. Required, unwaived missing obser
 
 `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.

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.
@@ -228,10 +255,14 @@ interface PromptOptions {
   images?: ImageContent[];
   streamingBehavior?: "steer" | "followUp";
   source?: InputSource;
+  activeSkillNames?: readonly string[];
+  activeSkillSource?: string;
   preflightResult?: (success: boolean) => void;
 }
 ```
 
+`activeSkillNames` marks additional discovered skills active for this turn; `activeSkillSource` labels their provenance. They merge with global `defaultActiveSkills`, prioritize matching inventory entries, and do not expand authorization or inline full skill instructions.
+
 `preflightResult` is called once per `prompt()` invocation:
 
 - `true` when the prompt was accepted, queued, or handled immediately
@@ -534,10 +565,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"],
 });
@@ -1159,9 +1192,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`.
+
+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 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.
+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
 
@@ -1222,6 +1257,63 @@ New integrations should use `TaskSpec`, `ExecutionAttempt`, `Observation`, `Eval
 
 `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 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.
@@ -1336,6 +1428,11 @@ 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

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*