open-multi-agent-kit 0.95.1 → 0.96.0

package/docs/sdk.md

@@ -5,6 +5,7 @@
 The SDK provides programmatic access to omk's agent capabilities. Use it to embed omk in other applications, build custom interfaces, or integrate with automated workflows.
 
 **Example use cases:**
+
 - Build a custom UI (web, desktop, mobile)
 - Integrate agent capabilities into existing applications
 - Create automated pipelines with agent reasoning
@@ -112,6 +113,7 @@ interface AgentSession {
   thinkingLevel: ThinkingLevel;
   messages: AgentMessage[];
   isStreaming: boolean;
+  getSessionStats(): SessionStats;
 
   // In-place tree navigation within the current session file
   navigateTree(targetId: string, options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string }): Promise<{ editorText?: string; cancelled: boolean }>;
@@ -128,6 +130,8 @@ interface AgentSession {
 }
 ```
 
+`getSessionStats()` returns message, token, and cost totals. Its `promptCache` field includes provider-eligible input tokens, provider hit rate (`cacheRead / (input + cacheRead + cacheWrite)`), stable-prefix characters, cache-key changes, boundary bypasses, and the last local break reason. These values diagnose cache-affinity changes; only provider-reported `cacheRead` proves a hit.
+
 Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
 
 ### createAgentSessionRuntime() and AgentSessionRuntime
@@ -212,6 +216,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:
@@ -250,6 +256,7 @@ await session.prompt("After you're done, also check X", { streamingBehavior: "fo
 ```
 
 **Behavior:**
+
 - **Extension commands** (e.g., `/mycommand`): Execute immediately, even during streaming. They manage their own LLM interaction via `omk.sendMessage()`.
 - **File-based prompt templates** (from `.md` files): Expanded to their content before sending or queueing.
 - **During streaming without `streamingBehavior`**: Throws an error. Use `steer()` or `followUp()` directly, or specify the option.
@@ -280,6 +287,8 @@ const state = session.agent.state;
 // state.model: Model - current model
 // state.thinkingLevel: ThinkingLevel - current thinking level
 // state.systemPrompt: string - system prompt
+// state.systemPromptCacheBoundary?: number - stable-prefix UTF-16 offset
+// state.systemPromptCacheBoundaryBypass?: boolean - suppress explicit cache affinity/markers
 // state.tools: AgentTool[] - available tools
 // state.streamingMessage?: AgentMessage - current partial assistant message
 // state.errorMessage?: string - latest assistant error
@@ -294,6 +303,8 @@ session.agent.state.tools = tools; // copies the top-level array
 await session.agent.waitForIdle();
 ```
 
+The cache boundary must be a positive safe integer no greater than `systemPrompt.length`. Missing, invalid, or bypassed boundaries suppress explicit stable-prefix cache metadata. Providers may still ignore valid metadata, so inspect provider usage before claiming a hit.
+
 ### Events
 
 Subscribe to events to receive streaming output and lifecycle notifications.
@@ -365,6 +376,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
@@ -380,6 +393,7 @@ const { session } = await createAgentSession({
 ```
 
 `cwd` is used by `DefaultResourceLoader` for:
+
 - Project extensions (`.omk/extensions/`)
 - Project skills:
   - `.omk/skills/`
@@ -389,6 +403,7 @@ const { session } = await createAgentSession({
 - Session directory naming
 
 `agentDir` is used by `DefaultResourceLoader` for:
+
 - Global extensions (`extensions/`)
 - Global skills:
   - `skills/` under `agentDir` (for example `~/.omk/agent/skills/`)
@@ -438,6 +453,7 @@ const { session } = await createAgentSession({
 ```
 
 If no model is provided:
+
 1. Tries to restore from session (if continuing)
 2. Uses default from settings
 3. Falls back to first available model
@@ -447,6 +463,7 @@ If no model is provided:
 ### API Keys and OAuth
 
 API key resolution priority (handled by AuthStorage):
+
 1. Runtime overrides (via `setRuntimeApiKey`, not persisted)
 2. Stored credentials in `auth.json` (API keys or OAuth tokens)
 3. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
@@ -499,6 +516,8 @@ await loader.reload();
 const { session } = await createAgentSession({ resourceLoader: loader });
 ```
 
+OMK records a stable cache boundary before loaded context files, selected skill content, the date, and the working directory. A turn-level extension that replaces the built prompt bypasses explicit stable-prefix caching unless it returns the prompt unchanged. See [Compaction & Branch Summarization](compaction.md#context-reduction-and-prompt-caching) for provider behavior and diagnostics.
+
 > See [examples/sdk/03-custom-prompt.ts](../examples/sdk/03-custom-prompt.ts)
 
 ### Tools
@@ -847,12 +866,14 @@ const { session } = await createAgentSession({
 ```
 
 **Static factories:**
+
 - `SettingsManager.create(cwd?, agentDir?)` - Load from files
 - `SettingsManager.inMemory(settings?)` - No file I/O
 
 **Project-specific settings:**
 
 Settings load from two locations and merge:
+
 1. Global: `~/.omk/agent/settings.json`
 2. Project: `<cwd>/.omk/settings.json`
 
@@ -1120,12 +1141,14 @@ omk --mode rpc --no-session
 See [RPC documentation](rpc.md) for the JSON protocol.
 
 The SDK is preferred when:
+
 - You want type safety
 - You're in the same Node.js process
 - You need direct access to agent state
 - You want to customize tools/extensions programmatically
 
 RPC mode is preferred when:
+
 - You're integrating from another language
 - You want process isolation
 - You're building a language-agnostic client
@@ -1134,14 +1157,16 @@ RPC mode is preferred when:
 
 Execution-bound evidence records a declared verification command and reported outcome between two artifact-set snapshots, then binds that record to a tamper-evident ledger. `VerifiedEvidenceExecutor` never executes the declared command. `executeVerifiedBash()` invokes caller-supplied `BashOperations`; `executeVerifiedLocalBash()` derives the shell identity and runner from OMK's built-in local backend.
 
-**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 the sorted dirty set (capped at 32 paths, 1 s TTL). 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 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 also carries a default `audit`-mode sandbox preflight (workspace-write policy rooted at the session cwd). The spawn stays unwrapped, but every decision is appended to the replay ledger as a `sandbox_audit` event, giving a tamper-evident audit trail. `OMK_BASH_SANDBOX=enforce` activates the real OS backend — macOS `sandbox-exec` seatbelt or Linux `bwrap` bubblewrap — and fails closed when neither is installed; `OMK_BASH_SANDBOX=0` disables the preflight entirely.
+**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`.
+
+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.
 
 ### Recorded and invoked inputs
 
 | Input | SDK behavior |
-|-------|--------------|
+| ------- | -------------- |
 | `request.command` (`EvidenceCommandDescriptor`) | Validates, hashes, and records the structured descriptor; never executes it |
 | `request.executor` (`"bash-tool" \| "ci-runner" \| "mcp" \| "internal"`) | Records a label only |
 | `request.workspaceScope` (`WorkspaceScope`) | Captures the selected artifact set before and after the callback |
@@ -1191,12 +1216,18 @@ 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.
+
 ### 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` |
-|------|-------------------|-----------------------|----------------------------|
+| ------ | ------------------- | ----------------------- | ---------------------------- |
 | `strict` | blocked | blocked | n/a |
 | `prefer` (default) | conditional | blocked | n/a |
 | `legacy` | receipt checks skipped | receipt checks skipped | checked by legacy options (enabled by default) |
@@ -1207,7 +1238,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 {
@@ -1308,6 +1341,7 @@ RunJournalStore, appendRunJournalRecordDurably, writeQuarantineBytesDurably,
 classifySessionTermination, formatSessionTermination, SessionTerminationError
 
 // Execution-bound evidence (optional, application-driven verification receipts)
+evidenceReceiptToObservation
 EvidenceReceiptStore
 ReplayLedgerManager
 EvidenceGate

package/docs/sessions.md

@@ -19,6 +19,12 @@ Use `/session` in interactive mode to see the current session file, session ID,
 
 For the JSONL file format and SessionManager API, see [Session Format](session-format.md).
 
+## Retries and Termination Events
+
+Each provider attempt writes its own `run_started`/`run_finished` journal pair and emits `session_termination`. A retryable termination is attempt-level when `auto_retry_start` follows it; consumers should not treat that event alone as the end of the outer `prompt()` call.
+
+If a retry or failover succeeds, the later attempt emits `completed` and becomes `session.lastTermination`. If retry budget is exhausted, the last provider failure remains final. Quota and billing-cycle exhaustion are classified as `provider.rate_limit` and can switch through the configured provider-resilience chain before retrying. See [Provider Resilience](provider-resilience.md).
+
 ## Session Commands
 
 | Command | Description |

package/docs/settings.md

@@ -17,7 +17,7 @@ Edit directly or use `/settings` for common options.
 | --------- | ------ | --------- | ------------- |
 | `defaultProvider` | string | - | Default provider (e.g., `"anthropic"`, `"openai"`) |
 | `defaultModel` | string | - | Default model ID |
-| `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"` |
+| `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`, `"ultra"` |
 | `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
 | `thinkingBudgets` | object | - | Custom token budgets per thinking level |
 | `reasoningRouterLearning` | object | - | Opt-in v4 router learning bias (global settings file only) |
@@ -41,16 +41,16 @@ Edit directly or use `/settings` for common options.
 ```json
 {
   "reasoningRouterLearning": {
-    "enabled": false,
-    "biasSnapshotPath": "~/.omk/agent/router-bias.json",
-    "feedbackLedgerPath": "~/.omk/agent/router-feedback.jsonl"
+    "enabled": false
   }
 }
 ```
 
+This opt-in remains global-only, but its default data is isolated per repository or git worktree under `~/.omk/agent/router-feedback/repositories/<opaque-scope>/`. The scope is derived from the canonical worktree root and never stores the raw path. Set `biasSnapshotPath` or `feedbackLedgerPath` only when intentionally overriding that isolation with fixed paths.
+
 #### adaptorchBridge
 
-Advisory-only hint source for the v4 auto thinking-level resolver. Read from the **global** settings file only — a project-scope `.omk/settings.json` value is ignored by design. Default is fully off; the bridge is circuit-breaker protected and TTL-cached, and its hint can only nudge the resolved level by a bounded ±2 steps.
+Global-only, default-off lifecycle for a future v4 advisory source. The timeout, TTL, consult-budget, and circuit-breaker controls are wired, but the current transport is a no-op and cannot change the resolved level. A project-scope `.omk/settings.json` value is ignored by design.
 
 ```json
 {
@@ -70,7 +70,8 @@ Advisory-only hint source for the v4 auto thinking-level resolver. Read from the
 | --------- | ------ | --------- | ------------- |
 | `theme` | string | `"dark"` | Theme name (`"dark"`, `"light"`, or custom) |
 | `quietStartup` | boolean | `false` | Hide startup header |
-| `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
+| `collapseChangelog` | boolean | `true` | Show condensed changelog after updates (set `false` for the full "What's New" block) |
+| `footerSystemMetrics` | boolean | `false` | Show system-wide CPU/MEM usage in the footer stats line |
 | `enableInstallTelemetry` | boolean | `true` | Send an anonymous install/update version ping after first install or changelog-detected updates. This does not control update checks |
 | `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
 | `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` |
@@ -156,7 +157,7 @@ This setting is global-only: `.omk/settings.json` cannot enable or disable it. U
 | `agent.toolTimeoutMs` | number | `0` | Fallback tool execution timeout in milliseconds; `0` disables the fallback timer |
 | `agent.toolTimeouts` | object | built-in defaults | Per-tool-name timeout overrides; `0` disables that tool's timer |
 
-Built-in defaults are 30 seconds for `read`, `grep`, `find`, and `ls`; 60 seconds for `edit` and `write`; and 300 seconds for `bash`. Explicit `agent.toolTimeouts` entries override these defaults. Extension/custom tools without a per-name value use `agent.toolTimeoutMs`. Timeout values must be integer milliseconds from `0` through `2147483647`.
+Built-in defaults are 30 seconds for `read`, `grep`, `find`, and `ls`; 60 seconds for `edit` and `write`; and 300 seconds for `bash`. Explicit `agent.toolTimeouts` entries override these defaults. Extension tools may override settings per call with `resolveTimeoutMs(ctx)`; otherwise custom tools without a per-name value use `agent.toolTimeoutMs`. Timeout values must be integer milliseconds from `0` through `2147483647`.
 
 ```json
 {
@@ -201,6 +202,8 @@ When a provider requests a retry delay longer than `retry.provider.maxRetryDelay
 
 Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explicitly needed. Setting it above `0` can make SDK/provider retries handle out-of-usage-limit errors before OMK sees them, which may block the agent until the provider quota resets in some circumstances.
 
+At the agent level, recognized quota and billing-cycle failures are retryable so OMK can first switch to an authenticated `providerResilience.failoverCandidates` entry. If no candidate qualifies, normal retry backoff applies. See [Provider Resilience](provider-resilience.md).
+
 ```json
 {
   "retry": {

package/docs/skills.md

@@ -11,6 +11,7 @@ OMK implements the [Agent Skills standard](https://agentskills.io/specification)
 ## Table of Contents
 
 - [Locations](#locations)
+- [Optional Document Compiler](#optional-document-compiler)
 - [How Skills Work](#how-skills-work)
 - [Skill Commands](#skill-commands)
 - [Skill Structure](#skill-structure)
@@ -42,6 +43,10 @@ Discovery rules:
 
 Disable discovery with `--no-skills` (explicit `--skill` paths still load).
 
+## Optional Document Compiler
+
+Install [`omk-book-to-skill`](book-to-skill.md) to compile PDF, EPUB, DOCX, HTML, Markdown, text, RTF, MOBI, and AZW sources into generated skills. It is an optional OMK package, not a built-in skill, and keeps Python extractors outside OMK core.
+
 ### Using Skills from Other Harnesses
 
 To use skills from Claude Code or OpenAI Codex, add their directories to settings:
@@ -88,7 +93,7 @@ Arguments after the command are appended after the skill content for the current
 
 `!omk <role-or-request>` is a deterministic OMK hub router. Exact role aliases such as `frontend`, `backend`, `loop`, and `plan` select `omk-frontend`, `omk-backend-data`, `omk-loop`, and `omk-plan`; free-form prompts are scored against the same hub vocabulary and fall back to `omk-skills` when no role is clear.
 
-In interactive mode, type `!` to open skill autocomplete. Selecting a skill inserts the explicit `!skill:name ` form, and `!omk` is offered when the OMK skill hub index is available. Bash remains available as `! command`, and `!! command` runs bash without sending output to the model. If `!token` is not a known skill, it falls back to bash; use `! command` when a command name might collide with a skill. `!omk` is reserved for OMK hub routing and never falls through to bash.
+In interactive mode, type `!` to open skill autocomplete. Selecting a skill inserts the explicit `!skill:name` form, and `!omk` is offered when the OMK skill hub index is available. Bash remains available as `! command`, and `!! command` runs bash without sending output to the model. If `!token` is not a known skill, it falls back to bash; use `! command` when a command name might collide with a skill. `!omk` is reserved for OMK hub routing and never falls through to bash.
 
 Toggle skill commands via `/settings` in interactive mode or in `settings.json`:
 
@@ -173,11 +178,13 @@ Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`
 The description determines when the agent loads the skill. Be specific.
 
 Good:
+
 ```yaml
 description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
 ```
 
 Poor:
+
 ```yaml
 description: Helps with PDFs.
 ```
@@ -206,6 +213,7 @@ brave-search/
 ```
 
 **SKILL.md:**
+
 ````markdown
 ---
 name: brave-search

package/docs/usage.md

@@ -87,9 +87,19 @@ Precedence:
 
 Resolved levels are clamped to the model's capabilities: models without `xhigh`/`max` are capped at their highest supported level, and models without reasoning support bypass the router entirely.
 
-The v4 learning path is available only through the global `reasoningRouterLearning` setting and is off by default. When `reasoningRouterLearning.enabled` is `true`, `/think auto` loads one validated bias snapshot for the session, applies a bounded `-2..2` ladder-step bias, and appends a privacy-safe feedback record containing only bounded enums, booleans, and buckets. Project-local settings cannot enable or redirect this feature, and the ledger never stores raw prompts, file paths, diffs, session identifiers, model/provider payloads, tool output, or hook output.
+The v4 learning path is available only through the global `reasoningRouterLearning` setting and is off by default. When enabled, `/think auto` loads one validated, session-pinned bias snapshot, applies a bounded `-2..2` ladder-step bias, and appends a privacy-safe record containing only bounded enums, booleans, and buckets. A later explicit `/think <level>` choice adds one directional `s1-override` record for the same decision. Project-local settings cannot enable the feature, and records never contain raw prompts, repository paths, diffs, session identifiers, provider payloads, tool output, or hook output.
 
-The Adaptorch advisory bridge module still ships as default-off groundwork only. It has no settings key, command, transport, or session call site yet, so it does not affect `/think auto` until a future transport and security review explicitly wire it.
+Default ledgers and snapshots are isolated by an opaque hash of the canonical repository or git worktree root. Compile the current repository's accumulated records between sessions:
+
+```bash
+omk router-feedback compile-bias --cwd /path/to/repository
+```
+
+Compilation is deterministic. It creates a randomized same-directory temporary file exclusively, enforces POSIX mode `0600`, then atomically renames it over the snapshot; this is atomic replacement, not `fsync`-backed crash durability, and explicit output paths should use a trusted directory. Snapshot loading fails closed on malformed or internally inconsistent cells, including any nonzero bias backed by fewer than five strong records. A session pins either a snapshot or a miss on its first learning-enabled auto turn, so later compilations are observed only by sessions that have not yet attempted that load. Fixed `biasSnapshotPath` or `feedbackLedgerPath` session settings remain explicit compatibility overrides and can intentionally share state across repositories; pass matching `--out` or `--ledger` paths to the compiler when using them.
+
+The ledger intentionally keeps causal buckets instead of free-form memories or raw trajectories. This follows CLIN's causal-abstraction approach ([arXiv:2310.10134](https://arxiv.org/abs/2310.10134)) and session-boundary updates from the Red Queen Gödel Machine ([arXiv:2606.26294](https://arxiv.org/abs/2606.26294)); CTIM-Rover found that repository-level episodic memories could add distracting noise and failed to improve its base coding agent ([arXiv:2505.23422](https://arxiv.org/abs/2505.23422)).
+
+The Adaptorch advisory bridge is also global-only and default-off. Its timeout, TTL, consult-budget, and circuit-breaker lifecycle is wired, but the current advisory transport is a no-op and cannot change the router level.
 
 ## Message Queue
 
@@ -140,7 +150,7 @@ The doctor verifies the session's complete JSONL prefix, run journal, compaction
 
 Session and journal bytes after the final newline are copied byte-for-byte to a `.quarantine-*` file before the original is atomically rewritten to its valid complete prefix. Opening a session uses the same complete-prefix rule; `SessionManager.getQuarantineReport()` reports any startup quarantine.
 
-Each real agent run writes fsynced `run_started` and `run_finished` records to `<session>.runjournal`. An unclosed valid run is recorded as an inferred `process_crash` on the next startup. JSON/RPC emit `session_termination`; text and TUI errors include kind, provider/model, retryability, cause, run ID, and next action.
+Each agent attempt writes fsynced `run_started` and `run_finished` records to `<session>.runjournal`. An unclosed valid run is recorded as an inferred `process_crash` on the next startup. JSON/RPC emit `session_termination`; text and TUI errors include kind, provider/model, retryability, cause, run ID, and next action. Recovered retries therefore record the failed attempt and a later `completed` attempt.
 
 ## Context Files
 
@@ -242,7 +252,7 @@ cat README.md | omk -p "Summarize this text"
 | `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
 | `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
 | `--api-key <key>` | API key, overriding environment variables |
-| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra` |
 | `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
 | `--list-models [search]` | List available models |
 

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "omk-extension-custom-provider-anthropic",
-  "version": "0.95.1",
+  "version": "0.96.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-custom-provider-anthropic",
-      "version": "0.95.1",
+      "version": "0.96.0",
       "dependencies": {
         "@anthropic-ai/sdk": "0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "0.95.1",
+	"version": "0.96.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "0.95.1",
+	"version": "0.96.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "omk-extension-gondolin",
-	"version": "0.95.1",
+	"version": "0.96.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-gondolin",
-			"version": "0.95.1",
+			"version": "0.96.0",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/examples/extensions/gondolin/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-gondolin",
 	"private": true,
-	"version": "0.95.1",
+	"version": "0.96.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/plannotator-approval-bridge.ts

@@ -0,0 +1,83 @@
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import {
+	ApprovalReceiptStore,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+	PlannotatorApprovalBridge,
+} from "open-multi-agent-kit";
+
+interface LoadedPlan {
+	path: string;
+	content: string;
+}
+
+function loadWorkspacePlan(cwd: string, input: string): LoadedPlan {
+	const workspaceRoot = realpathSync(cwd);
+	const planPath = realpathSync(resolve(workspaceRoot, input));
+	const relativePath = relative(workspaceRoot, planPath);
+	if (!relativePath || relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
+		throw new Error("Plan must be a file inside the current workspace");
+	}
+	if (!statSync(planPath).isFile()) throw new Error("Plan must be a regular file");
+	return { path: relativePath.split(sep).join("/"), content: readFileSync(planPath, "utf8") };
+}
+
+export default function plannotatorApprovalBridgeExtension(omk: ExtensionAPI): void {
+	let bridge: PlannotatorApprovalBridge | undefined;
+
+	function initializeBridge(ctx: ExtensionContext): void {
+		bridge?.dispose();
+		bridge = new PlannotatorApprovalBridge({
+			eventBus: omk.events,
+			store: new ApprovalReceiptStore(join(ctx.sessionManager.getSessionDir(), "approval-receipts")),
+			workspaceRoot: ctx.cwd,
+			sessionId: ctx.sessionManager.getSessionId(),
+			interactive: ctx.mode === "tui" && ctx.hasUI,
+			requestTimeoutMs: 5_000,
+			onReceipt: (receipt, write) => {
+				omk.appendEntry("approval-receipt-v1", receipt);
+				ctx.ui.notify(
+					`Approval ${receipt.core.decision}; immutable receipt ${write.created ? "created" : "verified"}. No execution was started.`,
+					receipt.core.decision === "approved" ? "info" : "warning",
+				);
+			},
+			onError: () => ctx.ui.notify("Ignored an invalid or uncorrelated Plannotator event.", "warning"),
+		});
+		bridge.start();
+	}
+
+	omk.on("session_start", async (_event, ctx) => initializeBridge(ctx));
+	omk.on("session_shutdown", async () => {
+		bridge?.dispose();
+		bridge = undefined;
+	});
+
+	omk.registerCommand("approval-review", {
+		description: "Review a workspace plan with Plannotator and persist a non-executing approval receipt",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			if (ctx.mode !== "tui" || !ctx.hasUI) {
+				ctx.ui.notify("Approval review requires interactive TUI mode.", "error");
+				return;
+			}
+			if (!bridge) initializeBridge(ctx);
+			const input = args.trim();
+			if (!input) {
+				ctx.ui.notify("Usage: /approval-review <workspace-relative-plan.md>", "warning");
+				return;
+			}
+			try {
+				const plan = loadWorkspacePlan(ctx.cwd, input);
+				const correlation = await bridge?.requestReview({ planPath: plan.path, planContent: plan.content });
+				if (!correlation) throw new Error("Approval bridge is unavailable");
+				ctx.ui.notify(
+					`Plannotator review opened (${correlation.reviewId}); waiting for an explicit decision.`,
+					"info",
+				);
+			} catch {
+				ctx.ui.notify("Approval review failed. Confirm the plan path and that Plannotator is loaded.", "error");
+			}
+		},
+	});
+}

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "omk-extension-sandbox",
-	"version": "0.95.1",
+	"version": "0.96.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-sandbox",
-			"version": "0.95.1",
+			"version": "0.96.0",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-sandbox",
 	"private": true,
-	"version": "0.95.1",
+	"version": "0.96.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",