open-multi-agent-kit 0.98.2 → 0.98.4

package/docs/environment-variables.md

@@ -82,6 +82,8 @@ These variables are read by OMK itself. The four built-in harness flags below ar
 | `OMK_SKIP_VERSION_CHECK` | Disable the latest-version request |
 | `OMK_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
 | `OMK_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
+| `PI_DISABLE_INPUT_REDACTION` | Stop masking credentials on the way to the model and the session. Persistence and report boundaries still mask |
+| `OMK_DISABLE_REDACTION` | Alias for the input-redaction opt-out when `PI_DISABLE_INPUT_REDACTION` is unset. Only `1`/`true`/`yes`/`on` enable it. Forced persistence/report redaction remains active; this does not disable masking everywhere |
 | `OMK_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
 | `OMK_CONTEXT_GOVERNOR` | Context Budget V2 process override: `1` forces it on and `0` forces it off; otherwise the global `contextBudget.enabled` setting applies |
 | `OMK_CONTEXT_GOVERNOR_CACHE` | Set to `memory` to keep representations, negative results, and plans in session memory instead of persisting representations per workspace |

package/docs/grok-harness.md

@@ -68,6 +68,10 @@ Do not select `grok-imagine-image`, `grok-imagine-image-quality`, `grok-imagine-
 
 Use the normal OMK lane grant model: grant the smallest skill and MCP surface that matches the task, and keep media exceptions explicit.
 
+For each non-queued native `xai` request started through `AgentSession.prompt()`, OMK calls `selectGrokHarnessSkills()` against the live discovered skill descriptions after ordinary prompt-template expansion. It merges up to three matches with explicit/settings selections and rebuilds that turn's `<active_skills>` marker.
+
+The pure `selectSkills()` scorer uses the task plus independent camelCase-aware path-to-skill-name signals, weak 0.35 / strong 0.7 thresholds, deterministic input-order ties, and first-name-wins deduplication. Explicit-only skills are never auto-selected. `headroom` is added only for lexical pressure cues or the session's measured context-pressure bucket. A task with no signals yields an empty automatic grant rather than the full allowlist. Messages queued through `steer`, `followUp`, or `prompt(..., { streamingBehavior })` retain the active run's system prompt; they do not trigger a second skill-selection rebuild.
+
 | Task class | Skills | MCP |
 | --- | --- | --- |
 | Multi-package or repo-context work | `packages`; add `headroom` only under context pressure | none by default |

package/docs/harness-boundaries.md

@@ -0,0 +1,154 @@
+# 벤치마크 실패에서 다시 나눈 하네스 책임
+
+2026-09-09. 대상은 Terminal-Bench 2.1의 **중단된 Flash 24-task 개발용 비교**다.
+새 오케스트레이터를 추가하는 대신, 기존 런타임에서 입력·권한·실행·완료 판정의 책임을
+분리한다. 이 문서는 구현한 경계와 후속 설계를 구분하며 성능 우위를 주장하지 않는다.
+
+## 1. 무엇을 고쳐야 하는가
+
+비공개 실행 `tb21-flash24-20260908T151234Z-pYN3`의 결과·요청 원장·세션 메타데이터를
+읽기 전용으로 재집계했다. 고정 dataset SHA는 `5c8eadf1f393183288fa08b8f73ca9a469cc5e00`,
+실행 소스 HEAD는 `29624c3962d00cc8355191265e7827d9fdf0f3ad`다. 실행에는 미커밋 코드가
+포함됐으므로 HEAD만으로 실행물을 재현할 수 없다. 실행 manifest의 파일 해시가 별도로 필요하다.
+
+| 관측 | 확인된 사실 | 설계 결정 |
+| --- | --- | --- |
+| 완료 범위 | 43/48시행. A 21개, B 22개 | 같은 21쌍만 비교. 미완료 5개를 실패·성공으로 채우지 않음 |
+| 같은 21쌍 해결 | OMK 7, Terminus-2 10 | 최종 24개 점수나 공식 순위가 아님 |
+| OMK 비정상 종료 4건 | 모두 `read`의 image 결과 다음 공급자 계약 거부 | 도구 관측값이 모델 선택을 변경하지 않게 함 |
+| 시간 초과 | OMK 4, Terminus 3 | 원인별 시간 분해 뒤에만 deadline 정책 변경 |
+| 같은 21쌍 요청 | OMK 574, Terminus 617 | 이전 Pro 실험의 요청 증폭 결론을 그대로 재사용하지 않음 |
+| 같은 21쌍 기록된 입력 토큰 | OMK 9,523,530, Terminus 22,752,932 | 토큰 감소만으로 품질·비용 개선을 판정하지 않음 |
+| 동일 tool 인수 반복 | OMK 완료 시행에서 최대 3회 | 반복 차단 임계값을 일괄 낮출 근거 없음 |
+| 중단 상태 | 소유 프로세스가 없는데 `state.json`은 running | supervisor 상태와 살아 있는 실행 소유권을 분리 |
+| 별도 WSL 측정 | OMK 8세션과 자식 프로세스 PSS 약15.8GiB, SwapPSS 약6.4GiB | MCP 시작 전 자원 입장 제어가 필요. benchmark만의 점유량이 아님 |
+
+이미지 실패 4건은 자동 라우팅→계약 거부까지 확인한 인과 경로다. 아래 수정으로 그
+종료 원인을 없애도 네 task가 해결된다는 뜻은 아니다. 시간 초과 중 `tune-mjcf`의
+기록된 gateway 시간은 약120초, `db-wal-recovery`는 약712초였다. 나머지 시간을 모두
+도구 낭비라고 추정하지 않는다. 대기·tool·검증·호스트 압박 측정이 더 필요하다.
+
+## 2. 선택한 구조
+
+```text
+원본 session / tool artifact                         [보관·재생]
+              │
+사용자가 선택한 모델 + 명시적 사용자 첨부             [모델 선택]
+              │
+ProviderInputProjection                             [전송 표현]
+  ├─ 지원하는 입력: 유지
+  └─ text-only + tool image: 명시적 미관측 안내
+              │
+ModelContract → provider-specific payload check      [허용·거부]
+              │
+SDK/provider → tool execution → 실행 관측             [실행]
+              │
+classifyRunTermination → durable run journal          [시도 종료]
+              │
+prompt_settled (retry·continuation 종료 후)            [프롬프트 종료]
+              │
+CLI exit status ── text / JSON renderer               [보고]
+```
+
+원본 보관은 입력 변환과 별개다. 계약 검사는 입력을 해석하거나 임의 모델을 선택하지 않는다.
+`agent_end`는 재시도 전의 시도 종료일 수 있으므로 CLI의 최종 판정으로 바로 쓰지 않는다.
+종료 코드 0이나 `prompt_settled=completed`도 외부 verifier의 해결 판정과는 다르다.
+
+선행연구는 [SWE-agent의 ACI 연구](https://arxiv.org/abs/2405.15793v3)의 초록을 확인했다.
+모델과 도구 사이의 인터페이스를 먼저 고친다는 방향의 참고 자료이며, 이 변경의 구현
+세부사항이나 TB 성능 이득을 증명하는 자료가 아니다. 새 학습형 라우터·judge·앙상블은
+이번 실패 원인을 해결하지 않으므로 추가하지 않는다.
+
+## 3. 이번에 구현한 경계
+
+### 입력 표현: provider-input.ts
+
+`packages/agent/src/provider-input.ts`는 `projectToolImagesForModel()`을 제공한다.
+계약이 있는 core/SDK 경로에서만 사용한다.
+
+- text-only 모델의 `toolResult` 이미지 블록만 텍스트 안내로 바꾼다. 시각 내용을
+  추측하거나 OCR 결과를 만들어 내지 않는다.
+- 기존 text, tool-call ID, 오류 여부와 순서를 유지한다. 원본 세션의 image는 수정하지 않는다.
+- 현재 모델이 이미지 입력을 지원하면 그대로 전송한다. 사용자 첨부는 자동 제거하지 않는다.
+- 계약 모드에서는 **tool 이미지로 자동 vision 모델을 선택하지 않는다**. 사용자 이미지가
+  있는 경우는 기존 vision 라우트를 검사하고, 허용된 vision 모델이면 모든 첨부를 유지한다.
+- 계약 없는 일반 제품 경로는 기존 자동 vision 라우팅을 유지한다.
+- core의 `provider_request.omittedToolImages`는 해당 요청에서 생략한 이미지 수다.
+  누적 제거량이나 이미지 해석 성공률이 아니다. SDK 요약은 동일 변환을 쓰지만 아직 이
+  core 사건 원장의 소비자가 아니므로 별도의 완전한 요청 원장으로 주장하지 않는다.
+
+이는 원본 이미지 메모리를 줄이는 변경이 아니다. read producer의 decode/resize나
+세션 내 base64 저장을 없애지 않았다. 그 부분은 아래 artifact-reference 후속 단위다.
+
+### 원인 분류: session-run-termination.ts
+
+기존 `AgentSession`의 종료 원인 분류를 별도 순수 함수로 옮겼다. 세션 수명주기와
+원장 append 책임은 그대로 두고, 시계·모델·관측된 거부/timeout을 분류기에 전달한다.
+
+`provider_denied(contract-violation)`가 관측된 core run은 문자열 추측보다 먼저
+`configuration.invalid`, `retryable=false`로 분류한다. 계약을 완화하거나 다른 모델로
+전환하는 재시도는 추가하지 않는다. 다음 run에서 원인을 초기화한다.
+이전 로그의 `retryable=true`는 잘못된 안내였으며, 그것만으로 실제 재시도 지출이
+발생했다고 주장하지 않는다. SDK/사용자 정의 stream의 모든 오류까지 이 사건으로
+변환한 것은 아니다.
+
+### CLI 결과: print-mode.ts
+
+최종 실패 판단은 renderer 바깥에 둔다. 각 `session.prompt()`가 끝난 뒤
+`prompt_settled` 결과를 확인한다. 이 사건이 없는 호환 경로에서는 해당 프롬프트의
+assistant error/abort와 typed termination을 확인한다.
+
+text와 JSON 모두 실패 시 종료 코드 1을 반환하고 후속 CLI 프롬프트를 실행하지 않는다.
+내부 재시도에서 한 번 실패했어도 최종 settlement가 성공이면 실패로 고정하지 않는다.
+실행 전부터 존재하던 이전 termination을 새 프롬프트의 실패로 재사용하지 않는다.
+
+## 4. 다음 고도화: 작은 독립 단위로 구현
+
+아래는 **설계이며 아직 구현하지 않았다**. 이번 실행이나 기본 설정에 몰래 적용하지 않는다.
+
+| 단위 | 기존 책임과 연결 지점 | 수용 기준·중단 기준 |
+| --- | --- | --- |
+| H1: 실행 소유권·재개 | benchmark supervisor, `run-journal-store.ts` | PID뿐 아니라 boot ID+process start+heartbeat로 소유권 식별. 중단 시 미확정 요청·원본 결과 보존. 재시도는 새 attempt이며 사용자 승인 필요 |
+| H2: 공유 시간 예산 | prompt 수명주기, provider signal, `tool-timeout.ts` | 단조 시계 deadline 하나를 모든 대기에 전달. 남은 예산에서 검증·정리 시간을 예약. queue/model/tool/cleanup 구간 측정; fake-clock·child 종료·부분 결과 보존 검사 통과 전 활성화 금지 |
+| H3: artifact-reference 입력 | read producer, 세션 저장, provider-input | 큰 이미지/출력을 파일·digest·MIME·크기 참조로 보관. text-only 요청은 decoding 이전에 metadata만 사용. 원본 회수·권한·수명·재생 동일성을 검사하며 조용한 정보 손실 금지 |
+| H4: MCP 입장 제어 | MCP manager의 spawn, 기존 resource admission | 사용자 선택 loadout에서 필요할 때 시작. 실제 소유 child에만 종료·유휴회수 적용. 다른 세션·인증·프로젝트 경계를 공유하지 않음. host memory pressure와 startup 비용을 전후 측정 |
+| H5: 단일 요청 원장 | core 사건+SDK 요약+provider HTTP 경계 | run/trial/attempt/request ID로 시작·완료·거부·미확정을 연결. 시간창 귀속 금지. 사용량 결측을0으로 대체하지 않음. redaction·append 실패는 평가 completeness에 반영 |
+
+H1→H2→H3/H4→H5 순으로 무조건 전부 재작성하지 않는다. 먼저 각각의 현재 호출 경로와
+검사로 최소 diff를 정한다. H2는 “더 빨리 포기하기”가 목표가 아니며, H4는 머신 전체의
+프로세스나 Docker를 일괄 종료하는 기능이 아니다. global MCP pool은 인증 격리 비용이
+크므로 첫 구현에서 제외한다.
+
+## 5. 검증과 주장 범위
+
+이번 회귀는 공개 합성 입력만 사용했다. benchmark task 이름에 따라 동작을 바꾸거나
+원본 정답·verifier를 모델에 노출하지 않았다. 원본 실행물·결과·STOP 상태는 그대로다.
+
+| 검증 | 증명하는 범위 |
+| --- | --- |
+| core 이미지 회귀 | text-only 모델 유지, 원본 불변, idempotent 입력, 사용자 이미지 거부/허용, legacy 라우팅 유지 |
+| SDK 요약 회귀 | 요약에도 동일한 이미지 projection, 계약 거부 후 다음 허용 run 복구 |
+| 실제 소스 CLI + loopback HTTP | 실제 read image→두 번째 모델 요청 성공, raw 이벤트의 원본 image 보존, 최종 요청에 image payload 없음 |
+| CLI text/JSON 회귀 | 금지 모델의 네트워크0·exit1, settlement 실패 전파, 실패 후 후속 프롬프트 중단, 내부 복구 성공 보존 |
+| 기존 런타임 회귀 | auth/network/quota/abort/tool/persistence/compaction 분류와 기존 계약 유지 |
+
+구현 전에는 core 이미지 2개, SDK 요약/분류 2개, CLI 결과 5개 요구 검사가 실제 실패했다.
+직접 검토 중 사용자 이미지로 허용된 vision 모델을 선택했을 때 tool image까지 제거되는
+문제를 별도 RED로 발견하고 수정했다. 테스트 타입/fixture 오류는 제품 RED에 합산하지 않는다.
+
+실행 명령은 해당 package 디렉터리 기준이다. 메모리 부담을 줄이기 위해 worker 1로 실행한다.
+
+```bash
+# packages/agent
+node ../../node_modules/vitest/dist/cli.js --run test/provider-input.test.ts test/provider-request-boundary.test.ts --maxWorkers=1 --no-file-parallelism
+# packages/coding-agent
+node ../../node_modules/vitest/dist/cli.js --run test/sdk-model-contract.test.ts test/print-mode.test.ts test/model-contract-wire-cli.test.ts test/agent-session-termination-runtime.test.ts --maxWorkers=1 --no-file-parallelism
+# repository root
+node_modules/.bin/tsgo --noEmit --pretty false
+npm run check
+```
+
+실제 모델 재호출·벤치마크 재개·WSL 재시작·빌드/설치·커밋은 이번 작업에서 하지 않는다.
+본 변경은 중단된 24-task 결과를 보정하지 않는다. 재측정 전에 실행 snapshot과 양 arm의
+동일 조건을 다시 고정해야 한다. 현재 본 적 있는 24개는 개발 집합으로 유지하고,
+일반화 주장은 별도의 사전 고정 확인 평가로 검증한다.

package/docs/harness-improvements.md

@@ -0,0 +1,90 @@
+# OMK 하네스 개선 점검 — 2026-09-05
+
+기준은 `60f520f0c1`에서 시작한 현재 작업 트리입니다. 시작 시 다른 작업의
+미커밋 변경이 존재했으며 이를 보존했습니다. 아래는 주요 실행 경로에 대한
+소스·로컬 회귀 테스트 점검이지, 전체 코드 감사나 성능·SOTA 인증이 아닙니다.
+이번 변경은 작업 트리 상태이며 배포·릴리스된 기능으로 간주하지 않습니다.
+
+## 이번에 수정한 항목
+
+| 우선순위 | 관찰한 문제 | 수정과 증거 |
+| --- | --- | --- |
+| P0 | WPL의 `shouldSubmit`이 BLOCKED 여부만 확인해 preview·증거 부족·검증기 오류도 제출 가능으로 표시 | `b2c-mapper.ts`에서 적용 가능 + non-preview + run ID + `CONFIRMED`를 모두 요구. `submission-gates.test.ts`로 실패·누락·성공 대조 |
+| P0 | deep runner의 음수·비정수·실패 종료 코드와 공백 증거가 완료로 인정됨 | `deep-wall.ts`에서 비어 있지 않은 digest/command와 종료 코드 `0` 요구. `deep-wall-gates.test.ts` |
+| P0 | 완료된 deep check가 기존 BLOCKED/INCONCLUSIVE의 사람 검토 요구를 삭제 | `evaluate-correctness-wall.ts`가 기존 검토 요구를 유지하고, 요청한 deep check가 불가능하면 제출을 보류 |
+| P1 | 같은 테스트가 패키지 디렉터리에서는 통과하지만 저장소 루트에서는 오래된 WPL `dist`를 읽어 실패 | 루트 Vitest 프로젝트 설정과 coding-agent의 WPL 소스 alias 추가. 루트 실행에서 7개 실패를 재현한 뒤 같은 테스트 통과 |
+| P1 | WPL 사용자용 웹 가입·상담 접점과 키 없는 CLI 안내가 없음 | `getAdaptOrchLinks()`와 `omk doctor adaptorch --links [--json]` 추가. 고정 URL·UTM만 제공하며 정책 판정과 분리 |
+
+WPL의 `canApply`와 기존 shadow/soft/hard 적용 정책은 바꾸지 않았습니다.
+증거 요건을 충족한 `shouldSubmit=true`도 사람의 커밋·병합·배포 승인을 대신하지 않습니다.
+CTA를 verdict, 서명 receipt, 모델 프롬프트 또는 tool 실행 게이트에 끼워 넣지 않았습니다.
+
+## 다음 개선 순서
+
+| 우선순위 | 영역 / 현재 근거 | 후속 작업과 완료 기준 |
+| --- | --- | --- |
+| P0 | 전체 정적 검사: 아래 기존 파일의 Biome 오류 4개와 module-size 초과 5개 | 해당 변경 소유자가 수정한 뒤 `npm run check` 전체를 다시 통과시킬 것. 이번 작업 밖의 diff나 크기 baseline을 임의 수정하지 않음 |
+| P1 | 완료·취소·재시도: `prompt-settlement.ts`, `session-termination.ts`, `tool-timeout-settlement.ts` | 중간 `agent_end`와 최종 완료를 계속 분리. timeout 후 계속 쓰는 도구, 큐 취소, 중단 복원 조합을 실제 세션 경계 회귀에 추가 |
+| P1 | 컨텍스트·스킬: Context Budget V2와 Grok의 요청별 skill 선택은 별도 경로 | 공급자별 컨텍스트 비용·캐시 적중·compaction 후 명시 규칙 보존을 같은 작업으로 비교. 일반 공급자로 확장하기 전에 explicit-only 권한과 토큰 상한 회귀 확보 |
+| P1 | 공급자·도구 계약: `tool-schema`와 종료 원인 분류 테스트 | 인증/모델 미지원/환경 실패를 후보 코드 실패와 계속 구분. JSON schema 정규화와 tool pair 수선 후 공급자별 키 없는 cassette 회귀를 일관된 진입점에서 실행 |
+| P2 | 자원·스케줄링: DAG scheduler, resource admission의 현재 테스트 | `observe` 데이터를 먼저 수집하고 p95 지연·메모리·중복 도구 실행을 측정. adaptive 기본값 변경이나 자동 fan-out은 별도 승인·비교 실험 이후 |
+| P2 | 구조: 큰 session/interactive 모듈과 버전이 다른 런타임 설명 | 동작 변경과 파일 이동을 분리하고 역할별 모듈 크기·import-cycle 기준을 유지. 오래된 문서는 실제 소비자·기본값·revision에 묶어 갱신 |
+| P2 | CRM: 이번 변경은 링크 전달까지만 구현 | 사이트 측 동의 기반 UTM 보존 → 가입/상담 제출 → 첫 사용 이벤트를 연결하고, 로컬 평가와 호스티드 사용을 분리 집계. 링크 출력은 전환이 아님 |
+
+측정은 [Turn metrics](metrics.md)의 동일 모델·공급자·작업·예산 비교 계약을 따릅니다.
+회귀 테스트 통과만으로 더 빠르다거나 정확도가 높아졌다고 주장하지 않습니다.
+AdaptOrch 브리지는 계속 기본 비활성·advisory이며, WPL은 기본 CLI에서
+자동 dispatch/polling 루프가 되지 않습니다.
+
+## 검증 기록
+
+- 제출/deep-check 신규 회귀: 수정 전 **25개 중 17개 실패**, 수정 후 모두 통과.
+- CRM 안내 신규 회귀: 수정 전 **8개 중 7개 실패**, 수정 후 모두 통과.
+- WPL 관련 **9개 파일 / 68개 테스트 통과**. 변경한 mapper, deep wall, evaluator,
+  service links 네 모듈의 V8 커버리지: **lines 98.74%, branches 94.7%, functions 100%**.
+  `service-links.ts`는 모든 지표 100%.
+- coding-agent 하네스/컨텍스트/자원/브리지/벽 회귀 **13개 파일 / 154개 통과**.
+- 기존 doctor + 신규 offline handoff **2개 파일 / 20개 통과**.
+- 실제 소스 CLI 진입점 3개 시나리오와 agent scheduler/timeout/harness,
+  AI tool schema를 루트에서 함께 실행: **5개 파일 / 48개 통과**.
+- 최종 루트 통합 실행: 위의 **29개 파일 / 290개 테스트 모두 통과**, 종료 코드 `0`.
+- 루트 `node_modules/.bin/tsgo --noEmit`: 종료 코드 `0`. 변경 TypeScript 13개 파일의 LSP 오류 없음.
+- 변경 소스·테스트 Biome 검사와 범위 지정 `git diff --check`: 종료 코드 `0`.
+- `check:doc-links`, `check:feature-claims`, `check:private-home`, `check:import-cycles`:
+  각각 별도 실행에서 종료 코드 `0`. private-home 검사는 추적 중인 파일 범위입니다.
+- `npm run check`: 종료 코드 `1`, 아래 기존 파일의 import 정렬/포맷 오류 4개에서 중단.
+  이후 연결된 전체 게이트가 실행됐다고 간주하지 않습니다.
+- 별도 `npm run check:module-size`: 종료 코드 `1`, 이번에 수정하지 않은 아래 5개 모듈이
+  기존 baseline을 초과. 새 baseline을 등록해 오류를 숨기지 않았습니다.
+
+전체 검사를 막은 이번 작업 밖의 파일:
+
+- `packages/ai/src/utils/oauth/meta.ts`
+- `packages/ai/test/openai-responses-codex-turn-metadata.test.ts`
+- `packages/coding-agent/test/mcp/tools.test.ts`
+- `packages/coding-agent/test/session-termination.test.ts`
+
+Module-size 초과 파일 (현재 pure LOC / baseline):
+
+- `packages/agent/src/harness/reverse-skill.ts`: 905 / 792
+- `packages/ai/src/types.ts`: 362 / 361
+- `packages/coding-agent/src/core/model-registry.ts`: 886 / 885
+- `packages/coding-agent/src/core/provider-usage.ts`: 996 / 994
+- `packages/coding-agent/src/modes/interactive/interactive-mode.ts`: 5574 / 5473
+
+주요 신규 계약 재실행:
+
+```bash
+LIVE_E2E=0 node node_modules/vitest/dist/cli.js --run \
+  packages/adaptorch-wpl/test/submission-gates.test.ts \
+  packages/adaptorch-wpl/test/deep-wall-gates.test.ts \
+  packages/adaptorch-wpl/test/service-links.test.ts \
+  packages/coding-agent/test/adaptorch-onboarding.test.ts \
+  packages/coding-agent/test/adaptorch-doctor-cli.test.ts \
+  packages/coding-agent/test/adaptorch-links-cli.test.ts
+```
+
+명시적으로 미검증: 실제 Docker runner, 실제 인증 API 요청, 사이트 가입·상담
+저장, 클릭/전환 집계, 유료 provider 실행, 전체 e2e, 설치된 배포본/TUI 반영.
+벤치마크·AdaptOrch 실행·배포·커밋은 수행하지 않았습니다.
+CRM 사용법과 개인정보 경계는 [AdaptOrch 안내](adaptorch-onboarding.md)를 참조하세요.

package/docs/json.md

@@ -75,6 +75,25 @@ Followed by events as they occur:
 {"type":"agent_end","messages":[...]}
 ```
 
+## Completion and exit status
+
+`agent_end` closes an attempt, not necessarily the whole prompt: retries and
+continuations may still run. Use `prompt_settled` for the final prompt outcome
+(`completed`, `failed`, or `aborted`). Neither event proves task correctness.
+
+Print mode returns exit code **1** for a final failed or aborted prompt in both
+text and JSON output. If several CLI prompts were supplied, it stops at the first
+failed prompt instead of hiding it with a later success. An internally recovered
+attempt followed by a completed prompt still exits successfully. No prompt is an
+argument error (exit code **2**).
+
+Keep `pipefail` when filtering events, or the filter can hide OMK's nonzero status:
+
+```bash
+set -o pipefail
+omk --mode json "List files" | jq -c 'select(.type == "prompt_settled")'
+```
+
 ## Example
 
 ```bash

package/docs/keybindings.md

@@ -87,7 +87,7 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
 | `app.exit` | `ctrl+d` | Exit (when editor empty) |
 | `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
 | `app.editor.external` | `ctrl+g` | Open in external editor (`$VISUAL` or `$EDITOR`) |
-| `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows) | Paste image from clipboard |
+| `app.clipboard.pasteImage` | `ctrl+v`, `alt+v` | Paste image from clipboard; use `alt+v` when Windows Terminal consumes `ctrl+v` |
 
 ### Sessions
 

package/docs/mcp.md

@@ -49,8 +49,9 @@ Servers are read from three files, later wins on a name collision:
 
 The `omk` CLI calls `attachMcpServers()` for every session it creates —
 interactive, `-p`, and RPC, including `/new`, `/resume`, and forks — so a
-configured server's tools reach the model without further setup. A server that
-fails to start is reported as a startup warning and the session continues.
+configured server's tools reach the model without further setup. An enabled
+server that fails to start is reported as a startup warning and the session
+continues. Intentionally disabled entries are skipped without a startup warning.
 `--help` and `--list-models` never spawn servers.
 
 SDK callers attach explicitly:
@@ -95,6 +96,25 @@ OMK_MCP_SMOKE_HANDSHAKE_MS=120000 node scripts/mcp-smoke.mjs   # override slow h
 The script prints server state, tool counts, and versions. It never prints env
 values.
 
+### Package and credential errors
+
+An npm `E404` happens before the MCP handshake: the configured npm package could
+not be resolved. A longer `startup_timeout_sec` does not fix a wrong package name.
+The server's configuration key is not necessarily its package name:
+
+- [Context7](https://github.com/upstash/context7): `npx -y @upstash/context7-mcp`,
+  not `npx -y context7-mcp`.
+- [Fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch):
+  `uvx mcp-server-fetch`, not `npx -y @modelcontextprotocol/server-fetch`.
+
+Check all three configuration paths above: a project entry overrides a user entry
+with the same server name. Recreate the session after correcting a command.
+
+A `No API key` error is different: the executable started but lacks credentials.
+For Resend, supply `RESEND_API_KEY` securely to the server process, or explicitly
+set `disabled: true` if you do not need it. Do not paste keys into diagnostic
+output. Missing-key and other genuine startup failures remain warnings.
+
 ## Scope
 
 Implemented: `initialize`, `notifications/initialized`, `tools/list`,

package/docs/metrics.md

@@ -119,31 +119,40 @@ Counts, durations, ids, and error *classes*:
 
 ```json
 {
-  "schemaVersion": "omk-turn-metrics-1",
+  "schemaVersion": "omk-turn-metrics-2",
   "sessionId": "…", "turnIndex": 12,
   "provider": "anthropic", "model": "claude-sonnet-4-5",
   "startedAtEpochMs": 1, "endedAtEpochMs": 2, "durationMs": 1,
   "usage": { "input": 100, "output": 20, "cacheRead": 900, "cacheWrite": 10, "costUsd": 0.0125 },
   "stopReason": "toolUse",
-  "toolCalls": [{ "name": "bash", "durationMs": 120, "ok": false, "error": "exit 1" }],
+  "toolCalls": [{ "name": "bash", "durationMs": 120, "ok": false, "errorClass": "unknown" }],
   "toolCallCount": 1, "toolFailureCount": 1
 }
 ```
 
-**Never recorded:** prompt text, tool arguments, tool output, file contents, or
-environment values. Tool error strings are whitespace-collapsed and truncated to
-200 characters — enough to tell failure modes apart, too short to carry a
-payload.
+New records project an explicit field allowlist. Prompt, argument, output, environment,
+and unknown nested fields are not copied into the record; caller-supplied `toJSON`
+properties are not retained. Raw tool errors are classified as `timeout`, `aborted`,
+`permission`, `not_found`, `invalid_input`, or `unknown` and then discarded.
+Length truncation alone was not redaction. Identifiers are still metadata, not anonymized
+identities: callers must not put secrets or task content in ID/name fields.
 
-Metrics are advisory. A failed write is counted and dropped; it can never make a
-turn fail.
+The reader validates required fields, finite nonnegative quantities, counters, and
+nested tool/usage/cache shapes before aggregation. Invalid records count as malformed.
+Valid v1 records remain readable, but existing files are **not rewritten or scrubbed**;
+review old files separately before sharing them.
+
+Metrics remain advisory. Invalid input, an oversized record, or a failed write is
+counted and dropped rather than failing the agent. Single records cannot exceed the
+configured file bound. Rotation is still best-effort and does not provide a transactional
+multi-writer size guarantee.
 
 ## Capability baseline
 
 Runtime metrics tell you what a session cost, not whether the harness can solve
 tasks. For that, `scripts/tb-mini-suite.mjs` selects a deterministic,
-difficulty-balanced Terminal-Bench 2.1 subset so scores are comparable across
-runs:
+difficulty-stratified Terminal-Bench 2.1 subset. Score comparisons still require
+the controlled comparison contract above:
 
 ```bash
 node scripts/tb-mini-suite.mjs             # human-readable selection
@@ -151,9 +160,50 @@ node scripts/tb-mini-suite.mjs --json      # feed a runner
 node scripts/tb-mini-suite.mjs --seed 7    # a different fixed subset
 ```
 
-Selection is a pure function of (tasks directory, seed, size): the same inputs
-always produce the same task list, which is the whole point of using it as a
-regression gate. Selection alone is not a capability result. The scoring run
-itself requires Docker, `harbor`, and real model spend — it is deliberately not
-wired into `npm run check`. Any comparison produced from it must follow the
-controlled comparison contract above.
+With identical task metadata, seed, size, and collation, selection is repeatable.
+The default 15-task subset oversamples easy tasks and prioritizes shorter expert
+time estimates; it is a regression signal, not a population-representative score
+or an agent runtime bound. Selection alone is not a capability result. Scoring
+requires Docker, `harbor`, and model spend, and is not wired into `npm run check`.
+
+`--size` must be a positive safe integer no larger than the available task
+population. Missing difficulty quotas are filled from unselected tasks using the
+same ordering, so a valid request returns exactly that many distinct tasks.
+`--seed` accepts integers from `0` through `4294967295`. Invalid or missing option
+values and oversized requests exit with code `2`; absent, empty, or non-directory
+task paths exit with code `1`. The existing default subset remains unchanged.
+
+Run the offline CLI regression tests without downloading tasks or calling models:
+
+```bash
+node --test scripts/test/tb-mini-suite.test.mjs
+```
+
+See [the harness roadmap](../../../ROADMAP.md) for the dated OMK versus Terminus-2
+baseline, statistical limitations, implementation boundaries, and staged acceptance
+criteria. Planned runtime improvements are not measured benchmark gains.
+
+### Audit recorded TB 2.1 results
+
+The checkout-only `scripts/tb21-audit.mjs` audits explicitly selected Harbor jobs
+against a caller-pinned manifest digest. It rejects duplicate tasks/trials, missing
+results or costs, mismatched task checksums or configured model labels, and
+contradictory success records. It never starts a model, picks the latest job, joins
+requests by timestamp, or rewrites evidence. See [TB 2.1 offline audit](tb21-audit.md)
+for the schema, invocation, error codes, and limitations.
+
+A complete audit means recorded outcomes passed these checks, not that every
+provider request obeyed a single-model contract. Wire provenance, actual billing,
+repeated-trial analysis, and statistical superiority need separate evidence.
+
+### Explicit output-limit validation
+
+For callers that supply `AgentLoopConfig.modelContract`, both the contract's
+`maxOutputTokens` and an explicitly supplied request `maxTokens` must be positive
+safe integers. Invalid explicit values are refused before `provider_request` and
+before calling the provider stream function; they are not treated as absent.
+
+An omitted request limit still leaves provider defaults unchecked by this
+predicate. This change does not activate a contract in the CLI or impose an
+effective cap on compaction and other provider paths. Full run-wide enforcement
+remains a roadmap item.