Skip to content

fix(delegation): use the active CLI for bootstrap and follow-ups - #433

Open
AIR-hl wants to merge 1 commit into
BytePioneer-AI:mainfrom
AIR-hl:codex/fix-delegation-cli-invocation
Open

AIR-hl wants to merge 1 commit into
BytePioneer-AI:mainfrom
AIR-hl:codex/fix-delegation-cli-invocation

Conversation

@AIR-hl

@AIR-hl AIR-hl commented Sep 28, 2026

Copy link
Copy Markdown
Contributor

Packaged installations can fail before delegation starts because the Skill invokes a bare codexhost. A global npm installation can instead select another installation's CLI. Shipped v4 Skills also remain stuck because their digest is missing from the managed upgrade list.

This fixes bootstrap and follow-up invocation while preserving the current main branch's watch instructions and user-edited Skill protection.

Changes

  • Use the Host-provided CLI in Skill bootstrap, mention instructions, help and environment-recovery guidance. Recognize shipped v4/v7/v8 Skill fixtures and upgrade to v9.
  • Format JSON next.read / next.wait at the invoking CLI boundary, using its local executable paths rather than a potentially remote Runtime's paths. Quote executable paths and Thread arguments. Missing paths remain explicit environment references; they never fall back to PATH. Compact output and Runtime API shapes stay unchanged.
  • For npm installations, select the npm JavaScript launcher with its matching Node executable, supplied through optional CODEXHOST_CLI_NODE_PATH. Forward the pair through the broker and native delegation surfaces; Cursor executes the pair directly. Native packaged CLI invocation clears a stale Node override.
  • Keep POSIX, PowerShell and cmd bootstrap guidance explicit. Generated follow-ups use POSIX syntax on macOS/Linux and PowerShell on Windows; other shells need syntax adaptation.

Related PR

Related to #223, which identified the packaged CLI/PATH mismatch and missing v4 digest. This is an alternative implementation against current main, sharing that diagnosis and extending coverage to caller-local follow-ups, an explicit npm Node/script pair, mention and environment guidance, and executable regression tests. It does not require merging #223 first.

Validation

On macOS arm64:

  • npm run typecheck; changed-file ESLint/Prettier; node tools/check-boundaries.mjs; cargo fmt --all --check; git diff --check: passed.
  • cargo check --locked --package codexhost-launcher: passed.
  • Vitest with tests/vitest.config.js --maxWorkers=1: 129 tests passed across 11 focused CLI, Skill, Runtime, broker, Cursor, CodeBuddy, WorkBuddy and npm-release files.
  • Regression cases execute installed Skill bootstrap and returned read/wait commands with an empty PATH or stale CLI, literal spaces/quotes/dollar signs, and native or Node-script entry points. They also verify shipped-template migration and broker forwarding.
  • A downstream macOS installer containing the same fixes passed signature/DMG verification, two native updater checks on a disposable old-app copy, and packaged CLI start → returned read/wait commands against a local fixture HTTP Runtime.

The pre-existing Cursor shutdown test hit its one-second process-start wait under concurrent build/test load; it passed in isolation and in the complete focused run with one worker. No native Windows/Linux or real-model cross-Harness end-to-end run was performed; Windows coverage here checks command rendering and generated npm launcher behavior.

@coderabbitai

coderabbitai Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository: BytePioneer-AI/codex-host/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 57ab356f-0ee0-417c-b327-afdbd2c5b950

📥 Commits

Reviewing files that changed from the base of the PR and between 636b501 and 3d8d326.

📒 Files selected for processing (28)
  • crates/launcher/src/main.rs
  • docs/architecture/harness-executable-discovery.md
  • openspec/specs/cross-harness-delegation/spec.md
  • packages/adapters/codebuddy/src/command.ts
  • packages/adapters/cursor-cli/src/delegation-bridge.ts
  • packages/adapters/cursor-cli/test/delegation-bridge.test.ts
  • packages/adapters/hermes/src/gateway-delegation.ts
  • packages/adapters/workbuddy/src/delegation.ts
  • packages/harness-broker/src/client.ts
  • packages/harness-broker/src/validation.ts
  • packages/harness-broker/test/broker-recovery.test.ts
  • packages/host-runtime/src/delegation-cli-help.ts
  • packages/host-runtime/src/delegation-cli-invocation.ts
  • packages/host-runtime/src/delegation-cli.ts
  • packages/host-runtime/src/delegation-mention-rewrite.ts
  • packages/host-runtime/src/delegation-skill.ts
  • packages/host-runtime/src/delegation-types.ts
  • packages/host-runtime/src/index.ts
  • packages/host-runtime/src/run-host-runtime.ts
  • packages/host-runtime/test/delegation-cli-invocation.test.ts
  • packages/host-runtime/test/delegation-cli.test.ts
  • packages/host-runtime/test/delegation-mention-rewrite.test.ts
  • packages/host-runtime/test/delegation-skill.test.ts
  • packages/host-runtime/test/fixtures/codexhost-delegation-v4.md
  • packages/host-runtime/test/fixtures/codexhost-delegation-v7.md
  • packages/host-runtime/test/fixtures/codexhost-delegation-v8.md
  • scripts/release/prepare-npm.mjs
  • tests/release/npm-package.test.mjs

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

📜 Recent review details
⏰ Context from checks skipped due to timeout. (4)
  • GitHub Check: Check ubuntu-22.04
  • GitHub Check: Check macos-14
  • GitHub Check: Check windows-latest
  • GitHub Check: Check Linux ARM64
🧰 Additional context used
🪛 ast-grep (0.45.3)
packages/adapters/cursor-cli/src/delegation-bridge.ts

[warning] Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import { execFile, type ChildProcess } from "node:child_process";
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').

(detect-child-process-typescript)

packages/host-runtime/test/delegation-skill.test.ts

[warning] Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import { spawnSync } from "node:child_process";
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').

(detect-child-process-typescript)

packages/host-runtime/test/delegation-cli-invocation.test.ts

[warning] Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import { spawnSync } from "node:child_process";
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').

(detect-child-process-typescript)

🪛 OpenGrep (1.30.0)
packages/host-runtime/test/delegation-skill.test.ts

[ERROR] 74-74: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.

(coderabbit.command-injection.exec-js)


📝 Summary

Summary by CodeRabbit

  • 功能更新
    • 委派任务现在通过 Host 提供的 CLI 入口调用,可在未安装额外 npm CLI 或系统 PATH 中存在旧版 CLI 时正常使用。
    • 支持通过指定的 Node.js 可执行文件启动 CLI,并在不同平台生成后续读取和等待命令。
  • 文档
    • 补充 CLI 调用方式、环境配置及故障排查说明。

Walkthrough

委派 CLI 现在通过 Host 提供的路径调用。npm 安装可通过指定的 Node 路径启动 CLI。Host Runtime 根据环境生成后续 Thread 命令,委派规范和 Skill 指引也已更新。

Changes

委派 CLI 调用

Layer / File(s) Summary
Node 路径传递与适配器调用
crates/launcher/src/main.rs, packages/host-runtime/src/delegation-types.ts, packages/harness-broker/src/*, packages/adapters/*, scripts/release/prepare-npm.mjs, tests/release/npm-package.test.mjs
新增 CODEXHOST_CLI_NODE_PATH 的定义、验证和环境转发。适配器及 npm 发布流程使用该变量启动 CLI;Host 启动的委派子进程会移除该变量。
运行时环境选择与后续命令生成
packages/host-runtime/src/delegation-cli-invocation.ts, packages/host-runtime/src/delegation-cli.ts, packages/host-runtime/src/run-host-runtime.ts, packages/host-runtime/test/delegation-cli-invocation.test.ts, packages/host-runtime/test/delegation-cli.test.ts
Host Runtime 选择 CLI 与 Node 路径,并为委派 JSON 结果生成 Thread read 和 wait 命令。测试覆盖环境选择、平台参数转义、命令执行及环境诊断。
委派指引与 Skill 更新
openspec/specs/cross-harness-delegation/spec.md, docs/architecture/harness-executable-discovery.md, packages/host-runtime/src/delegation-*.ts, packages/host-runtime/test/delegation-*.test.ts, packages/host-runtime/test/fixtures/codexhost-delegation-*
委派规范和 Skill 指引改为使用 Host 提供的 CLI 路径。Skill 版本升至 9;测试覆盖旧版 Skill 更新和通过指定路径调用 CLI。

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant HostRuntime
  participant DelegationCliEnvironment
  participant DelegationCli
  HostRuntime->>DelegationCliEnvironment: 选择 CLI 与 Node 路径
  DelegationCliEnvironment-->>HostRuntime: 返回子进程环境
  HostRuntime->>DelegationCli: 执行委派命令
  DelegationCli-->>HostRuntime: 返回 threadId 与 JSON 结果
  HostRuntime->>HostRuntime: 生成 Thread read 和 wait 命令
Loading

Suggested reviewers: bytepioneer-ai

Merge Risk: ⚪ Minimal · up to 3d8d3

No actionable issue is established that would prevent merging after normal checks. Native Windows/Linux and real cross-Harness execution remain unverified, but are not confirmed defects.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 3d8d3

The change should make delegation use the active installation rather than another CLI on the user's PATH. Ordinary user edits to installed guidance remain protected, but a concurrent edit can be overwritten during an eligible upgrade. No externally reachable attack path was established.

Retained concerns

  • Low · security · inferred: Newly eligible legacy Skill copies can enter a pre-existing read-then-replace path that may overwrite a concurrent user edit. The ordinary conflict check does not revalidate ownership immediately before replacement.
Security review details

Security Blast Radius

  • inferred — The directly evidenced executable-selection scope is a delegated CLI process and, for forwarded sessions, its broker-connected adapter. The inspected paths do not establish tenant-wide or independently remote control of the new Node variable.

Security Findings and Attack Paths

  • inferred — A user edit made after the installer reads a newly eligible legacy Skill, but before its rename, can be replaced by the managed copy. This expands exposure to an existing ownership race; the normal path preserves content whose digest is not recognized.

Trust Boundaries and Controls

  • observed — The broker's opt-in allowlist and strict environment schema restrict forwarded variable names, not executable provenance. Cursor checks that supplied CLI and Node paths are absolute and invokes them without a shell, with a timeout and output limit.

Resilience and Maintainability Implications

  • observed — The Skill writer uses a temporary file and rename, but its two destination updates are not transactional; verification occurs after replacement.

Hardening Proposals

  • proposed — Revalidate destination ownership immediately before a managed Skill replacement, and ensure temporary-file cleanup covers write and sync failures as well as rename failures.
🚥 Pre-merge checks | ✅ 4
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed 标题准确概括了主要变更:委派启动和后续操作使用当前活动的 CLI。标题简洁、明确,并与变更内容一致。
Description check ✅ Passed 描述详细说明了 CLI 选择、Skill 升级、后续命令生成、Node 路径转发和测试结果,内容与变更集直接相关。
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create a new PR

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant