open-multi-agent-kit 0.97.0 → 0.98.0

package/docs/runtime-algorithms.md

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

package/docs/sdk.md

@@ -565,12 +565,12 @@ The `edit` tool returns `details.diff` for OMK's TUI display and `details.patch`
 
 The `diagnostics` tool runs the project's own checkers and normalizes the result — `tsc --noEmit` for TypeScript, `pyright`/`ruff` for Python, `go vet` for Go, `cargo check` for Rust. Missing checkers or project markers are reported as `skipped` in the tool result instead of failing. Output is capped at 50 diagnostics and cached for 5 s.
 
-With default OMP seams, truncated `read` output does not create a sidecar. With `OMK_OMP_SEAMS=0`, legacy truncation may write the selected window to `<absolute-source-path>.omk-spill.txt`; `ReadToolDetails.fullOutputPath` reports the path when present. A first line that alone exceeds the byte cap is clipped without a sidecar. The exported `spillTruncatedOutput()` helper provides the preview-plus-path contract for custom tools.
+Truncated `read` output may spill the selected window to a randomly named `omk-spill-*` directory under the OS temporary directory; `ReadToolDetails.fullOutputPath` reports the path when present. The directory is owner-only (`0700`) and the spill file is exclusive and owner-readable (`0600`) on POSIX. A first line that alone exceeds the byte cap is clipped without a spill. The exported `spillTruncatedOutput()` helper provides the same preview-plus-path contract for custom tools.
 
 ```typescript
 import { createAgentSession } from "open-multi-agent-kit";
 
-// Enable inspection tools; legacy read mode may create a spill sidecar
+// Enable inspection tools; a long read may create a private temp spill
 const { session } = await createAgentSession({
   tools: ["read", "grep", "find", "ls"],
 });

package/docs/settings.md

@@ -138,7 +138,7 @@ All numeric token reserves must be non-negative safe integers. Ratios must be fi
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `contextBudget.enabled` | boolean | `false` | Globally enable prompt resource budgeting and its in-memory, session-scoped plan/representation cache |
+| `contextBudget.enabled` | boolean | `false` | Globally enable prompt resource budgeting; representation entries persist per workspace by default while plan entries stay in session memory |
 
 ```json
 {
@@ -146,7 +146,7 @@ All numeric token reserves must be non-negative safe integers. Ratios must be fi
 }
 ```
 
-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.
+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. When enabled, content-addressed representation and negative-result entries persist under `.omk/cache/context-budget-v2`; plan entries stay in session memory. Set `OMK_CONTEXT_GOVERNOR_CACHE=memory` to keep every entry in session memory or `OMK_CONTEXT_GOVERNOR_CACHE_DIR` to relocate the representation snapshot.
 
 ### Agent Tool Execution
 
@@ -182,7 +182,7 @@ The DAG preserves source-order result artifacts. `bash`, unknown tools, and exte
 
 ### Resource Governor
 
-The governor probes host capacity (memory, workspace disk, V8 heap, system CPU) and evaluates a resource admission decision, surfaced through `/resource [probe|policy]` in the TUI and `omk doctor resources [--json]` headless. In `observe` mode (default) it records decisions without changing behavior; in `adaptive`/`strict` modes each top-level prompt runs a bounded preflight probe and throttles the effective tool concurrency for that run (never above `agent.maxToolConcurrency`), restoring it when the run settles. Heavy-process caps are enforced at the governed bash boundary; the internal subagent-lane launcher is not wired into live child dispatch. Absent settings keep prior behavior unchanged.
+The governor probes host capacity (memory, workspace disk, V8 heap, system CPU) and evaluates a resource admission decision, surfaced through `/resource [probe|policy]` in the TUI and `omk doctor resources [--json]` headless. `omk doctor resources --report [--json]` aggregates bounded, identifier-free admission counts from local run journals without probing the current host. Only reason-qualified records count toward the 30-record floor; legacy/malformed reason coverage remains diagnostic. The floor is only a sample signal, always requires human review, and never promotes the mode. In `observe` mode (default) it records decisions without changing behavior; in `adaptive`/`strict` modes each top-level prompt runs a bounded preflight probe and throttles the effective tool concurrency for that run (never above `agent.maxToolConcurrency`), restoring it when the run settles. Heavy-process caps are enforced at the governed bash boundary; the internal subagent-lane launcher is not wired into live child dispatch. Absent settings keep prior behavior unchanged.
 
 | Setting | Type | Default | Description |
 | --------- | ------ | --------- | ------------- |
@@ -213,20 +213,21 @@ Validation is explicit and fail-closed: invalid values are reported (in `/resour
 
 ### Completion Sound
 
-Plays a short system sound when a long prompt finally settles (all retries and continuations drained), only in the interactive TUI on a real TTY — never in RPC, JSON, print mode, or CI. Default off. Backends use fixed executables with fixed arguments (macOS `afplay`, Windows/WSL PowerShell system sound, Linux `canberra-gtk-play`/`paplay`/`aplay`), falling back to the terminal bell. Sound failures are diagnostics only and never affect the prompt outcome.
+Plays a short system sound only after the top-level prompt settles: retries, continuations, and tools must be drained first. Current subagent work is awaited inside its tool call, so that tool boundary also covers those children. The settlement contract reserves direct child/shard counters for future live wiring; those paths must connect the counters before activation. Sound is enabled by default only in the interactive TUI on a real TTY—never in RPC, JSON, print mode, or CI. Successful prompts honor `minDurationMs`; failed and aborted prompts notify immediately. Backends use fixed absolute executables and arguments (macOS `afplay`, Windows system PowerShell, Linux `canberra-gtk-play`/`paplay`/`aplay`), an allowlisted environment with no inherited `PATH` or credentials, and the OS temporary directory as cwd. WSL uses terminal BEL because Windows executable mounts have no fixed trusted path. Sound failures are diagnostics only and never affect the prompt outcome.
 
 | Setting | Type | Default | Description |
 | --------- | ------ | --------- | ------------- |
-| `notifications.completionSound.enabled` | boolean | `false` | Master switch; env `OMK_COMPLETION_SOUND` set to `0` or `1` overrides per process |
-| `notifications.completionSound.minDurationMs` | number | `5000` | Only chime for prompts that ran at least this long |
-| `notifications.completionSound.onSuccess` | boolean | `true` | Chime on completed prompts |
-| `notifications.completionSound.onFailure` | boolean | `true` | Chime on failed prompts (user aborts never chime) |
-| `notifications.completionSound.terminalBellFallback` | boolean | `true` | Fall back to the terminal BEL when no sound backend works |
+| `notifications.completionSound.enabled` | boolean | `true` | Master switch; `OMK_COMPLETION_SOUND=0` disables and `=1` enables it for one process |
+| `notifications.completionSound.minDurationMs` | number | `5000` | Minimum duration for successful-completion sounds; failed/aborted outcomes bypass it |
+| `notifications.completionSound.onSuccess` | boolean | `true` | Notify after a completed prompt that meets the duration floor |
+| `notifications.completionSound.onFailure` | boolean | `true` | Notify immediately after a failed terminal outcome |
+| `notifications.completionSound.onAbort` | boolean | `true` | Notify immediately after an aborted/stopped terminal outcome |
+| `notifications.completionSound.terminalBellFallback` | boolean | `true` | Fall back to terminal BEL when no sound backend works |
 
 ```json
 {
   "notifications": {
-    "completionSound": { "enabled": true, "minDurationMs": 10000 }
+    "completionSound": { "minDurationMs": 10000, "onAbort": false }
   }
 }
 ```

package/docs/usage.md

@@ -45,6 +45,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/new` | Start a new session |
 | `/name <name>` | Set session display name |
 | `/session` | Show session file, ID, messages, tokens, and cost |
+| `/resource [probe\|policy]` | Show resource pressure and effective concurrency for this run |
 | `/goal [objective]` | Show or set the durable goal for the current working directory |
 | `/tree` | Jump to any point in the session and continue from there |
 | `/fork` | Create a new session from a previous user message |
@@ -261,6 +262,21 @@ Diagnoses one provider and prints a single sanitized JSON document. Exit codes a
 
 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.
 
+### Resource Doctor
+
+```bash
+omk doctor resources [--json]
+omk doctor resources --report [--json]
+```
+
+The first form probes current host pressure. `--report` does not probe the host;
+it scans at most 500 bounded local resource-observation journals and emits only
+aggregate pressure/action/probe-health counts. It opens bounded regular files
+without following symlinks and never includes paths, prompt or decision IDs,
+digests, a command field, or raw capacity. Only reason-qualified records count
+toward the 30-record floor; the report always requires human false-positive
+review and never promotes `adaptive`.
+
 ### Modes
 
 | Flag | Description |
@@ -311,7 +327,7 @@ cat README.md | omk -p "Summarize this text"
 
 Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
 
-With default OMP seams, a long text `read` returns a bounded window and continuation marker without creating a sidecar. With `OMK_OMP_SEAMS=0`, legacy truncation may write the selected window to `<absolute-source-path>.omk-spill.txt` and report that path. A first line that alone exceeds the byte cap is clipped without a sidecar. An inspection-only tool allowlist is therefore not a strict no-write filesystem boundary in legacy read mode.
+A long text `read` returns a bounded window and continuation marker. Truncation may spill the selected window to a randomly named owner-only directory under the OS temporary directory and report that path; the directory uses mode `0700` and the file `0600` on POSIX. A first line that alone exceeds the byte cap is clipped without a spill. An inspection-only tool allowlist is therefore not a strict no-write filesystem boundary.
 
 ### Resource Options
 
@@ -380,7 +396,7 @@ omk --model sonnet:high "Solve this complex problem"
 # Limit model cycling
 omk --models "claude-*,gpt-4o"
 
-# Inspection-only tool allowlist; legacy read mode may create a spill sidecar
+# Inspection-only tool allowlist; a long read may create a private temp spill
 omk --tools read,grep,find,ls -p "Review the code"
 
 # Disable one extension or built-in tool while keeping the rest available

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

@@ -1,12 +1,12 @@
 {
   "name": "omk-extension-custom-provider-anthropic",
-  "version": "0.97.0",
+  "version": "0.98.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-custom-provider-anthropic",
-      "version": "0.97.0",
+      "version": "0.98.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.97.0",
+	"version": "0.98.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.97.0",
+	"version": "0.98.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.97.0",
+	"version": "0.98.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-gondolin",
-			"version": "0.97.0",
+			"version": "0.98.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.97.0",
+	"version": "0.98.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.97.0",
+	"version": "0.98.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-sandbox",
-			"version": "0.97.0",
+			"version": "0.98.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.97.0",
+	"version": "0.98.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.97.0",
+  "version": "0.98.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-with-deps",
-      "version": "0.97.0",
+      "version": "0.98.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.97.0",
+	"version": "0.98.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",