@akagilnc/pi-workflow-roles 0.1.5127 → 0.1.5139

package/README.md

@@ -25,7 +25,7 @@ ak-role judge --model <provider/model[:thinking]> --attach ./plan.md "Review thi
 
 Exit status reports lifecycle honesty, not business success: every lawful typed result (including `audit_escalation`) exits zero; a failure without a lawful result exits nonzero, and its Terminal carries the Error Artifact ref and original cause instead of a fabricated receipt.
 
-`ak-role resume <runId> [message]` reopens that run under the **current seat table** for model / host / engine — the same resolution as starting a new leg (model: `--model` → persistent seat → officer inherit; still none → error. host: `--host` → persistent seat host → package default `pi`). Configure seats first with `ak-role config set <seat> <provider/model[:thinking]>` or pass `--model` per invocation. Standard chain after a role `escalate`s: take the owner ruling and feed it back with `ak-role resume <runId> "<ruling>"` so the same run continues to a terminal. For every callable seat, including Notary/符宝郎, the optional `message` after `runId` is passed through unchanged as the continuation prompt (opaque: not parsed as flags); when omitted, the package adds no continuation text. Notary's separate explicit `new` command still accepts only its source-run locator, not a caller prompt. Global `--model` / `--thinking` / `--host` / `--engine` override the table for that resume only — place them before `<runId>` (either before `resume` or between `resume` and `<runId>`, e.g. `ak-role --model xai/grok-4.5 resume 01abc…` or `ak-role resume --model xai/grok-4.5 01abc…`); the one argv after `<runId>` is always the opaque message, never a flag (#471). On a real host switch (live seat host differs from the previous invocation host), prior native records of the previous host are delivered once as context to the target host; same-host resume does not re-inject. Each host writes only its native volume (Pi: `session/session.jsonl`; Grok CLI journals stay in the operator grok home, factory dossier is sitian records on the run), with unified ledger entries recorded in 司天台 (Sitian). Whether to resume is the caller's decision: the command does not require a typed HTTP 429 or a `resumable` state. Unknown run IDs and missing session principals are rejected. Every callable role accepts manual resume; Countersign and Gleaner-Left gained it in #599, Collector, Doctor, Notary, and Inspector in #633.
+`ak-role resume <runId> [message]` reopens that run under the **current seat table** for model / host / engine — the same resolution as starting a new leg (model: `--model` → persistent seat → officer inherit; still none → error. host: `--host` → persistent seat host → package default `pi`). Configure seats first with `ak-role config set <seat> <provider/model[:thinking]>` or pass `--model` per invocation. Standard chain after a role `escalate`s: take the owner ruling and feed it back with `ak-role resume <runId> "<ruling>"` so the same run continues to a terminal. For every callable seat, including Notary/符宝郎, the optional `message` after `runId` is passed through unchanged as the continuation prompt (opaque: not parsed as flags); when omitted, the package adds no continuation text. Notary's separate explicit `new` command still accepts only its source-run locator, not a caller prompt. Global `--model` / `--thinking` / `--host` / `--engine` override the table for that resume only — place them before `<runId>` (either before `resume` or between `resume` and `<runId>`, e.g. `ak-role --model xai/grok-4.5 resume 01abc…` or `ak-role resume --model xai/grok-4.5 01abc…`); the one argv after `<runId>` is always the opaque message, never a flag (#471). On a real host switch (live seat host differs from the previous invocation host), prior native records of the previous host are delivered once as context to the target host; same-host resume does not re-inject. Each host writes only its native volume (Pi: `session/session.jsonl`; Grok CLI journals stay in the operator grok home, factory dossier is sitian records on the run), with unified ledger entries recorded in 司天台 (Sitian). Whether to resume is the caller's decision: the command does not require a typed HTTP 429 or a `resumable` state. Unknown run IDs are rejected. Any other resume failure prints one line pointing at that attempt's error record (`续跑失败，当次错误记录：<path>`); open the file for the cause. Every callable role accepts manual resume; Countersign and Gleaner-Left gained it in #599, Collector, Doctor, Notary, and Inspector in #633.
 
 All callable roles also retry a non-lawful LLM call in place (same `runId` and session) up to `autoResumeLimit` times. Unset defaults to 2; `ak-role config set-auto-resume-limit <N>` writes the ceiling (`0` disables). Lawful typed terminals (`accepted`, `audit_escalation`, `no_receipt`) stop immediately. Manual `ak-role resume` stays available.
 
@@ -40,8 +40,8 @@ ak-role config set inspector <provider/model[:thinking]>
 ak-role config set notary <provider/model[:thinking]>
 ak-role config unset gatekeeper
 # persistent labor engine (callable roles); one-shot override remains --engine
-# optional model id for multi-model engines (cursor/opencode/agy); omit for name-is-model engines
-ak-role config set-engine judge opus
+# optional model id is a separate coordinate from the CLI engine name
+ak-role config set-engine judge claude-code
 ak-role config set-engine coder cursor cursor-grok-4.6-high
 ak-role config set-engine-model coder cursor-grok-4.6-high
 ak-role config unset-engine-model coder

package/README.zh-CN.md

@@ -25,7 +25,7 @@ ak-role judge --model <provider/model[:thinking]> --attach ./plan.md "Review thi
 
 退出码报的是生命周期诚实，不是业务成败：一切合法 typed 终态（含 `audit_escalation`）退出零；无合法终态的失败退出非零，其 Terminal 携带 Error Artifact 引用与原始原因，不伪造回执。
 
-`ak-role resume <runId> [message]` 按**现行席位表**的 model / host / engine 续跑该次运行——与新起角色腿同一解析（model：`--model` → 席位持久 → 官席继承；仍无则报错。host：`--host` → 席位持久 host → 包默认 `pi`）。先 `ak-role config set <seat> <provider/model[:thinking]>` 配席，或逐次带 `--model`。角色 `escalate`（直通御前）后拿到 owner 裁定，标准续跑是 `ak-role resume <runId> "<裁定>"`——把裁定喂回同一 run，角色继续走到终局。所有可调用席位（包括 Notary/符宝郎）都会将 `runId` 后可选的 `message` 原样作为续跑 prompt（opaque：不进全局旗标语法）；省略时包不会添加续跑文本。Notary 另行的显式 `new` 命令仍只接受 source-run locator，不接受 caller prompt。全局 `--model` / `--thinking` / `--host` / `--engine` 仅覆盖本次 resume——须置于 `<runId>` 之前（放 `resume` 之前或 `resume` 与 `<runId>` 之间均可，例如 `ak-role --model xai/grok-4.5 resume 01abc…` 或 `ak-role resume --model xai/grok-4.5 01abc…`）；`<runId>` 之后的那一个 argv 恒为原样透传的 message，绝非旗位（#471）。真实换宿主时（现行席位 host 与上一次 invocation host 不同），将前序宿主原生卷宗一次性作为 context 交付目标宿主；同宿主续跑不重复注入。各宿主仅直写自身原生卷宗（Pi：`session/session.jsonl`；Grok CLI 原始会话留在操作员 grok 家，工厂卷宗为该 run 的司天台记录），统一账目归入司天台。要不要续跑由调用者决定：不再要求 typed HTTP 429，也不要求 `resumable` 状态。未知 run ID、session 主体不在则拒绝。所有可调用角色均可手动 resume：给事中、左拾遗始于 #599，通进司、太医署、符宝郎、台院始于 #633。
+`ak-role resume <runId> [message]` 按**现行席位表**的 model / host / engine 续跑该次运行——与新起角色腿同一解析（model：`--model` → 席位持久 → 官席继承；仍无则报错。host：`--host` → 席位持久 host → 包默认 `pi`）。先 `ak-role config set <seat> <provider/model[:thinking]>` 配席，或逐次带 `--model`。角色 `escalate`（直通御前）后拿到 owner 裁定，标准续跑是 `ak-role resume <runId> "<裁定>"`——把裁定喂回同一 run，角色继续走到终局。所有可调用席位（包括 Notary/符宝郎）都会将 `runId` 后可选的 `message` 原样作为续跑 prompt（opaque：不进全局旗标语法）；省略时包不会添加续跑文本。Notary 另行的显式 `new` 命令仍只接受 source-run locator，不接受 caller prompt。全局 `--model` / `--thinking` / `--host` / `--engine` 仅覆盖本次 resume——须置于 `<runId>` 之前（放 `resume` 之前或 `resume` 与 `<runId>` 之间均可，例如 `ak-role --model xai/grok-4.5 resume 01abc…` 或 `ak-role resume --model xai/grok-4.5 01abc…`）；`<runId>` 之后的那一个 argv 恒为原样透传的 message，绝非旗位（#471）。真实换宿主时（现行席位 host 与上一次 invocation host 不同），将前序宿主原生卷宗一次性作为 context 交付目标宿主；同宿主续跑不重复注入。各宿主仅直写自身原生卷宗（Pi：`session/session.jsonl`；Grok CLI 原始会话留在操作员 grok 家，工厂卷宗为该 run 的司天台记录），统一账目归入司天台。要不要续跑由调用者决定：不再要求 typed HTTP 429，也不要求 `resumable` 状态。未知 run ID 则拒绝；其余续跑失败只输出一行指向当次错误记录的指针（`续跑失败，当次错误记录：<path>`），原因看该文件。所有可调用角色均可手动 resume：给事中、左拾遗始于 #599，通进司、太医署、符宝郎、台院始于 #633。
 
 全部可调用角色在单次调用内对非 lawful LLM 终态原地续跑（同一 `runId` 与 session），次数上限为 `autoResumeLimit`。缺键默认 2；`ak-role config set-auto-resume-limit <N>` 写入（`0` 关闭自动续）。lawful typed 终态（`accepted` / `audit_escalation` / `no_receipt`）立即停止。手动 `ak-role resume` 仍可用。
 
@@ -40,8 +40,8 @@ ak-role config set inspector <provider/model[:thinking]>
 ak-role config set notary <provider/model[:thinking]>
 ak-role config unset gatekeeper
 # 持久劳务引擎（可调用角色）；一次性覆盖仍用 --engine
-# 多模型引擎（cursor/opencode/agy）可附型号；名字即模型的引擎可省略
-ak-role config set-engine judge opus
+# 可选型号是独立坐标，与 CLI 引擎名分开指定
+ak-role config set-engine judge claude-code
 ak-role config set-engine coder cursor cursor-grok-4.6-high
 ak-role config set-engine-model coder cursor-grok-4.6-high
 ak-role config unset-engine-model coder

package/dist/acp-host/production-host.js

@@ -10542,7 +10542,7 @@ var init_option_definitions = __esm({
         examples: [
           "ak-role config set judge openai-codex/gpt-5.6-sol:high",
           "ak-role config unset gatekeeper",
-          "ak-role config set-engine judge opus",
+          "ak-role config set-engine judge claude-code",
           "ak-role config set-engine coder cursor cursor-grok-4.6-high",
           "ak-role config set-engine-model coder cursor-grok-4.6-high",
           "ak-role config set-host judge grok-build",

package/dist/headless-host/production-host.js

@@ -10003,7 +10003,7 @@ var init_option_definitions = __esm({
         examples: [
           "ak-role config set judge openai-codex/gpt-5.6-sol:high",
           "ak-role config unset gatekeeper",
-          "ak-role config set-engine judge opus",
+          "ak-role config set-engine judge claude-code",
           "ak-role config set-engine coder cursor cursor-grok-4.6-high",
           "ak-role config set-engine-model coder cursor-grok-4.6-high",
           "ak-role config set-host judge grok-build",

package/dist/migrate-book-topology.js

@@ -15802,7 +15802,7 @@ var init_option_definitions = __esm({
         examples: [
           "ak-role config set judge openai-codex/gpt-5.6-sol:high",
           "ak-role config unset gatekeeper",
-          "ak-role config set-engine judge opus",
+          "ak-role config set-engine judge claude-code",
           "ak-role config set-engine coder cursor cursor-grok-4.6-high",
           "ak-role config set-engine-model coder cursor-grok-4.6-high",
           "ak-role config set-host judge grok-build",

package/dist/public-cli/main.js

@@ -19808,7 +19808,7 @@ var init_option_definitions = __esm({
         examples: [
           "ak-role config set judge openai-codex/gpt-5.6-sol:high",
           "ak-role config unset gatekeeper",
-          "ak-role config set-engine judge opus",
+          "ak-role config set-engine judge claude-code",
           "ak-role config set-engine coder cursor cursor-grok-4.6-high",
           "ak-role config set-engine-model coder cursor-grok-4.6-high",
           "ak-role config set-host judge grok-build",

package/dist/public-cli/option-definitions.js

@@ -1082,7 +1082,7 @@ const SUPPORT_COMMAND_HELP = {
         examples: [
             "ak-role config set judge openai-codex/gpt-5.6-sol:high",
             "ak-role config unset gatekeeper",
-            "ak-role config set-engine judge opus",
+            "ak-role config set-engine judge claude-code",
             "ak-role config set-engine coder cursor cursor-grok-4.6-high",
             "ak-role config set-engine-model coder cursor-grok-4.6-high",
             "ak-role config set-host judge grok-build",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.5127",
+  "version": "0.1.5139",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/resources/engines/{opus.md → claude-code.md}

@@ -1,29 +1,29 @@
-# opus engine method material
+# claude-code engine method material
 
-This file is packaged technical material for the `opus` labor engine
-(Claude Code CLI on the host).
+This file is packaged technical material for labor using the Claude Code CLI
+on the host.
 
 Before invoking the engine, read `../engine-dispatch.md`, resolving that path
-relative to this note. This note only covers this engine's CLI technical
-parameters.
+relative to this note. This note only covers this CLI's technical parameters.
 
 ## Invocation examples (local Claude Code CLI)
 
-The machine entrypoint is `claude`. Run from the role project root. Non-interactive
-print mode (`-p` / `--print`) is verified available on this host.
+The machine entrypoint is `claude`. Run from the role project root.
+Non-interactive print mode (`-p` / `--print`) is verified available on this
+host.
 
-Print mode (`-p`) with `--output-format text` returns the labor body on stdout;
-stderr carries banners only. Measured with separate fd redirects (`1>` / `2>`).
+Print mode with `--output-format text` returns the labor body on stdout;
+stderr carries banners only. Measured with separate fd redirects (`1>` / `2>`):
 
 ```bash
-claude -p --output-format text "YOUR_LABOR_PROMPT"
+claude -p --dangerously-skip-permissions --output-format text "YOUR_LABOR_PROMPT"
 ```
 
-Pin the Opus model explicitly (`--model opus` verified accepted on this host;
-init event reports `claude-opus-5`):
+Pass the model requested by the labor mandate through `--model` when one is
+specified:
 
 ```bash
-claude -p --model opus --output-format text "YOUR_LABOR_PROMPT"
+claude -p --dangerously-skip-permissions --model <MODEL_ID> --output-format text "YOUR_LABOR_PROMPT"
 ```
 
 Use `--output-format text` (the default): stdout is the labor body and nothing
@@ -31,8 +31,9 @@ else. Never use `--output-format=stream-json` / `--verbose` for labor — the
 returned body goes back into the seat's context, and the event stream is noise:
 measured 2026-09-06 on this host, the same one-sentence task returned 382 bytes
 as `text` and 45,028 bytes as `stream-json --verbose` (118×); a 12-minute labor
-returned 957k chars and killed the seat with a 712k-token request (#675). Progress observability belongs to the runner's
-process watch, not to the returned body.
+returned 957k chars and killed the seat with a 712k-token request (#675).
+Progress observability belongs to the runner's process watch, not to the
+returned body.
 
 ## Headless permissions
 
@@ -42,7 +43,7 @@ particular, reading any path outside the project root — such as frozen
 attachments under `~/.ak-roles/books/<book>/runs/<run>/attachments/` — is
 refused without the flag ("The read was not permitted — I don't have access to
 that file outside the current worktree") and succeeds with it (host-verified
-2026-08-28, both directions).
+2026-08-28).
 
-Prefer `claude --help` on the host over any remembered flag set. Do not wrap this
-engine behind `ak-role` flags.
+Prefer `claude --help` on the host over any remembered flag set. Do not wrap
+this engine behind `ak-role` flags.

package/resources/engines/codex.md

@@ -11,12 +11,20 @@ parameters.
 
 The machine entrypoint is `codex`. Run from the role project root. Non-interactive
 labor uses `codex exec` (alias `e`). Always pass `--skip-git-repo-check` so the
-labor subprocess can start outside a Git work tree when needed:
+labor subprocess can start outside a Git work tree when needed. When the dispatch
+order specifies a model, pass it with `-m` / `--model`:
 
 ```bash
 codex exec --skip-git-repo-check "YOUR_LABOR_PROMPT"
 ```
 
+```bash
+codex exec --skip-git-repo-check -m <MODEL_ID> "YOUR_LABOR_PROMPT"
+```
+
+When no model is specified in the dispatch order, omit `-m` and let Codex use
+its configured default.
+
 For concurrent or disposable labor turns, add `--ephemeral` so session files are
 not persisted to disk:
 
@@ -33,7 +41,7 @@ codex exec --skip-git-repo-check --ephemeral -C "$PROJECT_ROOT" "YOUR_LABOR_PROM
 Default (non-`--json`) mode prints the session banner and progress on stderr
 (measured on this host). Collect the labor body from stdout so that stderr log
 noise is not mixed into the returned body. Never use `--json` for labor: its
-JSONL event rows go back into the seat's context as noise (see `opus.md` for the
+JSONL event rows go back into the seat's context as noise (see `claude-code.md` for the
 measured ratio).
 
 Prefer `codex exec --help` on the host over any remembered flag set. Do not wrap

package/resources/engines/cursor.md

@@ -20,31 +20,22 @@ the Grok Build balance is exhausted).
 Run from the role project root. Non-interactive print mode; `-f/--force`
 allows command execution headlessly; `-p` prints responses for scripts:
 
+```bash
+cursor-agent -p -f --output-format text "YOUR_LABOR_PROMPT"
+```
+
+When the dispatch order specifies a model, pass it verbatim via `--model`:
+
 ```bash
 cursor-agent -p -f --output-format text --model <MODEL_ID> "YOUR_LABOR_PROMPT"
 ```
 
-- Model ids come from `cursor-agent models`. Effort tiers are encoded in the
-  id itself (e.g. `cursor-grok-4.6-low`, `cursor-grok-4.6-medium`,
-  `cursor-grok-4.6-high`, plus `-fast` variants); some models also accept a
-  bracket override form (`'claude-opus-4-8[context=1m,effort=high]'` — see
-  `cursor-agent --help`).
-- This note does not pin a model id. The dispatch order (owner pool
-  directive) names the model to pass verbatim via `--model`. If `--model
-  <MODEL_ID>` is not provided, please uses `cursor-grok-4.6-high`.
+- Model ids come from `cursor-agent models`. Effort tiers may be encoded in
+  the id; see `cursor-agent --help` for supported model-specific forms.
+- This note does not pin a model id. Without one in the dispatch order, omit
+  `--model` and let the CLI use its configured default.
 - Always `--output-format text`; never `stream-json` (the event stream goes back
-  into the seat's context as noise — see `opus.md`).
+  into the seat's context as noise — see `claude-code.md`).
 
 Prefer `cursor-agent --help` on the host over any remembered flag set. Do not
 wrap this engine behind `ak-role` flags.
-
-## Smoke test (run before first labor leg of a session)
-
-```bash
-cursor-agent -p -f --output-format text --model <MODEL_ID> "Reply with exactly one word: OK"
-```
-
-Expected: stdout ends with exactly `OK`, exit code 0. Mechanics verified
-2026-08-28 on this host (Cursor subscription login) with a dispatch-order
-model id substituted for `<MODEL_ID>`. If it asks about directory trust, the
-`-f` flag (or `--trust`) is missing.

package/resources/engines/grok.md

@@ -0,0 +1,74 @@
+# grok engine method material
+
+This file is packaged technical material for labor using the Grok CLI on the
+host.
+
+Before invoking the engine, read `../engine-dispatch.md`, resolving that path
+relative to this note. This note only covers this CLI's technical parameters.
+
+## Invocation examples (local Grok CLI)
+
+The machine entrypoint is `grok`. Run from the role project root.
+Non-interactive labor reads the prompt from a file and prints plain output:
+
+```bash
+grok --trust --prompt-file /path/to/labor-prompt.md --always-approve --output-format plain
+```
+
+When the dispatch order specifies a model, pass it with `-m`:
+
+```bash
+grok --trust --prompt-file /path/to/labor-prompt.md -m <MODEL_ID> --always-approve --output-format plain
+```
+
+When the dispatch order (or seat ordered thinking tier) supplies an effort
+tier, pass it with `--reasoning-effort` (alias `--effort`):
+
+```bash
+grok --trust --prompt-file /path/to/labor-prompt.md --reasoning-effort <EFFORT> --always-approve --output-format plain
+```
+
+- `-m <MODEL_ID>` selects the model; `grok models` lists valid ids. Without a
+  model in the dispatch order, omit `-m` and let the CLI use its configured
+  default.
+- `--reasoning-effort <low|medium|high>` is optional (`grok --help`). Pass it
+  only when the dispatch order or seat ordered thinking tier supplies a tier;
+  omit the flag otherwise. Do not invent a default effort or require seat
+  config to fill one (verified live 2026-08-21: flag exists; a low-tier run
+  completed correctly when a tier was ordered).
+- `--always-approve` (equivalently `--yolo` or `--permission-mode
+  bypassPermissions`) keeps the run non-interactive (documented). Headless
+  permissions otherwise default to interactive approval, where an `ask`
+  decision has no UI to answer; alternatively, use an explicit permission
+  setup that auto-approves the required call.
+- Official docs list `-p/--single` as the canonical headless prompt input;
+  `--prompt-file` exists in the installed CLI (`--help`) and is smoke-verified
+  on this host — prefer it for long prompts, fall back to `-p` if absent.
+- `--output-format plain` keeps stdout clean for capture and is the only
+  format to use for labor. Do not use `streaming-json`: its NDJSON deltas go
+  back into the seat's context as noise (see `claude-code.md` for the measured
+  ratio); progress observability belongs to the runner's process watch, not to
+  the returned body.
+- Feeding raw JSON directly through `--prompt-file` is rejected by the CLI as
+  non-ACP JSON (`JSON object must have a type field`; live-verified
+  2026-08-21).
+
+## MCP host behavior
+
+- Repository MCP entries live under `[mcp_servers.<name>]` in `.grok/config.toml`.
+  They take effect only after the folder is trusted; pass `--trust` on
+  unattended/headless invocations. Without it, the project server may be absent
+  even though the file is present (`live-1787838141494`), and `grok mcp doctor`
+  reports `folder untrusted…re-run with --trust` (`live-1787838491136`).
+- Diagnose server startup with `grok mcp doctor [<server>]`, then inspect
+  `~/.grok/logs/mcp/<server>.stderr.log`; Grok truncates that stderr log on
+  each stdio server launch.
+- MCP tools are exposed to the model as `<server>__<tool>` (for example,
+  `ak_489_coder__ak_coder_output`). Use the fully qualified name in prompts;
+  a bare tool name relies on the host's loose discovery/matching behavior.
+- The headless permission setting described above also covers MCP calls.
+- Grok launches a stdio server from the task cwd. Make `command` and `args`
+  cwd-independent: use absolute entrypoint paths and do not rely on resolving
+  a task-local `node_modules` binary. A cwd-dependent `tsx` launcher failed in
+  `live-1787838491136`; the absolute-path form completed the MCP route in
+  `live-1787838776163`.

package/resources/engines/hermes.md

@@ -67,17 +67,3 @@ hermes -z "YOUR_LABOR_PROMPT" --in /path/to/project --no-restore-cwd \
   01a046ec-*/01a046f4-*, 14:55-15:04 window).
   No concurrency ceiling has been measured beyond this observation; policy on
   concurrency and retries is the dispatcher's call, not this note's.
-
-## Smoke test (run before first labor leg of a session)
-
-```bash
-hermes -z "Reply with exactly one word: OK" --no-restore-cwd
-# long-prompt form used by labor legs:
-printf 'Reply with exactly one word: OK' > /tmp/smoke.txt
-hermes -z "$(cat /tmp/smoke.txt)" --no-restore-cwd
-```
-
-Expected: stdout is exactly `OK`, exit code 0. Verified 2026-08-28 on this
-host (model `poolside/laguna-s-2.1:free`, Nous Portal). If it fails, check
-`hermes status` (model/provider block) and `~/.hermes/provider_models_cache.json`
-for the current catalog; the interactive picker is `hermes model`.

package/resources/engines/{kimi.md → kimi-code.md}

@@ -1,7 +1,7 @@
-# kimi engine method material
+# kimi-code engine method material
 
-This file is packaged technical material for the `kimi` labor engine
-(Kimi Code CLI on the host).
+This file is packaged technical material for labor using the Kimi Code CLI on
+the host.
 
 Before invoking the engine, read `../engine-dispatch.md`, resolving that path
 relative to this note. This note only covers this engine's CLI technical
@@ -22,16 +22,16 @@ those flags to prompt-mode argv:
 kimi -p "YOUR_LABOR_PROMPT"
 ```
 
-Pin a model alias configured in the host `config.toml` when the seat needs a
-known Kimi model id (example alias shape measured: `kimi-code/k3-256k`):
+Pass the model requested by the labor mandate through `-m` when one is
+specified:
 
 ```bash
-kimi -m <model-alias> -p "YOUR_LABOR_PROMPT"
+kimi -m <MODEL_ID> -p "YOUR_LABOR_PROMPT"
 ```
 
 Use `--output-format text` (the default). Do not use `stream-json` for labor:
 the returned body goes back into the seat's context and the event stream is
-noise (see `opus.md` for the measured ratio). Progress observability belongs to
+noise (see `claude-code.md` for the measured ratio). Progress observability belongs to
 the runner's process watch, not to the returned body. Measured on this host
 with separate fd redirects (`1>` / `2>`): stdout is the labor answer body;
 stderr carries the version line, thinking bullets, and the trailing

package/resources/engines/opencode.md

@@ -10,12 +10,21 @@ parameters.
 ## Invocation examples (local OpenCode CLI)
 
 The machine entrypoint is `opencode`. Run from the role project root.
-Non-interactive labor uses `run` with `--auto` and an explicit model:
+Non-interactive labor uses `run` with `--auto`. When the labor order specifies
+an engine model, pass it with `-m`:
 
 ```bash
 opencode run --auto -m <MODEL_ID> "YOUR_LABOR_PROMPT"
 ```
 
+When no engine model is specified, omit `-m` and let OpenCode choose: it uses
+the model configured in OpenCode, then the last-used model, then its internally
+prioritized first model.
+
+```bash
+opencode run --auto "YOUR_LABOR_PROMPT"
+```
+
 - `--auto` is required: it auto-approves permissions that are not explicitly
   denied. Without it, any `ask` permission (e.g. `external_directory` when the
   labor reads the case dossier outside the project root) is auto-rejected in a

package/resources/engines/zcode.md

@@ -19,25 +19,27 @@ zcode --prompt 'YOUR_LABOR_PROMPT' --cwd /path/to/worktree
 `--prompt` defaults to permission mode `yolo` (no TTY permission stalls).
 Useful extras measured from `zcode --help`: `--attach <path>` (repeatable),
 `--mode build|edit|plan|yolo`, `--resume <sess_...>`. Never `--json` for
-labor (the returned body goes back into the seat's context as plain text). Prefer `zcode --help` on the host over any remembered flag set.
+labor (the returned body goes back into the seat's context as plain text). The
+headless CLI help exposes no per-invocation model flag; do not translate a
+requested model into a config edit or invent a CLI flag. Report that capability
+gap through the existing path. Prefer `zcode --help` on the host over any
+remembered flag set.
 
-## Realm and model traps (host-verified 2026-08-29, all three hit in sequence)
+## Historical realm and model observations (host-verified 2026-08-29)
+
+These are dated observations, not model or dispatch recommendations. Model
+choice remains with the dispatch order; this note does not prescribe a model.
 
 - Missing `~/.zcode/cli/config.json` → hard error `Model config is missing`.
   The desktop app's login is NOT shared with the CLI.
 - `zcode login` signs into the **overseas Z.AI realm only**. An account on the
   mainland BigModel realm then fails with
   `[1113][Insufficient balance or no resource package]`.
-- The scaffolded config defaults `model.main` to `zai/glm-5.2`, which is not
-  in the coding plan — same 1113 failure even with a valid plan.
-
-Working mainland configuration (per official docs
-`docs.bigmodel.cn/cn/coding-plan/quick-start`): in
-`~/.zcode/cli/config.json`, provider kind `anthropic` with
-`baseURL: https://open.bigmodel.cn/api/anthropic`, `options.apiKey` = the
-coding-plan key (host keychain: service `glm-key`, account `akagilnc`), and
-`model.main: zai/glm-5.3`, `model.lite: zai/glm-5.3-flash`. With that config
-the smoke prompt returns normally.
+- At that time, the scaffolded config defaulted `model.main` to `zai/glm-5.2`,
+  which was not included in the coding plan and returned the same 1113 failure.
+- A mainland configuration using the Anthropic-compatible endpoint and
+  `zai/glm-5.3` / `zai/glm-5.3-flash` returned normally with the tested key at
+  that time. This is a historical result, not a suggested fixed configuration.
 
 ## Quota facts (owner-provided, 2026-08-28)
 
@@ -45,7 +47,7 @@ Plan quotas are daily and per-model (GLM-5.3 3M/day, Flash 5M/day on the
 current plan; a weekend event granted a larger temporary pool). Whether cached
 tokens count toward quota is unverified.
 
-## Lane status: PARKED (host-verified 2026-08-29)
+## Historical funding observations (host-verified 2026-08-29)
 
 The "working" configuration above drew from a new-user gift resource package
 (2M general-model tokens), not from any plan. Once that package expired,
@@ -59,5 +61,7 @@ app's OAuth connection ("Start Plan" connection mode); the CLI's
 the desktop app; no env override exists — only `BIGMODEL_*_API_BASE_URL`).
 The plan page issues exactly one API key and it is the key tested above.
 
-Net: this engine lane has no funded model until a key with actual balance or
-an in-plan API path exists. Do not dispatch `--engine zcode` until then.
+The later tests found that the tested key had no funded model after the gift
+resource package expired. Current funding and model availability were not
+established by those tests; report an actual invocation failure through the
+existing path and leave any seat change to the caller.

package/src/public-cli/option-definitions.ts

@@ -1298,7 +1298,7 @@ const SUPPORT_COMMAND_HELP = {
     examples: [
       "ak-role config set judge openai-codex/gpt-5.6-sol:high",
       "ak-role config unset gatekeeper",
-      "ak-role config set-engine judge opus",
+      "ak-role config set-engine judge claude-code",
       "ak-role config set-engine coder cursor cursor-grok-4.6-high",
       "ak-role config set-engine-model coder cursor-grok-4.6-high",
       "ak-role config set-host judge grok-build",

package/resources/engines/grok-4.6.md

@@ -1,63 +0,0 @@
-# grok-4.6 engine method material
-
-This file is packaged technical material for the `grok-4.6` labor
-engine (Grok CLI on the host).
-
-Before invoking the engine, read `../engine-dispatch.md`, resolving that path
-relative to this note. This note only covers this engine's CLI technical
-parameters.
-
-## Invocation examples (local Grok CLI)
-
-The machine entrypoint is `grok` (NOT `grok-4.6` — the engine name is the model
-id, not the executable). Run from the role project root. Non-interactive labor
-reads the prompt from a file and prints plain output:
-
-```bash
-grok --prompt-file /path/to/labor-prompt.md -m grok-4.6 --always-approve --output-format plain
-```
-
-- `-m grok-4.6` selects the model; `grok models` lists valid ids (currently
-  `grok-4.6` default, `grok-4.5`).
-- `--always-approve` (equivalently `--yolo` or `--permission-mode
-  bypassPermissions`) keeps the run non-interactive (documented). Headless
-  permissions otherwise default to interactive approval, where an `ask`
-  decision has no UI to answer; alternatively, use an explicit permission
-  setup that auto-approves the required call.
-- Official docs list `-p/--single` as the canonical headless prompt input;
-  `--prompt-file` exists in the installed CLI (`--help`) and is smoke-verified
-  on this host — prefer it for long prompts, fall back to `-p` if absent.
-- `--output-format plain` keeps stdout clean for capture and is the only
-  format to use for labor. Do not use `streaming-json`: its NDJSON deltas go
-  back into the seat's context as noise (see `opus.md` for the measured ratio);
-  progress observability belongs to the runner's process watch, not to the
-  returned body.
-- **Always pass `--reasoning-effort <low|medium|high>`** matching the effort
-  tier ordered in the labor mandate (verified live 2026-08-21: flag exists,
-  alias `--effort`; a low-tier run completed correctly). If the mandate names
-  no tier, use the seat's ordered thinking tier; never omit the flag — the
-  CLI default is not guaranteed to match the ordered tier.
-- Feeding raw JSON directly through `--prompt-file` is rejected by the CLI as
-  non-ACP JSON (`JSON object must have a type field`; live-verified
-  2026-08-21).
-
-## MCP host behavior
-
-- Repository MCP entries live under `[mcp_servers.<name>]` in
-  `.grok/config.toml`. They take effect only after the folder is trusted; pass
-  `--trust` on unattended/headless invocations. Without it, the project server
-  may be absent even though the file is present (`live-1787838141494`), and
-  `grok mcp doctor` reports `folder untrusted…re-run with --trust`
-  (`live-1787838491136`).
-- Diagnose server startup with `grok mcp doctor [<server>]`, then inspect
-  `~/.grok/logs/mcp/<server>.stderr.log`; Grok truncates that stderr log on
-  each stdio server launch.
-- MCP tools are exposed to the model as `<server>__<tool>` (for example,
-  `ak_489_coder__ak_coder_output`). Use the fully qualified name in prompts;
-  a bare tool name relies on the host's loose discovery/matching behavior.
-- The headless permission setting described above also covers MCP calls.
-- Grok launches a stdio server from the task cwd. Make `command` and `args`
-  cwd-independent: use absolute entrypoint paths and do not rely on resolving
-  a task-local `node_modules` binary. A cwd-dependent `tsx` launcher failed in
-  `live-1787838491136`; the absolute-path form completed the MCP route in
-  `live-1787838776163`.

package/resources/engines/ox-alpha.md

@@ -1,44 +0,0 @@
-# ox-alpha engine method material
-
-This file is packaged technical material for the `ox-alpha` labor
-engine (OpenRouter stealth preview model, reached via OpenCode CLI).
-
-Before invoking the engine, read `../engine-dispatch.md`, resolving that path
-relative to this note. This note only covers this engine's CLI technical
-parameters.
-
-## Identity and warnings
-
-- Model id: `stealth/ox-alpha` on OpenRouter (listed 2026-08-20). Anonymous
-  vendor, preview-period pricing $0. Specs claimed by the listing: 1M ctx /
-  131K out, text+image+video in, tool calling, reasoning.
-- **Retention**: the provider retains prompts/completions (stated not used for
-  training). Time-boxed experiment — may be delisted or re-priced at any time.
-- Free-tier rate limit (official ~20 req/min).
-- Quality role (live exam 2026-08-21/22): control / hardening seat, not a
-  substitute for the main-court engine. On a standard-answer tool-idle-clock
-  final exam it caught all 7 residual shells at every effort tier (medium 59s
-  best); sol low missed `converged`, grok-4.6 low also caught 7 but took 979s.
-
-## Invocation examples
-
-### Recommended: agentic via OpenCode CLI
-
-The machine entrypoint is `opencode` with the OpenRouter-routed model id.
-Key is on this host's keychain under label `openrouter` (smoke-verified
-2026-08-21/22). Run from the role project root:
-
-```bash
-OPENROUTER_API_KEY=$(security find-generic-password -l openrouter -w) \
-  opencode run -m openrouter/stealth/ox-alpha '<task>'
-```
-
-Smoke: prompt `只回两个字：收到` → `收到` (agentic leg usable).
-
-- `-m openrouter/stealth/ox-alpha` selects the model; confirm the current id
-  with `opencode models` before long labor — stealth ids can vanish.
-- Effort tier: align with the labor mandate's ordered tier (`low` / `medium` /
-  `high`). Live wall-times on the same 148KB grading payload:
-  low 73s / medium 59s / high 228s — all produced correct three-state verdicts.
-  Prefer the ordered tier; when the mandate is silent, medium was the
-  fastest correct run on that payload.

package/resources/engines/sonnet.md

@@ -1,26 +0,0 @@
-# sonnet engine method material
-
-This file is packaged technical material for the `sonnet` labor engine
-(Claude Code CLI on the host, pinned to the Sonnet model).
-
-Before invoking the engine, read `../engine-dispatch.md`, resolving that path
-relative to this note. This note only covers this engine's CLI technical
-parameters.
-
-## Invocation
-
-Same host CLI as the `opus` engine: the machine entrypoint is `claude`, and all
-CLI mechanics (print mode, `--output-format text`, fd layout) are documented in `../opus.md` — read that
-note for them; they are not duplicated here.
-
-The only difference is the model pin:
-
-```bash
-claude -p --model sonnet --output-format text "YOUR_LABOR_PROMPT"
-```
-
-`--model sonnet` is verified accepted on this host (Claude Code 2.1.233); the
-`json` init metadata reports `claude-sonnet-5` (host-verified 2026-08-28).
-
-Prefer `claude --help` on the host over any remembered flag set. Do not wrap
-this engine behind `ak-role` flags.