@kasenri/dsh-orbit

Usage

The orbit_controller tool drives the run:

Action	Meaning
run / start	Start a run for a goal (or continue the current one).
resume	Continue the persisted run after an interruption.
status	Inspect phase, plan, loop budget and last error.
stop	Close the run.
doctor	Read-only environment and configuration checks.

// orbit_controller
{
  "action": "run",
  "goal": "…",
  "approved_loop_count": 4,
  "user_hard_constraints": ["only touch src/"]
}

Model configuration (Web)

The Orbit model control is the final entry in conversation.input.right, so other composer-side controls (for example DSH's rollback control) stay to its left while the native conversation.input.model seat stays immediately to its right. Its button names the Commander's model. The first-level menu stays compact: Orbit toggle, Commander, Executor, Watchdog, and one MoA 多候选模式 entry. All Candidate/Judge details live in the MoA second-level menu.

• Commander and Watchdog pick from the same native model catalog and persist into the DSH orbit settings namespace (settings.yaml). Picking a model first opens reasoning selection; nothing is saved until the user chooses a catalog-declared effort or provider default. No effort is inferred.
• Executor follows the current session model ("Follows current session model"). Both the Orbit row and the native seat read and write the SAME per-session ModelDirectory, so a change in either place updates the other.
• MoA Candidate / Judge routes appear only inside the MoA second-level menu. Candidate count and max-MoA-step values use explicit selectors instead of click-to-cycle controls.

A new run resolves its routes exactly once — Commander/Watchdog from orbit settings, Executor from the initiating session's current selection — and freezes them into state.routes. Orbit ships no provider/model or reasoning defaults. Changes made while a run is active apply to the next run; resumed runs keep their frozen routes. Explicit profile routes are permitted for headless/CLI: Commander/Watchdog use settings then explicit config; Executor uses the Session selection, with explicit config only when there is no Session. Missing or unavailable roles block creation of a Run before any child starts.

Optional MoA execution mode

需要额外安装 @goodandready/dsh-moa。只安装 Orbit 时，SINGLE 模式仍然完整可用。

Orbit 可以把少量高不确定性步骤标记为 execution_mode: "MOA"。这不是新的顶层 Supervisor，也不会把状态机交给 MoA：

Commander PLAN
      ↓
SINGLE ─────────────→ Executor
      \
       MOA → Candidate 1 ─┐
             Candidate 2 ─┼→ Judge → Orbit controlled promotion → Executor verification
             Candidate 3 ─┘
                                              ↓
                                      Commander STEP_EVALUATE

关键边界：

• Candidate 和 Judge 都是零工具的一次性模型调用，不能直接 write/edit/bash/subagent。
• 候选文件只写入 .cx/moa///candidate-N/，普通 Executor 不能修改 .cx。
• Judge 只负责在已有候选中做相对选择，必须返回 WINNER_CANDIDATE_INDEX；它不能决定 PASS_CURRENT_STEP，也不能生成新的综合实现。
• 胜出候选由 Orbit Supervisor 确定性提升到项目目录；之后仍由 Executor 运行真实测试，最后由 Commander 做绝对验收。
• 整个 MoA Step 只消耗一个 Orbit loop；候选和 Judge 的内部调用受独立的候选数和 maxMoaSteps 限制。
• 候选数固定为 2–4；至少需要 2 个成功候选。失败不会偷偷回退成单 Executor，也不会自动换 Judge 模型。
• peerCritique 默认关闭；开启时只允许一轮有界互评。
• 新 Run 会冻结 Candidate/Judge 的 provider、model、reasoningEffort、MoA policy，以及原版 MoA settings 中用户显式配置的价格表（如果存在）。中途修改 UI 只影响下一次 Run。
• Candidate/Judge 的 input/output/cache Token 来自 DSH 子 Session 的真实 assistant/message.usage；如果冻结的价格表能匹配对应 Route，同时记录美元成本；没有价格时只展示 Token，并明确标记无法计算成本，不猜价格。
• Orbit 会把一个不含目标正文、候选正文、Judge 推理或代码的有界运行快照写进所属 DSH Session projection。v0.6.1 的配置首页不再直接展开这些运行详情，而是保持紧凑；运行快照仍保留给会话恢复与后续运行态界面使用。
• 冷恢复按 durable phase 继续：JUDGE 不重跑 Candidate，SELECTED 不重跑 Candidate/Judge，PROMOTED 不重跑 Candidate/Judge/Promotion。
• Orbit ACTIVE 时会在下游 hook 之前阻止独立 /moa，避免原版 MoA 的自动 Promotion 与 Orbit 同时争夺 workspace。
• @goodandready/dsh-moa 是可选依赖；未安装时普通 SINGLE 模式完全不受影响。

当前兼容层接受 @goodandready/dsh-moa >=0.2.19，并已在 0.2.19 与 0.2.20 上完成真实 DSH 烟雾验证。更高版本不再被 Orbit 主动版本上限拦截；若上游未来发生实际 API 不兼容，再按真实故障修正。Orbit 只依赖它公开的项目上下文接口；候选调度、Judge、持久化与 Promotion 权限均由 moa-adapter.ts 封装。

Configuration

Key	Default	Meaning
projectDir	session cwd	Project the run operates on.
routes.commander	none	Explicit profile fallback; normally user-selected in Orbit settings.
routes.executor	none	Explicit config only without a Session; otherwise follows DSH Session selection.
routes.watchdog	none	Explicit profile fallback; normally user-selected in Orbit settings.
moa.enabled	false	允许 Commander 为关键步骤选择 MOA 执行模式。
moa.candidateCount	3	固定候选数量，运行时只允许 2–4。
moa.candidates	none	用户显式选择的 Candidate routes；不会从 Executor 猜测或继承。
moa.judge	none	用户显式选择的 Judge route。
moa.peerCritique	false	是否启用一轮有界候选互评。
moa.maxMoaSteps	2	一个 Run 最多允许的 MoA 步骤数（上限受 1–5 步 Plan 约束）。
MoA prices	none	若 dsh-moa settings 已配置 prices，Orbit 在新 Run 冻结该表并据真实 Token 计算成本；否则不估价。
executorTools	read/read_image/glob/grep	Base read-only subset; mutation tools require Step capabilities.
browserTools	["agent_browser"]	Browser capability tool names.
commanderReadOnlyTools	read/glob/grep/web…	Commander allowlist.
watchdogTools	read/glob/grep	Watchdog allowlist.
executorTimeoutMs	480000	Deterministic executor runtime timeout.
registerTool	true	Register the orbit_controller tool and the legacy cx_controller alias.
registerGuards	true	Register recoverable tool guards.
slashCommand	true	Register the /agent-orbit host command and the gesture boundary.

Routes are normal DSH model routes; configure them for your own provider and model identifiers. No credentials are included in this package.