@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

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

@@ -34,6 +34,8 @@ export type OptionOwner =
   | "inspector"
   | "gatekeeper"
   | "navigator"
+  | "auditor"
+  | "evidence-child"
   | "diarist"
   | "analyst";
 
@@ -423,6 +425,44 @@ const NAVIGATOR_OPTIONS = [
   bindOwner("navigator", SHARED_ATTACH_SEMANTICS),
 ] as const satisfies readonly PublicOptionDefinition[];
 
+const AUDITOR_OPTIONS = [
+  bindOwner("auditor", SHARED_PROJECT_SEMANTICS),
+  bindOwner("auditor", SHARED_ATTACH_SEMANTICS),
+  {
+    id: "subject",
+    owner: "auditor",
+    canonical: "--subject",
+    aliases: [],
+    valueMetavar: "judge|doctor",
+    required: true,
+    repeatable: false,
+    form: "option",
+    description: {
+      en: "Required audited subject: judge or doctor (selects judge-auditor.md / doctor-auditor.md).",
+      zh: "必填受审对象：judge 或 doctor（装 judge-auditor.md / doctor-auditor.md）。",
+    },
+  },
+  {
+    id: "source-run",
+    owner: "auditor",
+    canonical: "--source-run",
+    aliases: [],
+    valueMetavar: "runId@role|path",
+    required: true,
+    repeatable: false,
+    form: "option",
+    description: {
+      en: "Required source run locator of the audited subject volume (same input for direct and nested summons).",
+      zh: "必填受审卷宗 locator（直调与传召同一输入面）。",
+    },
+  },
+] as const satisfies readonly PublicOptionDefinition[];
+
+const EVIDENCE_CHILD_OPTIONS = [
+  bindOwner("evidence-child", SHARED_PROJECT_SEMANTICS),
+  bindOwner("evidence-child", SHARED_ATTACH_SEMANTICS),
+] as const satisfies readonly PublicOptionDefinition[];
+
 const COUNTERSIGN_OPTIONS = [
   bindOwner("countersign", SHARED_PROJECT_SEMANTICS),
   bindOwner("countersign", SHARED_ATTACH_SEMANTICS),
@@ -790,6 +830,8 @@ export const PUBLIC_OPTION_TABLE = {
   inspector: INSPECTOR_OPTIONS,
   gatekeeper: GATEKEEPER_OPTIONS,
   navigator: NAVIGATOR_OPTIONS,
+  auditor: AUDITOR_OPTIONS,
+  "evidence-child": EVIDENCE_CHILD_OPTIONS,
   diarist: DIARIST_OPTIONS,
   analyst: ANALYST_OPTIONS,
 } as const satisfies Record<OptionOwner, readonly PublicOptionDefinition[]>;
@@ -811,6 +853,8 @@ export const PUBLIC_ROLE_OPTION_OWNERS = [
   "inspector",
   "gatekeeper",
   "navigator",
+  "auditor",
+  "evidence-child",
   "diarist",
   "analyst",
 ] as const satisfies readonly PublicRoleOptionOwner[];
@@ -1209,6 +1253,23 @@ const ROLE_COMMAND_HELP = {
       'ak-role navigator "刚完成 coder apply 收敛，下一步？"',
     ],
   },
+  auditor: {
+    command: "auditor",
+    summary: "Direct Auditor (审刑院) compliance audit: pass, revise, or escalate.",
+    usage: ["ak-role auditor --subject <judge|doctor> --source-run <runId@role|path> [options] [instruction]"],
+    examples: [
+      'ak-role auditor --subject judge --source-run 01abc…@judge --attach ./dossier "审：本 run 是否合规。"',
+      'ak-role auditor --subject doctor --source-run 01abc…@doctor "审：太医候选是否合规。"',
+    ],
+  },
+  "evidence-child": {
+    command: "evidence-child",
+    summary: "Direct evidence-child fact gathering; submit one report.",
+    usage: ["ak-role evidence-child [options] [instruction]"],
+    examples: [
+      'ak-role evidence-child "查：本工作树 diff 与票面是否一致。"',
+    ],
+  },
   diarist: {
     command: "diarist",
     summary:

package/src/public-cli/post-admission.ts

@@ -110,6 +110,12 @@ export type PostAdmissionEnv = {
   sessionAppender: SessionCustomEntryAppender;
   autoResumeLimit?: number;
   createRunId?: () => string;
+  /**
+   * Parent cancellation for a nested public summon (#675). Every dispatched turn
+   * carries it so an aborted parent terminates the nested activation; a CLI
+   * process has no parent and leaves it absent.
+   */
+  signal?: AbortSignal;
   /**
    * #724 explicit fresh summons (`ak-role new <role>`): skip same-ticket auto-resume
    * and mint a new run. Absent on ordinary role commands and on `ak-role resume`.
@@ -302,7 +308,7 @@ export async function dispatchPostAdmissionTurn<
               piSessionFile: principalCoordinates.sessionFile,
             })
           : undefined;
-      turnRequest = request;
+      turnRequest = env.signal === undefined ? request : { ...request, signal: env.signal };
       if (hostTransition !== undefined) {
         turnRequest = { ...turnRequest, hostTransition };
       }

package/src/public-cli/registry.ts

@@ -99,13 +99,16 @@ const STARTUP_CANDIDATES: Record<PublicConfigurableSeat, readonly ModelRef[]> =
   // #620: subordinate officers inherit gatekeeper; no package startup model.
   notary: [],
   // #453/#620/#639: gatekeeper callable but no package startup model — caller
-  // configures it or the institutional resolution applies on the province path.
+  // configures it or inherits on the province path.
   gatekeeper: [],
   inspector: [],
   navigator: [
     { provider: "openai-codex", model: "gpt-5.6-luna", thinking: "medium" },
     { provider: "xai", model: "grok-4.5", thinking: "high" },
   ],
+  // #675: auditor / evidence-child public seats — no package startup; caller configures.
+  auditor: [],
+  "evidence-child": [],
   // #708 `diarist-seat-default`: owner-set initial value; changed in the seat
   // table like any other seat. No engine axis, package-default host.
   diarist: [{ provider: "xai", model: "grok-4.5", thinking: "medium" }],

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

@@ -97,6 +97,8 @@ export type RoleRunRecord = {
     | "inspector"
     | "gatekeeper"
     | "navigator"
+    | "auditor"
+    | "evidence-child"
     | "diarist";
   readonly state: RoleRunState;
   readonly bookKey: string;
@@ -351,6 +353,8 @@ async function readRoleRunStateDisk(
     record.role !== "inspector" &&
     record.role !== "gatekeeper" &&
     record.role !== "navigator" &&
+    record.role !== "auditor" &&
+    record.role !== "evidence-child" &&
     record.role !== "diarist"
   ) {
     return undefined;
@@ -1454,7 +1458,11 @@ export type LoadedResumableDiaristRun = {
 };
 
 export type LoadedResumableInstructionSeatRun = {
-  readonly admitted: AdmittedGatekeeperInvocation | AdmittedNavigatorInvocation;
+  readonly admitted:
+    | AdmittedGatekeeperInvocation
+    | AdmittedNavigatorInvocation
+    | import("./invocation.ts").AdmittedAuditorInvocation
+    | import("./invocation.ts").AdmittedEvidenceChildInvocation;
   readonly run: RoleRunRecord;
   readonly observation?: TypedHttp429Observation;
 };
@@ -1676,7 +1684,12 @@ export async function loadResumableInstructionSeatRun(
   authority: DurablePrincipalAuthority,
 ): Promise<LoadedResumableInstructionSeatRun> {
   const loaded = await loadResumableRunRecord(home, runId, authority);
-  if (loaded.run.role !== "gatekeeper" && loaded.run.role !== "navigator") {
+  if (
+    loaded.run.role !== "gatekeeper"
+    && loaded.run.role !== "navigator"
+    && loaded.run.role !== "auditor"
+    && loaded.run.role !== "evidence-child"
+  ) {
     throw new CliUsageError(
       `role run ${runId} belongs to ${loaded.run.role}, not an instruction seat`,
     );
@@ -1684,7 +1697,11 @@ export async function loadResumableInstructionSeatRun(
   const admitted = {
     role: loaded.run.role,
     ...resumedBaseAdmitted(loaded),
-  } as AdmittedGatekeeperInvocation | AdmittedNavigatorInvocation;
+  } as
+    | AdmittedGatekeeperInvocation
+    | AdmittedNavigatorInvocation
+    | import("./invocation.ts").AdmittedAuditorInvocation
+    | import("./invocation.ts").AdmittedEvidenceChildInvocation;
   return seatLoadedResult(loaded, admitted);
 }
 
@@ -1956,6 +1973,8 @@ export async function peekRoleRunRole(
   | "inspector"
   | "gatekeeper"
   | "navigator"
+  | "auditor"
+  | "evidence-child"
   | "diarist"
   | undefined
 > {

package/src/public-cli/settlement.ts

@@ -24,6 +24,7 @@ import { AUDITOR_SOUL_ROLES } from "../auditor-soul.ts";
 import { DOCTOR_AUDIT_TOOL_NAME } from "../doctor-auditor.ts";
 import { JUDGE_AUDIT_TOOL_NAME } from "../judge-auditor.ts";
 import type { RoleTurnKnownFailure } from "../host-contracts.ts";
+import { stampShapeUnreadableDetails } from "../shape-unreadable-failure.ts";
 import { knownFailureFromProviderStop } from "../pi/known-failure.ts";
 import { readReviewerDispatchRejection } from "./reviewer-dispatch-rejection.ts";
 import {
@@ -118,6 +119,17 @@ import {
   navigatorDecisiveFacts,
   validateRecordedNavigatorOutput,
 } from "../package-contracts/navigator-output.ts";
+import {
+  AUDITOR_OUTPUT_TOOL_NAME,
+  auditorDecisiveFacts,
+  projectLawfulAuditorOutput,
+  validateRecordedAuditorOutput,
+} from "../package-contracts/auditor-output.ts";
+import {
+  EVIDENCE_CHILD_OUTPUT_TOOL_NAME,
+  evidenceChildDecisiveFacts,
+  validateRecordedEvidenceChildOutput,
+} from "../package-contracts/evidence-child-output.ts";
 import {
   observePackagedMethodSkillInvocation,
   type ObservedPackagedMethodSkillInvocation,
@@ -1223,9 +1235,11 @@ function typedFailedTerminatingToolKnownFailure(
     const diagnostic = isRecord(textPart) ? textPart.text : undefined;
     // Durable details already carry fact + typed evidence from envelope one-shot projection (#475).
     // Do not re-parse retained compliance responses here.
+    // Host infrastructure must NOT map to cause=output — that cause is reserved for
+    // shape-unreadable retained candidates (ADR 0055 / #675 producer→consumer diversion).
     const details = isRecord(message.details) ? message.details : classification.fact;
     return {
-      cause: "output",
+      cause: "activation",
       identity: { name: message.toolName, code: message.toolCallId },
       ...(typeof diagnostic === "string" && diagnostic.trim() !== "" ? { diagnostic } : {}),
       details,
@@ -1489,6 +1503,16 @@ function auditNoReceiptDecisiveFact(candidate: object): Record<string, unknown>
   }
 }
 
+/** Typed unreadable audit leg beside accepted parent candidate (ADR 0055 / #675). */
+function auditUnreadableDecisiveFact(candidate: object): Record<string, unknown> {
+  const projected = safelyRead(candidate, "auditUnreadable");
+  if (!projected.readable || projected.value === undefined) return {};
+  if (typeof projected.value !== "object" || projected.value === null || Array.isArray(projected.value)) {
+    return { auditUnreadable: projected.value };
+  }
+  return { auditUnreadable: projected.value as Record<string, unknown> };
+}
+
 /** Countersign terminal projection — escalate keeps decisionGate; continue keeps fix (#572 / ADR 0074). */
 function countersignDecisiveFacts(
   verdict: object,
@@ -1531,6 +1555,7 @@ function judgeDecisiveFacts(
   const facts: Record<string, unknown> = {
     judgeStatus,
     ...auditNoReceiptDecisiveFact(verdict),
+    ...auditUnreadableDecisiveFact(verdict),
   };
   const statusBase = judgeStatus;
   if (statusBase === "continue") {
@@ -1695,7 +1720,10 @@ function collectorDecisiveFacts(
 function doctorDecisiveFacts(output: DoctorOutput): Record<string, unknown> {
   const candidate = output as unknown as object;
   const status = safelyRead(candidate, "status");
-  const facts: Record<string, unknown> = { ...auditNoReceiptDecisiveFact(candidate) };
+  const facts: Record<string, unknown> = {
+    ...auditNoReceiptDecisiveFact(candidate),
+    ...auditUnreadableDecisiveFact(candidate),
+  };
   if (status.readable && typeof status.value === "string") facts.doctorStatus = status.value;
   const statusBase =
     status.readable && typeof status.value === "string"
@@ -3367,6 +3395,8 @@ type SeatAcceptedSettlementSpec = {
     | "inspector"
     | "gatekeeper"
     | "navigator"
+    | "auditor"
+    | "evidence-child"
     | "diarist";
   readonly toolName: string;
   readonly nonUsableDiagnostic: string;
@@ -3395,6 +3425,8 @@ async function settleLawfulSeatAcceptedTerminalResult(
     | AdmittedInspectorInvocation
     | AdmittedGatekeeperInvocation
     | AdmittedNavigatorInvocation
+    | import("./invocation.ts").AdmittedAuditorInvocation
+    | import("./invocation.ts").AdmittedEvidenceChildInvocation
     | AdmittedDiaristInvocation,
   authority: DurablePrincipalAuthority,
   spec: SeatAcceptedSettlementSpec,
@@ -3436,7 +3468,7 @@ async function settleLawfulSeatAcceptedTerminalResult(
         return settleFailureTerminalResult(admitted, {
           cause: "output",
           diagnostic: residual.diagnostic,
-          details: { candidate: residual.candidate, acceptedReceipt: false },
+          details: stampShapeUnreadableDetails(residual.candidate),
         }, authority);
       }
       if (
@@ -3454,7 +3486,7 @@ async function settleLawfulSeatAcceptedTerminalResult(
       return settleFailureTerminalResult(admitted, {
         cause: "output",
         diagnostic: spec.nonUsableDiagnostic,
-        details: { candidate: acceptedNonUsable, acceptedReceipt: false },
+        details: stampShapeUnreadableDetails(acceptedNonUsable),
       }, authority);
     }
     return undefined;
@@ -3465,7 +3497,7 @@ async function settleLawfulSeatAcceptedTerminalResult(
       {
         cause: "output",
         diagnostic: spec.nonUsableDiagnostic,
-        details: { candidate: roleOutcome.decisiveFacts, acceptedReceipt: false },
+        details: stampShapeUnreadableDetails(roleOutcome.decisiveFacts),
       },
       authority,
     );
@@ -3818,6 +3850,89 @@ export async function trySettleNavigatorTerminalResult(
   return settleLawfulNavigatorTerminalResult(admitted, authority, scope);
 }
 
+/** Lawful Auditor accepted outcome (pass/revise/escalate, #675). */
+export type LawfulAuditorRoleOutcome = {
+  kind: "accepted";
+  role: "auditor";
+  status: string;
+  decisiveFacts: Readonly<Record<string, unknown>>;
+};
+
+async function settleLawfulAuditorTerminalResult(
+  admitted: import("./invocation.ts").AdmittedAuditorInvocation,
+  authority: DurablePrincipalAuthority,
+  scope?: SettlementCourtScope,
+): Promise<TerminalResult | undefined> {
+  return settleLawfulSeatAcceptedTerminalResult(admitted, authority, {
+    role: "auditor",
+    toolName: AUDITOR_OUTPUT_TOOL_NAME,
+    nonUsableDiagnostic: "审刑院回执无显式 pass/revise/escalate",
+    // Only pass/revise/escalate are lawful releases. Unreadable mystery status
+    // fails closed with candidate retained for parent ComplianceCandidateUnreadableError.
+    tryAcceptDetails: (details) => projectLawfulAuditorOutput(details) !== undefined,
+    projectAccepted: (sealed) => {
+      const lawful = projectLawfulAuditorOutput(sealed.decisiveFacts);
+      if (lawful === undefined) {
+        throw new Error("auditor projectAccepted requires lawful pass/revise/escalate");
+      }
+      const accepted: LawfulAuditorRoleOutcome = {
+        kind: "accepted",
+        role: "auditor",
+        status: lawful.status,
+        decisiveFacts: auditorDecisiveFacts(lawful),
+      };
+      return accepted;
+    },
+  }, scope);
+}
+
+export async function trySettleAuditorTerminalResult(
+  admitted: import("./invocation.ts").AdmittedAuditorInvocation,
+  authority: DurablePrincipalAuthority,
+  scope?: SettlementCourtScope,
+): Promise<TerminalResult | undefined> {
+  return settleLawfulAuditorTerminalResult(admitted, authority, scope);
+}
+
+/** Lawful Evidence-Child accepted outcome (#675). */
+export type LawfulEvidenceChildRoleOutcome = {
+  kind: "accepted";
+  role: "evidence-child";
+  status: string;
+  decisiveFacts: Readonly<Record<string, unknown>>;
+};
+
+async function settleLawfulEvidenceChildTerminalResult(
+  admitted: import("./invocation.ts").AdmittedEvidenceChildInvocation,
+  authority: DurablePrincipalAuthority,
+  scope?: SettlementCourtScope,
+): Promise<TerminalResult | undefined> {
+  return settleLawfulSeatAcceptedTerminalResult(admitted, authority, {
+    role: "evidence-child",
+    toolName: EVIDENCE_CHILD_OUTPUT_TOOL_NAME,
+    nonUsableDiagnostic: "取证回执无报告正文",
+    tryAcceptDetails: tryAcceptWithValidator(validateRecordedEvidenceChildOutput),
+    projectAccepted: (sealed) => {
+      const output = validateRecordedEvidenceChildOutput(sealed.decisiveFacts);
+      const accepted: LawfulEvidenceChildRoleOutcome = {
+        kind: "accepted",
+        role: "evidence-child",
+        status: "report",
+        decisiveFacts: evidenceChildDecisiveFacts(output),
+      };
+      return accepted;
+    },
+  }, scope);
+}
+
+export async function trySettleEvidenceChildTerminalResult(
+  admitted: import("./invocation.ts").AdmittedEvidenceChildInvocation,
+  authority: DurablePrincipalAuthority,
+  scope?: SettlementCourtScope,
+): Promise<TerminalResult | undefined> {
+  return settleLawfulEvidenceChildTerminalResult(admitted, authority, scope);
+}
+
 /** Try to settle a lawful Coder Terminal; undefined only for genuine absence. */
 export async function trySettleCoderTerminalResult(
   admitted: AdmittedCoderInvocation,

package/src/public-cli/terminal.ts

@@ -41,6 +41,8 @@ export type TerminalRoleName =
   | "inspector"
   | "gatekeeper"
   | "navigator"
+  | "auditor"
+  | "evidence-child"
   | "diarist";
 
 /** Merger/Collector residual only — Notary/audit residual abolished (#475). */