@akagilnc/pi-workflow-roles 0.1.1918 → 0.1.2004

package/src/public-cli/invocation.ts

@@ -134,6 +134,11 @@ export type AdmittedReviewerInvocation = AdmittedRoleInvocationBase & {
   readonly role: "reviewer";
   /** Required fixed base revision for the pinned review target (ADR 0037). */
   readonly baseRevision: string;
+  /**
+   * Optional durable authority references/URLs frozen at admission.
+   * Spec evidence-child material only — never Standards, never invocation prose promotion.
+   */
+  readonly authorityRefs: readonly string[];
 };
 
 /** Mechanical envelope derived from the active ordinary two-parent merge. */
@@ -318,6 +323,8 @@ export type ParseReviewerArgvResult = {
   attachmentPaths: string[];
   /** Required fixed base revision for the pinned review target. */
   baseRevision: string;
+  /** Repeatable durable authority references/URLs (exact order preserved). */
+  authorityRefs: string[];
   project?: string;
 };
 
@@ -327,6 +334,50 @@ export type ParseMergerArgvResult = {
   project?: string;
 };
 
+/**
+ * #336/#337/#338 taishi public argv — four faces on one registration seam.
+ * - issue (default): ticket N and/or project-root P
+ * - sweep (#337): optional positional `sweep` and/or --attach paths;
+ *   sweep payload rides exactly one typed JSON attachment (not argv/stdin)
+ * - cohort: two labeled issue-number groups
+ * - model-groups: one or more project-root scope keys
+ */
+export type ParseTaishiIssueArgv = {
+  readonly query: "issue";
+  /** Caller ticket / issue number face (#176 numbering space). */
+  readonly ticket?: number;
+  /** Direct projectRoot mechanical key (ADR 0068). */
+  readonly projectRoot?: string;
+};
+
+export type ParseTaishiSweepArgv = {
+  readonly query: "sweep";
+  /**
+   * Public CLI attachment paths (--attach). Sweep mode only (#337).
+   * Cardinality validated on the sweep run path (exactly one).
+   */
+  readonly attachmentPaths: readonly string[];
+};
+
+export type ParseTaishiCohortArgv = {
+  readonly query: "cohort";
+  readonly groups: readonly [
+    { readonly groupLabel: string; readonly issues: readonly number[] },
+    { readonly groupLabel: string; readonly issues: readonly number[] },
+  ];
+};
+
+export type ParseTaishiModelGroupsArgv = {
+  readonly query: "model-groups";
+  readonly projectRoots: readonly string[];
+};
+
+export type ParseTaishiArgvResult =
+  | ParseTaishiIssueArgv
+  | ParseTaishiSweepArgv
+  | ParseTaishiCohortArgv
+  | ParseTaishiModelGroupsArgv;
+
 /** Honest activation-class failure while deriving the active-merge envelope. */
 export class MergerEnvelopeDerivationError extends Error {
   readonly code = "merger-envelope-derivation" as const;
@@ -340,7 +391,13 @@ export class MergerEnvelopeDerivationError extends Error {
 
 /** Reject missing/blank path values so empty overrides cannot silently degrade. */
 function requireOptionPath(
-  flag: "--project" | "--attach" | "--prerequisites" | "--request-manifest" | "--base",
+  flag:
+    | "--project"
+    | "--attach"
+    | "--prerequisites"
+    | "--request-manifest"
+    | "--base"
+    | "--project-root",
   value: string | undefined,
 ): string {
   if (value === undefined || value.trim() === "") {
@@ -353,6 +410,25 @@ function requireOptionPath(
   return value;
 }
 
+/**
+ * Public --authority-ref admission grammar (refs-only).
+ * Unique owner for fresh argv and durable resume restore — no string-only parallel.
+ * Accepts durable reference tokens as-is; rejects blank and inline Spec prose
+ * (whitespace-bearing sentences). Does not fetch, normalize, or judge content.
+ */
+export function requireAuthorityRef(value: string | undefined): string {
+  if (value === undefined || value.trim() === "") {
+    throw new CliUsageError("--authority-ref requires a nonempty durable reference");
+  }
+  // Spec prose sentences contain whitespace; durable public refs are single tokens.
+  if (/\s/.test(value)) {
+    throw new CliUsageError(
+      "--authority-ref requires a durable reference, not inline Spec prose",
+    );
+  }
+  return value;
+}
+
 /**
  * Parse Judge-specific argv after the `judge` token.
  * Rejects any public burden selector/hint and unknown flags.
@@ -1581,13 +1657,15 @@ export function buildDoctorTransportPrompt(
 
 /**
  * Parse Reviewer-specific argv after the `reviewer` token.
- * Public flags: --project and required --base (the non-interactive CLI cannot answer the canonical fixed-point question).
+ * Public flags: --project, required --base, optional repeatable --authority-ref.
  * Reviewer gathers its own evidence; users submit neither attachments nor capability packets.
+ * Caller instruction remains scope/procedure provenance — not Spec authority.
  */
 export function parseReviewerArgv(
   args: readonly string[],
 ): ParseReviewerArgvResult {
   const attachmentPaths: string[] = [];
+  const authorityRefs: string[] = [];
   let project: string | undefined;
   let baseRevision: string | undefined;
   const positional: string[] = [];
@@ -1615,6 +1693,14 @@ export function parseReviewerArgv(
       baseRevision = requireOptionPath("--base", token.slice("--base=".length));
       continue;
     }
+    if (token === "--authority-ref") {
+      authorityRefs.push(requireAuthorityRef(tokens.shift()));
+      continue;
+    }
+    if (token.startsWith("--authority-ref=")) {
+      authorityRefs.push(requireAuthorityRef(token.slice("--authority-ref=".length)));
+      continue;
+    }
     if (token.startsWith("-") && token !== "-") {
       throw new CliUsageError(`unknown reviewer option: ${token}`);
     }
@@ -1628,6 +1714,7 @@ export function parseReviewerArgv(
     instruction: positional.join(" "),
     attachmentPaths,
     baseRevision,
+    authorityRefs,
     ...(project === undefined ? {} : { project }),
   };
 }
@@ -1639,6 +1726,8 @@ export type AdmitReviewerInvocationOptions = {
   instruction: string;
   attachmentPaths: readonly string[];
   baseRevision: string;
+  /** Optional durable authority references/URLs; frozen unchanged at admission. */
+  authorityRefs?: readonly string[];
   project?: string;
   createRunId?: () => string;
 };
@@ -1646,6 +1735,7 @@ export type AdmitReviewerInvocationOptions = {
 /**
  * Admit a Reviewer Role run on the fixed base only.
  * Caller instruction is optional provenance; Reviewer acquires issue/authority independently.
+ * Optional authorityRefs are frozen as durable references only — not Spec prose.
  */
 export async function admitReviewerInvocation(
   options: AdmitReviewerInvocationOptions,
@@ -1656,6 +1746,9 @@ export async function admitReviewerInvocation(
   if (options.baseRevision.trim() === "") {
     throw new CliUsageError("--base requires a nonempty revision");
   }
+  const authorityRefs = Object.freeze(
+    (options.authorityRefs ?? []).map((ref) => requireAuthorityRef(ref)),
+  );
 
   const projectRoot = resolve(options.project ?? options.cwd);
   const runId = (options.createRunId ?? uuidv7)();
@@ -1686,6 +1779,7 @@ export async function admitReviewerInvocation(
     instruction,
     instructionEmpty,
     baseRevision: options.baseRevision,
+    authorityRefs: [...authorityRefs],
     attachments: attachments.map((a) => ({
       provenancePath: a.provenancePath,
       frozenPath: a.frozenPath,
@@ -1715,6 +1809,7 @@ export async function admitReviewerInvocation(
     sessionFile,
     admittedRequestPath,
     baseRevision: options.baseRevision,
+    authorityRefs,
     ...ticketFields,
   };
 }
@@ -1996,3 +2091,304 @@ export function buildMergerTransportPrompt(
   }
   return lines.join("\n");
 }
+
+const TAISHI_TICKET_NUMBER_PATTERN = /^[1-9]\d*$/;
+
+/**
+ * Parse a positive ticket / issue number for public taishi admission.
+ * Leading zeros and non-integers are structural rejects (same face as #176).
+ * `flag` names the actual argv face in diagnostics (cohort group lists reuse this).
+ */
+export function parseTaishiTicketNumber(
+  raw: string,
+  flag: string = "--ticket",
+): number {
+  const trimmed = raw.trim();
+  if (!TAISHI_TICKET_NUMBER_PATTERN.test(trimmed)) {
+    throw new CliUsageError(
+      `taishi ${flag} must be a positive integer, got ${raw}`,
+    );
+  }
+  const value = Number(trimmed);
+  // Digit-only strings beyond MAX_SAFE_INTEGER round or become Infinity — reject.
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new CliUsageError(
+      `taishi ${flag} must be a positive integer, got ${raw}`,
+    );
+  }
+  return value;
+}
+
+function parseTaishiIssueNumberList(raw: string, flag: string): number[] {
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    throw new CliUsageError(`${flag} requires a comma-separated positive integer list`);
+  }
+  const parts = trimmed.split(",").map((part) => part.trim());
+  if (parts.some((part) => part === "")) {
+    throw new CliUsageError(`${flag} requires a comma-separated positive integer list`);
+  }
+  // Same numeric rule as --ticket; diagnostic names the actual group flag.
+  return parts.map((part) => parseTaishiTicketNumber(part, flag));
+}
+
+function requireOptionValue(
+  flag: string,
+  value: string | undefined,
+  what: string,
+): string {
+  if (value === undefined || value.trim() === "") {
+    throw new CliUsageError(`${flag} requires ${what}`);
+  }
+  return value;
+}
+
+/**
+ * Parse taishi-specific argv after the `taishi` token (#336/#337/#338).
+ * Issue: at least one of --ticket / --project-root.
+ * Sweep: positional `sweep` and/or --attach; payload is the attachment body only.
+ * Cohort / model-groups: explicit query flags with their own required faces.
+ * Faces are mutually exclusive.
+ */
+export function parseTaishiArgv(args: readonly string[]): ParseTaishiArgvResult {
+  let query: "issue" | "cohort" | "model-groups" = "issue";
+  let ticketRaw: string | undefined;
+  const projectRoots: string[] = [];
+  let groupALabel: string | undefined;
+  let groupAIssuesRaw: string | undefined;
+  let groupBLabel: string | undefined;
+  let groupBIssuesRaw: string | undefined;
+  let sweepToken = false;
+  const attachmentPaths: string[] = [];
+  const tokens = [...args];
+
+  while (tokens.length > 0) {
+    const token = tokens.shift()!;
+    if (token === "--") {
+      if (tokens.length > 0) {
+        throw new CliUsageError(`unexpected taishi argument: ${tokens[0]}`);
+      }
+      break;
+    }
+    if (token === "--cohort") {
+      if (query !== "issue") {
+        throw new CliUsageError("taishi accepts only one of --cohort / --model-groups");
+      }
+      query = "cohort";
+      continue;
+    }
+    if (token === "--model-groups") {
+      if (query !== "issue") {
+        throw new CliUsageError("taishi accepts only one of --cohort / --model-groups");
+      }
+      query = "model-groups";
+      continue;
+    }
+    if (token === "--ticket") {
+      const value = tokens.shift();
+      if (value === undefined || value.trim() === "") {
+        throw new CliUsageError("taishi --ticket requires a positive integer");
+      }
+      ticketRaw = value;
+      continue;
+    }
+    if (token.startsWith("--ticket=")) {
+      ticketRaw = token.slice("--ticket=".length);
+      if (ticketRaw.trim() === "") {
+        throw new CliUsageError("taishi --ticket requires a positive integer");
+      }
+      continue;
+    }
+    if (token === "--project-root") {
+      projectRoots.push(requireOptionPath("--project-root", tokens.shift()));
+      continue;
+    }
+    if (token.startsWith("--project-root=")) {
+      projectRoots.push(
+        requireOptionPath("--project-root", token.slice("--project-root=".length)),
+      );
+      continue;
+    }
+    if (token === "--group-a-label") {
+      groupALabel = requireOptionValue("--group-a-label", tokens.shift(), "a label");
+      continue;
+    }
+    if (token.startsWith("--group-a-label=")) {
+      groupALabel = requireOptionValue(
+        "--group-a-label",
+        token.slice("--group-a-label=".length),
+        "a label",
+      );
+      continue;
+    }
+    if (token === "--group-a-issues") {
+      groupAIssuesRaw = requireOptionValue(
+        "--group-a-issues",
+        tokens.shift(),
+        "a comma-separated positive integer list",
+      );
+      continue;
+    }
+    if (token.startsWith("--group-a-issues=")) {
+      groupAIssuesRaw = requireOptionValue(
+        "--group-a-issues",
+        token.slice("--group-a-issues=".length),
+        "a comma-separated positive integer list",
+      );
+      continue;
+    }
+    if (token === "--group-b-label") {
+      groupBLabel = requireOptionValue("--group-b-label", tokens.shift(), "a label");
+      continue;
+    }
+    if (token.startsWith("--group-b-label=")) {
+      groupBLabel = requireOptionValue(
+        "--group-b-label",
+        token.slice("--group-b-label=".length),
+        "a label",
+      );
+      continue;
+    }
+    if (token === "--group-b-issues") {
+      groupBIssuesRaw = requireOptionValue(
+        "--group-b-issues",
+        tokens.shift(),
+        "a comma-separated positive integer list",
+      );
+      continue;
+    }
+    if (token.startsWith("--group-b-issues=")) {
+      groupBIssuesRaw = requireOptionValue(
+        "--group-b-issues",
+        token.slice("--group-b-issues=".length),
+        "a comma-separated positive integer list",
+      );
+      continue;
+    }
+    if (token === "--attach") {
+      attachmentPaths.push(requireOptionPath("--attach", tokens.shift()));
+      continue;
+    }
+    if (token.startsWith("--attach=")) {
+      attachmentPaths.push(
+        requireOptionPath("--attach", token.slice("--attach=".length)),
+      );
+      continue;
+    }
+    if (token.startsWith("-") && token !== "-") {
+      throw new CliUsageError(`unknown taishi option: ${token}`);
+    }
+    // Optional sweep mode token (like coder plan/apply); only once, no other positionals.
+    if (token === "sweep") {
+      if (sweepToken) {
+        throw new CliUsageError("unexpected taishi argument: sweep");
+      }
+      sweepToken = true;
+      continue;
+    }
+    throw new CliUsageError(`unexpected taishi argument: ${token}`);
+  }
+
+  const hasSweepFace = sweepToken || attachmentPaths.length > 0;
+  const hasCohortFlags =
+    groupALabel !== undefined
+    || groupAIssuesRaw !== undefined
+    || groupBLabel !== undefined
+    || groupBIssuesRaw !== undefined;
+
+  if (query === "cohort") {
+    if (
+      groupALabel === undefined
+      || groupAIssuesRaw === undefined
+      || groupBLabel === undefined
+      || groupBIssuesRaw === undefined
+    ) {
+      throw new CliUsageError(
+        "usage: ak-role taishi --cohort --group-a-label <L> --group-a-issues <N[,N...]> --group-b-label <L> --group-b-issues <N[,N...]>",
+      );
+    }
+    if (ticketRaw !== undefined || projectRoots.length > 0) {
+      throw new CliUsageError(
+        "taishi --cohort does not accept --ticket or --project-root",
+      );
+    }
+    if (hasSweepFace) {
+      throw new CliUsageError(
+        "taishi --cohort does not accept sweep --attach",
+      );
+    }
+    return {
+      query: "cohort",
+      groups: [
+        {
+          groupLabel: groupALabel,
+          issues: parseTaishiIssueNumberList(groupAIssuesRaw, "--group-a-issues"),
+        },
+        {
+          groupLabel: groupBLabel,
+          issues: parseTaishiIssueNumberList(groupBIssuesRaw, "--group-b-issues"),
+        },
+      ],
+    };
+  }
+
+  if (query === "model-groups") {
+    if (projectRoots.length === 0) {
+      throw new CliUsageError(
+        "usage: ak-role taishi --model-groups --project-root <P> [--project-root <P> ...]",
+      );
+    }
+    if (ticketRaw !== undefined) {
+      throw new CliUsageError("taishi --model-groups does not accept --ticket");
+    }
+    if (hasCohortFlags) {
+      throw new CliUsageError("taishi --model-groups does not accept cohort group flags");
+    }
+    if (hasSweepFace) {
+      throw new CliUsageError(
+        "taishi --model-groups does not accept sweep --attach",
+      );
+    }
+    return {
+      query: "model-groups",
+      projectRoots,
+    };
+  }
+
+  // default issue or sweep (#336/#337 faces)
+  if (hasCohortFlags) {
+    throw new CliUsageError("taishi issue query does not accept cohort group flags");
+  }
+
+  if (hasSweepFace) {
+    if (ticketRaw !== undefined || projectRoots.length > 0) {
+      throw new CliUsageError(
+        "taishi sweep --attach cannot combine with --ticket or --project-root",
+      );
+    }
+    return {
+      query: "sweep",
+      attachmentPaths,
+    };
+  }
+
+  if (projectRoots.length > 1) {
+    throw new CliUsageError(
+      "taishi issue query accepts at most one --project-root (use --model-groups for many)",
+    );
+  }
+  const projectRoot = projectRoots[0];
+  if (ticketRaw === undefined && projectRoot === undefined) {
+    throw new CliUsageError(
+      "usage: ak-role taishi ((--ticket <N> | --project-root <P>) | [sweep] --attach <sweep.json> | --cohort ... | --model-groups ...)",
+    );
+  }
+
+  return {
+    query: "issue",
+    ...(ticketRaw === undefined
+      ? {}
+      : { ticket: parseTaishiTicketNumber(ticketRaw) }),
+    ...(projectRoot === undefined ? {} : { projectRoot }),
+  };
+}

package/src/public-cli/main.ts

@@ -1,11 +1,30 @@
+import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { ensureHostPiRuntimeResolvable } from "./host-pi-runtime.ts";
 
 const here = dirname(fileURLToPath(import.meta.url));
-// dist/public-cli/main.js → package root is ../..
-const packageRoot = join(here, "..", "..");
+
+/**
+ * Resolve install package root from the public bin location.
+ *
+ * Shipped layout is `<packageRoot>/dist/public-cli/main.js` → two levels up when
+ * that ancestor owns package.json. A relocated single-file bundle (no package
+ * tree beside the bin) must NOT keep climbing: `join("/tmp/<bin>","..","..")`
+ * is `"/"` on Linux CI, and host-pi linking then does
+ * `mkdir('/node_modules/@earendil-works')` → EACCES. Fall back to the bin
+ * directory so links stay on the ESM ancestor walk and remain writable.
+ */
+function resolvePackageRoot(binDir: string): string {
+  const canonical = join(binDir, "..", "..");
+  if (existsSync(join(canonical, "package.json"))) {
+    return canonical;
+  }
+  return binDir;
+}
+
+const packageRoot = resolvePackageRoot(here);
 
 // The host-provided runtime must be resolvable before the CLI module graph loads it.
 ensureHostPiRuntimeResolvable(packageRoot);

package/src/public-cli/registry.ts

@@ -97,6 +97,12 @@ export function publicStartupCandidates(
   return STARTUP_CANDIDATES[seat];
 }
 
+/** Deterministic public commands — discoverable, never LLM-configurable seats. */
+export const PUBLIC_DETERMINISTIC_COMMANDS = ["taishi"] as const;
+
+export type PublicDeterministicCommand =
+  (typeof PUBLIC_DETERMINISTIC_COMMANDS)[number];
+
 export type HelpCapability =
   | {
       kind: "support";
@@ -107,11 +113,16 @@ export type HelpCapability =
       name: PublicCallableRole;
       phases: readonly (string | null)[];
       defaultPhase: string | null;
+    }
+  | {
+      kind: "deterministic";
+      name: PublicDeterministicCommand;
     };
 
 /**
  * Typed help surface. Presentation formats these facts; tests must not assert
  * exact help prose or layout (锚定宪法 / ADR 0016 / #105 AC).
+ * taishi is a deterministic analysis command on the public CLI — not an LLM seat.
  */
 export function listHelpCapabilities(): readonly HelpCapability[] {
   const support: HelpCapability[] = PUBLIC_CLI_SUPPORT_COMMANDS.map((name) => ({
@@ -133,7 +144,13 @@ export function listHelpCapabilities(): readonly HelpCapability[] {
       defaultPhase,
     };
   });
-  return [...support, ...roles];
+  const deterministic: HelpCapability[] = PUBLIC_DETERMINISTIC_COMMANDS.map(
+    (name) => ({
+      kind: "deterministic" as const,
+      name,
+    }),
+  );
+  return [...support, ...roles, ...deterministic];
 }
 
 export function isPublicCallableRole(value: string): value is PublicCallableRole {

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

@@ -118,6 +118,10 @@ export function buildReviewerActivationExtraArgs(
     options.packageRoot,
     "code-review",
   );
+  const authorityRefArgs =
+    admitted.authorityRefs.length === 0
+      ? []
+      : ["--ak-review-authority-refs", JSON.stringify([...admitted.authorityRefs])];
   return [
     "--no-skills",
     "--skill",
@@ -134,6 +138,7 @@ export function buildReviewerActivationExtraArgs(
     "reviewer",
     "--ak-review-base",
     admitted.baseRevision,
+    ...authorityRefArgs,
     "--mode",
     "json",
     ...buildModelArgs(options.model),
@@ -157,6 +162,10 @@ export function buildReviewerResumeActivationExtraArgs(
     options.packageRoot,
     "code-review",
   );
+  const authorityRefArgs =
+    admitted.authorityRefs.length === 0
+      ? []
+      : ["--ak-review-authority-refs", JSON.stringify([...admitted.authorityRefs])];
   return [
     "--no-skills",
     "--skill",
@@ -173,6 +182,7 @@ export function buildReviewerResumeActivationExtraArgs(
     "reviewer",
     "--ak-review-base",
     admitted.baseRevision,
+    ...authorityRefArgs,
     "--mode",
     "json",
     ...buildModelArgs(options.model),
@@ -420,6 +430,7 @@ export async function runPublicReviewer(
     instruction: string;
     attachmentPaths: string[];
     baseRevision: string;
+    authorityRefs: string[];
     project?: string;
   },
 ): Promise<{
@@ -436,6 +447,7 @@ export async function runPublicReviewer(
       instruction: parsed.instruction,
       attachmentPaths: parsed.attachmentPaths,
       baseRevision: parsed.baseRevision,
+      authorityRefs: parsed.authorityRefs,
       ...(parsed.project === undefined ? {} : { project: parsed.project }),
       ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
     });

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

@@ -24,6 +24,7 @@ export {
 import type { FixerPhase } from "../package-contracts/fixer-output.ts";
 import type { FixerPrerequisite } from "../package-contracts/fixer-packet.ts";
 import {
+  requireAuthorityRef,
   type AdmittedCoderInvocation,
   type AdmittedFixerInvocation,
   type AdmittedJudgeInvocation,
@@ -389,6 +390,7 @@ type LoadedAdmittedRequestFields = {
   readonly prerequisitesPath?: string;
   readonly prerequisites?: readonly FixerPrerequisite[];
   readonly baseRevision?: string;
+  readonly authorityRefs?: readonly string[];
   readonly mergerInputPath?: string;
   readonly derived?: DerivedMergerEnvelope;
   readonly correlationId?: string;
@@ -463,6 +465,7 @@ async function loadResumableRunRecord(
   let prerequisitesPath: string | undefined;
   let prerequisites: readonly FixerPrerequisite[] | undefined;
   let baseRevision: string | undefined;
+  let authorityRefs: readonly string[] | undefined;
   let mergerInputPath: string | undefined;
   let derived: DerivedMergerEnvelope | undefined;
   let correlationId: string | undefined;
@@ -506,6 +509,19 @@ async function loadResumableRunRecord(
       ) {
         baseRevision = record.baseRevision;
       }
+      if (Array.isArray(record.authorityRefs)) {
+        // Reuse unique --authority-ref grammar; blank/inline prose must not resume as authority.
+        authorityRefs = Object.freeze(
+          record.authorityRefs.map((ref) => {
+            if (typeof ref !== "string") {
+              throw new CliUsageError(
+                "role run admitted authority refs must be durable reference strings",
+              );
+            }
+            return requireAuthorityRef(ref);
+          }),
+        );
+      }
       if (
         typeof record.mergerInputPath === "string" &&
         record.mergerInputPath.trim() !== ""
@@ -540,9 +556,12 @@ async function loadResumableRunRecord(
       correlationId = fromAdmitted.correlationId;
       ticketNumber = fromAdmitted.ticketNumber;
     }
-  } catch {
+  } catch (error) {
+    // Preserve unique --authority-ref grammar failures; do not collapse to unreadable.
+    if (error instanceof CliUsageError) throw error;
     throw new CliUsageError(
       `role run admitted request is unreadable: ${runId}`,
+      { cause: error },
     );
   }
   if (correlationId === undefined || ticketNumber === undefined) {
@@ -589,6 +608,7 @@ async function loadResumableRunRecord(
       ...(prerequisitesPath === undefined ? {} : { prerequisitesPath }),
       ...(prerequisites === undefined ? {} : { prerequisites }),
       ...(baseRevision === undefined ? {} : { baseRevision }),
+      ...(authorityRefs === undefined ? {} : { authorityRefs }),
       ...(mergerInputPath === undefined ? {} : { mergerInputPath }),
       ...(derived === undefined ? {} : { derived }),
       ...(correlationId === undefined ? {} : { correlationId }),
@@ -806,6 +826,7 @@ export async function loadResumableReviewerRun(
     sessionFile: loaded.run.sessionFile,
     admittedRequestPath: loaded.run.admittedRequestPath,
     baseRevision,
+    authorityRefs: Object.freeze([...(loaded.admittedFields.authorityRefs ?? [])]),
     ...restoredTicketFields(loaded.admittedFields),
   };
   return {