Host Codex Commander Skeleton

本文定义 host Codex 指挥官的本地 skeleton 阶段。当前只提供 /health、/api/commander/contract、.state/commander/ 状态读写、trace summary dry-run 聚合和 approval draft preview；不接 live bridge，不发送 ClaudeQQ，不接管人工指挥官。

边界

host-codex-commander 是独立的本地 skeleton，不是运行中的 live daemon。
只允许本地文件状态、trace 摘要和审批草案预览。
所有输出必须 redaction token/secret/URL credential。
不得重启或接管 Code Queue backend，不得 cancel/interrupt 运行任务，不得打印 token 明文。

CLI

bun scripts/cli.ts commander contract
bun scripts/cli.ts commander plan --dry-run [--session-id primary]
bun scripts/cli.ts commander smoke --dry-run [--session-id primary]
bun scripts/cli.ts commander approval request --action <action> --dry-run [--reason text] [--task-id id]

plan、smoke 与 approval request 必须显式使用 --dry-run，缺失时返回 error=dry-run-required。

Dev 验证计划

commander smoke --dry-run 是无 daemon smoke contract。它只输出验证计划，不启动 HTTP daemon、不打开 SSH/PTY/stdio bridge、不发送 ClaudeQQ、不重启服务、不 interrupt/cancel 任务、不部署、不跑全量 check/e2e。

需要验证的 source/contract 面：

health endpoint：用 createCommanderRequestHandler 和临时 RuntimeConfig 调用 GET /health，期望返回 service=host-codex-commander、stateRoot 和日志文件路径；禁止 Bun.serve 和端口监听。
state file：只在临时目录写读 sessions/<sessionId>.json、events/<sessionId>.jsonl 和 approvals/draft.json，确认 session 状态和 redaction round-trip；禁止触碰真实 .state/commander/。
trace summary dry-run：只喂 mock JSONL 给 summarizeCommanderTrace，确认 taskId、sessionId、lastSeq、status、redactionsApplied 和有界摘要；禁止读取 live Code Queue trace、标记已读、interrupt 或 cancel。
approval draft preview：只运行 commander approval request --dry-run 或 buildCommanderApprovalDraft，确认 requiresExplicitUserApproval=true、claudeqq.mutation=false、sendImplemented=false 和敏感信息脱敏；禁止 POST ClaudeQQ。
SSH bridge boundary：只检查 commander plan --dry-run 中 bridge.mutation=false、startPlan.enabled=false 和 safetyBoundary.phaseOneMutationAllowed=false；禁止打开 SSH、PTY 或 stdio bridge。

轻量契约测试是：

bun scripts/host-codex-commander-no-daemon-smoke-contract-test.ts

该测试只执行 CLI dry-run 和短命 source-level handler/helper，不启动长期进程。

HTTP

Method	Path	说明
GET	`/health`	返回 service id、启动时间、state root 和日志文件
GET	`/api/commander/contract`	返回机器可读 contract
GET	`/api/commander/sessions`	读取本地 session 摘要
POST	`/api/commander/state`	写入本地 session state
GET	`/api/commander/trace-summary`	对 mock trace JSONL 做 dry-run 摘要
POST	`/api/commander/trace-summary`	读取 mock trace JSONL 并更新本地 session 状态
POST	`/api/commander/approvals`	生成 approval draft preview 并落盘

State

状态根目录固定为 .state/commander/，至少包含：

sessions/<sessionId>.json
events/<sessionId>.jsonl
approvals/<approvalId>.json
logs/commander.jsonl

session 状态只保留 unknown、discovered、planned、starting、running、attention_required、stopping、stopped、degraded。

Trace summary

trace summary 输入 mock Code Queue trace JSONL 和可选 task summary，输出：

taskId
sessionId
lastSeq
status
keyEvents
openQuestions
recommendedNextActions
redactionsApplied

输出只做摘要，不返回 live transcript。

Approval draft

高风险动作只生成 approval draft JSON / Markdown preview。preview 必须显示 redaction 结果，并明确 sendImplemented=false。

进入真实运行态前

启用 daemon、PTY/stdio bridge、SSH bridge 或 ClaudeQQ 发送路径前，必须先获得人工授权。授权必须绑定一个精确 action 和目标 session/task/service，已有 smoke/skeleton contract 通过，风险审查确认不会打印 token、不会直接 patch 数据库、不会绕过 backend 确认策略，并且已有可审计的 approval id、回滚步骤和观测步骤。

4.4 KiB Raw Blame History