@kyo-so/cli 0.13.1 → 0.15.0

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

@@ -39,8 +39,9 @@ Do not use this skill for every coding task. It is intended for deliberate revie
    - If the typed contract contains non-goals or accepted risks and MCP is unavailable, stop and explain that the CLI fallback cannot preserve those trusted fields. A focus-only contract may use the CLI fallback.
    - If the MCP tools are unavailable, use the first available CLI path with JSON output:
      1. An installed `kyoso` executable on `PATH`.
-     2. `npx -y @kyo-so/cli`.
-     3. `bunx @kyo-so/cli`.
+     2. `npx -y --package=@kyo-so/cli kyoso`.
+     3. `bunx --package @kyo-so/cli kyoso`.
+     - The Bun fallback requires a Bun version that supports `bunx --package`; if it does not, return to the npx or PATH fallback.
    - Append the review command to the selected CLI path:
      - `plan_review` -> `plan --goal <text> [--plan <path-or-text>] [--file <path>] --json`
      - `security_review` -> `security --goal <text> [--diff <path>] [--file <path>] --json`

package/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-07-21
+
+### Added
+
+- Add `agents.codex.openRouter` retry configuration for OpenRouter Codex
+  reviews. It maps idle timeout, stream retries, and request retries to the
+  fixed provider preset without changing omitted Codex runtime defaults.
+- Record observed ACP stream retries, discarded retry-message bytes, and ACP
+  output timestamps in model-call audit records and JSONL trace events.
+- Add typed core review-progress events, bounded non-blocking progress delivery,
+  CLI stderr renderers (`auto`, `plain`, `jsonl`, and `off`), and graceful
+  SIGINT cancellation through primary and verifier ACP subprocesses.
+- Add MCP `notifications/progress` support when a client provides a
+  `progressToken`, with per-request monotonic sequences and fixed-field messages.
+  Whether progress is displayed remains client-dependent.
+- Propagate MCP cancellation through primary and verification ACP subprocesses
+  and in-flight OpenAI or Anthropic judge calls without converting cancellation
+  into a normal result or judge fallback.
+- Add a release-gated mock Responses SSE integration suite for the pinned Codex
+  ACP adapter, covering stream retries and exhaustion without credentials or an
+  externally configurable provider base URL.
+
+### Fixed
+
+- Prevent incomplete Codex message chunks from leaking into final agent output
+  after a structured stream retry, while retaining full wire-byte accounting
+  and output-limit enforcement.
+- Bound retry-progress trace writes per primary agent and preserve retry
+  metrics when an output cap stops a session.
+- Treat a terminal Codex ACP system error as a failed agent result even when
+  the adapter returns an ACP `end_turn` response.
+
+### Changed
+
+- Promote the Marketplace Plugin to `0.7.3` and pin its Codex and Claude Code
+  MCP definitions and Skill fallbacks to `@kyo-so/cli@0.14.0`.
+
+## [0.14.0] - 2026-07-19
+
+### Changed
+
+- Promote the Marketplace Plugin to `0.7.2` and make its Codex and Claude Code
+  MCP definitions explicitly launch the `kyoso` executable from
+  `@kyo-so/cli@0.13.1`, avoiding ambiguous npm executable inference.
+- Align new manual MCP setup, Skill fallbacks, documentation, and client
+  examples with explicit npx/bunx package-and-executable commands. Existing
+  custom, execution-altering environment, or unknown registrations remain
+  untouched; `--write --force` migrates a safe exact legacy npx command. Legacy
+  bunx is preserved without a `--runner` and requires explicit `--runner bunx`
+  verification or intentional `--runner npx` migration. Current bunx
+  registrations can be capability-checked without changing their bytes.
+- Add local multi-bin package smoke, exact published npx/bunx artifact smoke,
+  PATH-sentinel fallback detection, and fail-closed promotion verification with
+  rollback after a post-write failure. These durable CLI changes ship with the
+  next CLI release; they do not retroactively alter the already-recovered
+  Plugin `0.7.2` artifact.
+
 ## [0.13.1] - 2026-07-17
 
 ### Changed

package/README.ja.md

@@ -92,8 +92,8 @@ Plugin は Kyoso review Skill と、公開済み CLI version に pin したロ
 3. または、MCP を登録して review skill をインストールします。
 
 ```bash
-npx @kyo-so/cli setup claude-code --write
-bunx @kyo-so/cli setup claude-code --write
+npx -y --package=@kyo-so/cli kyoso setup claude-code --write
+bunx --package @kyo-so/cli kyoso setup claude-code --write
 ```
 
 手動で MCP を登録する場合は、`examples/claude-code-mcp.json` を使用します。
@@ -101,8 +101,8 @@ bunx @kyo-so/cli setup claude-code --write
 4. セットアップを確認します。
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. Claude Code からレビューを依頼します。
@@ -133,15 +133,15 @@ Codex Auto modeでは、approvalが必要なKyoso toolの呼び出しが拒否
 3. または、MCP を登録して review skill をインストールします。
 
 ```bash
-npx @kyo-so/cli setup codex --write
-bunx @kyo-so/cli setup codex --write
+npx -y --package=@kyo-so/cli kyoso setup codex --write
+bunx --package @kyo-so/cli kyoso setup codex --write
 ```
 
 4. セットアップを確認します。
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. Codex からレビューを依頼します。
@@ -154,7 +154,9 @@ Use Kyoso diff_review on the current diff. I need a second opinion before mergin
 
 ## CLI
 
-通常の実行経路は `npx @kyo-so/cli` と `bunx @kyo-so/cli` です。以下の例では、この prefix を `kyoso` と省略しています。Naming note: npm パッケージは `@kyo-so/cli` (製品名 Kyo-so に対応) で、インストールされる CLI コマンドは短い `kyoso` です。
+package-runner の実行経路では、package と executable を必ず別指定します: `npx -y --package=@kyo-so/cli kyoso` と `bunx --package @kyo-so/cli kyoso` です。workflowで固定する場合は、`@kyo-so/cli@0.14.0` のようにpackage名へcomplete SemVer pinを付けます。以下の例の `kyoso` は、すでにインストールされた executable の省略形です。Naming note: npm パッケージは `@kyo-so/cli` (製品名 Kyo-so に対応) で、インストールされる CLI コマンドは短い `kyoso` です。
+
+Bun fallback は Bun `1.3.14` で検証済みです。古い Bun では npx 形式またはインストール済みの `kyoso` を使い、複数bin packageからの Bun のbinary推論に依存しないでください。
 
 ```bash
 kyoso plan --goal "Review this OAuth callback plan" --plan plan.md
@@ -198,7 +200,7 @@ Kyoso を Codex または Claude Code の MCP server として登録し、client
 # See examples/codex-config.toml
 [mcp_servers.kyoso]
 command = "npx"
-args = ["-y", "@kyo-so/cli", "mcp", "--network", "model_only"]
+args = ["-y", "--package=@kyo-so/cli", "kyoso", "mcp"]
 ```
 
 client request の例:
@@ -210,8 +212,8 @@ Use Kyoso plan_review on this plan and the selected auth files. I need a second
 ## MCP
 
 ```bash
-npx @kyo-so/cli mcp --network model_only
-bunx @kyo-so/cli mcp --network model_only
+npx -y --package=@kyo-so/cli kyoso mcp --network model_only
+bunx --package @kyo-so/cli kyoso mcp --network model_only
 ```
 
 `--network` を省略すると、Kyoso は `model_only` を使用します。これは Kyoso が backend agents からの通信を model-provider traffic のみにすることを期待する policy-level constraint です。OS-level network isolation ではありません。
@@ -228,13 +230,19 @@ MCP stdout は protocol messages 専用です。logs は stderr または local
 
 同梱の `kyoso-review` skill は意図的に狭い用途にしています。Kyoso、multi-agent review、plan review、security review、CISA Secure by Design review、diff review を明示的に依頼したときだけ trigger されるべきです。
 
-Skillは利用可能な最初の経路を使います。順序はKyoso MCP tools、PATH上のインストール済み`kyoso`、`npx -y @kyo-so/cli`、`bunx @kyo-so/cli`です。package runner fallbackはnetwork accessが必要になり、version driftも起こり得るため、MCPなしの通常経路にはインストール済みCLIを使います。typed [review contract](#review-contract-と-finding-admission) にnon-goalsまたはaccepted risksがありMCPを利用できない場合、CLI fallbackは`focus`しか保持できないためSkillは停止します。
+Skillは利用可能な最初の経路を使います。順序はKyoso MCP tools、PATH上のインストール済み`kyoso`、`npx -y --package=@kyo-so/cli kyoso`、`bunx --package @kyo-so/cli kyoso`です。package runner fallbackはnetwork accessが必要になり、pinなしでは新しいreleaseへ解決され得るため、MCPなしの通常経路にはインストール済みCLIを使います。typed [review contract](#review-contract-と-finding-admission) にnon-goalsまたはaccepted risksがありMCPを利用できない場合、CLI fallbackは`focus`しか保持できないためSkillは停止します。
 
 `kyoso setup codex --write --skill-only`はcanonical Skill directoryを既定で`.agents/skills/kyoso-review/`へコピーします。`--global`を追加すると`~/.agents/skills/kyoso-review/`へコピーします。
 
 `kyoso setup claude-code --write --skill-only`は既定で`.claude/skills/kyoso-review/`へコピーします。`--global`を追加すると`~/.claude/skills/kyoso-review/`へコピーします。
 
-managed installはcanonical directoryのdigestとCLI versionを`.kyoso-install.json`へ記録します。現行または既知historical copyはadoptして自動更新します。変更済み／未知のcopyはconflictとして残し、上書きしません。`--force`はそのSkill directoryだけを置換し、MCP設定を削除・上書きしません。
+managed installはcanonical directoryのdigestとCLI versionを`.kyoso-install.json`へ記録します。現行または既知historical copyはadoptして自動更新します。変更済み／未知のcopyはconflictとして残し、上書きしません。`--force`はそのmanaged Skillを置換できます。manual MCPに対する例外は次節の限定移行だけであり、custom／unknown登録、選択した安全な対象外のglobal／nested登録、Marketplace Plugin／cacheは変更しません。
+
+### 手動 MCP の移行
+
+最初に `kyoso setup codex` または `kyoso setup claude-code` を実行し、既存登録を確認します。dry-run と `--write` は既存の MCP entry をすべて保持します。`--write --force` は生成時allowlist内のenvを持つ認識済み完全一致 legacy npx Kyoso commandを、上記のpackageとexecutableを分離した形式へ移行します。完全一致 legacy bunx command は `--runner` を省略するとprobeせず保持します。`--write --runner bunx --force` は Bun を検証して明示bunx形式へ移行し、`--write --runner npx --force` は意図的にnpx形式へ移行します。いずれもlegacy commandにcomplete SemVer pinがあった場合は保持します。currentの明示bunx登録は`--write --runner bunx`で確認でき、setupは登録bytesを変えずにBunを検証します。
+
+`--force` が対象にできるのは managed Skill の置換と、上記runner policyに従う安全な完全一致 legacy MCP entry の移行だけです。`NODE_OPTIONS`などexecutionを変え得るenv、custom `--command` entry、unknown structure、選択対象外の global / nested registration、Marketplace Plugin / cache は変更しません。`kyoso doctor` は保持したentryを ready とせず、`legacy`、`custom-unverified`、`unknown` として表示します。examplesを使って手動修復してから doctor を再実行してください。
 
 ## Review contract と finding admission
 
@@ -537,7 +545,7 @@ Windows、および必要なfilesystem capabilityを証明できない環境で
 ## Troubleshooting
 
 - MCP timeout: client timeoutはreview-wide deadlineより長くしてください。35分presetではCodexに2160秒、Claude Codeに`MCP_TOOL_TIMEOUT=2160000`を設定します。[Timeouts](#timeouts)を参照してください。
-- Fresh npm release: safe-chain などの minimum-package-age protection により、publish 直後は `npx @kyo-so/cli` の解決が一時的に block される場合があります。
+- Fresh npm release: safe-chain などの minimum-package-age protection により、publish 直後は `npx -y --package=@kyo-so/cli@<version> kyoso` が一時的に block される場合があります。`latest` や ambient `kyoso` へfallbackせず、その exact version を待ってください。
 - 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 `0.4.0`以降はこの変数名をKyoso processへ転送し、それ以前のversionは転送しません。既存MCP registrationはsetupで再書換えされません。
 

package/README.md

@@ -90,8 +90,8 @@ The Plugin installs the Kyoso review Skill and a local stdio MCP server pinned t
 3. Alternatively, register MCP and install the review skill.
 
 ```bash
-npx @kyo-so/cli setup claude-code --write
-bunx @kyo-so/cli setup claude-code --write
+npx -y --package=@kyo-so/cli kyoso setup claude-code --write
+bunx --package @kyo-so/cli kyoso setup claude-code --write
 ```
 
 For manual MCP registration, use `examples/claude-code-mcp.json`.
@@ -99,8 +99,8 @@ For manual MCP registration, use `examples/claude-code-mcp.json`.
 4. Verify the setup.
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. Ask for a review from Claude Code.
@@ -131,15 +131,15 @@ Codex Auto mode may reject Kyoso tool calls that require approval. To pre-approv
 3. Alternatively, register MCP and install the review skill.
 
 ```bash
-npx @kyo-so/cli setup codex --write
-bunx @kyo-so/cli setup codex --write
+npx -y --package=@kyo-so/cli kyoso setup codex --write
+bunx --package @kyo-so/cli kyoso setup codex --write
 ```
 
 4. Verify the setup.
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. Ask for a review from Codex.
@@ -152,7 +152,9 @@ Manual setup examples are kept in `examples/codex-config.toml` and `examples/cla
 
 ## CLI
 
-`npx @kyo-so/cli` and `bunx @kyo-so/cli` are the normal execution paths. The examples below abbreviate that prefix as `kyoso`. Naming note: the npm package is `@kyo-so/cli` (matching the product name Kyo-so), while the installed CLI command is the shorter `kyoso`.
+The package-runner execution paths always select the package and executable separately: `npx -y --package=@kyo-so/cli kyoso` and `bunx --package @kyo-so/cli kyoso`. Add a complete SemVer pin after the package name when a workflow needs one, for example `@kyo-so/cli@0.14.0`. The examples below abbreviate an already installed executable as `kyoso`. Naming note: the npm package is `@kyo-so/cli` (matching the product name Kyo-so), while the installed CLI command is the shorter `kyoso`.
+
+The Bun fallback is verified on Bun `1.3.14`. On an older Bun, use the npx form or an installed `kyoso`; do not rely on Bun inferring a binary from a multi-bin package.
 
 ```bash
 kyoso plan --goal "Review this OAuth callback plan" --plan plan.md
@@ -166,6 +168,36 @@ kyoso setup codex --write --skill-only
 kyoso setup claude-code --write --skill-only
 ```
 
+### Progress and cancellation
+
+Review results always use stdout: Markdown by default and JSON with `--json`.
+Progress and errors use stderr, so structured output remains pipe-safe.
+
+```bash
+kyoso plan --goal "Review this plan" --plan plan.md --json --progress jsonl \
+  >result.json 2>progress.jsonl
+```
+
+`--progress auto|plain|jsonl|off` defaults to `auto`: it shows plain,
+line-oriented progress only when stderr is a TTY. Use `plain` to force
+human-readable stderr output, `jsonl` for one typed event per stderr line, or
+`off` to suppress progress. Progress never includes prompts, selected-file
+contents, diffs, or model message/thought text.
+
+Press Ctrl-C once to request graceful cancellation of the review and its ACP
+child agents; Kyoso exits with status 130 after cleanup. Press it a second time
+to force immediate exit.
+
+For MCP tools, Kyoso sends `notifications/progress` only when the client supplies
+a `progressToken` in request metadata. Each request receives its own monotonically
+increasing sequence and no `total`, because review work is dynamic. Kyoso supports
+MCP progress notifications when the client requests them; whether progress is
+displayed is controlled by the MCP client.
+
+An MCP `notifications/cancelled` request aborts the review, including primary and
+verification ACP subprocesses and an in-flight LLM judge. A cancelled tool call is
+not converted into a normal review result. MCP stdout remains JSON-RPC only.
+
 ## Usage Examples
 
 Review an implementation plan with selected code:
@@ -196,7 +228,7 @@ Register Kyoso with Codex or Claude Code as an MCP server, then call `plan_revie
 # See examples/codex-config.toml
 [mcp_servers.kyoso]
 command = "npx"
-args = ["-y", "@kyo-so/cli", "mcp", "--network", "model_only"]
+args = ["-y", "--package=@kyo-so/cli", "kyoso", "mcp"]
 ```
 
 Example client request:
@@ -208,8 +240,8 @@ Use Kyoso plan_review on this plan and the selected auth files. I need a second
 ## MCP
 
 ```bash
-npx @kyo-so/cli mcp --network model_only
-bunx @kyo-so/cli mcp --network model_only
+npx -y --package=@kyo-so/cli kyoso mcp --network model_only
+bunx --package @kyo-so/cli kyoso mcp --network model_only
 ```
 
 When `--network` is omitted, Kyoso uses `model_only`. This means Kyoso expects only model-provider traffic from backend agents. It is a policy-level constraint, not OS-level network isolation.
@@ -226,13 +258,19 @@ MCP stdout is reserved for protocol messages. Logs go to stderr or local audit t
 
 The bundled `kyoso-review` skill is intentionally narrow. It should trigger only when you explicitly ask for Kyoso, multi-agent review, plan review, security review, CISA Secure by Design review, or diff review.
 
-The Skill uses the first available path: Kyoso MCP tools, an installed `kyoso` on `PATH`, `npx -y @kyo-so/cli`, then `bunx @kyo-so/cli`. The package-runner fallbacks may need network access and can drift to a newer version, so an installed CLI is the normal MCP-less path. If a typed [review contract](#review-contract-and-finding-admission) contains non-goals or accepted risks and MCP is unavailable, the Skill stops because the CLI fallback can preserve only `focus`.
+The Skill uses the first available path: Kyoso MCP tools, an installed `kyoso` on `PATH`, `npx -y --package=@kyo-so/cli kyoso`, then `bunx --package @kyo-so/cli kyoso`. The package-runner fallbacks may need network access and can resolve a newer unpinned release, so an installed CLI is the normal MCP-less path. If a typed [review contract](#review-contract-and-finding-admission) contains non-goals or accepted risks and MCP is unavailable, the Skill stops because the CLI fallback can preserve only `focus`.
 
 `kyoso setup codex --write --skill-only` copies the canonical Skill directory to `.agents/skills/kyoso-review/` by default. Add `--global` to copy it to `~/.agents/skills/kyoso-review/`.
 
 `kyoso setup claude-code --write --skill-only` copies it to `.claude/skills/kyoso-review/` by default. Add `--global` to copy it to `~/.claude/skills/kyoso-review/`.
 
-Managed installs record the canonical directory digest and CLI version in `.kyoso-install.json`. Exact current or known historical copies are adopted and updated automatically. A changed or unknown copy is reported as a conflict and left untouched; `--force` replaces only that Skill directory and never removes or overwrites MCP configuration.
+Managed installs record the canonical directory digest and CLI version in `.kyoso-install.json`. Exact current or known historical copies are adopted and updated automatically. A changed or unknown copy is reported as a conflict and left untouched; `--force` can replace that managed Skill. Its only manual-MCP exception is the limited migration below: it never rewrites custom or unknown registrations, global/nested registrations outside the selected safe target, or Marketplace Plugin/cache entries.
+
+### Manual MCP migration
+
+Run `kyoso setup codex` or `kyoso setup claude-code` first to inspect the existing registration. Dry-run and `--write` preserve every existing MCP entry. `--write --force` migrates an exact recognized legacy npx Kyoso command with a generated-safe environment to the explicit package-and-executable form shown above. For an exact legacy bunx command, omitting `--runner` preserves it without probing; use `--write --runner bunx --force` to verify Bun and migrate it to explicit bunx, or `--write --runner npx --force` to intentionally migrate it to npx. Each migration keeps a complete SemVer pin when the legacy command had one. A current explicit bunx registration can be checked with `--write --runner bunx`; setup verifies Bun without changing the registration bytes.
+
+`--force` can replace a managed Skill and migrate only the safe exact legacy MCP entries under the runner policy above. It never changes an entry with execution-altering environment fields such as `NODE_OPTIONS`, a custom `--command` entry, an unknown structure, global or nested registrations outside the selected safe target, or a Marketplace Plugin/cache. `kyoso doctor` reports preserved entries as `legacy`, `custom-unverified`, or `unknown` rather than ready; repair those entries manually from the examples, then rerun doctor.
 
 ## Review contract and finding admission
 
@@ -283,7 +321,7 @@ Kyoso loads config in this order:
 
 Unknown keys are rejected. Boolean and numeric config keys are converted to their schema types; string keys remain strings. The complete config is then validated.
 
-Project `kyoso.toml` is declarative and does not require trust approval. It can set safe project-scoped keys such as agent `enabled` / `model` / `effort` / `role` / `timeoutMs`, the Codex-only `provider` or a model override while OpenRouter is inherited after user-global authorization, workspace byte limits and additive `workspace.deny`, verification settings, advisory judge settings, and tightening-only security/network/CISA settings.
+Project `kyoso.toml` is declarative and does not require trust approval. It can set safe project-scoped keys such as agent `enabled` / `model` / `effort` / `role` / `timeoutMs`, the Codex-only `provider`, OpenRouter model, or retry-policy override after user-global authorization, workspace byte limits and additive `workspace.deny`, verification settings, advisory judge settings, and tightening-only security/network/CISA settings.
 
 `entrypoints.*`, `tools.*`, and `reviewPolicy.*` are user-global policy. A disabled entrypoint or tool returns a structured policy block before agents start. `firstClassClient = "codex"`, `workspace.readOnly = true`, `network.mediatedWeb.enabled = false`, and `audit.includeFileContents = false` are fixed or reserved values; unsupported values are rejected instead of acting as no-ops.
 
@@ -302,7 +340,7 @@ CODEX_CONFIG = '{"model":"gpt-5.5"}'
 
 ### Agents
 
-Agent keys: `agents.<codex|claude>.<enabled|model|effort|role|timeoutMs>`. Codex also supports `agents.codex.provider`: `"openrouter"` selects the external provider, while `"default"` resets an inherited OpenRouter selection to normal Codex behavior; Claude has no provider setting. Selecting the provider from a project requires the global-config-only `agents.codex.allowProjectProvider` allowlist; see [Codex OpenRouter project opt-in](#codex-openrouter-project-opt-in) for the full rules. The `command`, `args`, and `env` keys are also global-config-only (see [Files and precedence](#files-and-precedence)).
+Agent keys: `agents.<codex|claude>.<enabled|model|effort|role|timeoutMs>`. Codex also supports `agents.codex.provider`: `"openrouter"` selects the external provider, while `"default"` resets an inherited OpenRouter selection to normal Codex behavior; Claude has no provider setting. `agents.codex.openRouter.streamIdleTimeoutMs`, `streamMaxRetries`, and `requestMaxRetries` configure the selected OpenRouter transport only. Selecting the provider or changing that retry policy from a project requires the global-config-only `agents.codex.allowProjectProvider` allowlist; see [Codex OpenRouter project opt-in](#codex-openrouter-project-opt-in) for the full rules. The `command`, `args`, and `env` keys are also global-config-only (see [Files and precedence](#files-and-precedence)).
 
 Omit `agents.<name>.model` or `agents.<name>.effort` to use each agent's own default. Codex uses the local Codex config, such as `~/.codex/config.toml` (or `$CODEX_HOME/config.toml` when `CODEX_HOME` is set); Claude uses the adapter default.
 
@@ -342,13 +380,20 @@ Then opt in only in the project that needs OpenRouter:
 [agents.codex]
 provider = "openrouter"
 model = "openai/o4-mini"
+
+[agents.codex.openRouter]
+streamIdleTimeoutMs = 90000
+streamMaxRetries = 3
+requestMaxRetries = 2
 ```
 
 `model` is required and must not be blank when `provider = "openrouter"`. It is an OpenRouter model ID; Kyoso does not validate the catalog or whether that model supports tool calling, so confirm tool support with the provider.
 
-`allowProjectProvider` applies to a project `provider` and to a project `model` override while OpenRouter is inherited; its list must contain the absolute canonical directory containing the resolved project configuration file, not the invocation cwd or a lexical path, with no descendant or glob matching. A project configuration file (including trusted `kyoso.config.ts`) and an allowlist entry that resolve through symlinks to that directory match; entries resolving elsewhere, or unresolvable paths, fail closed. A user-global `provider = "openrouter"` needs no allowlist entry. An explicit CLI pair of `--set agents.codex.provider=openrouter` and `--set agents.codex.model=<model>` in the same invocation is also allowed without it; a project model cannot supply the CLI override's model. `allowProjectProvider` is not a `--set` path and legacy boolean values are rejected.
+`agents.codex.openRouter` is experimental. `streamIdleTimeoutMs` is an integer of at least `1000`; `streamMaxRetries` and `requestMaxRetries` are integers from `0` through `100`, where `0` disables that retry class. These fields require `provider = "openrouter"`; omitting them leaves the corresponding Codex runtime defaults unchanged. Retry can regenerate an unfinished Codex turn rather than resume its bytes, so do not broadly enable it until partial-output protection ships in the next release.
+
+`allowProjectProvider` applies to a project `provider`, a project `model` override while OpenRouter is inherited, and a project `agents.codex.openRouter.*` override while OpenRouter is inherited; its list must contain the absolute canonical directory containing the resolved project configuration file, not the invocation cwd or a lexical path, with no descendant or glob matching. A project configuration file (including trusted `kyoso.config.ts`) and an allowlist entry that resolve through symlinks to that directory match; entries resolving elsewhere, or unresolvable paths, fail closed. A user-global `provider = "openrouter"` needs no allowlist entry. An explicit CLI pair of `--set agents.codex.provider=openrouter` and `--set agents.codex.model=<model>` in the same invocation is also allowed without it; a project model cannot supply the CLI override's model. `allowProjectProvider` is not a `--set` path and legacy boolean values are rejected.
 
-When a user-global config selects OpenRouter, a project can explicitly opt out with `provider = "default"`. This reset needs neither a model nor authorization, clears the inherited OpenRouter model unless the same layer explicitly supplies a normal Codex model, and prevents OpenRouter key forwarding for that project.
+When a user-global config selects OpenRouter, a project can explicitly opt out with `provider = "default"`. This reset needs neither a model nor authorization, clears the inherited OpenRouter model unless the same layer explicitly supplies a normal Codex model, clears inherited OpenRouter retry policy, and prevents OpenRouter key forwarding for that project. A retry policy in the same reset layer remains invalid because it requires `provider = "openrouter"`.
 
 Set the key in the process environment that starts the Codex or Claude client running Kyoso. A direct environment variable is the primary path; a secret manager such as 1Password is optional and is not a Kyoso dependency:
 
@@ -362,7 +407,7 @@ The Marketplace Plugin exposes the `OPENROUTER_API_KEY` variable name to its MCP
 
 New manual MCP registrations omit `OPENROUTER_API_KEY` by default. Add it only with `--with-openrouter` after intentionally selecting the provider; existing registrations are never rewritten. The `kyoso setup ... --with-openrouter` output and the manual setup examples remain user-managed client-registration templates. In a Claude Code registration, `${OPENROUTER_API_KEY}` must be expanded by the client; Kyoso ignores only a whole unexpanded credential placeholder — `${NAME}`, `$NAME`, or `%NAME%`, with optional surrounding whitespace — and emits a sanitized warning containing only the variable name. Values with any other text are preserved. The same rule applies to custom credential-like names ending in `_KEY`, `_TOKEN`, `_SECRET`, or `_PASSWORD`; non-credential templates are preserved.
 
-Prefer this user-authorized project-scoped opt-in. A global `provider = "openrouter"` is inherited by projects until a project sets `provider = "default"`; merely omitting `provider` does not unset it. The fixed OpenRouter Responses API preset is beta; custom endpoints, provider routing, fallbacks, and judge integration are not exposed. To keep the key bound to that preset, OpenRouter mode rejects a `CODEX_CONFIG` with a top-level `profile` or `profiles` field and rejects a non-object `model_providers` value before launching the child. For an object value, it replaces `model_providers` with only the fixed `kyoso-openrouter` entry and emits a sanitized warning with the discarded-entry count only; provider IDs and configuration values never appear. Apart from those rejected fields, it preserves unrelated `CODEX_CONFIG` fields outside `model`, `model_provider`, and `model_providers`, so no foreign provider configuration can select an endpoint with the key. Claude remains on its configured provider, and the judge does not use `OPENROUTER_API_KEY`.
+Prefer this user-authorized project-scoped opt-in. A global `provider = "openrouter"` is inherited by projects until a project sets `provider = "default"`; merely omitting `provider` does not unset it. The fixed OpenRouter Responses API preset is beta; custom endpoints, provider routing, fallbacks, and judge integration are not exposed. When configured, `streamIdleTimeoutMs`, `streamMaxRetries`, and `requestMaxRetries` map only to `stream_idle_timeout_ms`, `stream_max_retries`, and `request_max_retries`; omitted fields are absent from `CODEX_CONFIG`. To keep the key bound to that preset, OpenRouter mode rejects a `CODEX_CONFIG` with a top-level `profile` or `profiles` field and rejects a non-object `model_providers` value before launching the child. For an object value, it replaces `model_providers` with only the fixed `kyoso-openrouter` entry and emits a sanitized warning with the discarded-entry count only; provider IDs and configuration values never appear. Apart from those rejected fields, it preserves unrelated `CODEX_CONFIG` fields outside `model`, `model_provider`, and `model_providers`, so no foreign provider configuration can select an endpoint with the key. Claude remains on its configured provider, and the judge does not use `OPENROUTER_API_KEY`.
 
 After user-global authorization, a project `kyoso.toml` can select the external provider or override its inherited OpenRouter model and route review context to it. For an untrusted repository, use `--ignore-config` and pass only the needed CLI options explicitly.
 
@@ -372,7 +417,7 @@ The real Codex ACP/OpenRouter smoke is release-gated and never runs in tests. On
 KYOSO_OPENROUTER_ACP_SMOKE=release KYOSO_OPENROUTER_MODEL=<model> safe-chain bun run smoke:openrouter:codex-acp
 ```
 
-It accepts no CLI arguments, uses the pinned Codex ACP adapter, and creates fresh empty temporary workspace, `HOME`, and `CODEX_HOME` directories so it cannot use the calling repository or cached Codex login. It returns only a fixed success or failure message without writing the key or model to config, temporary artifacts, or output.
+It accepts no CLI arguments, uses the pinned Codex ACP adapter, and creates fresh empty temporary workspace, `HOME`, and `CODEX_HOME` directories so it cannot use the calling repository or cached Codex login. It returns only a fixed success or failure message without writing the key or model to config, temporary artifacts, or output. This credentialed smoke checks only interoperability; retry correctness is covered by the release-only `KYOSO_CODEX_ACP_MOCK_SSE=1` local mock SSE integration gate.
 
 ### Agent auth
 
@@ -535,7 +580,7 @@ Windows, and environments where the required filesystem capabilities cannot be p
 ## Troubleshooting
 
 - MCP timeout: keep the client timeout longer than the review-wide deadline. For the 35-minute preset, use 2160 seconds in Codex or `MCP_TOOL_TIMEOUT=2160000` in Claude Code. See [Timeouts](#timeouts).
-- Fresh npm release: minimum-package-age protection in tools such as safe-chain may briefly block `npx @kyo-so/cli` resolution after publish.
+- Fresh npm release: minimum-package-age protection in tools such as safe-chain may briefly block `npx -y --package=@kyo-so/cli@<version> kyoso` after publish. Wait for the exact version instead of falling back to `latest` or an ambient `kyoso`.
 - 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`. 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.
 

package/README.zh-CN.md

@@ -92,8 +92,8 @@ Plugin 会安装 Kyoso review Skill 和 pin 到已发布 CLI version 的本地 s
 3. 或者，注册 MCP 并安装 review skill。
 
 ```bash
-npx @kyo-so/cli setup claude-code --write
-bunx @kyo-so/cli setup claude-code --write
+npx -y --package=@kyo-so/cli kyoso setup claude-code --write
+bunx --package @kyo-so/cli kyoso setup claude-code --write
 ```
 
 需要手动注册 MCP 时，请使用 `examples/claude-code-mcp.json`。
@@ -101,8 +101,8 @@ bunx @kyo-so/cli setup claude-code --write
 4. 验证 setup。
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. 从 Claude Code 请求 review。
@@ -133,15 +133,15 @@ codex plugin add kyoso@kyoso
 3. 或者，注册 MCP 并安装 review skill。
 
 ```bash
-npx @kyo-so/cli setup codex --write
-bunx @kyo-so/cli setup codex --write
+npx -y --package=@kyo-so/cli kyoso setup codex --write
+bunx --package @kyo-so/cli kyoso setup codex --write
 ```
 
 4. 验证 setup。
 
 ```bash
-npx @kyo-so/cli doctor
-bunx @kyo-so/cli doctor
+npx -y --package=@kyo-so/cli kyoso doctor
+bunx --package @kyo-so/cli kyoso doctor
 ```
 
 5. 从 Codex 请求 review。
@@ -154,7 +154,9 @@ Use Kyoso diff_review on the current diff. I need a second opinion before mergin
 
 ## CLI
 
-`npx @kyo-so/cli` 和 `bunx @kyo-so/cli` 是正常执行路径。下面的示例将此前缀简写为 `kyoso`。Naming note: npm package 是 `@kyo-so/cli` (对应产品名 Kyo-so)，安装后的 CLI command 是更短的 `kyoso`。
+package-runner 执行路径始终分别指定 package 和 executable：`npx -y --package=@kyo-so/cli kyoso` 与 `bunx --package @kyo-so/cli kyoso`。需要固定 workflow 时，在 package 名后加 complete SemVer pin，例如 `@kyo-so/cli@0.14.0`。下面的示例把已安装 executable 简写为 `kyoso`。Naming note: npm package 是 `@kyo-so/cli` (对应产品名 Kyo-so)，安装后的 CLI command 是更短的 `kyoso`。
+
+Bun fallback 已在 Bun `1.3.14` 上验证。旧版 Bun 请使用 npx 形式或已安装的 `kyoso`，不要依赖 Bun 从多 bin package 推断 binary。
 
 ```bash
 kyoso plan --goal "Review this OAuth callback plan" --plan plan.md
@@ -198,7 +200,7 @@ kyoso security \
 # See examples/codex-config.toml
 [mcp_servers.kyoso]
 command = "npx"
-args = ["-y", "@kyo-so/cli", "mcp", "--network", "model_only"]
+args = ["-y", "--package=@kyo-so/cli", "kyoso", "mcp"]
 ```
 
 client request 示例：
@@ -210,8 +212,8 @@ Use Kyoso plan_review on this plan and the selected auth files. I need a second
 ## MCP
 
 ```bash
-npx @kyo-so/cli mcp --network model_only
-bunx @kyo-so/cli mcp --network model_only
+npx -y --package=@kyo-so/cli kyoso mcp --network model_only
+bunx --package @kyo-so/cli kyoso mcp --network model_only
 ```
 
 省略 `--network` 时，Kyoso 使用 `model_only`。这意味着 Kyoso 期望 backend agents 只产生 model-provider traffic。这是 policy-level constraint，不是 OS-level network isolation。
@@ -228,13 +230,19 @@ MCP stdout 专用于 protocol messages。Logs 会写到 stderr 或 local audit t
 
 内置的 `kyoso-review` skill 有意保持范围很窄。只有当你明确请求 Kyoso、multi-agent review、plan review、security review、CISA Secure by Design review 或 diff review 时，才应触发它。
 
-Skill使用第一个可用路径，顺序是Kyoso MCP tools、PATH上已安装的`kyoso`、`npx -y @kyo-so/cli`、`bunx @kyo-so/cli`。package runner fallback可能需要network access，也可能发生version drift，因此MCP-less正常路径应使用已安装CLI。如果 typed [review contract](#review-contract-与-finding-admission) 包含non-goals或accepted risks且MCP不可用，CLI fallback只能保留`focus`，因此Skill会停止。
+Skill使用第一个可用路径，顺序是Kyoso MCP tools、PATH上已安装的`kyoso`、`npx -y --package=@kyo-so/cli kyoso`、`bunx --package @kyo-so/cli kyoso`。package runner fallback可能需要network access，且未 pin 时可能解析到更新 release，因此MCP-less正常路径应使用已安装CLI。如果 typed [review contract](#review-contract-与-finding-admission) 包含non-goals或accepted risks且MCP不可用，CLI fallback只能保留`focus`，因此Skill会停止。
 
 `kyoso setup codex --write --skill-only`默认将canonical Skill directory复制到`.agents/skills/kyoso-review/`。添加`--global`后复制到`~/.agents/skills/kyoso-review/`。
 
 `kyoso setup claude-code --write --skill-only`默认复制到`.claude/skills/kyoso-review/`。添加`--global`后复制到`~/.claude/skills/kyoso-review/`。
 
-managed install会把canonical directory digest和CLI version记录到`.kyoso-install.json`。当前或已知historical copy会被adopt并自动更新；修改过或未知的copy会报告conflict并保持不变。`--force`只替换该Skill directory，不会删除或覆盖MCP配置。
+managed install会把canonical directory digest和CLI version记录到`.kyoso-install.json`。当前或已知historical copy会被adopt并自动更新；修改过或未知的copy会报告conflict并保持不变。`--force`可以替换该managed Skill。它对manual MCP的唯一例外是下文的有限迁移：绝不会重写custom或unknown注册、所选安全目标之外的global／nested注册，或Marketplace Plugin／cache。
+
+### 手动 MCP 迁移
+
+先运行 `kyoso setup codex` 或 `kyoso setup claude-code` 检查现有注册。dry-run 与 `--write` 会保留所有现有 MCP entry。`--write --force` 会把环境字段限于生成时allowlist的完全匹配 legacy npx Kyoso command迁移为上文的显式package-and-executable形式。对于完全匹配的 legacy bunx command，省略 `--runner` 会保留它且不执行probe；使用 `--write --runner bunx --force` 可验证 Bun 并迁移为显式 bunx，或使用 `--write --runner npx --force` 有意迁移为 npx。每种迁移都会保留 legacy command 中的 complete SemVer pin。对于当前的显式bunx注册，可运行`--write --runner bunx`；setup会验证Bun且不改变注册bytes。
+
+`--force` 只能替换 managed Skill，并按上述runner policy迁移安全且完全匹配的 legacy MCP entry。它绝不会修改`NODE_OPTIONS`等可能改变execution的env、custom `--command` entry、unknown structure、所选安全目标之外的 global / nested registration，或 Marketplace Plugin / cache。`kyoso doctor` 不会把保留的 entry 标记为 ready，而会显示为 `legacy`、`custom-unverified` 或 `unknown`；请依据 examples 手动修复后再运行 doctor。
 
 ## Review contract 与 finding admission
 
@@ -537,7 +545,7 @@ Windows，以及无法证明所需 filesystem capability 的环境，会 fail-cl
 ## Troubleshooting
 
 - MCP timeout: client timeout应长于review-wide deadline。35分钟preset在Codex中使用2160秒，在Claude Code中使用`MCP_TOOL_TIMEOUT=2160000`。请参阅[Timeouts](#timeouts)。
-- Fresh npm release: safe-chain 等 minimum-package-age protection 可能会在 publish 后短时间内 block `npx @kyo-so/cli` resolution。
+- Fresh npm release: safe-chain 等 minimum-package-age protection 可能会在 publish 后短时间内 block `npx -y --package=@kyo-so/cli@<version> kyoso`。请等待该 exact version，不要 fallback 到 `latest` 或 ambient `kyoso`。
 - 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 `0.4.0` 及更高版本会将此变量名 forward 给 Kyoso process，旧版本不会。setup 也不会重写已有 MCP registration。
 

package/dist/acp/AcpAgentProcess.d.ts

@@ -4,7 +4,10 @@ import { BaseAcpAgentManager } from "./AcpAgentManager.js";
 export declare class SubprocessAcpAgentManager extends BaseAcpAgentManager {
     private readonly config;
     private readonly parentEnv;
-    constructor(config: KyosoConfig, parentEnv?: NodeJS.ProcessEnv);
+    private readonly internalOptions;
+    constructor(config: KyosoConfig, parentEnv?: NodeJS.ProcessEnv, internalOptions?: {
+        openRouterBaseUrlForTest?: string;
+    });
     runAgent(input: AgentRunInput): Promise<AgentRunResult>;
 }
 export declare function readWorkspaceFile(workspaceDir: string, requestedPath: string, line?: number | null, limit?: number | null): Promise<string>;

package/dist/acp/AgentOutputAccumulator.d.ts

@@ -0,0 +1,29 @@
+export type MessagePhase = "commentary" | "final_answer" | "unknown";
+export type AgentOutputMetrics = {
+    observedStreamRetries: number;
+    discardedRetryMessageBytes: number;
+    firstOutputAt?: string;
+    lastAcpUpdateAt?: string;
+};
+export declare class AgentOutputAccumulator {
+    private readonly segments;
+    private readonly messageChunks;
+    private retryEpoch;
+    private observedStreamRetries;
+    private discardedRetryMessageBytes;
+    private firstOutputAt;
+    private lastAcpUpdateAt;
+    private nextChunkSequence;
+    addMessageChunk(text: string, meta: {
+        messageId?: string;
+        phase?: MessagePhase;
+    }): void;
+    addThoughtChunk(_text: string): void;
+    noteUpdate(): void;
+    markRetryBoundary(): {
+        discardedMessageBytes: number;
+    };
+    finalRawText(): string;
+    metrics(): AgentOutputMetrics;
+    private noteOutput;
+}

package/dist/acp/codexRetryUpdate.d.ts

@@ -0,0 +1,6 @@
+export type CodexRetryUpdate = {
+    message: string;
+    attempt?: number;
+    maxRetries?: number;
+};
+export declare function parseCodexRetryUpdate(update: unknown): CodexRetryUpdate | undefined;