@akagilnc/pi-workflow-roles 0.1.2340 → 0.1.2348

package/README.md

@@ -23,11 +23,11 @@ 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, Doctor, and Notary 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 <provider/model[:thinking]> 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 seats like this:
 
@@ -100,6 +100,9 @@ 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

@@ -23,11 +23,11 @@ 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 <provider/model[:thinking]> resume <runId>`。
+全局覆盖须在 opaque message 段之前：`ak-role --model <provider/model[:thinking]> resume <runId>` 或 `ak-role resume --model <provider/model[:thinking]> <runId>`。
 
 每次运行游奕使自动出席，建议随同一 Terminal 给出。配置：
 
@@ -100,6 +100,9 @@ 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> "<裁定>"
 ```
 
 ## 班子（唐宋官署命名）

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.2340",
+  "version": "0.1.2348",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

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";