open-multi-agent-kit 0.98.3 → 0.98.5

package/docs/sdk.md

@@ -147,6 +147,208 @@ interface AgentSession {
 
 Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
 
+### Model dispatch policy
+
+Pass `modelContract` to `createAgentSession()` or `createAgentSessionFromServices()`
+to restrict logical model/provider, reasoning, and output-limit choices. The SDK
+stream also checks first-party summaries using `session.agent.streamFn`.
+The CLI equivalent is `--model-contract <file>`. This is opt-in dispatch control,
+not final-wire or billing attestation. See [Model dispatch contracts](model-contract.md)
+for the JSON shape, events, hook restrictions, and uncovered paths.
+
+### Isolated command runs (SDK, opt-in)
+
+`planVerifiedRun()` and `createRunCoordinator()` provide three experimental profiles:
+`linux-command-v1` executes an approved command, `linux-scripted-agent-v1` drives
+approved steps through the real `AgentSession` and the offline Faux adapter, and
+`linux-command-dag-v1` executes a bounded command DAG serially.
+Commands run in private sandboxes; native EvidenceReceipt v3 cores and a supervisor
+attestation bind the checked candidate before artifact retrieval.
+
+The high-level factory injects the closed session runtime through a host-only port;
+low-level `new RunCoordinator(root)` needs no session port for command execution or
+candidate-only recovery. `inspectRecovery(runId)` is read-only; `resume(command,
+approval)` acquires a new generation and rechecks the exact frozen candidate under
+the original boot-relative deadline. It never restarts the writer or model and
+refuses missing process identity, stale refs, unavailable clocks and expired budget.
+
+`inspectWriterRecovery(runId)` and `restartWriter(command, approval)` separately
+restart an interrupted local writer from its durable input checkpoint. They preserve
+spent requests and the original work deadline, use a fresh private directory, and
+never continue from partial output or a changed original workspace.
+
+For the command DAG, `inspectTaskRecovery(runId)` returns read-only readiness and
+`retryTasks(command, approval)` acquires a new generation for selected failed or
+interrupted tasks. `RunTaskRetryCommand` pins `baseDigest` and `taskIds` alongside the
+contract/revision/generation fields; an empty selection only continues pending work.
+Successful checkpoints are revalidated against their complete ancestor inputs before
+adoption. Final integration verification always uses fresh native receipts. The
+profile supports at most 16 tasks and two preapproved commands per task; it does not
+synthesize a repair or accept overlapping task write scopes. `RunProjection.tasks`
+exposes task attempts and checkpoint digests; a blocked DAG returns `execution: "paused"`.
+All recovery actions share the generation cap, original budget and command-id fence.
+
+This does not enable live-model task generation, opaque remote replay, parallel
+frontier scheduling, plan amendment, or host application. See [Verified Run](verified-run.md) for contracts and trust boundaries.
+
+### Shared run budgets (SDK, opt-in)
+
+Pass `runBudget` to `session.prompt()` to bound one prompt's logical model
+requests. The budget starts before prompt preflight and stays shared across
+provider retries, continuations, and first-party summaries using that session's
+`agent.streamFn` while the prompt is active.
+
+```typescript
+import { RunBudgetExceededError } from "open-multi-agent-kit";
+
+try {
+  await session.prompt("Implement the selected change and run its focused tests", {
+    runBudget: { timeoutMs: 120_000, maxRequests: 12, maxConcurrentRequests: 2 },
+  });
+} catch (error) {
+  if (!(error instanceof RunBudgetExceededError)) throw error;
+  console.log(error.code); // deadline, requests, concurrency, or closed
+}
+console.log(session.getRunBudgetSnapshot());
+```
+
+| Limit | Meaning |
+| --- | --- |
+| `timeoutMs` | One monotonic work deadline, including preflight and retry waiting; at most 2,147,483,647 ms. |
+| `maxRequests` | Total entries into the scoped stream-dispatch boundary. Failed requests also consume this allowance. |
+| `maxConcurrentRequests` | Outstanding logical streams. Returning a stream object does not release its reservation; terminal metadata does. |
+
+Limits must be non-negative safe integers. Zero denies the corresponding
+admission; omitted limits are unbounded. Supply at least one limit. Unknown
+fields, accessors, inherited fields, and malformed values raise
+`RunBudgetPolicyError`. The policy is copied before asynchronous work, so later
+caller mutation cannot enlarge it.
+
+Exhaustion latches, requests cancellation through the existing provider, tool,
+retry, compaction, and branch-summary paths, and rejects with
+`RunBudgetExceededError`. Termination records use `kind: "budget_exhausted"` and
+`causeCode: "budget.deadline"`, `"budget.requests"`, or `"budget.concurrency"`;
+these are not automatic-retry or model-failover instructions. A separate prompt
+cannot borrow or reset an active budget. Preflight ownership also applies when
+the first prompt has no budget, preventing a competing budgeted prompt from
+changing its stream or aborting it. Explicit steering/follow-up messages join the
+running prompt without receiving a new allowance; registered commands retain
+their existing streaming path.
+
+`getRunBudgetSnapshot()` returns the active or most recent budget's immutable
+limits, started-request count, outstanding-stream count, remaining time, closed
+state, and optional exhaustion reason. It returns `undefined` when no budget has
+been used. Missing terminal metadata retains an outstanding reservation; an
+abort request alone does not release it. Outstanding streams block admission of
+a new bounded or unbounded prompt even after the scope closes. Once terminal
+metadata arrives, that reservation drains and new work can proceed. The original
+stream and core credential resolver are restored unless another owner replaced
+them. Captured old wrappers reject further dispatch after closure.
+
+The core credential resolver and compaction-auth preflight now check admission
+before consulting credentials. This is a pre-check, not a reservation: logical
+request counts are still reserved at stream dispatch. Cancellation or expiry
+during credential lookup is checked again before continuing.
+
+**Limits of this slice:** request counts are not HTTP-attempt or billing counts.
+The wrapper requests `maxRetries: 0` to disable adapter retries, but cannot attest
+that every provider honors it. Independent context/auth hooks, remote work, detached
+children, direct `omk-ai` calls, and replacement of the stream wrapper remain
+outside that dispatch-count guarantee. In-process plugins are trusted. Deadline
+cancellation is cooperative: synchronous blocking code, an uncooperative hook,
+or a remote service can outlive the signal. This is not an OS kill/join boundary
+or a guaranteed wall-clock return time. There is no financial/output-token cap,
+verification/cleanup reserve, persisted budget recovery, CLI flag, or global
+setting in this slice. Restart does not reconstruct an in-flight budget.
+
+Regression tests: `test/run-budget.test.ts`, `test/run-budget-scope.test.ts`,
+`test/suite/agent-session-run-budget.test.ts`, and
+`test/suite/agent-session-admission.test.ts`.
+
+### Prompt settlement
+
+**Working-tree hardening:** a timeout/abort result is not proof that the tool stopped.
+
+| Signal | Meaning |
+| --- | --- |
+| `tool_execution_end` | A result was committed; a timeout/abort can win before the tool stops. |
+| `session_termination` | One agent-loop attempt ended; retries may follow. |
+| `prompt()` resolves | The outer loop returned. A timed-out or aborted tool may remain active. |
+| `prompt_settled` | The prompt producer closed, registered local tool promises ended, and streaming/queues no longer block settlement. |
+
+The session retains a per-prompt owner across retries and continuations. Tools
+selected through its registry receive unique runtime tokens, independent of
+model tool-call IDs. Actual promise completion removes only its own token;
+duplicate flushes and an earlier run's finish callback cannot settle another run.
+
+After timeout or cancellation, the session withholds `prompt_settled` and its
+resource-lease release while registered tool promises remain active. Another
+ordinary prompt is rejected before model dispatch. Clearing a leftover queue
+rechecks settlement, so a drained run can release its owner and accept new work.
+Default late-settlement handling triggers a fresh settlement check after the workspace-mutation audit.
+With explicit `lateSettlement: "ignore"`, actual completion triggers that check
+without inventing an audit. Durations and the core tool-timeout teardown window
+use a monotonic clock; wall-clock adjustments cannot extend or shorten that window.
+
+User cancellation during tool execution remains an abort even when the last
+assistant message says `toolUse`. Timeout text reports cancellation requested,
+not process termination confirmed. Late success never replaces the failed or
+aborted result. **`prompt_settled` is a UX signal, not semantic verification.**
+
+This safeguard is session-local. It does not persist ownership, join detached
+work, prove remote cancellation, or fence writers across replacement/disposal,
+restart, or workspace reuse. Direct `Agent` calls, replacing
+`session.agent.state.tools`, independent interactive bash, and plugin-created
+background work are not automatically enrolled. In-process plugins remain trusted.
+
+#### Independent bash commands
+
+`executeBash()` owns one cancellation controller per invocation, including permit
+waiting. Concurrent commands never share or overwrite that controller. Completion
+removes only its own entry, so `isBashRunning` remains true while another command
+is active. `abortBash()` signals every owned command and does not declare them
+terminated. Cancellation observed after permit admission prevents backend dispatch.
+
+These commands remain independent of prompt settlement and its model-request
+budget. Backend promises still own actual termination; detached processes and
+remote completion are not inferred from cancellation. Regression:
+`test/suite/agent-session-bash-ownership.test.ts`.
+
+#### Shared permits and internal lanes
+
+`WorkloadPermitPool` captures request identity, weight, and signal before waiting;
+caller mutation cannot alter a later release. Per-permit release latches replace
+the unbounded retired-ID set. Removing a cancelled/expired FIFO head immediately
+reconsiders the next request. Explicit pool `capacity: 0` denies grants and
+`maxQueue: 0` denies waiting; lowering capacity never revokes held permits.
+
+Internal `launchSubagentLanes()` preserves computed zero width as
+`admission-deferred`, observes run-specific heavy caps, defers marked heavy lanes
+under `defer-heavy`, and rechecks abort after acquiring a permit. It forwards the
+parent signal and awaits the callback before release. Parent cancellation reports
+`cancelled`; failures use a fixed diagnostic rather than arbitrary child error
+text. The existing configured lane setting `0 = unlimited` remains distinct from
+computed admission zero. `heavyLaneIds` is a trusted caller classification.
+This does not activate a live task DAG or a detached-process join adapter.
+
+Regression checks from the repository root:
+
+```bash
+LIVE_E2E=0 node node_modules/vitest/dist/cli.js --run \
+  packages/coding-agent/test/session-prompt-lifecycle.test.ts \
+  packages/coding-agent/test/suite/agent-session-owned-settlement.test.ts \
+  packages/coding-agent/test/suite/agent-session-child-settlement.test.ts \
+  packages/coding-agent/test/workload-permit-pool-admission.test.ts \
+  packages/coding-agent/test/subagent-lane-ownership.test.ts
+npm run check
+```
+
+The child test observes a local Node process closing before settlement and lease
+restoration. These are not paid-provider, crash-recovery, or coding-quality benchmarks.
+Shared logical request budgets are available through the opt-in SDK path above.
+Verification/cleanup reserves, protected candidate/verifier binding, effect recovery,
+and approval-bound application remain prerequisites for a durable verified run.
+
 ### AgentSession policy seams
 
 The package root exports focused policy helpers for custom runtimes and tests:
@@ -261,7 +463,7 @@ interface PromptOptions {
 }
 ```
 
-`activeSkillNames` marks additional discovered skills active for this turn; `activeSkillSource` labels their provenance. They merge with global `defaultActiveSkills`, prioritize matching inventory entries, and do not expand authorization or inline full skill instructions.
+`activeSkillNames` marks additional discovered skills active for this turn; `activeSkillSource` labels their provenance. They merge with global `defaultActiveSkills`, prioritize matching inventory entries, and do not expand authorization or inline full skill instructions. When the active provider is native `xai` and `OMK_GROK_HARNESS` is enabled, each non-queued `AgentSession.prompt()` request also derives up to three request-scoped matches from the live skill inventory after ordinary prompt-template expansion. Explicit-only skills are excluded from automatic selection, while explicit SDK/settings/bang selections remain authoritative additions. Queued steering and follow-up messages reuse the active run's system prompt and therefore do not perform another automatic skill-selection pass.
 
 `preflightResult` is called once per `prompt()` invocation:
 
@@ -1307,7 +1509,7 @@ const decision = await chooseWithAdvisoryJudge({
 });
 ```
 
-The sidecar makes no call when zero or one candidate passes. For multiple passing candidates it sends only bounded, forced-redacted material through a tool-free request and requires a complete 0–4 score matrix. Invalid output or provider failure returns `status: "fallback"` with the deterministic first candidate and a sanitized reason. It never persists model prose. Re-run fresh deterministic gates after applying the selected result.
+The sidecar makes no call when zero or one candidate passes. For multiple passing candidates it sends only bounded, forced-redacted material through a tool-free request and requires a complete 0–4 score matrix. Invalid output or provider failure returns `status: "fallback"` with the deterministic first eligible candidate and a sanitized reason. It never persists model prose. Re-run fresh deterministic gates after applying the selected result.
 
 **Since v0.98.3:** the first-party `createModelAdvisoryJudge()` adapter requires an explicit normal `stop`; valid JSON from truncated, aborted or missing completion metadata cannot supply scores. The chooser checks cancellation before and after judge work. Top-score ties retain the caller's deterministic rank but report `judge-tied` / `deterministic`. Additive `diagnostics` preserve submitted/eligible/excluded counts and distinguish unmeasured comparisons from scored ties. See [Advisory selection integrity](advisory-selection.md).
 

package/docs/sessions.md

@@ -34,7 +34,7 @@ For the JSONL file format and SessionManager API, see [Session Format](session-f
 
 Each provider attempt writes its own `run_started`/`run_finished` journal pair and emits `session_termination`. A retryable termination is attempt-level when `auto_retry_start` follows it; consumers should not treat that event alone as the end of the outer `prompt()` call.
 
-If a retry or failover succeeds, the later attempt emits `completed` and becomes `session.lastTermination`. If retry budget is exhausted, the last provider failure remains final. Quota and billing-cycle exhaustion are classified as `provider.rate_limit` and can switch through the configured provider-resilience chain before retrying. See [Provider Resilience](provider-resilience.md).
+If a retry or failover succeeds, the later attempt emits `completed` and becomes `session.lastTermination`. If retry budget is exhausted, the last provider failure remains final. Quota, billing-cycle exhaustion, and provider-capacity waits (`at capacity`, Anthropic `overloaded_error`) are classified as `provider.rate_limit` and can switch through the configured provider-resilience chain before retrying. A Codex ChatGPT-account unsupported-model 400 or Anthropic `claude_code_version_too_old` is `configuration.invalid`: `/new session` will not grant access; switch with `/model`. See [Provider Resilience](provider-resilience.md).
 
 ## Session Commands
 

package/docs/settings.md

@@ -139,15 +139,31 @@ 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; representation entries persist per workspace by default while plan entries stay in session memory |
+| `contextBudget.openwiki` | boolean | `false` | Offer the workspace's `openwiki/` pages as budget candidates, ranked against each turn's query. Requires `contextBudget.enabled` |
 
 ```json
 {
-  "contextBudget": { "enabled": true }
+  "contextBudget": { "enabled": true, "openwiki": 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. 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.
 
+#### Repository wiki retrieval
+
+`contextBudget.openwiki` lets a generated [`openwiki/`](https://github.com/dmae97/omk/blob/main/README.md#repository-understanding) corpus take part in prompt budgeting. The corpus is loaded once per session and never enters the prompt directly: each page becomes a low-priority `evidence` candidate that the governor ranks against the turn's query, so pages compete for leftover budget and can never displace instructions or skills.
+
+A corpus is admitted only on the same terms `scripts/check-openwiki.mjs` applies, because generated prose about a repository is exactly the kind of content that is expensive to be wrong about:
+
+| Generator state | Result |
+|---|---|
+| `complete`, generated at the current `HEAD` | Page titles, declared symbols, and bounded page text are all offered |
+| `complete`, but `HEAD` has moved | Titles and symbols only. Page text is withheld, and entries are marked stale |
+| `interrupted`, with `openwiki/.manual-review.json` bound to the exact corpus digest | Treated as complete |
+| `interrupted` without that review, unknown status, missing `gitHead`, or unreadable state | Refused; no page reaches the prompt |
+
+A corpus over 200 pages or 4 MiB is refused rather than truncated, so the runtime and the gate always agree on the digest of the same directory. Symlinked pages are skipped. Source code and tests stay authoritative over every page; the pages are leads to verify, not claims to repeat.
+
 ### Agent Tool Execution
 
 | Setting | Type | Default | Description |

package/docs/skills.md

@@ -93,6 +93,8 @@ OMK adds a compact active-skills marker containing names and, for explicit-only
 
 This file is an explicit operator choice, so it may activate a skill whose frontmatter otherwise requires direct invocation. Active skills do not expand authorization and apply only when relevant. Keep the list focused because overlapping language or workflow instructions can conflict.
 
+When the native `xai` Grok harness is enabled, OMK may additionally mark up to three matching, non-explicit-only skills active for a non-queued top-level `prompt()` request. It scores the live discovered descriptions and does not persist those automatic selections into the next turn; operator and bang selections still merge normally.
+
 ## Skill Commands
 
 Skills register as `/skill:name` commands and interactive `!` launcher entries:

package/docs/tb21-audit.md

@@ -0,0 +1,131 @@
+# TB 2.1 오프라인 결과 감사
+
+`scripts/tb21-audit.mjs`는 명시한 두 Harbor job의 **기록된 결과**를 검증한다.
+모델·Harbor를 실행하지 않으며 입력 파일이나 기존 요약을 수정하지 않는다.
+저장소 checkout과 Node.js 22.19 이상이 필요하다. 공개 npm CLI의 하위 명령은 아니다.
+
+## 사용
+
+```bash
+node scripts/tb21-audit.mjs \
+  --manifest /path/to/evidence/manifest.json \
+  --expect-manifest-sha256 <사전에-고정한-64자리-SHA256>
+```
+
+두 옵션 모두 필수다. 알 수 없는 옵션·중복 옵션·위치 인수는 거부한다.
+manifest의 **원본 바이트**를 해싱하므로 줄바꿈이나 공백 변경도 digest를 바꾼다.
+불일치를 없애려고 변경된 manifest의 해시를 자동으로 다시 승인하지 않는다.
+해시 고정은 내용 식별 수단이지 서명, 실행 승인, 사전 등록의 증명이 아니다.
+
+성공하면 JSON을 stdout에 출력한다. 실패하면 stdout은 비우고 stderr에
+`{"status":"incomplete","code":"missing_cost"}` 같은 진단만 출력한다.
+경로·JSON 파서의 원문·provider 오류 메시지는 진단에 복사하지 않는다.
+
+| 종료 코드 | 의미 |
+| --- | --- |
+| 0 | 모든 입력 결과가 아래 계약을 충족함. 실제 전송·비교 조건 검증은 아님 |
+| 1 | 파일·digest·결과 무결성 오류 또는 예기치 않은 내부 오류 |
+| 2 | 옵션 오류 또는 manifest 스키마 오류 |
+
+## Manifest v1
+
+다음은 **합성 예시**다. 반복 문자 해시를 실제 평가의 provenance로 쓰지 않는다.
+
+```json
+{
+  "schemaVersion": "omk-tb21-manifest-1",
+  "runId": "example-run",
+  "datasetRevision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "conditionsSha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+  "tasks": [
+    {
+      "id": "example-task",
+      "checksum": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    }
+  ],
+  "arms": {
+    "A": {
+      "job": "arm-a",
+      "modelName": "gateway/model-one",
+      "harnessSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "adapterSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    },
+    "B": {
+      "job": "arm-b",
+      "modelName": "compatible/model-one",
+      "harnessSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "adapterSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    }
+  }
+}
+```
+
+- `tasks`는 1~1000개이며 중복 ID를 허용하지 않는다. ID는 영문·숫자로 시작하는
+  128자 이하의 영문·숫자·`.`·`_`·`-` 문자열이다.
+- `datasetRevision`은 전체 40자리 소문자 Git SHA, 나머지 해시는 64자리 소문자 SHA-256이다.
+- `job`은 manifest 디렉터리 아래의 상대 경로다. 절대 경로, `..`, 역슬래시,
+  빈 경로 조각, 동일한 두 job 경로와 심볼릭 링크를 거부한다.
+- `modelName`은 각 arm의 Harbor `config.agent.model_name`과 정확히 비교한다.
+  호환 공급자 이름이 다를 수 있으므로 두 라벨의 동일성이 실제 모델 동일성을 뜻하지 않는다.
+- manifest의 모든 객체는 지정된 필드만 허용한다. 자격증명·환경 값·프롬프트를 넣지 않는다.
+- `conditionsSha256`, `harnessSha256`, `adapterSha256`, `datasetRevision`은 **선언값**이다.
+  이 도구가 조건 파일·실행 바이너리·컨테이너·데이터셋 저장소를 열어 대조하는 것은 아니다.
+
+## 읽는 파일과 검증 규칙
+
+```text
+manifest.json
+arm-a/
+  trial-a/result.json
+arm-b/
+  trial-b/result.json
+```
+
+각 job의 바로 아래 디렉터리는 모두 trial로 간주한다. 별도 산출물 디렉터리는
+job 바깥에 둔다. job 루트의 일반 파일(예: `config.json`, 전체 `result.json`)은
+개별 trial 집계에 사용하지 않는다. 최신 job 검색이나 시간창 기반 원장 귀속은 없다.
+
+각 task는 각 arm에 정확히 한 번 있어야 한다. v1은 재시도·다회 반복 집계를 지원하지
+않으므로 추가 attempt를 거부한다. 마지막 결과로 덮어쓰거나 가장 좋은 시행을 고르지 않는다.
+`trial_name`은 디렉터리 이름과 일치해야 하며 `id`는 두 arm 전체에서 유일해야 한다.
+Harbor가 절대 task 경로를 기록한 경우 마지막 경로 조각을 manifest ID와 비교하고,
+`task_checksum`도 고정된 task checksum과 대조한다.
+
+`verifier_result.rewards.reward`는 숫자 0 또는 1이어야 한다. 값이 없거나 null이면
+명시적인 `exception_info.exception_type`이 있을 때만 미해결로 집계한다.
+성공 보상 1과 예외가 함께 있으면 모순으로 거부한다. `exception_info` 필드 자체가
+없으면 예외 여부를 추측하지 않는다. timeout도 분모에 남는다.
+
+`agent_result.cost_usd`는 0 이상의 유한한 숫자여야 한다. 누락·null은 **0이 아니라
+미확인**이며 요약을 거부한다. 합산 overflow도 거부한다. 해결 task가 0개이면
+`costPerSolved`는 null이다. 비용 단가·캐시 할인·실제 청구서 정합성은 별도 확인 대상이다.
+
+manifest는 최대 256 KiB, 개별 결과는 최대 8 MiB까지 읽는다. 파일 읽기는 크기를
+제한하고 일반 파일만 허용한다. 실행이 끝나고 쓰기가 멈춘 자료를 입력해야 한다.
+이 검사는 같은 호스트의 동시 경로 교체를 격리하는 OS sandbox가 아니다.
+
+## 보고서의 주장 범위
+
+출력에는 arm별 task·해결·예외 수, 비용 합계·해결당 비용, 쌍대 성공표와 차이(pp),
+manifest와 결과 파일의 해시가 포함된다. 원본 trial ID·task 절대 경로·kwargs·예외
+메시지는 내보내지 않는다. 출력의 run/task ID는 manifest에서 승인한 식별자를 사용한다.
+
+항상 `modelVerification: "configuration-only"`, `costSource: "harbor-agent-result"`를
+표시한다. 설정이 같다는 사실로 실제 모든 provider 전송이 같았다고 추론하지 않는다.
+Gateway 원장으로만 비용을 알 수 있는 과거 trial은 비용을 지어내지 않고 `missing_cost`로
+거부한다. 신뢰할 수 있는 request ID별 원장 결합은 로드맵 R3의 후속 작업이다.
+
+이 도구는 실제 실행을 증명하는 attestator나 통계적 우열 검정기가 아니다. 공개하기 전
+식별자·가격·자료 보유 권한을 검토하고 [비교 계약](metrics.md)을 적용한다.
+
+## 검사
+
+저장소 루트에서 공급자·다운로드 없이 실행한다.
+
+```bash
+node --test --test-concurrency=1 scripts/test/tb21-audit.test.mjs scripts/test/tb21-audit-inputs.test.mjs
+node node_modules/typescript/bin/tsc --noEmit --allowJs --checkJs --strict --target ES2022 --module NodeNext --skipLibCheck --types node scripts/tb21-audit.mjs scripts/lib/tb21-input.mjs scripts/lib/tb21-audit.mjs
+```
+
+프로젝트 Biome 설정은 기본적으로 `.mjs`를 포함하지 않는다. 실제 파일이 검사됐는지
+확인하며, 빈 검사 결과를 통과 증거로 쓰지 않는다.

package/docs/terminal-setup.md

@@ -94,6 +94,26 @@ Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward
 
 If you already have an `actions` array, add the objects to it. If the old fullscreen behavior persists, fully close and reopen Windows Terminal.
 
+### Windows screenshots into a WSL prompt
+
+Capture with **Win+Shift+S**, return to OMK, and press **Alt+V**. The image is added
+to the prompt attachment strip; submit the prompt when ready. **Ctrl+V** also works
+when the terminal forwards that key to OMK. Windows Terminal normally handles Ctrl+V
+itself and pastes text, so an image-only clipboard may appear to do nothing.
+
+To deliberately forward Ctrl+V instead, add this action to Windows Terminal's
+existing settings (this changes Ctrl+V behavior for that terminal):
+
+```json
+{ "command": { "action": "sendInput", "input": "\u0016" }, "keys": "ctrl+v" }
+```
+
+Use the terminal's normal text-paste shortcut, commonly Ctrl+Shift+V, for clipboard
+text after this opt-in. OMK does not change terminal settings automatically.
+See [Windows setup](windows.md#windows-screenshot-paste) for clipboard prerequisites
+and error behavior. Inline image rendering is terminal-dependent; an attachment
+chip does not require the terminal to display image pixels.
+
 ## xfce4-terminal, terminator
 
 These terminals have limited escape sequence support. Modified Enter keys like `Ctrl+Enter` and `Shift+Enter` cannot be distinguished from plain `Enter`, preventing custom keybindings such as `submit: ["ctrl+enter"]` from working.

package/docs/usage.md

@@ -46,6 +46,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/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 |
+| `/debug [save]` | Preview runtime diagnostics; explicitly save a metadata-only local report |
 | `/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 |
@@ -61,6 +62,59 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/star` | Open the OMK GitHub repository |
 | `/quit` | Quit omk |
 
+### Diagnostics and failure details
+
+`/debug` previews runtime identity, terminal state and the latest typed outcome
+without saving or contacting a provider. The existing TUI debug shortcut opens
+the same preview instead of dumping the transcript.
+
+`/debug save` explicitly creates a new `omk-debug-*/diagnostics.json` under the OS
+temporary directory and prints its path. It does not upload or overwrite a report.
+POSIX directory/file permissions are `0700`/`0600`; Windows access follows the
+temporary directory's ACLs. Delete that directory when it is no longer needed.
+
+The version-1 JSON report contains approved metadata fields only. It excludes
+messages, prompts, images, tool output, rendered screen text, raw errors,
+configuration, environment values, credentials, local paths, session/run IDs and
+provider/model/tool names. Launch and UI module paths are visible locally, not
+saved. Metadata such as timestamps and message counts can still describe your
+workload; review a report before sharing it.
+
+There is no raw-transcript option in this command. Old `omk-debug.log` files are
+not deleted or rewritten and may contain private transcripts. Explicit raw ANSI
+capture via `OMK_TUI_WRITE_LOG` remains a separate, sensitive debugging facility;
+see [TUI components](tui.md#debug-logging).
+
+**Runtime identity:** The UI entry file's SHA-256 is observed at module initialization
+and compared with the same file during inspection. Missing, oversized, virtual or
+unreadable files are `unavailable`, not healthy. This is a single-file observation,
+not a fingerprint of all dependencies or proof of the exact executed bytes.
+An unchanged entry does not establish that a build includes current source changes.
+The package has no embedded build-to-commit binding, so build revision is reported
+as unavailable rather than inferred from checkout `HEAD`.
+
+`/reload` refreshes resources, not core JavaScript modules. Its last completion time
+is shown separately. Core changes need an authorized build where applicable and a
+restarted process. Source-mode QA does not update an installed launcher.
+
+**Failure cards:** Cause, impact and next action appear before technical fields.
+Ctrl+O (or the configured `app.tools.expand` binding) expands kind/phase/cause code,
+observation source, retry flags, run ID, timestamp and route. Credential-shaped
+values are masked even when input redaction is disabled; terminal controls are
+removed. These local details are not the saved report.
+
+Cards never retry, repair or approve effects. Retryability and automatic-retry
+safety stay separate; possible/confirmed side effects require inspection before
+repeating work. Duplicate delivery of the same termination is coalesced; separate
+failed attempts remain visible. Completed runs stay quiet, and compaction
+cancellation retains its concise status. Journal, print, JSON and RPC termination
+contracts are unchanged.
+
+Focused regression tests: `test/interactive-mode-diagnostics.test.ts` and
+`test/tui-diagnostics.test.ts` in `packages/coding-agent`. These cover the real
+command adapter, sensitive-field exclusion, private report creation, runtime file
+changes/unavailability, forced masking, narrow-terminal wrapping and theme changes.
+
 ### Durable Goals
 
 Use `/goal <objective>` to create or update the durable goal for the current working directory; `/goal` without arguments shows its status. See [Run Protocol](run-protocol.md#durable-goal-lifecycle) for the authoritative persistence, round-limit, continuation, and SDK lifecycle rules.
@@ -73,13 +127,35 @@ Use `/goal <objective>` to create or update the durable goal for the current wor
 | --- | --- | --- |
 | Identical-loop guard | Warns from the third consecutive identical tool call and blocks the sixth | `OMK_IDENTICAL_LOOP=0` |
 | Tool-pair repair | Removes unmatched tool-use and tool-result blocks from outbound context | `OMK_TOOL_PAIR_REPAIR=0` |
-| Model prompt presets | Adds model-specific execution guidance for supported Claude, Kimi, GLM, and Grok models | `OMK_PROMPT_PRESET=0` |
+| Model prompt presets | Adds model-specific execution guidance for GPT-6 Astra and supported Claude, Kimi, GLM, and Grok models | `OMK_PROMPT_PRESET=0` |
 | Goal controller | Registers `/goal` and continues active goals within their round limit | `OMK_GOAL_CONTROLLER=0` |
 
 These built-ins remain active with `--no-extensions`. A custom `ResourceLoader` owns its own extension set and does not receive them automatically.
 
 Claude models use a clean prompt context by default: OMK keeps tools, skills, and the Claude preset but omits discovered `AGENTS.md` and `CLAUDE.md` files. This avoids provider false positives caused by unrelated instruction text. Set `OMK_CLAUDE_CONTEXT_FILES=1` to restore those files for Claude.
 
+### GPT-6 Astra
+
+When the resolved model ID is exactly `gpt-6-astra`, the built-in preset appends
+`<model_preset id="gpt-6-astra">` at `before_agent_start`. Provider-qualified IDs
+such as `openai/gpt-6-astra` and `openrouter/openai/gpt-6-astra` match the same
+model. Similar names, dated variants, and other GPT models do not select this
+preset. Select the configured model through `/model`; the preset does not add
+model availability to an account.
+
+The Astra guidance encourages completing authorized work, asking only material
+clarifying questions, explaining any skill instruction that blocks progress,
+writing concise prose, delegating independent work when permitted, and using
+focused verification without unnecessary repeat runs. Explicit user requests
+outrank advisory skill guidance within higher-priority instructions and runtime
+permissions. Pending tool results must be accounted for before claiming completion.
+
+Each new request selects guidance from its current model and fresh base prompt;
+switching models does not carry the Astra preset into the next request.
+`OMK_PROMPT_PRESET=0` disables the existing model-preset built-in, including Astra.
+API parameters and transport capabilities remain controlled by the provider/runtime
+configuration.
+
 ## Automatic Thinking Level Routing
 
 `/think <level>` sets the thinking level manually. Manual levels always win: choosing a concrete level leaves auto routing, so no auto router runs.