@akagilnc/pi-workflow-roles 0.1.2336 → 0.1.2348

package/README.md

@@ -1,6 +1,6 @@
 # @akagilnc/pi-workflow-roles
 
-Packaged workflow roles for [Pi](https://pi.dev): `judge`, `fixer`, `coder`, `reviewer`, `collector`, `doctor`, `merger`. 中文说明见 [README.zh-CN.md](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/README.zh-CN.md)。
+Packaged workflow roles for [Pi](https://pi.dev): `judge`, `fixer`, `coder`, `reviewer`, `collector`, `doctor`, `merger`, `notary`, `analyst`. 中文说明见 [README.zh-CN.md](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/README.zh-CN.md)。
 
 ## Install
 
@@ -11,7 +11,7 @@ pi install npm:@akagilnc/pi-workflow-roles
 export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"
 ```
 
-Update with `pi update npm:@akagilnc/pi-workflow-roles`—never a second global `npm install -g`. Inspect with `ak-role roles` and `ak-role help <role>`; set per-seat model defaults with `ak-role config set judge openai-codex/gpt-5.6-sol:high`; set or clear a persistent labor engine (callable roles) with `ak-role config set-engine <seat> <name>` / `ak-role config unset-engine <seat>`.
+Update with `pi update npm:@akagilnc/pi-workflow-roles`—never a second global `npm install -g`. Inspect with `ak-role roles` and `ak-role help <role>`; set per-seat model defaults with `ak-role config set <seat> <provider/model[:thinking]>` (callable seats plus automatic `gatekeeper` / `inspector` / `navigator`); clear a Menxia officer override with `ak-role config unset <gatekeeper|inspector|notary>`; set or clear a persistent labor engine (callable roles) with `ak-role config set-engine <seat> <name>` / `ak-role config unset-engine <seat>`.
 
 ## Reading results
 
@@ -23,31 +23,41 @@ ak-role judge --attach ./plan.md "Review this plan." > result.txt
 
 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>` reopens that run's exact Pi session. 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. Collector and Doctor remain one-shot. The package never auto-switches providers; override the model for one run with the global flags.
+`ak-role resume <runId> [message]` reopens that run's exact Pi session. Standard chain after a role `escalate`s: take the owner ruling and feed it back with `ak-role resume <runId> "<ruling>"` so the same session continues to a terminal. The optional `message` after `runId` is passed through unchanged as the continuation prompt (opaque: not parsed as flags); omit it to use the package resume envelope. 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. Collector, Doctor, and Notary remain one-shot. The package never auto-switches providers; override the model for one run with the global flags.
 
 Judge, coder, fixer, reviewer, and merger 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.
 
-Global overrides work before or after the role: `ak-role --model xai/grok-4.5:high resume <runId>`.
+Global overrides work before the opaque message segment: `ak-role --model <provider/model[:thinking]> resume <runId>` or `ak-role resume --model <provider/model[:thinking]> <runId>`.
 
-Every run also prepares Navigator advice in the same Terminal. Configure it like any other seat:
+Every run also prepares Navigator advice in the same Terminal. Configure seats like this:
 
 ```bash
-ak-role config set navigator openai-codex/gpt-5.6-luna:medium
+ak-role config set judge <provider/model[:thinking]>
+ak-role config set navigator <provider/model[:thinking]>
+# Menxia officers (automatic on submission; not caller commands except direct notary)
+ak-role config set gatekeeper <provider/model[:thinking]>
+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; not navigator); one-shot override remains --engine
 ak-role config set-engine judge opus
 ak-role config unset-engine judge
 ak-role config set-auto-resume-limit 3
 ```
 
-`config set` stores the seat model default; `config set-engine` / `unset-engine` store or clear the persistent labor-engine name on callable roles (same seats as `--engine`; navigator refused — no independent activation). `config set-auto-resume-limit` stores the single-call auto-resume ceiling. Usage and refusal text are owned by `ak-role config` in the public CLI.
+`config set` stores the seat model default. For Menxia officers (`gatekeeper` / `inspector` / `notary`) resolution is officer pin → province (`gatekeeper`) pin → inherit parent session; an explicit selection that fails is loud and does not fall back. `config unset` clears only those officer overrides. `config set-engine` / `unset-engine` store or clear the persistent labor-engine name on callable roles (same seats as `--engine`; navigator refused — no independent activation). `config set-auto-resume-limit` stores the single-call auto-resume ceiling. Usage and refusal text are owned by `ak-role config` / `ak-role help config`.
 
 Receipts are typed, so callers compose roles without parsing prose; ordering and stopping stay caller-owned. Programmatic consumers derive contracts from the exported schemas in `src/package-contracts/`, not from this guide.
 
+### Menxia submission gate
+
+On completing-side submissions the package may spawn the Menxia province before the run settles: `gatekeeper` reads the subject and dispatches an officer (`inspector` or `notary`); existing auditor hooks stay where already wired. The gate runs inside the submission session; bounce means rewrite-and-resubmit in that same session — not role failure; the final receipt is the post-gate product. `planned` / `refused` / `unfinished` skip the province. Pointers only: [ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md), [ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md). Do not scrape session prose for gate status.
+
 When a labor-engine detour fails and the seat continues the labor on the main road, the typed receipt may carry a mechanical `engineLaborFallback` field: `{ engine, failure, laborBy: "seat" }`. It appears only after a real detour failure that fell back to seat labor—not on detour success or caller cancel. First failure wins for the activation; model-forged `engineLaborFallback` keys are stripped unless the package latch recorded one. Sole producer: `src/engine-labor-fallback.ts`; decision record: [ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md). This README only projects that contract.
 
 ## Call the roles
 
-Public option identity, aliases, requiredness, and mode faces live in the generated [Public CLI options](#public-cli-options-generated) table and in `ak-role help <command>` — both project the same typed source. The examples below are usage sketches, not a second flag contract. An instruction is optional for judge, collector, and doctor, and required nonblank for coder, fixer, reviewer, and merger.
+Public option identity, aliases, requiredness, and mode faces live in the generated [Public CLI options](#public-cli-options-generated) table and in `ak-role help <command>` — both project the same typed source. The examples below are usage sketches, not a second flag contract. An instruction is optional for judge, collector, and doctor; notary admits no caller prompt or attachment; analyst is deterministic (see help). Required nonblank for coder, fixer, reviewer, and merger.
 
 ```bash
 # judge — adjudicate the supplied materials; infers its burden, no burden flag
@@ -79,6 +89,20 @@ ak-role doctor --issue 115 "Diagnose this retained case."
 # merger — resolve one merge already in conflict (start it first with Git’s ort)
 ak-role merger --project /path/to/worktree "Reconcile the active merge."
 # hands new intent/authority questions back instead of inventing authority
+
+# notary — document-fidelity check on one retained source run; zero prompt/attachment; one-shot
+ak-role notary --source-run <runId@role|path>
+
+# analyst — deterministic metrics over the book (cwd git common-dir); bare = whole book
+ak-role analyst
+ak-role analyst --ticket <N>
+ak-role analyst sweep --attach ./payload.md
+ak-role analyst --cohort \
+  --group-a-label A --group-a-issues 1,2 \
+  --group-b-label B --group-b-issues 3,4
+
+# after escalate: feed the owner ruling into the same session (standard chain; see resume under Reading results)
+ak-role resume <runId> "<ruling>"
 ```
 
 ## Names

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # @akagilnc/pi-workflow-roles
 
-为 [Pi](https://pi.dev) 打包的工作流角色：大理寺（judge）、修内司（fixer）、将作监（coder）、御史台（reviewer）、门下省（collector）、太医署（doctor）、校书郎（merger）。English: [README.md](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/README.md)。
+为 [Pi](https://pi.dev) 打包的工作流角色：大理寺（judge）、修内司（fixer）、将作监（coder）、御史台（reviewer）、通进司（collector）、太医署（doctor）、校书郎（merger）、符宝郎（notary）、太史（analyst）。English: [README.md](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/README.md)。
 
 ## 安装
 
@@ -11,7 +11,7 @@ pi install npm:@akagilnc/pi-workflow-roles
 export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"
 ```
 
-更新用 `pi update npm:@akagilnc/pi-workflow-roles`——勿另起全局 `npm install -g`。查看能力：`ak-role roles`、`ak-role help <role>`；设席位模型默认：`ak-role config set judge openai-codex/gpt-5.6-sol:high`；设或清持久劳务引擎（可调用角色）：`ak-role config set-engine <seat> <name>` / `ak-role config unset-engine <seat>`。
+更新用 `pi update npm:@akagilnc/pi-workflow-roles`——勿另起全局 `npm install -g`。查看能力：`ak-role roles`、`ak-role help <role>`；设席位模型默认：`ak-role config set <seat> <provider/model[:thinking]>`（可调用席位，以及自动出席的 `gatekeeper`／`inspector`／`navigator`）；清除门下省官钉：`ak-role config unset <gatekeeper|inspector|notary>`；设或清持久劳务引擎（可调用角色）：`ak-role config set-engine <seat> <name>` / `ak-role config unset-engine <seat>`。
 
 ## 读结果
 
@@ -23,31 +23,41 @@ ak-role judge --attach ./plan.md "Review this plan." > result.txt
 
 退出码报的是生命周期诚实，不是业务成败：一切合法 typed 终态（含 `audit_escalation`）退出零；无合法终态的失败退出非零，其 Terminal 携带 Error Artifact 引用与原始原因，不伪造回执。
 
-`ak-role resume <runId>` 重开该次运行的同一 Pi session。要不要续跑由调用者决定：不再要求 typed HTTP 429，也不要求 `resumable` 状态。未知 run ID、session 主体不在则拒绝。门下省、太医署仍为一次性，无 resume。包绝不自动换 provider；临时换模型用全局旗标。
+`ak-role resume <runId> [message]` 重开该次运行的同一 Pi session。角色 `escalate`（直通御前）后拿到 owner 裁定，标准续跑是 `ak-role resume <runId> "<裁定>"`——把裁定喂回同一 session，角色继续走到终局。`runId` 后可选的 `message` 原样作为续跑 prompt（opaque：不进全局旗标语法）；省略则用包自带 resume envelope。要不要续跑由调用者决定：不再要求 typed HTTP 429，也不要求 `resumable` 状态。未知 run ID、session 主体不在则拒绝。通进司、太医署、符宝郎仍为一次性，无 resume。包绝不自动换 provider；临时换模型用全局旗标。
 
 大理寺、将作监、修内司、御史台、校书郎在单次调用内对非 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` 仍可用。
 
-全局覆盖前后皆可：`ak-role --model xai/grok-4.5:high resume <runId>`。
+全局覆盖须在 opaque message 段之前：`ak-role --model <provider/model[:thinking]> resume <runId>` 或 `ak-role resume --model <provider/model[:thinking]> <runId>`。
 
 每次运行游奕使自动出席，建议随同一 Terminal 给出。配置：
 
 ```bash
-ak-role config set navigator openai-codex/gpt-5.6-luna:medium
+ak-role config set judge <provider/model[:thinking]>
+ak-role config set navigator <provider/model[:thinking]>
+# 门下省官席（交卷自动出席；除直调符宝郎外无独立命令）
+ak-role config set gatekeeper <provider/model[:thinking]>
+ak-role config set inspector <provider/model[:thinking]>
+ak-role config set notary <provider/model[:thinking]>
+ak-role config unset gatekeeper
 # 持久劳务引擎（可调用角色；不含 navigator）；一次性覆盖仍用 --engine
 ak-role config set-engine judge opus
 ak-role config unset-engine judge
 ak-role config set-auto-resume-limit 3
 ```
 
-`config set` 存席位模型默认；`config set-engine` / `unset-engine` 在可调用角色上写入或清除持久劳务引擎名（与 `--engine` 同轴；拒收 navigator——无独立 activation）。`config set-auto-resume-limit` 写入单次调用自动续跑上限。用法与拒绝文案以公开 CLI 的 `ak-role config` 为准。
+`config set` 存席位模型默认。门下省官席（`gatekeeper`／`inspector`／`notary`）解析顺序：官自钉 → 省钉（`gatekeeper`）→ 继承父 session；显式指定失败响亮、不回退。`config unset` 只清这三官的覆盖。`config set-engine`／`unset-engine` 在可调用角色上写入或清除持久劳务引擎名（与 `--engine` 同轴；拒收 navigator——无独立 activation）。`config set-auto-resume-limit` 写入单次调用自动续跑上限。用法与拒绝文案以 `ak-role config`／`ak-role help config` 为准。
 
 回执是 typed 的，调用者不必解析散文即可组合角色；顺序与停止归调用者。编程消费者从 `src/package-contracts/` 导出推导契约，不从本文。
 
+### 门下省交卷闸
+
+完成侧交卷时，包可能在本局结算前起门下省：`gatekeeper` 读受审物并派官（`inspector` 给事中或 `notary` 符宝郎）；既有审刑院挂钩仍在原位。闸在交卷 session 内运行；封驳＝当场重写重交，不是角色失败；最终回执即过闸产物。`planned`／`refused`／`unfinished` 不调省。指针：[ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md)、[ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md)。勿刮 session 散文当闸状态。
+
 当劳务引擎绕行失败、座席回到主路继续劳务时，typed 回执可带机械字段 `engineLaborFallback`：`{ engine, failure, laborBy: "seat" }`。仅在真实绕行失败并座席顶班后出现——成功绕行或调用方 cancel 不出现。同一次 activation 内先到先得；无包内 latch 时剥离模型伪造的 `engineLaborFallback` 键。唯一构造点：`src/engine-labor-fallback.ts`；决策记录：[ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)。本文只投影该契约。
 
 ## 调用百官
 
-公开 option 身份、别名、必填性与 mode 面以生成区 [公开 CLI 选项（生成）](#公开-cli-选项生成) 与 `ak-role help <command>` 为准——二者同源。下例只是用法速写，不是第二份旗标合同。指令对大理寺、门下省、太医署可省略，对将作监、修内司、御史台、校书郎必须非空。
+公开 option 身份、别名、必填性与 mode 面以生成区 [公开 CLI 选项（生成）](#公开-cli-选项生成) 与 `ak-role help <command>` 为准——二者同源。下例只是用法速写，不是第二份旗标合同。指令对大理寺、通进司、太医署可省略；符宝郎零 prompt／附件；太史为确定性命令（见 help）。对将作监、修内司、御史台、校书郎必须非空。
 
 ```bash
 # 大理寺——审断所供材料；自行推断举证责任，无 burden 旗标
@@ -63,7 +73,7 @@ ak-role reviewer --base main "Review the branch."
 # --base 为必填并钉住 fixed point；御史台不接受 --attach
 # completed ≠ 准行——findings 在 Terminal 里
 
-# 门下省——GitHub PR 收证；仅 github.com，需 gh 已认证；一次性
+# 通进司——GitHub PR 收证；仅 github.com，需 gh 已认证；一次性
 ak-role collector --pr 42 --repo owner/repository
 ak-role collector --pr 42 --request-manifest ./requests.json
 # 无配置时仅观察；可选 request manifest 为 {requests:[{id,body}]}；repo 默认取 origin
@@ -79,6 +89,20 @@ ak-role doctor --issue 115 "Diagnose this retained case."
 # 校书郎——雠校一个已在冲突的 merge（先用 Git ort 起动）
 ak-role merger --project /path/to/worktree "Reconcile the active merge."
 # 遇新意图/权限问题交回调用者，不捏造 authority
+
+# 符宝郎——对一份留存 source run 做文书核验；零 prompt／附件；一次性
+ak-role notary --source-run <runId@role|path>
+
+# 太史——确定性指标（cwd 候簿＝git common-dir）；裸调＝整簿
+ak-role analyst
+ak-role analyst --ticket <N>
+ak-role analyst sweep --attach ./payload.md
+ak-role analyst --cohort \
+  --group-a-label A --group-a-issues 1,2 \
+  --group-b-label B --group-b-issues 3,4
+
+# escalate 后：把 owner 裁定喂回同一 session（标准链；细则见上方「读结果」resume 段）
+ak-role resume <runId> "<裁定>"
 ```
 
 ## 班子（唐宋官署命名）
@@ -93,8 +117,11 @@ ak-role merger --project /path/to/worktree "Reconcile the active merge."
 | **修内司** | fixer | **缮修旧物。** 面对已有问题，不急于表面修补，而是追寻问题根源，找到真正需要修整之处。既要修复眼前缺漏，也要防止同类问题再次出现。 |
 | **御史台** | reviewer | **察举百弊。** 置身事外，以旁观之眼审视成果，寻找其中的不妥、遗漏与隐患。只负责指出问题、陈明依据，不参与修改，也不替人作最终判断。 |
 | **大理寺** | judge | **审理定谳。** 承接各方意见与材料，依照既定规则逐项判断，辨明是非曲直。可以准行、退回或请示更高决定，但自身不参与建设与修改。 |
-| **审刑院** | judge-auditor／reviewer-auditor（无 CLI，共享内部接缝） | **复核成案。** 不重新争论事情本身，而是检查整个办理过程是否合乎规矩。关注是否有人越过职责、是否遗漏必要步骤、是否以错误方式得出正确结果。 |
-| **门下省** | collector | **承接百议。** 位于决策之前，收集各方反馈与意见，确认事情是否已经具备继续推进的条件。它不替人裁决，只负责让信息完整、状态清楚。 |
+| **审刑院** | judge-auditor／reviewer-auditor（无 CLI，共享内部接缝） | **复核成案。** 不重新争论事情本身，而是检查整个办理过程是否合乎规矩。关注是否有人越过职责、是否遗漏必要步骤、是否以错误方式得出正确结果。直属陛下，不入门下省编制。 |
+| **门下省** | gatekeeper（无独立 CLI；交卷自动出席） | **质量保证省。** 交卷时判断受审物、够不够审、该谁审，派给事中或符宝郎；省内政，不是外层编排器。规范见 [ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md)、[ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md)。 |
+| **给事中** | inspector（无独立 CLI；可由门下省派发） | **复杂度与测试质量两轴质检。** 受审物是将作监／修内司完成侧交卷；封驳＝当场打回重写，不是本局失败。 |
+| **符宝郎** | notary | **引语真伪与票面对齐。** 受审物是大理寺拟判等文书；可被门下省派发，也可 `ak-role notary` 单独调。 |
+| **通进司** | collector | **承接百议／收证。** 门下省下的收证衙门：收集外部 GitHub PR 材料与意见，只收不审、不替人裁决。canonical 键仍为 `collector`。 |
 | **校书郎** | merger | **雠校异文。** 面对不同来源的修改，负责整理、校合与调和。保留双方有价值的部分，解决彼此冲突；遇到无法自行决定之处，则留待重新裁量。 |
 | **游奕使** | navigator（无 CLI，自动出席） | **巡行问路。** 不掌具体事务，而是观察全局变化，结合当前局面提醒下一步方向。它提供建议与路径参考，但最终选择仍由执掌之人决定。 |
 
@@ -103,14 +130,15 @@ ak-role merger --project /path/to/worktree "Reconcile the active merge."
 | 席位 | 名 | 职掌 | 状态 |
 | --- | --- | --- | --- |
 | doctor | **太医署** | 单案诊断工厂机制，开 `keep｜thin｜delete` 方 | 已建 |
-| — | **司天台** | 记候簿——只打点、只指针，不分析不执法 | **一期不是角色**（[ADR 0047](docs/adr/0047-sitian-phase-one-mechanism-not-role.md)：零 LLM 双面对账）；席位形态属 [#67](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/67) 素材，未定 |
-| — | **兰台** | 读档议制——耗时／缺口／冗余三条，上奏不执法 | 未建（[#67](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/67) 两席之一） |
-| — | **考功司** | 考具体效率——角色与档位的升档率、一次通过率、每票成本 | 留档，不属 #67，需要时另立票 |
+| analyst | **太史** | 司天台分析席：只读司天记录、出高阶指标；确定性机制，非 LLM，可单独调用 | 已建（[ADR 0068](docs/adr/0068-taishi-analysis-seat-reads-records-writes-sibling-home.md)；机器面键 `analyst`，[#445](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/445) 拼音清零） |
+| — | **司天台** | 记候簿——只打点、只指针，不分析不执法 | **一期不是角色**（[ADR 0047](docs/adr/0047-sitian-phase-one-mechanism-not-role.md)：零 LLM 双面对账）；分析席已由太史承担；机器面键 `archivist`（[#445](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/445)） |
+| — | **兰台** | 读档议制——耗时／缺口／冗余三条，上奏不执法 | 未建 |
+| — | **考功司** | 考具体效率——角色与档位的升档率、一次通过率、每票成本 | 留档，需要时另立票 |
 | — | **主簿** | 合并后勾稽销案：核实确已合上、清理残留、报到达 | 未建 |
 
-**merge 按钮归调用者**，没有任何角色握不可逆权限：门下省把收证这件苦活做完并报收集终态，人（或 AI）自己判断、自己点，点完想调主簿就调、不调也可以。
+**merge 按钮归调用者**，没有任何角色握不可逆权限：通进司把收证这件苦活做完并报收集终态，人（或 AI）自己判断、自己点，点完想调主簿就调、不调也可以。
 
-上表**不规定调用顺序**——组合、顺序、重复次数归调用者（[ADR 0010](docs/adr/0010-callers-own-role-composition-and-repetition.md)）。御史台／大理寺／审刑院是**职责分立的类比，不是必经链**；审刑院也并非只跟在大理寺之后，大理寺、御史台、太医署各自都有一次。
+上表**不规定调用顺序**——组合、顺序、重复次数归调用者（[ADR 0010](docs/adr/0010-callers-own-role-composition-and-repetition.md)）。御史台／大理寺／审刑院是**职责分立的类比，不是必经链**；审刑院也并非只跟在大理寺之后，大理寺、御史台、太医署各自都有一次。门下省交卷闸是完成侧挂钩，不是调用者必经编排链。
 
 `拾遗补阙` 成对留档，待将来出现第二个进言席再启用。
 

package/dist/public-cli/main.js

@@ -15904,6 +15904,9 @@ var init_typed_provider_http = __esm({
 // src/public-cli/run-lifecycle.ts
 import { chmod, lstat, open, readdir as readdir2, readFile as readFile5, unlink as unlink2, writeFile as writeFile3 } from "node:fs/promises";
 import { join as join7 } from "node:path";
+function selectResumeContinuationPrompt(message) {
+  return message !== void 0 ? message : RESUME_TRANSPORT_ENVELOPE;
+}
 function isV1ResumableProvider(provider) {
   return V1_RESUMABLE_PROVIDERS.includes(provider);
 }
@@ -17486,8 +17489,11 @@ var init_option_definitions = __esm({
       resume: {
         command: "resume",
         summary: "Reopen an exact role run whose Pi session principal still exists.",
-        usage: ["ak-role resume <runId>"],
-        examples: ["ak-role resume 01abc\u2026"]
+        usage: ["ak-role resume <runId> [message]"],
+        examples: [
+          "ak-role resume 01abc\u2026",
+          'ak-role resume 01abc\u2026 "owner ruling"'
+        ]
       }
     };
     PUBLIC_COMMAND_HELP = {
@@ -23571,7 +23577,7 @@ function buildCoderResumeActivationExtraArgs(admitted, options) {
     "--mode",
     "json",
     ...buildSeatModelCliArgs(options.model),
-    RESUME_TRANSPORT_ENVELOPE
+    selectResumeContinuationPrompt(options.message)
   ];
 }
 async function presentControlledFailure2(admitted, failureInput, io) {
@@ -23806,25 +23812,10 @@ async function runPublicCoder(argv, env, io, parseCoderArgv2) {
     })
   });
 }
-async function runPublicCoderResume(argv, env, io) {
-  const runId = argv[0];
-  if (runId === void 0 || runId.trim() === "" || runId.startsWith("-")) {
-    presentStructuralRejection(
-      new CliUsageError("usage: ak-role resume <runId>"),
-      io
-    );
-    return { exitCode: 2 };
-  }
-  if (argv.length > 1) {
-    presentStructuralRejection(
-      new CliUsageError("resume takes exactly one run id"),
-      io
-    );
-    return { exitCode: 2 };
-  }
+async function runPublicCoderResume(request, env, io) {
   let loaded;
   try {
-    loaded = await loadResumableCoderRun(env.home, runId);
+    loaded = await loadResumableCoderRun(env.home, request.runId);
   } catch (error) {
     if (error instanceof CliUsageError) {
       presentStructuralRejection(error, io);
@@ -23869,7 +23860,8 @@ async function runPublicCoderResume(argv, env, io) {
   const extraArgs = buildCoderResumeActivationExtraArgs(admitted, {
     packageRoot: env.packageRoot,
     ...env.model === void 0 ? {} : { model: env.model },
-    ...env.extraPiArgs === void 0 ? {} : { extraPiArgs: env.extraPiArgs }
+    ...env.extraPiArgs === void 0 ? {} : { extraPiArgs: env.extraPiArgs },
+    ...request.message === void 0 ? {} : { message: request.message }
   });
   const result2 = await dispatchAdmittedCoder({
     admitted,
@@ -24475,7 +24467,7 @@ function buildFixerResumeActivationExtraArgs(admitted, options) {
     "--mode",
     "json",
     ...buildSeatModelCliArgs(options.model),
-    RESUME_TRANSPORT_ENVELOPE
+    selectResumeContinuationPrompt(options.message)
   ];
 }
 async function presentControlledFailure5(admitted, failureInput, io) {
@@ -24723,25 +24715,10 @@ async function runPublicFixer(argv, env, io, parseFixerArgv2) {
     })
   });
 }
-async function runPublicFixerResume(argv, env, io) {
-  const runId = argv[0];
-  if (runId === void 0 || runId.trim() === "" || runId.startsWith("-")) {
-    presentStructuralRejection(
-      new CliUsageError("usage: ak-role resume <runId>"),
-      io
-    );
-    return { exitCode: 2 };
-  }
-  if (argv.length > 1) {
-    presentStructuralRejection(
-      new CliUsageError("resume takes exactly one run id"),
-      io
-    );
-    return { exitCode: 2 };
-  }
+async function runPublicFixerResume(request, env, io) {
   let loaded;
   try {
-    loaded = await loadResumableFixerRun(env.home, runId);
+    loaded = await loadResumableFixerRun(env.home, request.runId);
   } catch (error) {
     if (error instanceof CliUsageError) {
       presentStructuralRejection(error, io);
@@ -24779,7 +24756,8 @@ async function runPublicFixerResume(argv, env, io) {
   const extraArgs = buildFixerResumeActivationExtraArgs(admitted, {
     packageRoot: env.packageRoot,
     ...env.model === void 0 ? {} : { model: env.model },
-    ...env.extraPiArgs === void 0 ? {} : { extraPiArgs: env.extraPiArgs }
+    ...env.extraPiArgs === void 0 ? {} : { extraPiArgs: env.extraPiArgs },
+    ...request.message === void 0 ? {} : { message: request.message }
   });
   const result2 = await dispatchAdmittedFixer({
     admitted,
@@ -24932,7 +24910,7 @@ function buildJudgeResumeActivationExtraArgs(admitted, options = {}) {
     "--mode",
     "json",
     ...buildSeatModelCliArgs(options.model),
-    RESUME_TRANSPORT_ENVELOPE
+    selectResumeContinuationPrompt(options.message)
   ];
 }
 async function presentControlledFailure6(admitted, failureInput, io) {
@@ -25164,25 +25142,10 @@ async function runPublicJudge(argv, env, io, parseJudgeArgv2) {
     })
   });
 }
-async function runPublicResume(argv, env, io) {
-  const runId = argv[0];
-  if (runId === void 0 || runId.trim() === "" || runId.startsWith("-")) {
-    presentStructuralRejection(
-      new CliUsageError("usage: ak-role resume <runId>"),
-      io
-    );
-    return { exitCode: 2 };
-  }
-  if (argv.length > 1) {
-    presentStructuralRejection(
-      new CliUsageError("resume takes exactly one run id"),
-      io
-    );
-    return { exitCode: 2 };
-  }
+async function runPublicResume(request, env, io) {
   let loaded;
   try {
-    loaded = await loadResumableJudgeRun(env.home, runId);
+    loaded = await loadResumableJudgeRun(env.home, request.runId);
   } catch (error) {
     if (error instanceof CliUsageError) {
       presentStructuralRejection(error, io);
@@ -25203,7 +25166,8 @@ async function runPublicResume(argv, env, io) {
   }
   const extraArgs = buildJudgeResumeActivationExtraArgs(admitted, {
     ...env.model === void 0 ? {} : { model: env.model },
-    ...env.extraPiArgs === void 0 ? {} : { extraPiArgs: env.extraPiArgs }
+    ...env.extraPiArgs === void 0 ? {} : { extraPiArgs: env.extraPiArgs },
+    ...request.message === void 0 ? {} : { message: request.message }
   });
   const result2 = await dispatchAdmittedJudge({
     admitted,
@@ -25294,7 +25258,7 @@ function buildMergerResumeActivationExtraArgs(admitted, options) {
     "--mode",
     "json",
     ...buildSeatModelCliArgs(options.model),
-    RESUME_TRANSPORT_ENVELOPE
+    selectResumeContinuationPrompt(options.message)
   ];
 }
 async function presentControlledFailure7(admitted, failureInput, io) {
@@ -25615,25 +25579,10 @@ async function runPublicMerger(argv, env, io, parseMergerArgv2) {
     })
   });
 }
-async function runPublicMergerResume(argv, env, io) {
-  const runId = argv[0];
-  if (runId === void 0 || runId.trim() === "" || runId.startsWith("-")) {
-    presentStructuralRejection(
-      new CliUsageError("usage: ak-role resume <runId>"),
-      io
-    );
-    return { exitCode: 2 };
-  }
-  if (argv.length > 1) {
-    presentStructuralRejection(
-      new CliUsageError("resume takes exactly one run id"),
-      io
-    );
-    return { exitCode: 2 };
-  }
+async function runPublicMergerResume(request, env, io) {
   let loaded;
   try {
-    loaded = await loadResumableMergerRun(env.home, runId);
+    loaded = await loadResumableMergerRun(env.home, request.runId);
   } catch (error) {
     if (error instanceof CliUsageError) {
       presentStructuralRejection(error, io);
@@ -25672,7 +25621,8 @@ async function runPublicMergerResume(argv, env, io) {
   const extraArgs = buildMergerResumeActivationExtraArgs(admitted, {
     packageRoot: env.packageRoot,
     ...env.model === void 0 ? {} : { model: env.model },
-    ...env.extraPiArgs === void 0 ? {} : { extraPiArgs: env.extraPiArgs }
+    ...env.extraPiArgs === void 0 ? {} : { extraPiArgs: env.extraPiArgs },
+    ...request.message === void 0 ? {} : { message: request.message }
   });
   const result2 = await dispatchAdmittedMerger({
     admitted,
@@ -25777,7 +25727,7 @@ function buildReviewerResumeActivationExtraArgs(admitted, options) {
     "--mode",
     "json",
     ...buildSeatModelCliArgs(options.model),
-    RESUME_TRANSPORT_ENVELOPE
+    selectResumeContinuationPrompt(options.message)
   ];
 }
 async function presentControlledFailure8(admitted, failureInput, io) {
@@ -26033,25 +25983,10 @@ async function runPublicReviewer(argv, env, io, parseReviewerArgv2) {
     })
   });
 }
-async function runPublicReviewerResume(argv, env, io) {
-  const runId = argv[0];
-  if (runId === void 0 || runId.trim() === "" || runId.startsWith("-")) {
-    presentStructuralRejection(
-      new CliUsageError("usage: ak-role resume <runId>"),
-      io
-    );
-    return { exitCode: 2 };
-  }
-  if (argv.length > 1) {
-    presentStructuralRejection(
-      new CliUsageError("resume takes exactly one run id"),
-      io
-    );
-    return { exitCode: 2 };
-  }
+async function runPublicReviewerResume(request, env, io) {
   let loaded;
   try {
-    loaded = await loadResumableReviewerRun(env.home, runId);
+    loaded = await loadResumableReviewerRun(env.home, request.runId);
   } catch (error) {
     if (error instanceof CliUsageError) {
       presentStructuralRejection(error, io);
@@ -26089,7 +26024,8 @@ async function runPublicReviewerResume(argv, env, io) {
   const extraArgs = buildReviewerResumeActivationExtraArgs(admitted, {
     packageRoot: env.packageRoot,
     ...env.model === void 0 ? {} : { model: env.model },
-    ...env.extraPiArgs === void 0 ? {} : { extraPiArgs: env.extraPiArgs }
+    ...env.extraPiArgs === void 0 ? {} : { extraPiArgs: env.extraPiArgs },
+    ...request.message === void 0 ? {} : { message: request.message }
   });
   const result2 = await dispatchAdmittedReviewer({
     admitted,
@@ -28729,6 +28665,10 @@ function parseArgv(argv) {
   const positional = [];
   const globalOptions = createTypedOptionConsumer(PUBLIC_GLOBAL_OPTIONS);
   while (args.length > 0) {
+    if (positional[0] === "resume" && positional.length >= 2) {
+      positional.push(...args);
+      break;
+    }
     if (args[0] === "--") {
       args.shift();
       positional.push(...args);
@@ -28779,6 +28719,19 @@ function parseArgv(argv) {
     help
   };
 }
+function parseResumeRequest(args) {
+  const runId = args[0];
+  if (runId === void 0 || runId.trim() === "" || runId.startsWith("-")) {
+    throw new CliUsageError("usage: ak-role resume <runId> [message]");
+  }
+  if (args.length > 2) {
+    throw new CliUsageError("usage: ak-role resume <runId> [message]");
+  }
+  if (args.length === 2) {
+    return { runId, message: args[1] };
+  }
+  return { runId };
+}
 function invocationFromParsed(parsed) {
   if (parsed.model === void 0 && parsed.thinking === void 0 && parsed.engine === void 0) {
     return void 0;
@@ -29149,8 +29102,8 @@ async function runAkRole(argv, env) {
       const cwd = env.cwd ?? process.cwd();
       const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials = env.credentials ?? await loadCredentialProviders(agentDir);
-      const resumeRunId = parsed.args[0];
-      const resumeRole = resumeRunId === void 0 || resumeRunId.trim() === "" ? void 0 : await peekRoleRunRole(home, resumeRunId);
+      const resumeRequest = parseResumeRequest(parsed.args);
+      const resumeRole = await peekRoleRunRole(home, resumeRequest.runId);
       if (resumeRole === "collector") {
         throw new CliUsageError(
           "collector role runs are one-shot and cannot be resumed"
@@ -29170,7 +29123,7 @@ async function runAkRole(argv, env) {
       );
       if (resumeRole === "coder") {
         const result3 = await runPublicCoderResume(
-          parsed.args,
+          resumeRequest,
           {
             home,
             agentDir,
@@ -29192,7 +29145,7 @@ async function runAkRole(argv, env) {
       }
       if (resumeRole === "fixer") {
         const result3 = await runPublicFixerResume(
-          parsed.args,
+          resumeRequest,
           {
             home,
             agentDir,
@@ -29214,7 +29167,7 @@ async function runAkRole(argv, env) {
       }
       if (resumeRole === "reviewer") {
         const result3 = await runPublicReviewerResume(
-          parsed.args,
+          resumeRequest,
           {
             home,
             agentDir,
@@ -29236,7 +29189,7 @@ async function runAkRole(argv, env) {
       }
       if (resumeRole === "merger") {
         const result3 = await runPublicMergerResume(
-          parsed.args,
+          resumeRequest,
           {
             home,
             agentDir,
@@ -29257,7 +29210,7 @@ async function runAkRole(argv, env) {
         };
       }
       const result2 = await runPublicResume(
-        parsed.args,
+        resumeRequest,
         {
           home,
           agentDir,

package/package.json

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

package/src/factory-board.ts

@@ -398,7 +398,7 @@ const YAMEN_LABELS: Readonly<Record<string, string>> = {
   coder: "将作监",
   fixer: "修内司",
   reviewer: "御史台",
-  collector: "门下省",
+  collector: "通进司",
   doctor: "太医署",
   merger: "校书郎",
   marshal: "刑部",
@@ -808,7 +808,7 @@ const COLUMN_LABELS: Readonly<Record<string, string>> = {
   court: "大理寺 · 审票",
   coder: "将作监",
   marshal: "刑部",
-  collector: "门下省",
+  collector: "通进司",
   done: "已完成",
 };
 

package/src/public-cli/cli.ts

@@ -64,7 +64,11 @@ import { runPublicJudge, runPublicResume } from "./judge-run.ts";
 import { runPublicMerger, runPublicMergerResume } from "./merger-run.ts";
 import { runPublicReviewer, runPublicReviewerResume } from "./reviewer-run.ts";
 import { runPublicAnalyst } from "./analyst-run.ts";
-import { AUTO_RESUME_LIMIT, peekRoleRunRole } from "./run-lifecycle.ts";
+import {
+  AUTO_RESUME_LIMIT,
+  peekRoleRunRole,
+  type PublicResumeRequest,
+} from "./run-lifecycle.ts";
 import {
   INTERNAL_ROLE_ENTRYPOINT_RELATIVE,
   isAutomaticConfigurableSeat,
@@ -270,7 +274,14 @@ function parseArgv(argv: readonly string[]): ParsedGlobal {
   // Global flags may appear before or after the subcommand
   // (`ak-role --model x roles` and `ak-role roles --model x`).
   // Grammar authority: shared typed consumer over PUBLIC_OPTION_TABLE.global.
+  // #471: after `resume <runId>`, remaining argv is the opaque message segment
+  // and must not re-enter the global-option consumer — including bare `--`,
+  // which is a legal opaque message token, not an argv delimiter here.
   while (args.length > 0) {
+    if (positional[0] === "resume" && positional.length >= 2) {
+      positional.push(...args);
+      break;
+    }
     if (args[0] === "--") {
       args.shift();
       positional.push(...args);
@@ -326,6 +337,24 @@ function parseArgv(argv: readonly string[]): ParsedGlobal {
   };
 }
 
+/**
+ * Unique public resume request parser (#471).
+ * One optional argv after runId is the opaque message; no further positionals.
+ */
+function parseResumeRequest(args: readonly string[]): PublicResumeRequest {
+  const runId = args[0];
+  if (runId === undefined || runId.trim() === "" || runId.startsWith("-")) {
+    throw new CliUsageError("usage: ak-role resume <runId> [message]");
+  }
+  if (args.length > 2) {
+    throw new CliUsageError("usage: ak-role resume <runId> [message]");
+  }
+  if (args.length === 2) {
+    return { runId, message: args[1]! };
+  }
+  return { runId };
+}
+
 function invocationFromParsed(parsed: ParsedGlobal): InvocationModelOverride | undefined {
   if (
     parsed.model === undefined &&
@@ -784,17 +813,15 @@ export async function runAkRole(
 
     // Resume reopens an exact Role run (#416): caller decides; session principal
     // must still exist. Seat and dispatch follow the durable admitted role.
+    // #471: unique parser owns {runId, message?}; five role paths only consume it.
     if (parsed.command === "resume") {
       const agentDir = resolveAgentDir(env, home);
       const cwd = env.cwd ?? process.cwd();
       const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials =
         env.credentials ?? (await loadCredentialProviders(agentDir));
-      const resumeRunId = parsed.args[0];
-      const resumeRole =
-        resumeRunId === undefined || resumeRunId.trim() === ""
-          ? undefined
-          : await peekRoleRunRole(home, resumeRunId);
+      const resumeRequest = parseResumeRequest(parsed.args);
+      const resumeRole = await peekRoleRunRole(home, resumeRequest.runId);
       if (resumeRole === "collector") {
         throw new CliUsageError(
           "collector role runs are one-shot and cannot be resumed",
@@ -824,7 +851,7 @@ export async function runAkRole(
       );
       if (resumeRole === "coder") {
         const result = await runPublicCoderResume(
-          parsed.args,
+          resumeRequest,
           {
             home,
             agentDir,
@@ -852,7 +879,7 @@ export async function runAkRole(
       }
       if (resumeRole === "fixer") {
         const result = await runPublicFixerResume(
-          parsed.args,
+          resumeRequest,
           {
             home,
             agentDir,
@@ -880,7 +907,7 @@ export async function runAkRole(
       }
       if (resumeRole === "reviewer") {
         const result = await runPublicReviewerResume(
-          parsed.args,
+          resumeRequest,
           {
             home,
             agentDir,
@@ -908,7 +935,7 @@ export async function runAkRole(
       }
       if (resumeRole === "merger") {
         const result = await runPublicMergerResume(
-          parsed.args,
+          resumeRequest,
           {
             home,
             agentDir,
@@ -935,7 +962,7 @@ export async function runAkRole(
         };
       }
       const result = await runPublicResume(
-        parsed.args,
+        resumeRequest,
         {
           home,
           agentDir,

package/src/public-cli/coder-run.ts

@@ -45,7 +45,8 @@ import {
   markRunRunning,
   markRunTerminal,
   renderResumeCommand,
-  RESUME_TRANSPORT_ENVELOPE,
+  type PublicResumeRequest,
+  selectResumeContinuationPrompt,
   RunWriterLeaseHeldError,
   type RunWriterLease,
   type TypedProviderHttpObservation,
@@ -152,6 +153,7 @@ export function buildCoderResumeActivationExtraArgs(
     packageRoot: string;
     model?: SeatModelConfig;
     extraPiArgs?: readonly string[];
+    message?: string;
   },
 ): string[] {
   const skillArgs =
@@ -181,7 +183,7 @@ export function buildCoderResumeActivationExtraArgs(
     "--mode",
     "json",
     ...buildSeatModelCliArgs(options.model),
-    RESUME_TRANSPORT_ENVELOPE,
+    selectResumeContinuationPrompt(options.message),
   ];
 }
 
@@ -513,7 +515,7 @@ export async function runPublicCoder(
  * Restores role/phase/task/session identity; model override is temporary.
  */
 export async function runPublicCoderResume(
-  argv: readonly string[],
+  request: PublicResumeRequest,
   env: CoderRunEnv,
   io: CliIo,
 ): Promise<{
@@ -521,25 +523,9 @@ export async function runPublicCoderResume(
   admitted?: AdmittedCoderInvocation;
   terminal?: TerminalResult;
 }> {
-  const runId = argv[0];
-  if (runId === undefined || runId.trim() === "" || runId.startsWith("-")) {
-    presentStructuralRejection(
-      new CliUsageError("usage: ak-role resume <runId>"),
-      io,
-    );
-    return { exitCode: 2 };
-  }
-  if (argv.length > 1) {
-    presentStructuralRejection(
-      new CliUsageError("resume takes exactly one run id"),
-      io,
-    );
-    return { exitCode: 2 };
-  }
-
   let loaded;
   try {
-    loaded = await loadResumableCoderRun(env.home, runId);
+    loaded = await loadResumableCoderRun(env.home, request.runId);
   } catch (error) {
     if (error instanceof CliUsageError) {
       presentStructuralRejection(error, io);
@@ -590,6 +576,7 @@ export async function runPublicCoderResume(
     packageRoot: env.packageRoot,
     ...(env.model === undefined ? {} : { model: env.model }),
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+    ...(request.message === undefined ? {} : { message: request.message }),
   });
 
   const result = await dispatchAdmittedCoder({

package/src/public-cli/fixer-run.ts

@@ -47,7 +47,8 @@ import {
   markRunRunning,
   markRunTerminal,
   renderResumeCommand,
-  RESUME_TRANSPORT_ENVELOPE,
+  type PublicResumeRequest,
+  selectResumeContinuationPrompt,
   RunWriterLeaseHeldError,
   type RunWriterLease,
   type TypedProviderHttpObservation,
@@ -161,6 +162,7 @@ export function buildFixerResumeActivationExtraArgs(
     packageRoot: string;
     model?: SeatModelConfig;
     extraPiArgs?: readonly string[];
+    message?: string;
   },
 ): string[] {
   const diagnosisSkillPath = resolvePackagedMethodSkillPath(
@@ -196,7 +198,7 @@ export function buildFixerResumeActivationExtraArgs(
     "--mode",
     "json",
     ...buildSeatModelCliArgs(options.model),
-    RESUME_TRANSPORT_ENVELOPE,
+    selectResumeContinuationPrompt(options.message),
   ];
 }
 
@@ -532,7 +534,7 @@ export async function runPublicFixer(
  * Restores role/phase/packet/prerequisites/session identity; model override is temporary.
  */
 export async function runPublicFixerResume(
-  argv: readonly string[],
+  request: PublicResumeRequest,
   env: FixerRunEnv,
   io: CliIo,
 ): Promise<{
@@ -540,25 +542,9 @@ export async function runPublicFixerResume(
   admitted?: AdmittedFixerInvocation;
   terminal?: TerminalResult;
 }> {
-  const runId = argv[0];
-  if (runId === undefined || runId.trim() === "" || runId.startsWith("-")) {
-    presentStructuralRejection(
-      new CliUsageError("usage: ak-role resume <runId>"),
-      io,
-    );
-    return { exitCode: 2 };
-  }
-  if (argv.length > 1) {
-    presentStructuralRejection(
-      new CliUsageError("resume takes exactly one run id"),
-      io,
-    );
-    return { exitCode: 2 };
-  }
-
   let loaded;
   try {
-    loaded = await loadResumableFixerRun(env.home, runId);
+    loaded = await loadResumableFixerRun(env.home, request.runId);
   } catch (error) {
     if (error instanceof CliUsageError) {
       presentStructuralRejection(error, io);
@@ -601,6 +587,7 @@ export async function runPublicFixerResume(
     packageRoot: env.packageRoot,
     ...(env.model === undefined ? {} : { model: env.model }),
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+    ...(request.message === undefined ? {} : { message: request.message }),
   });
 
   const result = await dispatchAdmittedFixer({

package/src/public-cli/judge-run.ts

@@ -41,7 +41,8 @@ import {
   markRunTerminal,
   renderResumeCommand,
   type TypedProviderHttpObservation,
-  RESUME_TRANSPORT_ENVELOPE,
+  type PublicResumeRequest,
+  selectResumeContinuationPrompt,
   RunWriterLeaseHeldError,
   type RunWriterLease,
 } from "./run-lifecycle.ts";
@@ -147,6 +148,7 @@ export function buildJudgeResumeActivationExtraArgs(
   options: {
     model?: SeatModelConfig;
     extraPiArgs?: readonly string[];
+    message?: string;
   } = {},
 ): string[] {
   return [
@@ -164,7 +166,7 @@ export function buildJudgeResumeActivationExtraArgs(
     "--mode",
     "json",
     ...buildSeatModelCliArgs(options.model),
-    RESUME_TRANSPORT_ENVELOPE,
+    selectResumeContinuationPrompt(options.message),
   ];
 }
 
@@ -500,7 +502,7 @@ export async function runPublicJudge(
  * is temporary for this invocation only.
  */
 export async function runPublicResume(
-  argv: readonly string[],
+  request: PublicResumeRequest,
   env: JudgeRunEnv,
   io: CliIo,
 ): Promise<{
@@ -508,26 +510,9 @@ export async function runPublicResume(
   admitted?: AdmittedJudgeInvocation;
   terminal?: TerminalResult;
 }> {
-  const runId = argv[0];
-  if (runId === undefined || runId.trim() === "" || runId.startsWith("-")) {
-    presentStructuralRejection(
-      new CliUsageError("usage: ak-role resume <runId>"),
-      io,
-    );
-    return { exitCode: 2 };
-  }
-  if (argv.length > 1) {
-    // Resume does not accept free positionals beyond runId (model/thinking are global).
-    presentStructuralRejection(
-      new CliUsageError("resume takes exactly one run id"),
-      io,
-    );
-    return { exitCode: 2 };
-  }
-
   let loaded;
   try {
-    loaded = await loadResumableJudgeRun(env.home, runId);
+    loaded = await loadResumableJudgeRun(env.home, request.runId);
   } catch (error) {
     if (error instanceof CliUsageError) {
       presentStructuralRejection(error, io);
@@ -553,6 +538,7 @@ export async function runPublicResume(
   const extraArgs = buildJudgeResumeActivationExtraArgs(admitted, {
     ...(env.model === undefined ? {} : { model: env.model }),
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+    ...(request.message === undefined ? {} : { message: request.message }),
   });
 
   const result = await dispatchAdmittedJudge({

package/src/public-cli/merger-run.ts

@@ -50,7 +50,8 @@ import {
   markRunRunning,
   markRunTerminal,
   renderResumeCommand,
-  RESUME_TRANSPORT_ENVELOPE,
+  type PublicResumeRequest,
+  selectResumeContinuationPrompt,
   RunWriterLeaseHeldError,
   type RunWriterLease,
   type TypedProviderHttpObservation,
@@ -152,6 +153,7 @@ export function buildMergerResumeActivationExtraArgs(
     packageRoot: string;
     model?: SeatModelConfig;
     extraPiArgs?: readonly string[];
+    message?: string;
   },
 ): string[] {
   const skillPath = resolvePackagedMethodSkillPath(
@@ -177,7 +179,7 @@ export function buildMergerResumeActivationExtraArgs(
     "--mode",
     "json",
     ...buildSeatModelCliArgs(options.model),
-    RESUME_TRANSPORT_ENVELOPE,
+    selectResumeContinuationPrompt(options.message),
   ];
 }
 
@@ -613,7 +615,7 @@ export async function runPublicMerger(
  * Restores derived input/session identity; model override is temporary.
  */
 export async function runPublicMergerResume(
-  argv: readonly string[],
+  request: PublicResumeRequest,
   env: MergerRunEnv,
   io: CliIo,
 ): Promise<{
@@ -621,25 +623,9 @@ export async function runPublicMergerResume(
   admitted?: AdmittedMergerInvocation;
   terminal?: TerminalResult;
 }> {
-  const runId = argv[0];
-  if (runId === undefined || runId.trim() === "" || runId.startsWith("-")) {
-    presentStructuralRejection(
-      new CliUsageError("usage: ak-role resume <runId>"),
-      io,
-    );
-    return { exitCode: 2 };
-  }
-  if (argv.length > 1) {
-    presentStructuralRejection(
-      new CliUsageError("resume takes exactly one run id"),
-      io,
-    );
-    return { exitCode: 2 };
-  }
-
   let loaded;
   try {
-    loaded = await loadResumableMergerRun(env.home, runId);
+    loaded = await loadResumableMergerRun(env.home, request.runId);
   } catch (error) {
     if (error instanceof CliUsageError) {
       presentStructuralRejection(error, io);
@@ -683,6 +669,7 @@ export async function runPublicMergerResume(
     packageRoot: env.packageRoot,
     ...(env.model === undefined ? {} : { model: env.model }),
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+    ...(request.message === undefined ? {} : { message: request.message }),
   });
 
   const result = await dispatchAdmittedMerger({

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

@@ -1146,8 +1146,11 @@ const SUPPORT_COMMAND_HELP = {
   resume: {
     command: "resume",
     summary: "Reopen an exact role run whose Pi session principal still exists.",
-    usage: ["ak-role resume <runId>"],
-    examples: ["ak-role resume 01abc…"],
+    usage: ["ak-role resume <runId> [message]"],
+    examples: [
+      "ak-role resume 01abc…",
+      "ak-role resume 01abc… \"owner ruling\"",
+    ],
   },
 } as const satisfies Record<string, PublicCommandHelpFacts>;
 

package/src/public-cli/reviewer-run.ts

@@ -48,7 +48,8 @@ import {
   markRunRunning,
   markRunTerminal,
   renderResumeCommand,
-  RESUME_TRANSPORT_ENVELOPE,
+  type PublicResumeRequest,
+  selectResumeContinuationPrompt,
   RunWriterLeaseHeldError,
   type RunWriterLease,
   type TypedProviderHttpObservation,
@@ -169,6 +170,7 @@ export function buildReviewerResumeActivationExtraArgs(
     packageRoot: string;
     model?: SeatModelConfig;
     extraPiArgs?: readonly string[];
+    message?: string;
   },
 ): string[] {
   const skillPath = resolvePackagedMethodSkillPath(
@@ -201,7 +203,7 @@ export function buildReviewerResumeActivationExtraArgs(
     "--mode",
     "json",
     ...buildSeatModelCliArgs(options.model),
-    RESUME_TRANSPORT_ENVELOPE,
+    selectResumeContinuationPrompt(options.message),
   ];
 }
 
@@ -552,7 +554,7 @@ export async function runPublicReviewer(
  * Restores task/base/session identity; model override is temporary.
  */
 export async function runPublicReviewerResume(
-  argv: readonly string[],
+  request: PublicResumeRequest,
   env: ReviewerRunEnv,
   io: CliIo,
 ): Promise<{
@@ -560,25 +562,9 @@ export async function runPublicReviewerResume(
   admitted?: AdmittedReviewerInvocation;
   terminal?: TerminalResult;
 }> {
-  const runId = argv[0];
-  if (runId === undefined || runId.trim() === "" || runId.startsWith("-")) {
-    presentStructuralRejection(
-      new CliUsageError("usage: ak-role resume <runId>"),
-      io,
-    );
-    return { exitCode: 2 };
-  }
-  if (argv.length > 1) {
-    presentStructuralRejection(
-      new CliUsageError("resume takes exactly one run id"),
-      io,
-    );
-    return { exitCode: 2 };
-  }
-
   let loaded;
   try {
-    loaded = await loadResumableReviewerRun(env.home, runId);
+    loaded = await loadResumableReviewerRun(env.home, request.runId);
   } catch (error) {
     if (error instanceof CliUsageError) {
       presentStructuralRejection(error, io);
@@ -621,6 +607,7 @@ export async function runPublicReviewerResume(
     packageRoot: env.packageRoot,
     ...(env.model === undefined ? {} : { model: env.model }),
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+    ...(request.message === undefined ? {} : { message: request.message }),
   });
 
   const result = await dispatchAdmittedReviewer({

package/src/public-cli/run-lifecycle.ts

@@ -88,6 +88,22 @@ export type RoleRunRecord = {
 /** Package-owned turn trigger for resume. Not caller instruction and not semantic task content. */
 export const RESUME_TRANSPORT_ENVELOPE = "[ak-role:resume-continue]" as const;
 
+/** Public manual resume request after the unique CLI parser owns runId + optional message. */
+export type PublicResumeRequest = {
+  readonly runId: string;
+  /** Present when the caller supplied the post-runId argv (including empty string). */
+  readonly message?: string;
+};
+
+/**
+ * Unique continuation-prompt selector for manual/auto resume (#471).
+ * Message present → return bytes unchanged; absent → package transport envelope.
+ * Zero parse, zero classify, zero narrow.
+ */
+export function selectResumeContinuationPrompt(message?: string): string {
+  return message !== undefined ? message : RESUME_TRANSPORT_ENVELOPE;
+}
+
 const RUN_STATE_FILE = "run-state.json";
 const WRITER_LOCK_FILE = "writer.lock";