open-multi-agent-kit 0.98.4 → 0.99.0

package/docs/sdk.md

@@ -156,6 +156,203 @@ 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 by default or with
+an explicitly approved `writer.maxConcurrentTasks: 2`.
+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, two preapproved commands per task and an optional
+concurrency cap of 1 or 2. Omitted concurrency preserves legacy contract bytes.
+The eager frontier starts a ready consumer without waiting for unrelated work;
+fatal failure or cancellation drains all started tasks before returning. 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,
+verification-conditioned edges, 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:
@@ -270,7 +467,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. 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.
+`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, or `devin` and `OMK_DEVIN_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:
 

package/docs/settings.md

@@ -272,7 +272,7 @@ Plays a short system sound only after the top-level prompt settles: retries, con
 | `retry.enabled` | boolean | `true` | Enable automatic agent-level retry on transient errors |
 | `retry.maxRetries` | number | `3` | Maximum agent-level retry attempts |
 | `retry.baseDelayMs` | number | `2000` | Base delay for agent-level exponential backoff (2s, 4s, 8s) |
-| `retry.provider.timeoutMs` | number | SDK default | Provider/SDK request timeout in milliseconds |
+| `retry.provider.timeoutMs` | number | SDK default | Provider/SDK request timeout in milliseconds. Also bounds how long the `openai-codex` SSE transport waits for response headers (floor 10s); large contexts need more than the floor |
 | `retry.provider.maxRetries` | number | `0` | Provider/SDK retry attempts |
 | `retry.provider.maxRetryDelayMs` | number | `60000` | Max server-requested delay before failing (60s) |
 

package/docs/startup-resource-labels-testing.md

@@ -0,0 +1,47 @@
+# 시작 리소스 설명의 하네스 태그: 검증 기록
+
+기준: `cabbb38389`. 실제 launcher의 version/help와 credentials 없는 offline TUI를 확인했습니다.
+기본 시작 화면은 OMK였으며, 다른 실행기로 전환되는 현상은 재현되지 않았습니다.
+외부 스킬 설명의 `[OMX]`가 자동완성에 원문으로 나타나는 경로는 재현했습니다.
+
+## 현재 표시 규칙
+
+`resource-description.ts`는 설명 앞의 `[OMX]` / `[OMO]` 장식 표기를 제거합니다.
+설명이 태그만으로 구성되면 `OMK resource`를 표시합니다. source scope와 호출 이름은
+그대로이며, formatter 자체가 원본 스킬이나 metadata를 수정하지는 않습니다.
+일반 문장 속 제품명이나 `[preview]` 같은 다른 태그를 무차별 치환하지 않습니다.
+
+초기 구현은 태그를 설명 뒤의 `resource tag`로 옮겼지만, 사용자의 후속 요구에 따라
+현재는 그 꼬리표도 출력하지 않습니다. 출처와 라이선스는 원본·별도 provenance에서 보존합니다.
+
+## RED → GREEN
+
+현재 요구의 8개 검사 중 4개가 RED였습니다. 예:
+
+```text
+Expected: [t] Planning workflow
+Received: [t] Planning workflow · resource tag: OMX
+```
+
+수정 후 다음 명령은 41개 테스트 통과, exit 0입니다.
+
+```bash
+(cd packages/coding-agent && node ../../node_modules/vitest/dist/cli.js --run \
+  test/interactive-mode-resource-description.test.ts test/interactive-mode-startup-input.test.ts \
+  test/cli-resource-paths.test.ts test/resource-loader.test.ts)
+```
+
+## 실제 진입점과 제한
+
+원래 문제는 임시 home의 실제 TUI에서 같은 스킬을 추가하고 `/skill:deep`을 입력해
+재현했습니다. 사용자 프롬프트를 전송하거나 credential을 복사하지 않았습니다.
+표시 로직은 source CLI와 단위 검사로 확인하고, 설치된 실행기는 별도로 대조합니다.
+소스 변경만으로 이미 설치·실행 중인 bundle이 바뀐다고 주장하지 않습니다.
+
+개인 OMK 스킬 경로 이관·설정 백업·네이티브 스킬 검증은 별도의 운영 범위이며,
+그 개인 파일이나 설정을 이 저장소에 복제하지 않습니다. 외부 확장이 자신의 UI를
+직접 렌더링하는 모든 경로를 검사한 결과도 아닙니다.
+
+변경 경로: `src/modes/interactive/{interactive-mode,resource-description}.ts`,
+`test/interactive-mode-resource-description.test.ts`, [사용 안내](usage.md), 이 기록.
+제안 메시지: `fix(tui): OMK 설명에서 외부 하네스 장식 표기 제거`.

package/docs/tb21-audit.md

@@ -3,6 +3,7 @@
 `scripts/tb21-audit.mjs`는 명시한 두 Harbor job의 **기록된 결과**를 검증한다.
 모델·Harbor를 실행하지 않으며 입력 파일이나 기존 요약을 수정하지 않는다.
 저장소 checkout과 Node.js 22.19 이상이 필요하다. 공개 npm CLI의 하위 명령은 아니다.
+현재 출력은 `omk-tb21-audit-report-2`, manifest 입력은 기존 `omk-tb21-manifest-1`이다.
 
 ## 사용
 
@@ -85,7 +86,7 @@ arm-b/
 job 바깥에 둔다. job 루트의 일반 파일(예: `config.json`, 전체 `result.json`)은
 개별 trial 집계에 사용하지 않는다. 최신 job 검색이나 시간창 기반 원장 귀속은 없다.
 
-각 task는 각 arm에 정확히 한 번 있어야 한다. v1은 재시도·다회 반복 집계를 지원하지
+각 task는 각 arm에 정확히 한 번 있어야 한다. 이 감사기는 재시도·다회 반복 집계를 지원하지
 않으므로 추가 attempt를 거부한다. 마지막 결과로 덮어쓰거나 가장 좋은 시행을 고르지 않는다.
 `trial_name`은 디렉터리 이름과 일치해야 하며 `id`는 두 arm 전체에서 유일해야 한다.
 Harbor가 절대 task 경로를 기록한 경우 마지막 경로 조각을 manifest ID와 비교하고,
@@ -96,6 +97,17 @@ Harbor가 절대 task 경로를 기록한 경우 마지막 경로 조각을 mani
 성공 보상 1과 예외가 함께 있으면 모순으로 거부한다. `exception_info` 필드 자체가
 없으면 예외 여부를 추측하지 않는다. timeout도 분모에 남는다.
 
+`started_at`과 `finished_at`은 필수다. 누락/null이면 `unfinished_trial`로 거부한다.
+두 값은 `YYYY-MM-DDTHH:mm:ss[.fraction]Z` 또는 명시적인 `±HH:mm` 오프셋을 가진
+시각이어야 한다. 소수초 1~9자리를 보존하며 밀리초로 잘라 순서를 비교하지 않는다.
+`finished_at < started_at`, 존재하지 않는 날짜, `24:00:00`, 타임존 없는 값은
+`invalid_trial_time`으로 거부한다. 시각 문자열 뒤의 개행도 허용하지 않는다.
+윤초 표기는 지원하지 않는다. 두 시각이 같으면 허용한다.
+
+종료시각이 없으면 보상 1이나 timeout 예외가 있어도 전체 요약을 거부한다. 그 trial을
+분모에서 빼거나 누락 시각에 현재 시간을 대입하지 않는다. v1에서 통과한 자료가 이
+추가 검증으로 거부될 수 있으므로 출력 버전을 2로 구분한다.
+
 `agent_result.cost_usd`는 0 이상의 유한한 숫자여야 한다. 누락·null은 **0이 아니라
 미확인**이며 요약을 거부한다. 합산 overflow도 거부한다. 해결 task가 0개이면
 `costPerSolved`는 null이다. 비용 단가·캐시 할인·실제 청구서 정합성은 별도 확인 대상이다.
@@ -110,8 +122,10 @@ manifest는 최대 256 KiB, 개별 결과는 최대 8 MiB까지 읽는다. 파
 manifest와 결과 파일의 해시가 포함된다. 원본 trial ID·task 절대 경로·kwargs·예외
 메시지는 내보내지 않는다. 출력의 run/task ID는 manifest에서 승인한 식별자를 사용한다.
 
-항상 `modelVerification: "configuration-only"`, `costSource: "harbor-agent-result"`를
-표시한다. 설정이 같다는 사실로 실제 모든 provider 전송이 같았다고 추론하지 않는다.
+항상 `modelVerification: "configuration-only"`, `costSource: "harbor-agent-result"`,
+`completionVerification: "recorded-timestamps"`를 표시한다. 기록된 시각의 유효성·순서만
+검사하며 실제 프로세스 종료, 시계 정확도, 자식 프로세스 정리까지 증명하지 않는다.
+설정이 같다는 사실로 실제 모든 provider 전송이 같았다고 추론하지 않는다.
 Gateway 원장으로만 비용을 알 수 있는 과거 trial은 비용을 지어내지 않고 `missing_cost`로
 거부한다. 신뢰할 수 있는 request ID별 원장 결합은 로드맵 R3의 후속 작업이다.
 
@@ -123,7 +137,7 @@ Gateway 원장으로만 비용을 알 수 있는 과거 trial은 비용을 지
 저장소 루트에서 공급자·다운로드 없이 실행한다.
 
 ```bash
-node --test --test-concurrency=1 scripts/test/tb21-audit.test.mjs scripts/test/tb21-audit-inputs.test.mjs
+node --test --test-concurrency=1 scripts/test/tb21-audit.test.mjs scripts/test/tb21-audit-inputs.test.mjs scripts/test/tb21-audit-completion.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
 ```
 

package/docs/usage.md

@@ -34,6 +34,11 @@ See [Keybindings](keybindings.md) for all shortcuts and customization.
 
 Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, `!skill:name`, or `!name` for known skills, `!omk <role-or-request>` selects an OMK role hub such as frontend, backend, loop, or plan, and prompt templates expand via `/templatename`.
 
+OMK omits decorative `[OMX]` and `[OMO]` prefixes from completion descriptions,
+without adding another harness label. A marker-only description becomes `OMK resource`.
+The formatter preserves original skill metadata, invocation names and source scope;
+this display change enables no foreign tools or compatibility guarantees.
+
 | Command | Description |
 | --------- | ------------- |
 | `/login`, `/logout` | Manage OAuth or API-key credentials |
@@ -46,6 +51,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 +67,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.