open-multi-agent-kit 0.96.2 → 0.98.0

package/docs/correctness-wall.md

@@ -19,7 +19,7 @@ It does **not** prove that code is correct, complete, or safe for production.
 | **PASS** | Fast wall (and optional OA) found no blocking issues. |
 | **ADVISORY** | Proceed with caution; preview limits or weak discrimination may apply. |
 | **INCONCLUSIVE** | Not enough evidence (empty diff, missing fixture, verifier error). |
-| **BLOCKED** | Scope, secret heuristic, or OA contradiction — do not apply by default. |
+| **BLOCKED** | Scope, secret heuristic, or OA contradiction. `hard` blocks it; `soft` blocks unless overridden; `shadow` records it and proceeds. |
 
 Structured next steps on the verdict card: **Apply**, **Deep Check**, **Regenerate** (see `packages/adaptorch-wpl` B2C mapper).
 
@@ -28,13 +28,13 @@ Structured next steps on the verdict card: **Apply**, **Deep Check**, **Regenera
 ## Fast wall vs deep wall
 
 - **Fast wall (default):** Pure policy — diff paths, scope globs, secret-shaped lines, preview-only limits (`BATCH1_NO_DOCKER_RUNNER`). No Docker runner in batch 1.
-- **Deep wall (Pro / future):** Hermetic paired base/patch replay. Today `deepWall: true` returns **unavailable** (evidence-gated: requires a valid execution receipt per ALG-003 strict mode; no Docker runner wired in batch 1).
+- **Proposed deep wall (unavailable):** Hermetic paired base/patch replay. Today `deepWall: true` returns **unavailable** (evidence-gated: requires a valid execution receipt per ALG-003 strict mode; no Docker runner wired in batch 1).
 
-## Relationship to Adaptorch
+## Relationship to AdaptOrch
 
-- Hidden engine: `omk-adaptorch-wpl` (`evaluateCorrectnessWall`, outcome adjudicator, repair hints).
+- Library: published `omk-adaptorch-wpl` (`evaluateCorrectnessWall`, outcome adjudicator, repair hints); the extension remains explicit opt-in.
 - Optional OA path: `runIds` + `previewOnly: false` + in-memory or MCP transport.
-- Adaptorch **preview** planning is separate; see [adaptorch-preview.md](./adaptorch-preview.md).
+- AdaptOrch **preview** planning is separate; see [adaptorch-preview.md](./adaptorch-preview.md).
 
 ## Operator environment
 
@@ -72,7 +72,7 @@ The correctness wall is **not** part of the default `omk-core-verified` preset o
 | **Scope** | `OMK_WALL_SCOPE` — comma-separated path globs that approve write targets in the diff |
 | **Mode** | `OMK_PATCH_SAFETY_WALL_MODE` — `shadow` \| `soft` \| `hard` (see [Operator environment](#operator-environment)) |
 | **Role loadouts** | `code` / `executor` lanes still get `pre-shell-guard`, `protect-secrets`, and `typecheck-after-edit`; the wall **adds** a pre-apply policy gate on `edit` / `write` only when the extension is loaded |
-| **Domain router** | No dedicated domain profile today; patch-safety work may route to [`ai-agent-ops`](./loadout-domains/ai-agent-ops.md) for harness/eval discipline, but that does **not** auto-load this extension |
+| **Domain router** | The PATCH SAFETY profile routes relevant prompts, but it does **not** auto-load this extension |
 
 **Domain router triggers (implemented):** `packages/coding-agent/src/core/domain-loadouts.ts` already contains keyword triggers (`correctness wall`, `patch safety`) and a path trigger (`correctness-wall`) that route to the PATCH SAFETY domain profile. The profile instructs operators to load the correctness-wall extension explicitly (not in default preset) and follow the shadow → soft → hard rollout. Auto-generated docs under `docs/loadout-domains/` should be regenerated via `gen-domain-docs.mjs`, not hand-edited.
 
@@ -88,7 +88,7 @@ Roll out in **three phases** so telemetry and false positives are understood bef
 | **2 — Soft** | `soft` | **BLOCKED** verdicts block apply unless `OMK_WALL_OVERRIDE=1` (or `true` / `yes`). **INCONCLUSIVE** still applies in shadow-like fashion for scope tuning. Use for pilot teams with an explicit override path. |
 | **3 — Hard** | `hard` | **BLOCKED** and **INCONCLUSIVE** both block `edit` / `write`. Reserve for repos with stable scope globs, OA fixtures wired (`OMK_WALL_RUN_IDS` + `OMK_WALL_OA_FIXTURE_PATH`), and acceptable INCONCLUSIVE rate (missing files, empty diff). |
 
-**Checklist between phases**
+### Checklist between phases
 
 1. AC-1 vitest green for `packages/adaptorch-wpl` and regression `018-b2c-correctness-wall`.
 2. Root `npm run check` green after any source touch (includes unrelated **browser-smoke** esbuild gate — wall work does not require loading the extension in that script).
@@ -112,8 +112,8 @@ Goal orchestration v2 artifacts (planner P3) live beside batch-1 plan files:
 - ⬜ Lift `BATCH1_NO_DOCKER_RUNNER` for non-preview deep wall — still stub.
 - ⬜ Preset documentation in `~/.omk/runtime-preset.json` — deferred.
 
-**Wave 3 (productize) — Not started:**
-- ⬜ Publish `omk-adaptorch-wpl` from `dist/` for out-of-monorepo extensions.
+**Wave 3 (productize) — Partial:**
+- ✅ `omk-adaptorch-wpl` is published; out-of-monorepo consumers can install the package.
 - ✅ `domain-loadouts.ts` profile exists; `gen-domain-docs.mjs` regen pending.
 - ⬜ Default **soft** for internal dogfood presets after Wave 2 evidence.
 
@@ -122,4 +122,4 @@ Goal orchestration v2 artifacts (planner P3) live beside batch-1 plan files:
 - [adaptorch-preview.md](./adaptorch-preview.md)
 - [LOADOUT.md](../examples/extensions/correctness-wall/LOADOUT.md) — copy-paste for `omk-core-verified` sessions
 - Goal artifacts: `.omk/goals/b2c-correctness-wall-2026-07-08/` (`algorithm-v2.md`, `dag-v2.json`)
-- Extension README: `packages/coding-agent/examples/extensions/correctness-wall/README.md`
+- Extension README: `packages/coding-agent/examples/extensions/correctness-wall/README.md`

package/docs/docs.json

@@ -118,6 +118,18 @@
           "title": "Run Protocol & Durable Goals",
           "path": "run-protocol.md"
         },
+        {
+          "title": "Runtime Algorithms & Direction",
+          "path": "runtime-algorithms.md"
+        },
+        {
+          "title": "AdaptOrch Preview",
+          "path": "adaptorch-preview.md"
+        },
+        {
+          "title": "Correctness Wall",
+          "path": "correctness-wall.md"
+        },
         {
           "title": "RPC Mode",
           "path": "rpc.md"

package/docs/environment-variables.md

@@ -83,19 +83,26 @@ These variables are read by OMK itself. The four built-in harness flags below ar
 | `OMK_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
 | `OMK_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
 | `OMK_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
-| `OMK_CONTEXT_GOVERNOR` | Configure the context-budget governor; see `context-budget-*` sources |
+| `OMK_CONTEXT_GOVERNOR` | Context Budget V2 process override: `1` forces it on and `0` forces it off; otherwise the global `contextBudget.enabled` setting applies |
+| `OMK_CONTEXT_GOVERNOR_CACHE` | Set to `memory` to keep representations, negative results, and plans in session memory instead of persisting representations per workspace |
+| `OMK_CONTEXT_GOVERNOR_CACHE_DIR` | Relocate the Context Budget V2 representation snapshot from `.omk/cache/context-budget-v2`; plans remain session-memory-only |
 | `OMK_VERIFIED_BASH` | Default-on verified bash adapter for AgentSession/CLI bash. Set to `0` to opt out and use the legacy unverified path (see [SDK — Evidence and Verification](sdk.md#evidence-and-verification)) |
 | `OMK_BASH_SANDBOX` | AgentSession built-in local bash mode. Unset or unknown values select `enforce`: macOS `sandbox-exec` or Linux `bwrap`, workspace/temp writes only, network disabled, and fail closed without a usable backend. Explicit `audit` selects the unwrapped ledger-only path; `0`/`off` disables the preflight. Use `off` only when a verified outer whole-process sandbox owns isolation; it does not isolate OMK by itself |
 | `LIVE_E2E` | Test-only: keep provider credentials so live-API e2e suites run on purpose (default scrubbed for hermetic tests) |
-| `OMK_OMP_SEAMS` | Default-on OMP pure seams for `read`/`grep`. Set to `0` to opt out |
 | `OMK_IDENTICAL_LOOP` | Default-on consecutive-loop guard. Warns from the third identical `tool+args` call and blocks the sixth. Set a disabling value to opt out |
 | `OMK_TOOL_PAIR_REPAIR` | Default-on outbound-context repair. Removes unmatched tool-use and tool-result blocks before provider requests without rewriting the transcript. Set a disabling value to opt out |
 | `OMK_PROMPT_PRESET` | Default-on model-specific guidance for supported Claude/Anthropic, Kimi, GLM/ZAI, and Grok/xAI models. Set a disabling value to opt out |
 | `OMK_CLAUDE_CONTEXT_FILES` | Claude models omit discovered `AGENTS.md` and `CLAUDE.md` files by default to prevent unrelated context from causing provider false positives. Set to `1`, `true`, `on`, or `yes` to restore them |
 | `OMK_GOAL_CONTROLLER` | Default-on working-directory `/goal` command and automatic continuation. Goals created by `/goal` use an eight-round cap. Set a disabling value to opt out |
+| `OMK_COMPLETION_SOUND` | Interactive-TTY terminal notification override: `0` disables it and `1` enables it. Sounds never run in RPC, JSON, print mode, or CI |
+| `OMK_YOLO`, `OMK_COMMAND_SAFETY`, `OMK_DISABLE_COMMAND_SAFETY` | Disable the command-safety gate entirely (YOLO mode). `OMK_YOLO` and `OMK_DISABLE_COMMAND_SAFETY` accept `1`, `true`, `yes`, or `on`; `OMK_COMMAND_SAFETY` accepts `0`, `false`, `off`, `disable`, or `disabled`. Every verdict, including block-tier and privilege commands, is skipped in interactive and headless runs. Use only when a verified outer sandbox owns the boundary |
+| `OMK_COMMAND_SAFETY_ASSUME_YES` | `1` or `true` auto-accepts non-privilege confirm-tier commands in interactive **and headless** runs. Privilege confirmation and block-tier commands remain denied. Use only under a trusted outer sandbox when headless auto-accept is intended |
 | `OMK_GROK_HARNESS` | Default-on native `xai` provider dispatch to the `grok-harness` loadout. `0`, `false`, `off`, or `no` disables it |
 | `OMK_DOMAIN_ROUTING` | Set to `1` to enable general prompt-based domain routing. Native xAI harness dispatch does not require it |
 | `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
 | `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
+| `OMK_RESOURCE_GOVERNOR` | Resource-governor mode: `off`, `observe` (default), `adaptive`, or `strict`. Feeds `/resource [probe\|policy]` and `omk doctor resources [--json]`; see the resource governor section in [Settings](settings.md) |
+| `OMK_TOOL_SCHEDULER` | Tool scheduler override: `dag-v2` or the `waves-v1` rollback path; see also the `agent.toolScheduler` setting |
+| `OMK_TURN_METRICS`, `OMK_TURN_METRICS_DIR` | Turn metrics are written under `.omk/metrics/` as sessions run; set `OMK_TURN_METRICS=0` to disable or `OMK_TURN_METRICS_DIR` to relocate. Aggregate with `omk stats`; see [Metrics](metrics.md) |
 
 Provider credentials such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and cloud-provider configuration are listed in [Providers](providers.md).

package/docs/extensions.md

@@ -505,15 +505,24 @@ The `systemPromptOptions` field gives extensions access to the same structured d
 
 Inside `before_agent_start`, `event.systemPrompt` and `ctx.getSystemPrompt()` both reflect the chained system prompt as of the current handler. Later `before_agent_start` handlers can still modify it again.
 
-#### agent_start / agent_end
+#### agent_start / agent_end / agent_settled
 
-Fired once per user prompt.
+`agent_start` and `agent_end` fire once per agent-loop attempt. When the session
+retries a transient provider failure, the prompt produces several `agent_end`
+events, so `agent_end` alone does not mark the end of the work.
+
+`agent_settled` fires once, immediately after the `agent_end` that no retry
+follows. Use it to release per-run state exactly once.
 
 ```typescript
 omk.on("agent_start", async (_event, ctx) => {});
 
 omk.on("agent_end", async (event, ctx) => {
-  // event.messages - messages from this prompt
+  // event.messages - messages from this attempt; a retry may still follow
+});
+
+omk.on("agent_settled", async (event, ctx) => {
+  // No retry follows. Safe to clear activity, finalize queues, or release locks.
 });
 ```
 

package/docs/index.md

@@ -1,6 +1,8 @@
 # OMK Documentation
 
-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.
+OMK is a provider-neutral coding agent with multi-agent orchestration, durable harness controls, replayable sessions, SDK/RPC integration, and evidence-backed verification. Extensions, skills, prompts, themes, and packages add workflows without changing the run contract.
+
+OMK targets state-of-the-art quality as a CLI coding-agent harness. That target is not a claim of current leadership; see [Turn metrics and harness evaluation](metrics.md) for the qualification rules and current status.
 
 ## Quick start
 
@@ -59,6 +61,10 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 
 - [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.
+- [Runtime algorithms and direction](runtime-algorithms.md) - released, opt-in, internal, working-tree, and proposed mechanisms.
+- [AdaptOrch Preview](adaptorch-preview.md) - planning blueprint and claim boundary; not a default runtime path.
+- [Correctness Wall](correctness-wall.md) - opt-in patch-apply safety extension and evidence limits.
+- [Turn metrics and harness evaluation](metrics.md) - cost, latency, tool reliability, capability baselines, and comparative-claim rules.
 - [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/metrics.md

@@ -3,6 +3,76 @@
 OMK records one JSON line per agent turn so harness changes can be measured
 instead of guessed.
 
+## CLI harness SOTA target
+
+OMK targets state-of-the-art quality as a CLI coding-agent harness. **SOTA is
+not verified.** This is a product target, not a statement that the current
+release leads a benchmark or a named competitor cohort.
+
+The target covers the harness layer:
+
+| Dimension | Primary measure |
+| --- | --- |
+| Task success | solved tasks and pass rate |
+| Cost efficiency | model cost and tokens per solved task |
+| Latency | wall-clock p50/p95 per solved task |
+| Context efficiency | input, cache, compaction, and tool-output tokens per solved task |
+| Tool reliability | failure, retry, refusal, and intervention rates |
+| Orchestration | critical-path time, useful concurrency, and duplicate work |
+| Recovery | interrupted-run resume accuracy and repeated-run variance |
+| Safety | policy violations, unauthorized effects, and false-positive blocks |
+| Maintainability | complexity, module-size debt, and regression-gate health |
+
+No single feature count or self-score establishes leadership. OMK reports a
+dimension-specific result unless a preregistered aggregation defines an overall
+score.
+
+### Controlled comparison contract
+
+A comparative harness run MUST hold the **same model**, **same provider** and
+model configuration, **same task** and revision, **same budget**, equivalent
+tool permissions, and comparable container, hardware, region, and concurrency
+constant. The harness is the treatment variable. If a factor cannot be held
+constant, the report must label the result non-comparative.
+
+Every comparative report must include:
+
+- the date, harness versions, and **named comparison cohort**, with its inclusion rule frozen before execution;
+- immutable model, provider, container, environment, and configuration identities;
+- the task manifest, seeds, public prompt or sanitized prompt digest, budgets, run order, and stop policy;
+- sanitized per-task outcomes plus cost, token, latency, retry, and intervention data;
+- the confidence interval, significance threshold, minimum effect, and statistical test chosen before inspecting the result;
+- the exact commands and immutable manifests needed for **reproducible evidence**.
+
+Use paired A/B measurements. Randomize or interleave pair order when provider or
+machine drift can bias one side. Do not combine values produced by different
+methods, working directories, task revisions, or warm/cold conditions. A
+roadmap projection remains a hypothesis even when its inputs are measured.
+
+### Evidence privacy
+
+Benchmark evidence is private by default. Public artifacts may contain public
+or synthetic task identifiers, version and image digests, allowlisted runtime
+metadata, sanitized outcomes, and aggregate statistics. They must not contain
+credentials, private prompts, proprietary source, raw tool arguments or output,
+environment values, personal data, or absolute user paths.
+
+Keep restricted raw evidence local or in an access-controlled store with an
+explicit owner and retention period. Normalize paths, redact content, scan for
+secrets and PII, and obtain human approval before publication. Digests and
+public task manifests preserve reproducibility without disclosing restricted
+content.
+
+A public “SOTA,” “best,” “leading,” or “#1” claim requires a dated controlled
+comparison that places OMK on the relevant quality/cost/latency frontier without
+violating declared safety and regression floors. Until then, use “targets
+state-of-the-art quality.”
+
+[Harbor's Terminal-Bench runner](https://www.harborframework.com/docs/tutorials/running-terminal-bench)
+and the [SWE-bench containerized harness](https://www.swebench.com/SWE-bench/api/harness/)
+are reference evaluation surfaces. Their presence or a selected task list is
+infrastructure, not a benchmark result.
+
 This is separate from the two things that already existed:
 
 | Surface | Purpose |
@@ -83,5 +153,7 @@ 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`.
+regression gate. Selection alone is not a capability result. The scoring run
+itself requires Docker, `harbor`, and real model spend — it is deliberately not
+wired into `npm run check`. Any comparison produced from it must follow the
+controlled comparison contract above.

package/docs/provider-resilience.md

@@ -6,6 +6,7 @@ OMK can recover an agent turn from provider failures that are unlikely to succee
 - billing-cycle or quota exhaustion
 - orphaned `tool_call_id` protocol errors
 - transient transport and server failures
+- gateway/upstream availability failures (5xx passthroughs, streams that end without a finish reason)
 
 This is availability behavior, not a safety bypass. Provider safety policy and the user's configured model access remain authoritative.
 
@@ -53,6 +54,8 @@ A content/safety stop gets at most one automatic retry, including a retry that s
 
 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.
 
+Gateway/upstream availability failures — "503 Upstream request failed", "Endpoint is unavailable", or a stream that ended without a finish reason — are classified as `provider.network`: transport problems that heal by retry or model switch, never by transcript sanitization.
+
 The default candidate order is:
 
 1. `kimi-coding/k3`
@@ -63,6 +66,14 @@ The default candidate order is:
 6. `modelstudio-maas/deepseek-v4-pro`
 7. `kimi-coding/kimi-for-coding`
 
+## Same-model route rotation
+
+The same underlying model is often served by several provider routes (for example `openrouter/stealth/ox-alpha` and `opencode-go/ox-alpha-free`). When the active route fails with an upstream availability error, OMK rotates to another authenticated route of the same model family before touching the cross-model failover chain, so the retry lands on a live endpoint instead of hammering the dead one.
+
+Routes already visited this turn and routes without configured authentication are excluded from rotation. Route rotation runs inside the normal retry budget; when no sibling route remains, the standard failover behavior applies.
+
+Compaction summarization reuses the same chain: when the summarization model hits quota/billing exhaustion, the configured failover candidates are tried once each before the run fails with a non-retryable `compaction.quota_exhausted` termination cause. See [Compaction](compaction.md).
+
 ## Retry and termination events
 
 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.

package/docs/runtime-algorithms.md

@@ -0,0 +1,359 @@
+# Runtime Algorithms and Direction
+
+This page separates OMK's released behavior from internal mechanisms, current
+working-tree candidates, and proposals. Source and tests remain authoritative.
+
+- **Snapshot date:** 2026-08-27
+- **Released baseline:** OMK `v0.97.0` (`b38a2c8c84`)
+- **Repository baseline:** `4b79c65eaf` plus the local working tree
+
+## Status vocabulary
+
+| Status | Meaning |
+| --- | --- |
+| **Released / default** | Present in `v0.97.0` and selected when relevant settings do not override it |
+| **Released / opt-in** | Present in `v0.97.0`, but requires a command, setting, or explicit API call |
+| **Released / internal** | Implemented and tested, but not connected to a live user path |
+| **Working tree** | Present in the current checkout only; not shipped and not a release promise |
+| **Proposed** | Design direction without a complete implementation and verification path |
+
+A mechanism's existence does not make it authoritative. OMK promotes a mechanism
+only after its live call path, default, evidence, and rollback are all explicit.
+
+## Runtime control path
+
+```text
+Prompt or durable-goal round
+  -> system-prompt assembly
+     -> Context Budget V2 when globally enabled
+  -> local v4 reasoning routing when /think auto is active
+  -> provider attempt
+     -> same-family route rotation, retry, or configured failover when eligible
+  -> tool scheduling
+     -> v0.97.0 CLI default: dag-v2; direct core fallback is revision-specific
+     -> pre-hook claims -> deferred authorization -> post-hook claim re-plan
+     -> deterministic level execution and source-order results
+  -> journals, receipts, and session termination records
+  -> optional omk-protocol evaluation
+     TaskSpec -> ExecutionAttempt -> Observation -> EvaluationResult -> RuntimeDecision
+  -> retry, continuation, or final prompt settlement
+```
+
+The protocol line is a released library and adapter surface. An ordinary chat
+turn does not automatically become a `TaskSpec`; callers opt into that semantic
+evaluation contract.
+
+## Current algorithm surface
+
+### Tool scheduling and settlement
+
+**Status: Released / default.** The `v0.97.0` CLI sets `dag-v2`; direct
+`omk-agent-core` calls fall back to `waves-v1`. The working tree changes that
+core fallback to `dag-v2`, but that promotion is unreleased. The scheduler canonicalizes resource claims, preserves source order,
+and places conflicting calls in later levels. Before a level executes, OMK authorizes its calls and
+re-plans with post-hook arguments so a hook cannot silently invalidate the
+original claim plan.
+
+The live executor uses level barriers. `assignDagDependencies()` computes a
+finer predecessor graph, but no live executor consumes it. Each candidate level
+is authorized and then re-planned from post-hook arguments.
+
+Evidence:
+
+- `packages/agent/src/tool-dag-scheduler.ts`: `assignDagLevels`,
+  `assignDagDependencies`, `scheduleDagLevels`
+- `packages/agent/src/agent-loop.ts`: `executeToolCallsDagLevels`,
+  `runDagLevelCalls`
+- `packages/agent/test/tool-dag-scheduler*.test.ts`
+- `packages/agent/test/tool-dag-dependencies.test.ts`
+
+**Working tree:** timed-out tools receive a bounded 250 ms teardown window. A
+cooperative process may settle and let the model react to the timeout; a tool
+still running after the window stops the run because it may still mutate the
+workspace. This candidate lives in
+`packages/agent/src/tool-timeout-settlement.ts` and is covered by
+`packages/agent/test/tool-timeout-loop-continuation.test.ts`.
+
+### Context selection
+
+**Status: Released / opt-in.** Context Budget V2 is enabled globally through
+`contextBudget.enabled` or per process with `OMK_CONTEXT_GOVERNOR=1`.
+
+The planner:
+
+1. reserves response and safety tokens;
+2. pins hard or required items first;
+3. computes tier floors and ceilings;
+4. scores optional items for relevance, recency, evidence, redundancy,
+   priority, and full-text token cost;
+5. sorts optional items by
+   `density -> effectiveScore -> priorityRank -> fullTokens -> id`; and
+6. selects a full, summary, headroom-compressed, pointer, or omitted
+   representation that fits.
+
+Density divides effective score by the cheapest non-omit representation
+(`admissibleTokens`), not by full-text size. This avoids penalizing an item that
+can be represented by a small evidence pointer. Stable item IDs and explicit
+selection policy `sel-2` make tie-breaking and plan-cache invalidation
+deterministic.
+
+When enabled, representation and negative-result entries persist under
+`.omk/cache/context-budget-v2`; plan entries remain session-memory-only.
+`OMK_CONTEXT_GOVERNOR_CACHE=memory` keeps every cache entry in session memory,
+and `OMK_CONTEXT_GOVERNOR_CACHE_DIR` relocates the representation snapshot.
+
+Evidence:
+
+- `packages/coding-agent/src/core/context-budget-v2-planner.ts`
+- `packages/coding-agent/src/core/context-budget-v2-scoring.ts`
+- `packages/coding-agent/src/core/context-budget-v2-selection.ts`
+- `packages/coding-agent/test/context-budget-v2-knapsack-order.test.ts`
+- `packages/coding-agent/test/context-budget-selection-policy-version.test.ts`
+- `packages/coding-agent/test/context-budget-cache-disk.test.ts`
+
+**Working tree:** context files now treat their global/local relevance baseline
+as a floor. Lexical overlap can raise that score but cannot demote standing
+instructions below the no-query baseline. Skills remain topic-scored because
+they are optional capabilities, not standing authority. The change is in
+`scoreContextFileRelevance()` with regression coverage in
+`packages/coding-agent/test/context-budget-relevance.test.ts`.
+
+**Working tree:** the default compactor now strips model-generated managed-rule
+sections and deterministically carries explicit user-authored `RULE`/
+`INVARIANT`/`CONSTRAINT`/`MUST`/`NEVER`/`ALWAYS` markers (plus explicit Korean
+markers) outside LLM rewriting. Rules are bounded to 64 × 1,000 characters,
+stored in additive non-hook compaction details, and covered by a five-round
+byte-preservation test. Natural-language classification, hook summaries, branch
+summaries, and cross-session memory remain outside this slice. Persisted rules
+are credential-redacted and source-bound to a user entry/line/digest; previous
+details are reused only when their canonical block matches the prior summary.
+
+Evidence:
+
+- `packages/coding-agent/src/core/compaction/knowledge-triage.ts`
+- `packages/coding-agent/test/compaction-knowledge-triage.test.ts`
+- `packages/coding-agent/test/compaction-summary-reasoning.test.ts`
+
+### Reasoning routing
+
+**Status: Released / opt-in.** `/think auto` uses the local, deterministic v4
+router. It extracts bounded prompt features, classifies one of seven task
+classes, maps the class through `TASK_CLASS_THINKING_LEVELS`, applies lane
+steps, bounded bias/hint adjustments, and non-negative uncertainty escalation,
+then clamps the result to the selected model's supported levels.
+
+The released extension-signal coefficients are active and bounded:
+`multiTurnPrior=2`, `pressureBucket=1`, and `judgeVote=2`. History and pressure
+are supplied by the main session; a judge vote affects only callers that provide
+one. A zero-score fallback cannot be hijacked by these signals.
+
+The optional learning path is global-only and off by default. When enabled, a
+session loads one strictly validated `RouterBiasSnapshot` from the configured
+path or repository-scoped default, pins that snapshot or miss for the session,
+applies a `-2..2` step bias, and writes only bounded feedback buckets. It never stores prompts, diffs, tool
+output, provider payloads, or repository paths.
+
+Evidence:
+
+- `packages/coding-agent/src/core/reasoning-router-v4.ts`
+- `packages/coding-agent/src/core/reasoning-router-resolver.ts`
+- `packages/coding-agent/src/core/reasoning-router-bias.ts`
+- `packages/coding-agent/test/suite/regressions/013-reasoning-router-v4-accuracy.test.ts`
+- `packages/coding-agent/test/suite/regressions/014-reasoning-router-v4-learning-wiring.test.ts`
+- `packages/coding-agent/test/suite/regressions/018-reasoning-router-v4-inert-weights.test.ts`
+
+**Working tree:** promotion evidence now credits a row only when repeated
+baseline and candidate classifier replays each agree. It also requires a frozen
+baseline and fails closed on insufficient or unstable replays. See
+`reasoning-router-replay-stability.ts`, `reasoning-router-policy-ceiling.test.ts`,
+and `reasoning-router-replay-stability.test.ts`.
+
+### Resource governance, lanes, and shards
+
+The resource plane probes memory, workspace disk, V8 heap, and system CPU, then
+produces bounded admission caps.
+
+| Mechanism | Status | Authority |
+| --- | --- | --- |
+| Prompt-time probe, admission decision, and journal | Released / default | Observe and record |
+| `/resource` and `omk doctor resources` | Released / opt-in | Inspect current policy and probe state |
+| `omk doctor resources --report` | Working tree | Aggregate bounded local admission evidence; never promotes mode |
+| Per-run tool cap and governed heavy-process permits | Released / opt-in | Enforced in `adaptive` or `strict` mode |
+| `launchSubagentLanes()` | Released / internal | No live child-dispatch consumer |
+| Journaled Vitest/Jest/workspace/Go shard executor | Released / internal | No `autoShard` setting or session-command consumer |
+
+`observe` remains the default. Admission caps never raise configured caps.
+Corrupt shard journals are quarantined and block resume; completed shards may be
+skipped, but shard completion is only evidence and never a task verdict.
+
+Evidence:
+
+- `packages/coding-agent/src/core/resource-admission.ts`
+- `packages/coding-agent/src/core/resource-governor-settings.ts`
+- `packages/coding-agent/src/core/run-resource-lease.ts`
+- `packages/coding-agent/src/commands/resource-doctor-cli.ts`
+- `packages/coding-agent/src/core/resource-observation-report.ts`
+- `packages/coding-agent/test/resource-observation-report.test.ts`
+- `packages/coding-agent/src/core/subagent-lane-launcher.ts
+- `packages/coding-agent/src/core/workload-shard-executor.ts`
+- `packages/coding-agent/test/resource-admission.test.ts`
+- `packages/coding-agent/test/resource-doctor-cli.test.ts`
+- `packages/coding-agent/test/agent-session-resource-lease.test.ts`
+- `packages/coding-agent/test/agent-session-resource-permits.test.ts`
+- `packages/coding-agent/test/subagent-lane-launcher.test.ts`
+- `packages/coding-agent/test/workload-shard-executor.test.ts`
+
+### Terminal settlement notifications
+
+**Status: Working tree.** `v0.97.0` released completion sound as opt-in and
+suppressed user aborts. The current working tree enables it by default on an
+interactive TTY and adds an `onAbort` outcome switch. Successful prompts retain
+the 5-second duration floor; failed and aborted/stopped outcomes notify
+immediately.
+
+The sound consumes only `prompt_settled`, never intermediate `agent_end`. The
+current live path drains provider attempts, tools, and queued continuations;
+subagent work is awaited inside its tool call. The settlement reducer reserves
+direct child/shard counters, but no production signal call wires them yet, so
+future live lanes/shards must close that gap before activation.
+RPC, JSON, print mode, and CI remain silent. Playback uses fixed absolute
+executable/argv pairs, a minimal environment without inherited `PATH` or
+credentials, and a neutral temporary cwd. WSL uses BEL rather than resolving
+PowerShell through `PATH`. Playback is fire-and-forget and cannot change the
+prompt outcome.
+
+Evidence:
+
+- `packages/coding-agent/src/core/prompt-settlement.ts`
+- `packages/coding-agent/src/core/completion-sound.ts`
+- `packages/coding-agent/src/core/completion-sound-io.ts`
+- `packages/coding-agent/test/prompt-settlement.test.ts`
+- `packages/coding-agent/test/completion-sound.test.ts`
+- `packages/coding-agent/test/suite/agent-session-retry-events.test.ts`
+
+### Evidence, decisions, and recovery
+
+**Status: Released / opt-in.** The explicit `omk-protocol` API provides versioned,
+readonly record contracts and runtime parsers for tasks, attempts, observations,
+evaluations, waivers, and runtime decisions. `evaluateTask()` is pure. Among
+unwaived required claims, any violation yields `fail`; otherwise missing
+evidence yields `inconclusive`; otherwise the verdict is `pass`. A task with no
+required claims is `inconclusive`; explicit waivers remove their claims from
+verdict reduction. Advisory judging can choose among candidates that already
+passed; it cannot create evidence or change a semantic verdict.
+
+The coding-agent adds evidence receipts, a replay ledger, workspace
+fingerprints, attempt journals, durable goals, seam checkpoints, session doctor,
+and bounded provider retry/failover. Digests detect mismatch; they do not prove
+runner honesty, OS isolation, freshness, or trusted authorship by themselves.
+
+Evidence:
+
+- `packages/protocol/src/evaluation.ts`: `evaluateTask`
+- `packages/protocol/src/decision.ts`: `reduceRuntimeDecision`
+- `packages/protocol/test/protocol.test.ts`
+- `packages/coding-agent/src/core/advisory-judge.ts`
+- `packages/coding-agent/test/advisory-judge.test.ts`
+
+See [Run Protocol and Durable Goals](run-protocol.md),
+[Sessions](sessions.md), [Provider Resilience](provider-resilience.md), and
+[Turn Metrics](metrics.md).
+
+### AdaptOrch and WPL boundary
+
+**Status: Released / opt-in.** Published `omk-adaptorch-wpl` supplies typed packet state, client, adjudication, and
+verdict-projection primitives. Its `loop.ts` explicitly excludes end-to-end
+`adaptorch_run` dispatch, polling, request assembly, and persistence. The
+coding-agent has no production importer that turns those primitives into a
+default execution loop; the Correctness Wall remains an explicitly loaded
+example extension. The default-off AdaptOrch reasoning bridge currently returns
+no advisory hint.
+
+Evidence:
+
+- `packages/adaptorch-wpl/src/loop.ts`
+- `packages/adaptorch-wpl/test/loop.test.ts`
+- `packages/coding-agent/src/core/adaptorch-bridge.ts`
+- `packages/coding-agent/test/suite/regressions/011-reasoning-router-adaptorch-bridge.test.ts`
+- `packages/coding-agent/test/suite/regressions/012-reasoning-router-learning-adaptorch-activation.test.ts`
+
+See [AdaptOrch Preview](adaptorch-preview.md) and
+[Correctness Wall](correctness-wall.md).
+
+### Repository understanding
+
+**Status: Working tree.** The `v0.97.0` release shipped policy/workflow only and
+still ignored `/openwiki/` and contained neither the corpus nor its checker.
+Neither the release tag nor the current Git index tracks `openwiki/` or
+`.understand-anything/`; both datasets are untracked or ignored advisory state.
+The current `.last-update.json` says `interrupted` at current HEAD.
+
+`scripts/check-openwiki.mjs` validates entry pages, internal links, update-state
+shape, and global symbol-name presence in a source/test/script haystack. It does
+not validate prose or bind each symbol to a declared source path. A current-HEAD
+`interrupted` generation warns; a stale interrupted generation blocks. Source
+and tests outrank every generated page. There is no dedicated checker test in
+the current working tree; the executable checker is the available evidence.
+
+This is not a release-grade trust gate: the current corpus is `interrupted`,
+symbol checks are global substrings rather than declared source bindings, and
+the generation workflow still needs an output allowlist plus pre-upload secret
+and private-path scans. Do not load the corpus as trusted context until those
+blockers close.
+
+## Direction
+
+**Status: Proposed.** Owning specification:
+`specs/015-runtime-algorithm-direction/spec.md`. This section creates no runtime
+or test evidence; the internal mechanisms above do not satisfy these promotion
+gates. Apply them in order:
+
+1. **Measure before promoting authority.** Run dated, same-model, same-provider,
+   same-task comparisons before changing defaults or making leadership claims.
+   The protocol in [Turn Metrics](metrics.md) is mandatory.
+2. **Reduce structure before adding mechanisms.** Do not raise module-size,
+   dependency-tree, or import-cycle baselines. The dependency-tree and import-
+   cycle gates are working-tree changes. Split large session and interactive
+   modules by ownership; do not mix movement-only refactors with behavior.
+3. **Promote live authority in stages.** Collect resource observations before
+   making `adaptive` the default. Wire subagent lanes before exposing automatic
+   sharding. Keep automatic sharding opt-in and limited to known, semantically
+   equivalent command families.
+4. **Protect standing context.** The relevance floor and explicit-rule
+   compaction slice are Worktree-only. Broader natural-language, hook, and branch
+   triage still require evidence before expansion.
+5. **Design verified memory before implementing it.** Spec 019 requires
+   evidence-linked admission, Context Budget V2 data-only injection, source-span
+   provenance, staleness, and memory-injection probes. Implementation remains
+   blocked until fixtures and evaluation thresholds are preregistered.
+6. **Keep adaptation evidence-gated.** Do not add online router learning while
+   the current instrument cannot show gain after `BIAS_STRONG_THRESHOLD=5`.
+   Reopen only through an `advance` spec that preregisters the real outcome-
+   linked sample, sample size, minimum effect, confidence rule, and statistical
+   test before collecting the promotion result.
+7. **Keep hosted advice separate from local authority.** AdaptOrch remains a
+   separate service and any bridge remains advisory; local deterministic gates
+   own execution and completion.
+
+## Deliberate non-goals
+
+- Calling a level-barrier schedule an eager critical-path executor
+- Treating internal lane or shard code as a live feature
+- Auto-sharding arbitrary shell, deploy, publish, release, or migration commands
+- Treating model narration, reviewer opinion, or a digest alone as completion
+- Persisting unrestricted prompts or trajectories as learning memory
+- Claiming SOTA from tests, feature counts, self-scores, or roadmap projections
+
+## Verification map
+
+| Claim | Fast verification |
+| --- | --- |
+| Documentation links resolve | `npm run check:doc-links` |
+| Specification governance holds | `npm run check:constitution` |
+| Context selection behavior | focused context-budget tests named above |
+| Router behavior and promotion ceiling | focused reasoning-router tests named above |
+| Tool scheduling and timeout candidate | focused `packages/agent` scheduler/timeout tests |
+| Resource and internal execution mechanisms | focused resource, lane, and shard tests named above |
+
+A green focused test proves only its declared behavior. Release readiness still
+requires the repository's full release gates.