open-multi-agent-kit 0.90.8 → 0.91.0

package/docs/provider-resilience.md

@@ -0,0 +1,87 @@
+# Provider resilience (root-level)
+
+Built into OMK core — not an optional extension.
+
+## What it does
+
+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 session survival engineering, not a jailbreak.
+
+## Settings (`~/.omk/agent/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" }
+    ]
+  }
+}
+```
+
+| 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 |
+
+Disable only if you intentionally want Fable:
+
+```json
+"providerResilience": { "blockStickySafetyModels": false, "autoFailoverOnSafetyStop": false }
+```
+
+## Code
+
+| 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 |
+
+## How Fable is neutralized (not "jailbroken")
+
+Server-side content/safety stops cannot be removed by OAuth RE or local patches.
+OMK **deletes Fable from the operational surface**:
+
+| 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 |
+
+**You don't fight Fable. You never load it.**
+
+## Operator
+
+```
+# after rebuild — restart OMK session (required)
+
+/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
+```
+
+## arXiv note (2026-07)
+
+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.

package/docs/sdk.md

@@ -87,6 +87,19 @@ interface AgentSession {
   sessionFile: string | undefined;
   sessionId: string;
 
+  // Lifecycle and termination
+  lastTermination: SessionTermination | undefined;
+  recordProcessSignal(signal: "SIGINT" | "SIGTERM" | "SIGHUP" | "SIGQUIT"): SessionTermination;
+
+  // Audit / repair
+  transcriptRepair: { insertedToolCallIds: string[]; reason: string } | undefined;
+  runJournalRecords: readonly unknown[];
+  runJournalQuarantineReport: RunJournalQuarantineReport | null;
+
+  // Workspace mutation signals (used by evidence freshness gating)
+  sessionRiskLevel: "normal" | "elevated";
+  workspaceMutationCount: number;
+
   // Model control
   setModel(model: Model): Promise<void>;
   setThinkingLevel(level: ThinkingLevel): void;
@@ -181,6 +194,24 @@ session = runtime.session;
 unsubscribe = session.subscribe(() => {});
 ```
 
+### Run Termination and Replay Binding
+
+Every real AgentSession run emits a `session_termination` event and exposes the latest value as `session.lastTermination`. The typed record includes `kind`, `provider`, `model`, retry flags, `causeCode`, `nextAction`, and `runId`; persisted sessions also fsync lifecycle records to `<session>.runjournal`.
+
+To share evidence freshness ordering with runtime repairs and late tool settlements, pass the same optional replay ledger to the session and `VerifiedEvidenceExecutor`:
+
+```typescript
+const ledger = new ReplayLedgerManager(goalId, ledgerPath);
+const { session } = await createAgentSession({
+  replayLedger: ledger,
+  replayGoalId: goalId,
+  replayLaneId: laneId,
+});
+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`.
+
 ### Prompting and Message Queueing
 
 `PromptOptions` controls prompt expansion, queueing behavior while streaming, and prompt preflight notifications:
@@ -315,7 +346,7 @@ session.subscribe((event) => {
       // event.toolResults: tool results from this turn
       break;
     
-    // Session events (queue, compaction, retry)
+    // Session events (queue, compaction, retry, termination, workspace mutation)
     case "queue_update":
       console.log(event.steering, event.followUp);
       break;
@@ -324,6 +355,12 @@ session.subscribe((event) => {
     case "auto_retry_start":
     case "auto_retry_end":
       break;
+    case "session_termination":
+      // event.termination: latest session termination record
+      break;
+    case "workspace_mutation":
+      // Emitted when a late-settling potentially-writing tool may have mutated the workspace
+      break;
   }
 });
 ```
@@ -1091,6 +1128,122 @@ RPC mode is preferred when:
 - You want process isolation
 - You're building a language-agnostic client
 
+## Evidence and Verification
+
+Execution-bound evidence is an optional, application-driven layer. It 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. The opt-in `executeVerifiedBash()` adapter invokes caller-supplied `BashOperations`; `executeVerifiedLocalBash()` instead derives the shell identity and runner from OMK's built-in local backend. The default CLI and AgentSession bash paths remain unverified. The repository CI workflow is the sole built-in callsite: it runs the release-consistency verifier through the local adapter.
+
+### 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 |
+| `request.execute` | Invokes your callback; your application owns its implementation and truthfulness |
+| `executeVerifiedBash()` | Passes the exact shell script to injected `BashOperations`; the caller supplies the matching shell identity and trusts the runner |
+| `executeVerifiedLocalBash()` | Resolves OMK's local shell identity, creates the matching local `BashOperations`, and delegates to `executeVerifiedBash()` |
+
+### Runner honesty is a trust boundary
+
+The SDK cannot prove that a callback or injected runner executed what it reported. A direct `VerifiedEvidenceExecutor` callback must execute the exact descriptor, normalize the disposition, and return already-redacted `Uint8Array` output.
+
+`executeVerifiedBash()` handles the mechanical shell adapter contract:
+
+- records a `kind: "shell"` descriptor using the same script passed to `BashOperations.exec()`,
+- maps exit, timeout, and abort states to receipt dispositions,
+- retains a rolling 128 KiB combined-output tail, applies OMK's high-confidence text redaction, then keeps the final 64 KiB, and
+- records the combined `BashOperations` stream as receipt `stdout`; receipt `stderr` is empty because that interface does not expose separate channels.
+
+The policy is best-effort masking, not DLP. A credential spanning the rolling-window cut may lose matching context, although receipts persist only the resulting digest and byte count. The runner, declared shell identity, environment, remote execution behavior, and any runner-owned spill files remain caller trust boundaries. The script is stored in the receipt after credential-shaped preflight, so keep secrets out of command strings.
+
+Injected runners must follow the built-in terminal protocol: return an integer exit code, throw `Error("aborted")` for abort, or throw an error whose message starts with `timeout:`. Other failures propagate without a receipt; `null` or non-integer exit codes fail closed with `VerifiedBashAdapterError`.
+
+`executeVerifiedLocalBash()` removes the caller-declared shell mismatch by resolving the descriptor shell and local backend from the same shell setting. It does not bind the inherited environment, prove runner honesty, or provide OS isolation.
+
+### First-party CI callsite
+
+`.github/workflows/ci.yml` invokes the compiled `dist/verify-ci.js` entry after the normal repository check. That entry runs only `node scripts/check-release-consistency.mjs` through `executeVerifiedLocalBash()` with `executor: "ci-runner"`, applies a strict `EvidenceGate`, writes receipts, ledger, and report under `.omk/ci-evidence`, and returns a non-zero process exit when the gate is blocked. CI uploads that directory as `verified-release-consistency`.
+
+This callsite does not wrap the full build, check, or test suite and does not enable receipts for interactive, RPC, or SDK-created AgentSession bash calls. Its workspace freshness scope is limited to the root and coding-agent package manifests.
+
+### Execution ordering
+
+`VerifiedEvidenceExecutor.execute(request)` runs, in order:
+
+1. before artifact-set snapshot (`workspaceBefore`)
+2. your callback (`await request.execute()`)
+3. after artifact-set snapshot (`workspaceAfter`)
+4. replay-ledger `append` + `persist()`
+5. envelope binding to the ledger event (`seq`, `eventHash`)
+6. no-overwrite store publish (hard-link; cannot replace an existing receipt)
+
+Ledger and receipt publication are fail-closed but not one filesystem transaction. A failure after `ledger.persist()` and before publication can leave a dangling ledger event; a failure after hard-link publication can leave a readable receipt even though `execute()` rejects. Reconcile the ledger and store before retrying an explicit receipt ID.
+
+### Freshness, ledger load, and store hardening
+
+- **Freshness** compares only the caller-selected artifact set (`WorkspaceScope.artifactPaths`). It issues no Git command and carries no Git fingerprint.
+- **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.
+
+### 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.
+
+| 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) |
+
+Soft missing data means no resolver was supplied or a resolver returned `undefined`. Resolver exceptions are hard failures in both `strict` and `prefer`. The resolver from `createGateOptions()` calls `EvidenceReceiptStore.read()`, so a claimed receipt ID that has no stored file throws and blocks the gate.
+
+Tamper-grade mismatches include: receipt ID, goal, or claim mismatch; schema version ≠ 3; status not `passed` or `exitCode` ≠ 0; command-SHA mismatch; lane mismatch; artifact-changed-after-verification; and ledger-binding mismatch.
+
+`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
+
+```typescript
+import {
+  EvidenceGate, EvidenceReceiptStore, executeVerifiedLocalBash,
+  ReplayLedgerManager, TaskContractBuilder, VerifiedEvidenceExecutor,
+  type WorkspaceScope,
+} from "open-multi-agent-kit";
+
+const goalId = "goal-123";
+const claim = "repository checks passed";
+const cwd = process.cwd();
+const workspaceScope: WorkspaceScope = { root: cwd, artifactPaths: ["packages/coding-agent/src/index.ts"] };
+
+const store = new EvidenceReceiptStore("/secure/receipts");
+const ledger = new ReplayLedgerManager(goalId, "/secure/ledger.jsonl");
+const executor = new VerifiedEvidenceExecutor({ store, ledger });
+
+const { evidenceMetadata } = await executeVerifiedLocalBash({
+  evidenceExecutor: executor,
+  goalId,
+  claim,
+  script: "npm run check",
+  cwd,
+  timeoutMs: 30_000,
+  workspaceScope,
+});
+
+const contract = new TaskContractBuilder(goalId)
+  .setClaim(claim)
+  .addRequiredEvidence({
+    claim, category: "feature",
+    receiptId: evidenceMetadata.receiptId, receiptSchemaVersion: 3,
+    receiptCommandSha256: evidenceMetadata.receiptCommandSha256,
+  })
+  .updateEvidenceStatus(claim, "satisfied")
+  .setVerdict("pass")
+  .build();
+
+const result = new EvidenceGate(executor.createGateOptions()).check(contract);
+// result.status: "open" | "conditional" | "blocked"
+```
+
 ## Exports
 
 The main entry point exports:
@@ -1098,7 +1251,9 @@ The main entry point exports:
 ```typescript
 // Factory
 createAgentSession
+createAgentSessionFromServices
 createAgentSessionRuntime
+createAgentSessionServices
 AgentSessionRuntime
 
 // Auth and Models
@@ -1122,16 +1277,98 @@ createCodingTools
 createReadOnlyTools
 createReadTool, createBashTool, createEditTool, createWriteTool
 createGrepTool, createFindTool, createLsTool
+createLocalBashOperations
+
+// Compaction (programmatic primitives)
+calculateContextTokens, compact, createCompactionEnvelope,
+createCompactionHysteresisConfig, createCompactionHysteresisState,
+createCompactionSourceIdentity, createCompactionTransaction,
+createSessionRevisionToken, decideCompactionCommit, estimateTokens,
+evaluateCompactionBarrier, findCutPoint, findTurnStartIndex,
+generateBranchSummary, generateSummary, getLastAssistantUsage,
+prepareBranchEntries, serializeConversation, shouldCompact, stepCompactionHysteresis,
+validateCompactionEnvelope
+
+// Context-budget v2 and reserved-token budget
+planPromptContextBudgetV2, applyContextCacheInvalidation,
+createMemoryContextBudgetCacheProviderV2, buildContextBudgetPlanCacheKeyV2,
+buildContextBudgetMaterializedRepresentationCacheKeyV2, createContextBudgetCacheKeyBaseV2,
+createContextCacheInvalidationSnapshot, serializeContextCacheSnapshot,
+CONTEXT_BUDGET_POLICY_VERSION_V2
+computeReservedTokenBudget, estimateToolResultReserve, ReservedTokenBudgetError
+
+// Run journal and session termination
+RunJournalStore, appendRunJournalRecordDurably, writeQuarantineBytesDurably,
+classifySessionTermination, formatSessionTermination, SessionTerminationError
+
+// Execution-bound evidence (optional, application-driven verification receipts)
+EvidenceReceiptStore
+ReplayLedgerManager
+EvidenceGate
+FailClosedMergeGate
+TaskContractBuilder
+VerifiedEvidenceExecutor
+VerifiedEvidenceExecutorError
+executeVerifiedBash
+executeVerifiedLocalBash
+VERIFIED_BASH_REDACTION_POLICY_ID
+VerifiedBashAdapterError
+redactCommandDescriptor
+createCommandHmacBinder
+EVIDENCE_COMMAND_REDACTION_POLICY_ID
+MAX_COMMAND_REDACTION_PLACEHOLDERS
+parseCommandHmacBinding
+parseCommandRedactionSummary
+CommandRedactionError
 
 // Types
 type CreateAgentSessionOptions
 type CreateAgentSessionResult
+type CreateAgentSessionRuntimeFactory
+type CreateAgentSessionRuntimeResult
+type CreateAgentSessionServicesOptions
 type ExtensionFactory
 type ExtensionAPI
 type ToolDefinition
 type Skill
 type PromptTemplate
 type Tool
+type CompactionEnvelope
+type CompactionTransaction
+type CompactionHysteresisConfig
+type CompactionHysteresisState
+type CompactionBarrierResult
+type CompactionCommitDecision
+type ContextBudgetCacheProviderV2
+type ContextCacheInvalidationEvent
+type ContextCacheInvalidationSnapshot
+type ReservedTokenBudgetInput
+type ReservedTokenBudgetResult
+type RunJournalQuarantineReport
+type SessionTermination
+type SessionTerminationCause
+type SessionTerminationKind
+type ToolSchedulerSetting
+type AgentRuntimeSettings
+type VerifiedBashExecutionRequest
+type VerifiedLocalBashExecutionRequest
+type EvidenceGateOptions
+type VerifiedEvidenceExecutionRequest
+type VerifiedEvidenceExecutionResult
+type VerifiedEvidenceExecutionOutcome
+type EvidenceReceiptMode
+type TaskContract
+type EvidenceCommandDescriptor
+type WorkspaceScope
+type CommandRedactionPlaceholder
+type CommandRedactionSummary
+type EvidenceReceipt
+type EvidenceReceiptLedgerBinding
+type ReplayEvent
+type ReplayEventType
+type WorkspaceMutationReplayPayload
+type Sha256Hex
+type ArtifactSetWorkspaceFingerprint
 ```
 
 For extension types, see [extensions.md](extensions.md) for the full API.

package/docs/settings.md

@@ -20,6 +20,8 @@ Edit directly or use `/settings` for common options.
 | `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"` |
 | `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) |
+| `adaptorchBridge` | object | - | Opt-in AdaptOrch advisory bridge for the auto thinking-level resolver (global settings file only) |
 
 #### thinkingBudgets
 
@@ -34,6 +36,34 @@ Edit directly or use `/settings` for common options.
 }
 ```
 
+#### reasoningRouterLearning
+
+```json
+{
+  "reasoningRouterLearning": {
+    "enabled": false,
+    "biasSnapshotPath": "~/.omk/agent/router-bias.json",
+    "feedbackLedgerPath": "~/.omk/agent/router-feedback.jsonl"
+  }
+}
+```
+
+#### 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.
+
+```json
+{
+  "adaptorchBridge": {
+    "enabled": false,
+    "ttlMs": 300000,
+    "timeoutMs": 1500,
+    "maxConsultsPerSession": 5,
+    "failureThreshold": 3
+  }
+}
+```
+
 ### UI & Display
 
 | Setting | Type | Default | Description |
@@ -73,15 +103,31 @@ Set `OMK_SKIP_VERSION_CHECK=1` to disable the OMK version update check. Use `--o
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `compaction.enabled` | boolean | `true` | Enable auto-compaction |
-| `compaction.reserveTokens` | number | `16384` | Tokens reserved for LLM response |
+| `compaction.model` | string | session model | Authenticated canonical `provider/model` used only for compaction |
+| `compaction.reserveTokens` | number | `16384` | Legacy/default output reserve (tokens reserved for the LLM response) |
+| `compaction.reservedOutputTokens` | number | `reserveTokens` | Optional override for output-only reserve |
+| `compaction.reservedToolResultTokens` | number | `0` | Reserve tokens for pending tool results |
+| `compaction.safetyMarginTokens` | number | `0` | Extra safety margin added to the reserve |
+| `compaction.imageReserveTokens` | number | `0` | Reserve tokens for image content |
 | `compaction.keepRecentTokens` | number | `20000` | Recent tokens to keep (not summarized) |
+| `compaction.maxUsageRatio` | number | `0.9` | Normal trigger ratio (fraction of context window) |
+| `compaction.rearmRatio` | number | `0.75 × maxUsageRatio` | Ratio below which a triggered compaction can rearm |
+| `compaction.emergencyRatio` | number | `0.98` | Emergency compaction ratio |
+
+All numeric token reserves must be non-negative safe integers. Ratios must be finite and in `(0, 1]`. Invalid values fail session creation instead of silently weakening the policy.
 
 ```json
 {
   "compaction": {
     "enabled": true,
+    "model": "zai/glm-5.2",
     "reserveTokens": 16384,
-    "keepRecentTokens": 20000
+    "reservedToolResultTokens": 8192,
+    "safetyMarginTokens": 1024,
+    "keepRecentTokens": 20000,
+    "maxUsageRatio": 0.9,
+    "rearmRatio": 0.7,
+    "emergencyRatio": 0.98
   }
 }
 ```
@@ -100,6 +146,38 @@ Set `OMK_SKIP_VERSION_CHECK=1` to disable the OMK version update check. Use `--o
 
 This setting is global-only: `.omk/settings.json` cannot enable or disable it. Use `OMK_CONTEXT_GOVERNOR=1` to force it on for one process or `OMK_CONTEXT_GOVERNOR=0` to force it off for a baseline run. The cache is never persisted or shared between sessions.
 
+### Agent Tool Execution
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `agent.toolScheduler` | string | `"dag-v2"` | Deterministic resource-claim scheduler. Use `"waves-v1"` for compatibility rollback |
+| `agent.maxToolConcurrency` | number | `4` | Maximum calls in one DAG level; `0` removes the cap |
+| `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`.
+
+```json
+{
+  "agent": {
+    "toolScheduler": "dag-v2",
+    "maxToolConcurrency": 4,
+    "toolTimeoutMs": 0,
+    "toolTimeouts": {
+      "read": 30000,
+      "write": 60000,
+      "bash": 300000,
+      "my_mcp_tool": 120000,
+      "my_browser_tool": 180000
+    }
+  }
+}
+```
+
+`OMK_TOOL_SCHEDULER` overrides the file setting for one process. Set it to `waves-v1` for rollback or `dag-v2` to force the resource DAG. Invalid scheduler and timeout values fail session creation instead of silently weakening the policy.
+
+The DAG preserves source-order result artifacts. `bash`, unknown tools, and extension tools without explicit resource claims remain exclusive. Tool timeout is logical cancellation: OMK closes the tool call and signals cancellation, but arbitrary JavaScript or external side effects may continue if the tool ignores that signal.
+
 ### Branch Summary
 
 | Setting | Type | Default | Description |

package/docs/themes.md

@@ -41,6 +41,8 @@ On first run, omk detects your terminal background and defaults to `omk-control-
 
 The bundled Tinted themes are generated from [`tinted-theming/schemes`](https://github.com/tinted-theming/schemes) Base24 palettes (MIT): Catppuccin Mocha, Tokyo Night Storm, Kanagawa Dragon, Gruvbox Dark, and Dracula.
 
+The Aurora pair (`omk-aurora-dark`, `omk-aurora-light`; aliases `aurora`, `aurora-dark`, `aurora-light`) ships a WCAG-verified palette: body text ≥14:1 contrast, muted ≥5.7:1, and semantic colors (success/error/warning/accent) ≥4.5:1 against their backgrounds, with a stepped thinking-level color ramp (dim → muted → accent → accentSoft → magenta). Both variants share the same 51-token map so light/dark switching stays visually consistent.
+
 ## Creating a Custom Theme
 
 1. Create a theme file:

package/docs/usage.md

@@ -126,6 +126,21 @@ Useful session commands:
 
 See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
 
+### Session Doctor and Recovery
+
+```bash
+omk session doctor                              # inspect all stored sessions
+omk session doctor --session <path|id>          # inspect one session
+omk session doctor --session <path|id> --repair --dry-run
+omk session doctor --session <path|id> --repair
+```
+
+The doctor verifies the session's complete JSONL prefix, run journal, compaction envelopes/transactions, replay-evidence links, workspace, and provider/model binding. `--dry-run` plans repairs without writing. Repair mode rechecks file hashes under a lock before writing and only allows unambiguous missing tool results, exact trailing-fragment quarantine, unclosed-run crash recovery, and stale compaction abandonment. Duplicate/orphan tool results, duplicate IDs, broken hashes/chains, and changed preconditions are refused.
+
+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.
+
 ## Context Files
 
 OMK loads `AGENTS.md` or `CLAUDE.md` at startup from:
@@ -177,6 +192,28 @@ These commands manage omk packages, not the omk CLI installation. To uninstall o
 
 See [OMK Packages](packages.md) for package sources and security notes.
 
+### Session Doctor
+
+```bash
+omk session doctor [--session <path|id>] [--repair [--dry-run]]
+```
+
+Exit codes: `0` healthy or successfully repaired, `1` issues found or dry-run repairs available, `2` refused/usage/CAS failure.
+
+### Provider Doctor
+
+```bash
+omk provider doctor <provider-id> [--level <0|1>] [--model <model-id>] [--timeout <ms>] [--probe-model <model-id>]
+```
+
+Diagnoses one provider and prints a single sanitized JSON document. Exit codes are stable: `0` ok, `1` diagnosis failed, `2` usage error. The legacy flag form `omk --doctor-provider <provider-id>` (with `--doctor-level`, `--doctor-model`, `--doctor-timeout`) remains an alias.
+
+- **Level 0** (default) — static checks only, no network: config resolution, URL/scheme/address policy, model↔provider relation, credential presence.
+- **Level 1** (`--level 1`) — adds non-generative, GET-only reachability probes (root + `/models`) with strict timeouts, no redirects, and DNS/address pinning. Results use the exact probe categories `ok | network | auth | unsupported-endpoint | server`: a root or `/models` 404 is neutral (`unsupported-endpoint`), 401/403 is an auth failure, and 5xx is a `server` failure.
+- **Level 2** — reachable only via the explicit `--probe-model <model-id>` opt-in: sends one minimal-token generative request (`max_tokens: 1`) to the completions endpoint. **This may incur provider costs**; the JSON result marks it with `"costWarning": true`. No tool-call probe is ever sent.
+
+Config sources, highest precedence first: `models.json`, `KIMI_BASE_URL`/`KIMI_MODEL_NAME` env, `~/.kimi/config.toml` root keys, then `[providers.<name>]` TOML tables with `type = "openai_legacy"` — the last are classified `custom-openai-compatible`, so native-only checks (login, native config) are skipped and endpoint reachability is checked instead. Credentials, URL userinfo/query/fragment, request bodies, and response bodies never appear in the output; malformed TOML is reported by line number only.
+
 ### Modes
 
 | Flag | Description |
@@ -308,6 +345,7 @@ omk --exclude-tools ask_question
 | `OMK_CODING_AGENT_DIR` | Override config directory; default is `~/.omk/agent` |
 | `OMK_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
 | `OMK_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
+| `OMK_TOOL_SCHEDULER` | Override the tool scheduler with `dag-v2` or use `waves-v1` for process-local rollback |
 | `OMK_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
 | `OMK_SKIP_VERSION_CHECK` | Skip the OMK version update check at startup. This prevents the `the OMK repository` latest-version request |
 | `OMK_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |

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

@@ -1,14 +1,14 @@
 {
-  "name": "omk-extension-custom-provider",
-  "version": "0.90.8",
+  "name": "omk-extension-custom-provider-anthropic",
+  "version": "0.91.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "omk-extension-custom-provider",
-      "version": "0.90.8",
+      "name": "omk-extension-custom-provider-anthropic",
+      "version": "0.91.0",
       "dependencies": {
-        "@anthropic-ai/sdk": "^0.52.0"
+        "@anthropic-ai/sdk": "0.52.0"
       }
     },
     "node_modules/@anthropic-ai/sdk": {

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

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "0.90.8",
+	"version": "0.91.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.90.8",
+	"version": "0.91.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.90.8",
+	"version": "0.91.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-gondolin",
-			"version": "0.90.8",
+			"version": "0.91.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.90.8",
+	"version": "0.91.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.90.8",
+	"version": "0.91.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-sandbox",
-			"version": "0.90.8",
+			"version": "0.91.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.90.8",
+	"version": "0.91.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",