open-multi-agent-kit 0.95.2 → 0.96.0

package/docs/docs.json

@@ -60,6 +60,10 @@
           "title": "Skills",
           "path": "skills.md"
         },
+        {
+          "title": "Book to Skill",
+          "path": "book-to-skill.md"
+        },
         {
           "title": "MCP",
           "path": "mcp.md"
@@ -102,6 +106,10 @@
           "title": "SDK",
           "path": "sdk.md"
         },
+        {
+          "title": "Run Protocol v1",
+          "path": "run-protocol.md"
+        },
         {
           "title": "RPC Mode",
           "path": "rpc.md"

package/docs/index.md

@@ -35,6 +35,7 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 - [Quickstart](quickstart.md) - install, authenticate, and run a first session.
 - [Using OMK](usage.md) - interactive mode, slash commands, 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.
 - [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.
@@ -46,6 +47,7 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 
 - [Extensions](extensions.md) - TypeScript modules for tools, commands, events, and custom UI.
 - [Skills](skills.md) - Agent Skills for reusable on-demand capabilities.
+- [Book to Skill](book-to-skill.md) - optional document-to-skill compiler with local provenance checks.
 - [Prompt templates](prompt-templates.md) - reusable prompts that expand from slash commands.
 - [Themes](themes.md) - built-in and custom terminal themes.
 - [OMK packages](packages.md) - bundle and share extensions, skills, prompts, and themes.
@@ -55,6 +57,7 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 ## Programmatic usage
 
 - [SDK](sdk.md) - embed omk in Node.js applications.
+- [Run Protocol v1](run-protocol.md) - canonical task, attempt, observation, evaluation, decision, and waiver contracts.
 - [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/models.md

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

package/docs/provider-resilience.md

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

package/docs/providers.md

@@ -99,6 +99,10 @@ omk
 
 Reference for environment variables and `auth.json` keys: [`const envMap`](https://github.com/dmae97/omk/blob/main/packages/ai/src/env-api-keys.ts) in [`packages/ai/src/env-api-keys.ts`](https://github.com/dmae97/omk/blob/main/packages/ai/src/env-api-keys.ts).
 
+#### NVIDIA NIM
+
+Set `NVIDIA_API_KEY` and select an NVIDIA model with `/model`. The built-in `nvidia/z-ai/glm-5.2` entry sends `reasoning_effort`, including the `max` level. Other NVIDIA models keep conservative compatibility defaults unless their model metadata explicitly enables reasoning effort.
+
 #### Zyloo
 
 Zyloo is an OpenAI-compatible unified API gateway. Set `ZYLOO_API_KEY` and use any Zyloo-hosted model:

package/docs/run-protocol.md

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

package/docs/sdk.md

@@ -216,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:
@@ -374,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
@@ -1212,9 +1216,15 @@ 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` |
 | ------ | ------------------- | ----------------------- | ---------------------------- |
@@ -1228,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 {
@@ -1329,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

@@ -202,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

@@ -150,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
 

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

@@ -1,12 +1,12 @@
 {
   "name": "omk-extension-custom-provider-anthropic",
-  "version": "0.95.2",
+  "version": "0.96.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-custom-provider-anthropic",
-      "version": "0.95.2",
+      "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.2",
+	"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.2",
+	"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.2",
+	"version": "0.96.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-gondolin",
-			"version": "0.95.2",
+			"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.2",
+	"version": "0.96.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

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

@@ -1,12 +1,12 @@
 {
 	"name": "omk-extension-sandbox",
-	"version": "0.95.2",
+	"version": "0.96.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-sandbox",
-			"version": "0.95.2",
+			"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.2",
+	"version": "0.96.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "omk-extension-with-deps",
-  "version": "0.95.2",
+  "version": "0.96.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-with-deps",
-      "version": "0.95.2",
+      "version": "0.96.0",
       "dependencies": {
         "ms": "2.1.3"
       },

package/examples/extensions/with-deps/package.json

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