@kyo-so/cli 0.10.0 → 0.11.0

package/.agents/skills/kyoso-review/SKILL.md

@@ -45,6 +45,16 @@ Do not use this skill for every coding task. It is intended for deliberate revie
    - The CLI also accepts `--repo-summary`, repeatable `--constraint`, and repeatable `--file` flags. For a large review, adjust an agent timeout with `--set agents.<agent>.timeoutMs=<ms>`.
    - Run the CLI without a config trust flag first. Inspect `audit.warnings` in the JSON result; if it contains `untrusted config was not executed`, or the command fails with an untrusted-config message, ask the user whether to rerun with `--trust-config` to use it or `--ignore-config` to skip it. Never add `--trust-config` without confirmation.
    - Keep `--json` enabled and interpret the returned `decision` exactly like the MCP result.
-5. Treat `decision: block` as a stop signal. Present the result to the user before implementing.
-6. Treat `decision: approve_with_changes` as requiring changes to the plan or implementation.
-7. Do not claim Kyoso modified files. Kyoso only reviews.
+5. Apply the [review-pass stop contract](#review-pass-stop-contract) before deciding whether to run another review.
+6. Treat `decision: block` as a stop signal. Present the result to the user before implementing.
+7. Treat `decision: approve_with_changes` as requiring changes to the plan or implementation.
+8. Do not claim Kyoso modified files. Kyoso only reviews.
+
+## Review-pass stop contract
+
+- At one explicit review checkpoint, run one automatic review pass only.
+- Record the returned `requestFingerprint`. Do not run the same fingerprint again in the same task.
+- If `completion.status !== "complete"`, stop. Present the incomplete result; do not retry the same command or enter a finding-fix loop.
+- A single confirmation pass is allowed only after fixing actionable, material findings from the first complete pass.
+- After the confirmation pass, stop even when findings remain. Do not start a third pass without the user's explicit approval.
+- Do not interpret `approve_with_changes` as permission to repeat until `approve`.

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-07-15
+
+### Added
+
+- User-global review execution budgets with lower-only request overrides,
+  absolute deadlines, streamed ACP text-output caps (including thought chunks), token-usage accounting,
+  request fingerprints, and structured incomplete-review results.
+- Audit events and JSON/Markdown budget reporting for planned, consumed, and
+  skipped model calls, wall time, output bytes, token-usage state, and review
+  completion reasons.
+- A two-pass stop contract for the bundled Kyoso review Skill: one initial
+  review plus one confirmation after material fixes, with fingerprint-based
+  duplicate prevention and explicit approval required for a third pass.
+
+### Changed
+
+- Promote the Marketplace Plugin to `0.4.0`, pin its Codex and Claude Code MCP
+  definitions to `@kyo-so/cli@0.10.0`, and allow clients to forward
+  `OPENROUTER_API_KEY` by name for the existing OpenRouter project opt-in.
+- Default the Judge to deterministic-only mode. An LLM Judge now requires an
+  explicit `deterministic_plus_llm` opt-in and shares the review call budget.
+
 ## [0.10.0] - 2026-07-15
 
 ### Added

package/README.ja.md

@@ -50,11 +50,11 @@ backend が 1 つだけ有効な場合は、2 role の ensemble の代わりに
 
 PluginはSkillと公開済みのKyoso CLIの完全一致versionへpinしたMCP定義を同梱しますが、CLI本体は同梱しません。MCPの初回起動ではnpmへのnetwork accessが必要です。cache済みpackageでoffline起動できる場合はありますが、保証しません。manifestの`Read` capabilityは表示metadataであり、filesystem認可を追加するものではありません。
 
-`kyoso setup ... --with-openrouter` の出力と手動セットアップ例は、利用者が管理するクライアント登録テンプレートであり、Marketplace Plugin の manifest を変更・定義するものではありません。Stage A では同 manifest の公開済み CLI pin と環境契約を固定し、変更は Stage B の promotion でのみ行います。
+`kyoso setup ... --with-openrouter` の出力と手動セットアップ例は、引き続き利用者が管理するクライアント登録テンプレートです。Marketplace Plugin `0.4.0` は `@kyo-so/cli@0.10.0` へpinしています。
 
 PluginのSkillは同梱の`kyoso` MCP serverをdependencyとして宣言するため、Kyoso reviewの明示的な実行はCLI fallbackではなくMCPへ誘導されます。同梱Plugin MCPを無効化した場合は、Plugin Skillを利用不可として扱います。MCPを再有効化するか、Pluginを削除してCLI＋Skill-onlyへ移行してください。PluginはCLI fallback modeではありません。
 
-次回のPlugin promotionまでは、公開済みMarketplace Pluginは`OPENROUTER_API_KEY`を転送しません。OpenRouterのproject opt-inには、manual MCP registrationを伴うCLI／source経路を使ってください。この制約はpromotion後に対応Plugin versionの記載へ置き換えます。
+Marketplace Plugin `0.4.0` はMCP processへ`OPENROUTER_API_KEY`の変数名を公開しますが、credential値は保存しません。KyosoはOpenRouterを明示選択したCodex childだけへ値を転送し、展開されていないplaceholderは未設定として扱います。
 
 #### CLI＋Skill-only
 
@@ -373,8 +373,8 @@ Subscription-only setup:
 
 - Codex: local `codex` login を使用
 - Claude: `claude setup-token` を実行し、`CLAUDE_CODE_OAUTH_TOKEN` を設定
-- Judge: API keys を設定しないことで、Kyoso は `deterministic_fallback` を使用([Judge](#judge) を参照)
-- `OPENAI_API_KEY` が存在するときに OpenAI judge calls を避けるには、`judge.provider = "none"` を設定
+- Judge: default の `deterministic_only` mode は API key を必要としません([Judge](#judge) を参照)
+- 明示的な LLM judge opt-in を無効化するには、`judge.mode = "deterministic_only"` または `judge.provider = "none"` を設定
 
 Team admins は organization Usage credits も確認してください。Credits が有効な場合、subscription limits を超える billing behavior は Kyoso の外側で制御されます。
 
@@ -386,6 +386,23 @@ single-agent mode では、残った backend が `combined_reviewer` として 1
 
 この mode では独立した cross-model validation はなく、自己レビュー bias が残ります。一方で、別プロセスの read-only review、temporary snapshots、adversarial review prompts、secret scanning、deterministic gates は利用できます。
 
+### Execution budget and review stopping
+
+各 review には、model call数、総 wall time、streaming中のagent text（message / thought chunk）、agentあたりのfinding数に user-global の hard ceiling があります。
+
+```toml
+[reviewBudget]
+maxModelCalls = 4
+maxTotalWallTimeMs = 480000
+maxAgentOutputBytes = 65536
+maxFindingsPerAgent = 10
+skipOptionalPhasesWhenTokenUsageUnknown = true
+```
+
+`reviewBudget` は user-global 専用です。project `kyoso.toml` と `--set` では変更できません。MCP / library request は `options.reviewBudget` で ceiling を下げることだけができ、引き上げはできません。Kyoso は primary reviewer を両方予約してから開始し、残りのcallだけを verification に使い、LLM Judge は advisory として扱います。既定のJudge modeは `deterministic_only` です。
+
+結果には `completion`、`executionBudget`、`requestFingerprint` が含まれます。Markdown と Audit は call数、wall time、output bytes、reported / unknown token usage を示します。`completion.status` が `incomplete` の場合、Kyoso は `retryable: false` の通常の `block` 結果を返します。これは code defect の断定ではなく、review coverage が未完了であることを意味します。同じ fingerprint を自動 retry しないでください。同一review checkpointでは、bundled Skill は初回1 passと material fix後の確認1 passだけを許可し、3回目には明示的な user approval が必要です。
+
 ### Verification
 
 Verification keys: `verification.<enabled|maxFindings|timeoutMs>`。Optional finding verification は default で disabled です:
@@ -399,11 +416,11 @@ timeoutMs = 90000
 allowDemotion = false
 ```
 
-Enabled の場合、Kyoso は high/critical かつ single-source の各 finding について、その finding を報告していない agent に反証を試みさせます。Phase 1 は annotate-only です。verification は finding confidence と notes を更新できますが、severity や final decision は変更しません。`allowDemotion` は future opt-in phase 用に予約されており、現時点では no-op です。
+Enabled の場合、Kyoso は high/critical かつ single-source の各 finding について、その finding を報告していない agent に反証を試みさせます。Phase 1 は annotate-only で、verification は finding confidence と notes を更新できますが、severity は変更しません。verification が skip / fail / budget不足 / overflow の場合は finding を `not_verified` にし、coverage incomplete を返します。`allowDemotion` は future opt-in phase 用に予約されており、現時点では no-op です。
 
 ### Judge
 
-Judge keys: `judge.<mode|provider|timeoutMs>`。Judge LLMs は optional です。OpenAI judge を使うには `OPENAI_API_KEY` または `CODEX_API_KEY` を設定し、Anthropic judge を使うには `ANTHROPIC_API_KEY` を設定します。Optional overrides:
+Judge keys: `judge.<mode|provider|timeoutMs>`。Judge LLMs は optional で、default は `mode = "deterministic_only"` です。credential だけでは judge call を開始しません。OpenAI judge は `mode = "deterministic_plus_llm"` と `OPENAI_API_KEY` または `CODEX_API_KEY`、Anthropic judge は同modeと `ANTHROPIC_API_KEY` を設定します。Optional overrides:
 
 - `OPENAI_BASE_URL`: OpenAI-compatible API base URL
 - `KYOSO_OPENAI_JUDGE_MODEL`: OpenAI judge model, default `gpt-5.4-mini`
@@ -413,7 +430,7 @@ Judge defaults は意図的に lightweight models を使用します。より強
 
 ### Timeouts
 
-Default agent timeouts は Codex 120 秒、Claude 300 秒です。verification round の default は 90 秒です。MCP clients は tool calls に少なくとも 360 秒を許可してください。`verification.enabled` が true の場合、Kyoso は追加の cross-agent verification round を実行することがあるため、少なくとも 480 秒を許可してください。
+Default agent timeouts は Codex 120 秒、Claude 300 秒です。verification round の default は 90 秒です。review全体のdeadlineは既定480秒で、各phaseはdeadlineを延長せず残り時間を使います。MCP clients は tool calls に少なくとも480秒を許可してください。
 
 ### Audit
 
@@ -455,7 +472,7 @@ Windows、および必要なfilesystem capabilityを証明できない環境で
 - MCP timeout: client tool timeouts を少なくとも 360 秒、`verification.enabled` が true の場合は少なくとも 480 秒に設定してください。Kyoso defaults は [Timeouts](#timeouts) を参照してください。
 - Fresh npm release: safe-chain などの minimum-package-age protection により、publish 直後は `npx @kyo-so/cli` の解決が一時的に block される場合があります。
 - Deprecated TypeScript config: `--trust-config` を渡さない限り、untrusted `kyoso.config.ts` は skip されます。新規設定は `kyoso.toml` を使ってください。
-- OpenRouter key missing: 空でないCodex `model`、Kyoso processへ転送された`OPENROUTER_API_KEY`、clientの再起動を確認し、`kyoso doctor`を実行してください。公開済みMarketplace Pluginは次回promotionまでこのkeyを転送せず、既存MCP registrationはsetupで再書換えされません。
+- OpenRouter key missing: 空でないCodex `model`、Kyoso processへ転送された`OPENROUTER_API_KEY`、clientの再起動を確認し、`kyoso doctor`を実行してください。Marketplace Plugin `0.4.0`以降はこの変数名をKyoso processへ転送し、それ以前のversionは転送しません。既存MCP registrationはsetupで再書換えされません。
 
 ### Codex approval prompts
 

package/README.md

@@ -48,11 +48,11 @@ When in doubt, pick the Marketplace Plugin: two commands install the Skill and t
 
 The Plugin bundles the Skill and an MCP definition pinned to an exact published Kyoso CLI version; it does not bundle the CLI itself. Its first MCP start needs network access to npm. A cached package may work offline, but offline startup is not guaranteed. The manifest's `Read` capability is display metadata, not additional filesystem authorization.
 
-The `kyoso setup ... --with-openrouter` output and manual setup examples are user-managed client-registration templates; they neither modify nor define the Marketplace Plugin manifest. In Stage A, that manifest remains frozen at its released CLI pin and environment contract; only Stage B promotion changes it.
+The `kyoso setup ... --with-openrouter` output and manual setup examples remain user-managed client-registration templates. Marketplace Plugin `0.4.0` is pinned to `@kyo-so/cli@0.10.0`.
 
 The Plugin Skill declares the bundled `kyoso` MCP server as a dependency, so explicit Kyoso reviews are directed through MCP rather than a CLI fallback. If you disable the bundled Plugin MCP, treat the Plugin Skill as unavailable: re-enable it, or remove the Plugin and install CLI plus Skill-only instead. The Plugin is not a CLI-fallback mode.
 
-Until a future Plugin promotion, the released Marketplace Plugin does **not** forward `OPENROUTER_API_KEY`. Use the CLI/source path with a manual MCP registration for the OpenRouter project opt-in; this limitation will be replaced with the compatible Plugin version after that promotion.
+Marketplace Plugin `0.4.0` exposes the `OPENROUTER_API_KEY` variable name to its MCP process; it does not store a credential value. Kyoso forwards the value only to a Codex child that explicitly selects OpenRouter, and treats an unexpanded placeholder as missing.
 
 #### CLI plus Skill-only
 
@@ -371,8 +371,8 @@ Subscription-only setup:
 
 - Codex: use local `codex` login
 - Claude: run `claude setup-token`, then set `CLAUDE_CODE_OAUTH_TOKEN`
-- Judge: set no API keys, so Kyoso uses `deterministic_fallback` (see [Judge](#judge))
-- To avoid OpenAI judge calls when `OPENAI_API_KEY` is present, set `judge.provider = "none"`
+- Judge: the default `deterministic_only` mode needs no API key (see [Judge](#judge))
+- To disable an explicit LLM-judge opt-in, set `judge.mode = "deterministic_only"` or `judge.provider = "none"`
 
 Team admins should also check organization Usage credits. If credits are enabled, billing behavior beyond subscription limits is controlled outside Kyoso.
 
@@ -384,6 +384,23 @@ In single-agent mode, the remaining backend runs once as `combined_reviewer` and
 
 This mode does not provide independent cross-model validation and may retain self-review bias. It still provides a separate read-only review process, temporary snapshots, adversarial review prompts, secret scanning, and deterministic gates.
 
+### Execution budget and review stopping
+
+Every review has a user-global hard ceiling for model calls, total wall time, streamed agent text (message and thought chunks), and findings per agent:
+
+```toml
+[reviewBudget]
+maxModelCalls = 4
+maxTotalWallTimeMs = 480000
+maxAgentOutputBytes = 65536
+maxFindingsPerAgent = 10
+skipOptionalPhasesWhenTokenUsageUnknown = true
+```
+
+`reviewBudget` is user-global only: project `kyoso.toml` and `--set` cannot change it. MCP and library requests may lower a ceiling through `options.reviewBudget`, never raise it. Kyoso reserves both primary reviewers before starting either one, uses any residual calls for verification, and treats the LLM judge as advisory. The default judge mode is `deterministic_only`.
+
+The result includes `completion`, `executionBudget`, and `requestFingerprint`; Markdown and Audit show call counts, wall time, output bytes, and reported or unknown token usage. If `completion.status` is `incomplete`, Kyoso returns a normal `block` result with `retryable: false`: the block means review coverage is incomplete, not that a code defect was established. Do not automatically retry the same fingerprint. At one review checkpoint, the bundled Skill permits one initial pass and one confirmation pass only after material fixes; a third pass requires explicit user approval.
+
 ### Verification
 
 Verification keys: `verification.<enabled|maxFindings|timeoutMs>`. Optional finding verification is disabled by default:
@@ -397,11 +414,11 @@ timeoutMs = 90000
 allowDemotion = false
 ```
 
-When enabled, Kyoso asks the agent that did not report each high/critical single-source finding to try to refute it. Phase 1 is annotate-only: verification can update finding confidence and notes, but it does not change severity or the final decision. `allowDemotion` is reserved for a future opt-in phase and is currently a no-op.
+When enabled, Kyoso asks the agent that did not report each high/critical single-source finding to try to refute it. Phase 1 is annotate-only: verification can update finding confidence and notes, but it does not change severity. A skipped, failed, budget-exhausted, or overflowed verification leaves the finding marked `not_verified` and returns incomplete coverage. `allowDemotion` is reserved for a future opt-in phase and is currently a no-op.
 
 ### Judge
 
-Judge keys: `judge.<mode|provider|timeoutMs>`. Judge LLMs are optional. Set `OPENAI_API_KEY` or `CODEX_API_KEY` to use the OpenAI judge, or `ANTHROPIC_API_KEY` to use the Anthropic judge. Optional overrides:
+Judge keys: `judge.<mode|provider|timeoutMs>`. Judge LLMs are optional and default to `mode = "deterministic_only"`; credentials alone do not start a judge call. Set `mode = "deterministic_plus_llm"` plus `OPENAI_API_KEY` or `CODEX_API_KEY` for OpenAI, or `ANTHROPIC_API_KEY` for Anthropic. Optional overrides:
 
 - `OPENAI_BASE_URL`: OpenAI-compatible API base URL
 - `KYOSO_OPENAI_JUDGE_MODEL`: OpenAI judge model, default `gpt-5.4-mini`
@@ -411,7 +428,7 @@ Judge defaults intentionally use lightweight models. For a stronger judge, set `
 
 ### Timeouts
 
-Default agent timeouts are Codex 120 seconds and Claude 300 seconds; the verification round defaults to 90 seconds. MCP clients should allow at least 360 seconds for tool calls. If `verification.enabled` is true, allow at least 480 seconds because Kyoso may run an additional cross-agent verification round.
+Default agent timeouts are Codex 120 seconds and Claude 300 seconds; the verification round defaults to 90 seconds. The review-wide deadline defaults to 480 seconds, and each phase uses the remaining deadline rather than extending it. MCP clients should allow at least 480 seconds for tool calls.
 
 ### Audit
 
@@ -453,7 +470,7 @@ Windows, and environments where the required filesystem capabilities cannot be p
 - MCP timeout: set client tool timeouts to at least 360 seconds, or at least 480 seconds when `verification.enabled` is true. See [Timeouts](#timeouts) for the Kyoso defaults.
 - Fresh npm release: minimum-package-age protection in tools such as safe-chain may briefly block `npx @kyo-so/cli` resolution after publish.
 - Deprecated TypeScript config: untrusted `kyoso.config.ts` is skipped unless you pass `--trust-config`; prefer `kyoso.toml`.
-- OpenRouter key missing: confirm a non-empty Codex `model`, an `OPENROUTER_API_KEY` forwarded to the Kyoso process, and a restarted client; run `kyoso doctor`. The released Marketplace Plugin does not forward this key until the next Plugin promotion, and existing MCP registrations are not rewritten by setup.
+- OpenRouter key missing: confirm a non-empty Codex `model`, an `OPENROUTER_API_KEY` forwarded to the Kyoso process, and a restarted client; run `kyoso doctor`. Marketplace Plugin `0.4.0` and later forward this variable name to the Kyoso process; earlier versions do not. Existing MCP registrations are not rewritten by setup.
 
 ### Codex approval prompts
 

package/README.zh-CN.md

@@ -50,11 +50,11 @@ Kyoso 不会应用代码更改。
 
 Plugin包含Skill和pin到已发布Kyoso CLI精确版本的MCP定义，但不包含CLI本体。MCP首次启动需要访问npm网络。已缓存的package可能可以offline启动，但不作保证。manifest中的`Read` capability仅是显示metadata，不会授予额外filesystem权限。
 
-`kyoso setup ... --with-openrouter` 的输出和手动 setup 示例是用户管理的客户端注册模板；它们既不会修改 Marketplace Plugin manifest，也不会定义它。Stage A 期间，该 manifest 保持其已发布的 CLI pin 与环境契约；只有 Stage B promotion 才会更新它。
+`kyoso setup ... --with-openrouter` 的输出和手动 setup 示例仍是用户管理的客户端注册模板。Marketplace Plugin `0.4.0` pin 到 `@kyo-so/cli@0.10.0`。
 
 Plugin中的Skill将内置的`kyoso` MCP server声明为dependency，因此显式Kyoso review会通过MCP而不是CLI fallback。如果禁用内置Plugin MCP，应将Plugin Skill视为不可用：重新启用MCP，或移除Plugin并改用CLI＋Skill-only。Plugin不是CLI fallback mode。
 
-在下一次 Plugin promotion 前，已发布的 Marketplace Plugin **不会** forward `OPENROUTER_API_KEY`。OpenRouter 的 project opt-in 请使用带有 manual MCP registration 的 CLI/source 路径；promotion 后会用兼容的 Plugin version 替换这一限制说明。
+Marketplace Plugin `0.4.0` 向 MCP process 暴露 `OPENROUTER_API_KEY` 变量名，但不保存 credential 值。Kyoso 仅将该值传给显式选择 OpenRouter 的 Codex child，并将未展开的 placeholder 视为未设置。
 
 #### CLI＋Skill-only
 
@@ -373,8 +373,8 @@ Subscription-only setup:
 
 - Codex: 使用 local `codex` login
 - Claude: 运行 `claude setup-token`，然后设置 `CLAUDE_CODE_OAUTH_TOKEN`
-- Judge: 不设置 API keys，因此 Kyoso 使用 `deterministic_fallback`（参见 [Judge](#judge)）
-- 当存在 `OPENAI_API_KEY` 时，如需避免 OpenAI judge calls，请设置 `judge.provider = "none"`
+- Judge: 默认的 `deterministic_only` mode 不需要 API key（参见 [Judge](#judge)）
+- 如需禁用显式 LLM judge opt-in，请设置 `judge.mode = "deterministic_only"` 或 `judge.provider = "none"`
 
 Team admins 还应检查 organization Usage credits。如果启用了 credits，超出 subscription limits 的 billing behavior 由 Kyoso 外部控制。
 
@@ -386,6 +386,23 @@ Kyoso 可以在只有 Claude 或只有 Codex 可用时运行。请在 `kyoso.tom
 
 该 mode 不提供独立的 cross-model validation，仍可能有 self-review bias。它仍保留独立只读 review process、temporary snapshots、adversarial review prompts、secret scanning 和 deterministic gates。
 
+### Execution budget and review stopping
+
+每次 review 都有 user-global hard ceiling，用于限制 model call 数、总 wall time、streaming agent text（message 和 thought chunk）以及每个 agent 的 finding 数量。
+
+```toml
+[reviewBudget]
+maxModelCalls = 4
+maxTotalWallTimeMs = 480000
+maxAgentOutputBytes = 65536
+maxFindingsPerAgent = 10
+skipOptionalPhasesWhenTokenUsageUnknown = true
+```
+
+`reviewBudget` 只能在 user-global 配置中设置；project `kyoso.toml` 和 `--set` 都不能修改它。MCP / library request 只能通过 `options.reviewBudget` 降低 ceiling，不能提高。Kyoso 会先同时预留两个 primary reviewer，再将剩余 call 用于 verification，并把 LLM Judge 作为 advisory。默认 Judge mode 是 `deterministic_only`。
+
+结果包含 `completion`、`executionBudget` 和 `requestFingerprint`。Markdown 与 Audit 会显示 call 数、wall time、output bytes，以及 reported 或 unknown token usage。若 `completion.status` 为 `incomplete`，Kyoso 返回普通的 `block` 结果且 `retryable: false`：该 block 表示 review coverage 未完成，而不是已经确认 code defect。不要自动重试相同 fingerprint。对于一个 review checkpoint，bundled Skill 只允许首次评审与 material fix 后的确认评审各1次；第三次需要用户明确批准。
+
 ### Verification
 
 Verification keys: `verification.<enabled|maxFindings|timeoutMs>`。Optional finding verification 默认 disabled:
@@ -399,11 +416,11 @@ timeoutMs = 90000
 allowDemotion = false
 ```
 
-启用后，Kyoso 会让没有报告该 finding 的 agent 对 high/critical 且 single-source 的 finding 尝试反驳。Phase 1 是 annotate-only：verification 可以更新 finding confidence 和 notes，但不会改变 severity 或 final decision。`allowDemotion` 为未来的 opt-in phase 保留，目前是 no-op。
+启用后，Kyoso 会让没有报告该 finding 的 agent 对 high/critical 且 single-source 的 finding 尝试反驳。Phase 1 是 annotate-only：verification 可以更新 finding confidence 和 notes，但不会改变 severity。若 verification 被 skip、失败、预算耗尽或 overflow，finding 会保留为 `not_verified`，并返回 incomplete coverage。`allowDemotion` 为未来的 opt-in phase 保留，目前是 no-op。
 
 ### Judge
 
-Judge keys: `judge.<mode|provider|timeoutMs>`。Judge LLMs 是 optional。设置 `OPENAI_API_KEY` 或 `CODEX_API_KEY` 可使用 OpenAI judge，设置 `ANTHROPIC_API_KEY` 可使用 Anthropic judge。Optional overrides:
+Judge keys: `judge.<mode|provider|timeoutMs>`。Judge LLMs 是 optional，默认 `mode = "deterministic_only"`；仅设置 credential 不会启动 judge call。OpenAI judge 需要 `mode = "deterministic_plus_llm"` 与 `OPENAI_API_KEY` 或 `CODEX_API_KEY`；Anthropic judge 需要同一 mode 与 `ANTHROPIC_API_KEY`。Optional overrides:
 
 - `OPENAI_BASE_URL`: OpenAI-compatible API base URL
 - `KYOSO_OPENAI_JUDGE_MODEL`: OpenAI judge model, default `gpt-5.4-mini`
@@ -413,7 +430,7 @@ Judge defaults 有意使用 lightweight models。若需要更强的 judge，请
 
 ### Timeouts
 
-Default agent timeouts 是 Codex 120 秒、Claude 300 秒；verification round 默认 90 秒。MCP clients 应允许 tool calls 至少运行 360 秒。如果 `verification.enabled` 为 true，Kyoso 可能会运行额外的 cross-agent verification round，因此请至少允许 480 秒。
+Default agent timeouts 是 Codex 120 秒、Claude 300 秒；verification round 默认 90 秒。review-wide deadline 默认480秒，各 phase 使用剩余 deadline 而不会延长它。MCP clients 应允许 tool calls 至少运行480秒。
 
 ### Audit
 
@@ -455,7 +472,7 @@ Windows，以及无法证明所需 filesystem capability 的环境，会 fail-cl
 - MCP timeout: 将 client tool timeouts 设置为至少 360 秒；当 `verification.enabled` 为 true 时，设置为至少 480 秒。Kyoso defaults 请参阅 [Timeouts](#timeouts)。
 - Fresh npm release: safe-chain 等 minimum-package-age protection 可能会在 publish 后短时间内 block `npx @kyo-so/cli` resolution。
 - Deprecated TypeScript config: 除非传入 `--trust-config`，否则 untrusted `kyoso.config.ts` 会被 skip；新配置请使用 `kyoso.toml`。
-- OpenRouter key missing: 确认 Codex `model` 非空、`OPENROUTER_API_KEY` 已 forward 给 Kyoso process，并已重启 client；再运行 `kyoso doctor`。已发布 Marketplace Plugin 在下一次 promotion 前不会 forward 此 key，setup 也不会重写已有 MCP registration。
+- OpenRouter key missing: 确认 Codex `model` 非空、`OPENROUTER_API_KEY` 已 forward 给 Kyoso process，并已重启 client；再运行 `kyoso doctor`。Marketplace Plugin `0.4.0` 及更高版本会将此变量名 forward 给 Kyoso process，旧版本不会。setup 也不会重写已有 MCP registration。
 
 ### Codex approval prompts
 

package/dist/acp/FakeAgentManager.d.ts

@@ -1,6 +1,6 @@
 import type { AgentRunInput, AgentRunResult } from "../core/types.js";
 import { BaseAcpAgentManager } from "./AcpAgentManager.js";
-export type FakeAgentScenario = "success" | "markdown_json" | "timeout" | "malformed" | "preflight_failure" | "openrouter_key_missing" | "auth_failure" | "permission_request" | "write_attempt";
+export type FakeAgentScenario = "success" | "markdown_json" | "timeout" | "malformed" | "preflight_failure" | "openrouter_key_missing" | "auth_failure" | "permission_request" | "write_attempt" | "unknown_usage";
 export type FakeVerifierVerdict = {
     findingId: string;
     verdict: "confirmed" | "refuted" | "uncertain";