open-multi-agent-kit 0.90.7 → 0.90.9

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

@@ -1,6 +1,6 @@
 # Settings
 
-OMK uses JSON settings files with project settings overriding global settings.
+OMK uses JSON settings files with project settings overriding global settings, except settings explicitly marked global-only.
 
 | Location | Scope |
 |----------|-------|
@@ -73,19 +73,81 @@ 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
+  }
+}
+```
+
+### Context Budget
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `contextBudget.enabled` | boolean | `false` | Globally enable prompt resource budgeting and its in-memory, session-scoped plan/representation cache |
+
+```json
+{
+  "contextBudget": { "enabled": true }
+}
+```
+
+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 |
@@ -245,6 +307,7 @@ See [packages.md](packages.md) for package management details.
     "reserveTokens": 16384,
     "keepRecentTokens": 20000
   },
+  "contextBudget": { "enabled": true },
   "retry": {
     "enabled": true,
     "maxRetries": 3
@@ -259,7 +322,7 @@ See [packages.md](packages.md) for package management details.
 
 ## Project Overrides
 
-Project settings (`.omk/settings.json`) override global settings. Nested objects are merged:
+Project settings (`.omk/settings.json`) override global settings. Nested objects are merged. `contextBudget` is the exception: it is read from global settings only.
 
 ```json
 // ~/.omk/agent/settings.json (global)

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/correctness-wall/README.md

@@ -18,7 +18,7 @@ cp -r examples/extensions/correctness-wall ~/.omk/agent/extensions/correctness-w
 
 ## Claim boundaries
 
-- **In scope**: unified-diff preview for pending `edit`/`write`, fast policy wall (write scope, flags), optional OA adjudication when `correctness_wall_evaluate` is called with `runIds`, `previewOnly: false`, and an OA fixture file (env or tool param).
+- **In scope**: unified-diff preview for pending `edit`/`write`, fast policy wall (write scope, flags), optional OA adjudication when `correctness_wall_evaluate` is called with `runIds`, `previewOnly: false`, and either an OA fixture file or an explicitly enabled host-injected MCP transport.
 - **Out of scope**: Replacing core hooks, modifying `packages/adaptorch-wpl` from this lane, or adding npm workspace dependencies. The extension only **imports** `evaluateCorrectnessWall` and `AdaptOrchClient` from `../../../../adaptorch-wpl/src/index.ts`.
 
 ## Environment variables
@@ -29,12 +29,12 @@ cp -r examples/extensions/correctness-wall ~/.omk/agent/extensions/correctness-w
 | `OMK_WALL_SCOPE` | *(empty)* | Comma-separated glob/path prefixes allowed in the diff. Empty means scope checks do not approve any path (out-of-scope diffs can trigger blocking flags when paths are present). |
 | `OMK_WALL_OVERRIDE` | unset | When `1` / `true` / `yes`, `soft` mode does not block `BLOCKED` verdicts (human override). |
 | `OMK_WALL_REPAIR_BUDGET` | `1` | Capped regenerate budget: max **blocked attempts** per packet (keyed by `packetId` or SHA-256 of `kind` + sorted `OMK_WALL_SCOPE`) before repair hints are treated as exhausted. Also caps hint string count in UI/JSON. Persisted in `.omk/wall-cache/repair-budget.json`. Hints only — no auto-regenerate. |
-| `OMK_WALL_RUN_IDS` | *(empty)* | Comma-separated AdaptOrch run ids. On `edit`/`write` hooks, when non-empty **and** `OMK_WALL_OA_FIXTURE_PATH` (or per-tool `adjudicationFixturePath`) is set, evaluation uses `previewOnly: false` and OA adjudication via `resolveOaClientForEvaluation`. Otherwise hooks stay preview-only. |
-| `OMK_WALL_OA_FIXTURE_PATH` | unset | Path to OA adjudication fixture JSON. Used when `correctness_wall_evaluate` runs with `previewOnly: false` and non-empty `runIds`, and on edit/write hooks when combined with `OMK_WALL_RUN_IDS`. Overridden per call by `adjudicationFixturePath`. |
+| `OMK_WALL_RUN_IDS` | *(empty)* | Comma-separated AdaptOrch run ids. On `edit`/`write` hooks, non-empty IDs enable OA only with either `OMK_WALL_OA_FIXTURE_PATH` or explicit `OMK_WALL_OA_TRANSPORT=mcp`/`live` plus a bound host `callMcpTool`; otherwise hooks stay preview-only. An unbound MCP facade falls back to preview-only. |
+| `OMK_WALL_OA_FIXTURE_PATH` | unset | Path to OA adjudication fixture JSON. Used when `correctness_wall_evaluate` runs with `previewOnly: false` and non-empty `runIds`, or as the fixture alternative for edit/write hooks. Overridden per call by `adjudicationFixturePath`. |
 | `OMK_WALL_AUTO_REGENERATE` | unset | When `1` / `true` / `yes`, `correctness_wall_evaluate` JSON may include a `regeneratePacket` (capped hints only; no automatic patch apply). |
 | `OMK_WALL_RECEIPT_SIGNING_SECRET` | unset | When set, verification receipts include `signedReceipt` (HMAC-SHA256 over digest composite). Never log or commit this value. |
 | `OMK_WALL_DEEP_PHASE` | `stub` | `docker` records deep-wall intent; hermetic runner still unavailable (batch-2). |
-| `OMK_WALL_OA_TRANSPORT` | `fixture` | `mcp` or `live` uses session-injected MCP `callTool` via `setWallAdaptOrchCallTool` (see `adjudication-fixture.ts`). Fixture path optional for receipt metadata when using `mcp`. |
+| `OMK_WALL_OA_TRANSPORT` | `fixture` | `mcp` or `live` uses host-injected MCP `callMcpTool` via `setWallAdaptOrchCallTool` (see `adjudication-fixture.ts`). With non-empty `OMK_WALL_RUN_IDS` and a bound handler, this explicitly enables fixtureless read-only OA hook adjudication; it calls only `adaptorch_get_run`, `adaptorch_get_artifacts`, and `adaptorch_get_traces`. An unbound facade falls back to preview-only. |
 
 ## OA adjudication fixture format
 
@@ -98,7 +98,7 @@ Example receipt fragment:
 On each `edit` or `write` `tool_call` hook:
 
 1. Build a unified diff preview from `event.input` (edits or write content).
-2. Call `evaluateCorrectnessWall` with scope from `OMK_WALL_SCOPE`. Default `previewOnly: true`; when `OMK_WALL_RUN_IDS` is non-empty and an OA fixture path is set (`OMK_WALL_OA_FIXTURE_PATH`), hooks use `previewOnly: false`, pass `runIds`, and supply the OA client from `resolveOaClientForEvaluation`.
+2. Call `evaluateCorrectnessWall` with scope from `OMK_WALL_SCOPE`. Default `previewOnly: true`; with non-empty `OMK_WALL_RUN_IDS`, hooks use `previewOnly: false` when either an OA fixture path is set or `OMK_WALL_OA_TRANSPORT=mcp`/`live` reaches a bound host-injected MCP transport. An unbound facade falls back to preview-only. The live hook path performs read-only OA introspection only.
 3. Apply `OMK_PATCH_SAFETY_WALL_MODE` blocking rules; blocked calls return `{ block: true, reason: "<short user message>" }`.
 4. Write a summary snapshot to `.omk/wall-cache/latest.json` (mode, verdict, `wouldBlock`, compact card summary, timestamp — no full diff or secrets).
 5. In `shadow` mode, append one NDJSON line per gated tool call to **`.omk/wall-cache/shadow-telemetry.ndjson`** (`event`, `wall_version`, `mode`, `verdict`, `wouldBlock`, `kind`, `tool`, `previewOnly`, `usedOaFixture`, `timestamp` — no diff or secrets).
@@ -107,5 +107,5 @@ On each `edit` or `write` `tool_call` hook:
 ## Limitations
 
 - Edit preview reads the target file from disk relative to session `cwd`; if the file is missing or paths are wrong, the hook may return `INCONCLUSIVE` (and block in `hard` mode).
-- Hook OA requires both `OMK_WALL_RUN_IDS` and a fixture path; if either is missing, hooks remain preview-only. Explicit `correctness_wall_evaluate` can still pass `runIds`, `previewOnly: false`, and `adjudicationFixturePath` per call.
+- Hook OA requires non-empty `OMK_WALL_RUN_IDS` plus either a fixture path or explicit `OMK_WALL_OA_TRANSPORT=mcp`/`live` with bound host `callMcpTool`; otherwise hooks remain preview-only. An unbound facade also falls back to preview-only. Explicit `correctness_wall_evaluate` can still pass `runIds`, `previewOnly: false`, and `adjudicationFixturePath` per call.
 - Relative imports require loading this extension from the monorepo layout (or an equivalent path to `adaptorch-wpl` and `coding-agent` sources).

package/examples/extensions/correctness-wall/index.ts

@@ -17,6 +17,7 @@ import {
 	buildRegeneratePacket,
 	capRepairHints,
 	evaluateCorrectnessWall,
+	parseOaTransportModeFromEnv,
 	parseRepairBudget,
 	shouldOfferRepair,
 } from "../../../../adaptorch-wpl/src/index.ts";
@@ -105,6 +106,11 @@ function receiptSigningSecret(): string | undefined {
 	return v && v.length > 0 ? v : undefined;
 }
 
+function isUnboundMcpCall(value: unknown): boolean {
+	const message = value instanceof Error ? value.message : typeof value === "string" ? value : "";
+	return /callMcpTool is not bound/i.test(message);
+}
+
 function shortBlockReason(card: VerdictCard): string {
 	if (card.blocked_reasons.length > 0) return card.blocked_reasons[0];
 	if (card.next_actions.length > 0) return card.next_actions[0];
@@ -379,8 +385,10 @@ export default function (omk: ExtensionAPI) {
 		const approvedWriteScope = parseApprovedScope();
 		const runIds = parseRunIdsFromEnv();
 		const adjudicationFixturePath = resolveAdjudicationFixturePath(undefined);
-		const hookOaEnabled = runIds.length > 0 && adjudicationFixturePath !== undefined;
-		const previewOnly = !hookOaEnabled;
+		const hookOaEnabled =
+			runIds.length > 0 &&
+			(adjudicationFixturePath !== undefined || (parseOaTransportModeFromEnv() === "mcp" && omk.isMcpToolBound()));
+		let previewOnly = !hookOaEnabled;
 
 		const input = event.input as EditInput;
 		const preview =
@@ -413,19 +421,37 @@ export default function (omk: ExtensionAPI) {
 			return undefined;
 		}
 
-		const { verdictCard, receipt } = await evaluateDiff({
-			kind,
-			diffText: preview,
-			approvedWriteScope,
-			previewOnly,
-			runIds: hookOaEnabled ? runIds : undefined,
-			adjudicationFixturePath: hookOaEnabled ? adjudicationFixturePath : undefined,
-		});
+		const fixturelessLiveCall =
+			hookOaEnabled && adjudicationFixturePath === undefined && parseOaTransportModeFromEnv() === "mcp";
+		let evaluation: Awaited<ReturnType<typeof evaluateDiff>>;
+		try {
+			evaluation = await evaluateDiff({
+				kind,
+				diffText: preview,
+				approvedWriteScope,
+				previewOnly,
+				runIds: hookOaEnabled ? runIds : undefined,
+				adjudicationFixturePath: hookOaEnabled ? adjudicationFixturePath : undefined,
+			});
+		} catch (error) {
+			if (!fixturelessLiveCall || !isUnboundMcpCall(error)) throw error;
+			previewOnly = true;
+			evaluation = await evaluateDiff({ kind, diffText: preview, approvedWriteScope, previewOnly: true });
+		}
+		if (
+			fixturelessLiveCall &&
+			evaluation.receipt.adjudicationReasonCode === "RUN_FETCH_FAILED" &&
+			evaluation.verdictCard.blocked_reasons.some(isUnboundMcpCall)
+		) {
+			previewOnly = true;
+			evaluation = await evaluateDiff({ kind, diffText: preview, approvedWriteScope, previewOnly: true });
+		}
+		const { verdictCard, receipt } = evaluation;
 
 		await persistToolCallVerdict(ctx, mode, verdictCard, {
 			tool: event.toolName,
 			previewOnly,
-			usedOaFixture: hookOaEnabled,
+			usedOaFixture: adjudicationFixturePath !== undefined,
 			wall_version: receipt.wall_version,
 		});
 

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

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