@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/src/public-cli/instruction-seat-run.ts

@@ -1,33 +1,53 @@
 /**
- * Shared instruction-seat run (#639 repair seam): gatekeeper and navigator are
- * the same admit → turn-request → post-admission → settle shape, parameterized
- * by seat. Same direction as the settlement one-shot shared skeleton. cli.ts
- * calls this parameterized module directly; no per-seat wrappers.
+ * Shared instruction-seat run (#639 / #675 / #637): gatekeeper, navigator, auditor,
+ * and evidence-child share admit → turn-request → post-admission → settle.
+ * Same-ticket re-summons resume the seat's previous run via the shared public
+ * tryResumeSameTicketSeatRun seam (inspector/notary/countersign face) — no
+ * independent run/rebind/nest path.
  */
 import type { DurablePrincipalAuthority, RoleTurnRequest } from "../host-contracts.ts";
 import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
+import { readRunTicketNumber } from "../run-ticket-number.ts";
 import { CliUsageError } from "./cli-errors.ts";
 import {
+  admitAuditorInvocation,
+  admitEvidenceChildInvocation,
   admitGatekeeperInvocation,
   admitNavigatorInvocation,
+  bindAdmittedTicketNumber,
   buildInstructionTransportPrompt,
+  type AdmittedAuditorInvocation,
+  type AdmittedEvidenceChildInvocation,
   type AdmittedGatekeeperInvocation,
   type AdmittedNavigatorInvocation,
   type ParseInstructionArgvResult,
 } from "./invocation.ts";
 import {
+  prepareSummonsResumeMaterials,
   runPostAdmissionOneShot,
   runPostAdmissionSeatResume,
   resumeTurnRequestProjectionOptions,
+  type PostAdmissionAdapters,
   type PostAdmissionEnv,
 } from "./post-admission.ts";
 import {
   loadResumableInstructionSeatRun,
   markRunAdmitted,
   type PublicResumeRequest,
+  type SameTicketSummonsMaterials,
 } from "./run-lifecycle.ts";
+import {
+  applyInstructionTicketProbe,
+  probeInstructionTicket,
+  ticketNumberFromProbe,
+  tryResumeSameTicketSeatRun,
+  type InstructionTicketProbe,
+} from "./seat-ticket-binding.ts";
 import {
   presentStructuralRejection,
+  readEngineDetourInfrastructureFailure,
+  trySettleAuditorTerminalResult,
+  trySettleEvidenceChildTerminalResult,
   trySettleGatekeeperTerminalResult,
   trySettleNavigatorTerminalResult,
 } from "./settlement.ts";
@@ -38,11 +58,17 @@ import {
   type RoleTurnRequestProjectionOptions,
 } from "./turn-request.ts";
 
-export type InstructionSeatRole = "gatekeeper" | "navigator";
+export type InstructionSeatRole =
+  | "gatekeeper"
+  | "navigator"
+  | "auditor"
+  | "evidence-child";
 
 export type AdmittedInstructionSeatInvocation =
   | AdmittedGatekeeperInvocation
-  | AdmittedNavigatorInvocation;
+  | AdmittedNavigatorInvocation
+  | AdmittedAuditorInvocation
+  | AdmittedEvidenceChildInvocation;
 
 export type InstructionSeatRunEnv = PostAdmissionEnv & {
   principalAuthority: DurablePrincipalAuthority;
@@ -65,26 +91,81 @@ export function buildInstructionSeatTurnRequest(
   );
 }
 
-function instructionSeatAdapters() {
+function instructionSeatAdapters(options?: {
+  beforeDispatch?: (
+    admitted: AdmittedInstructionSeatInvocation,
+  ) => void | Promise<void>;
+}): PostAdmissionAdapters<AdmittedInstructionSeatInvocation> {
   return {
     trySettle: (
       admitted: AdmittedInstructionSeatInvocation,
       authority: DurablePrincipalAuthority,
       scope?: { readonly courtAttemptId?: string },
-    ) =>
-      admitted.role === "gatekeeper"
-        ? trySettleGatekeeperTerminalResult(admitted, authority, scope)
-        : trySettleNavigatorTerminalResult(admitted, authority, scope),
+    ) => {
+      switch (admitted.role) {
+        case "gatekeeper":
+          return trySettleGatekeeperTerminalResult(admitted, authority, scope);
+        case "navigator":
+          return trySettleNavigatorTerminalResult(admitted, authority, scope);
+        case "auditor":
+          return trySettleAuditorTerminalResult(admitted, authority, scope);
+        case "evidence-child":
+          return trySettleEvidenceChildTerminalResult(admitted, authority, scope);
+      }
+    },
     // Accepted receipts and failure terminals both present via shared path.
     shouldPresentSettled: () => true,
+    // #675 / #357 T2: failInfrastructure abort after engine-detour tool failure must not
+    // wash the durable toolResult diagnostic (same seam as reviewer-run / judge-run).
+    resolveRunnerKnownFailure: async ({
+      result,
+      sessionFile,
+    }: {
+      result: { knownFailure?: import("../host-contracts.ts").RoleTurnKnownFailure };
+      sessionFile: string;
+    }) => {
+      const infrastructureFailure = await readEngineDetourInfrastructureFailure(sessionFile);
+      return infrastructureFailure === undefined
+        ? result.knownFailure
+        : {
+            cause: infrastructureFailure.cause,
+            diagnostic: infrastructureFailure.diagnostic,
+            ...(infrastructureFailure.identity === undefined
+              ? {}
+              : { identity: infrastructureFailure.identity }),
+          };
+    },
+    ...(options?.beforeDispatch === undefined
+      ? {}
+      : { beforeDispatch: options.beforeDispatch }),
   };
 }
 
+async function admitInstructionSeat(
+  role: InstructionSeatRole,
+  options: Parameters<typeof admitGatekeeperInvocation>[0],
+): Promise<AdmittedInstructionSeatInvocation> {
+  switch (role) {
+    case "gatekeeper":
+      return admitGatekeeperInvocation(options);
+    case "navigator":
+      return admitNavigatorInvocation(options);
+    case "auditor":
+      return admitAuditorInvocation(options);
+    case "evidence-child":
+      return admitEvidenceChildInvocation(options);
+  }
+}
+
 export async function runPublicInstructionSeatResume(
   request: PublicResumeRequest,
   env: InstructionSeatRunEnv,
   io: CliIo,
-): Promise<{ exitCode: number; terminal?: TerminalResult }> {
+): Promise<{
+  exitCode: number;
+  admitted?: AdmittedInstructionSeatInvocation;
+  terminal?: TerminalResult;
+}> {
   return await runPostAdmissionSeatResume({
     request,
     env,
@@ -94,15 +175,62 @@ export async function runPublicInstructionSeatResume(
       effective.runId,
       env.principalAuthority,
     ),
-    buildTurnRequest: (admitted, effective) => buildInstructionSeatTurnRequest(
-      admitted,
-      resumeTurnRequestProjectionOptions(admitted, effective, env),
-    ),
+    buildTurnRequest: async (admitted, effective) => {
+      const summonsPrepared = await prepareSummonsResumeMaterials(
+        admitted.runDirectory,
+        effective.summons,
+      );
+      return buildInstructionSeatTurnRequest(
+        admitted,
+        resumeTurnRequestProjectionOptions(
+          admitted,
+          effective,
+          env,
+          summonsPrepared,
+        ),
+      );
+    },
     adapters: instructionSeatAdapters(),
     ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }
 
+/** Scope auditor subject/source-run env for the duration of one seat turn. */
+async function withAuditorSoulEnv<
+  T,
+>(options: {
+  readonly subject?: "judge" | "doctor";
+  readonly sourceRunDirectory?: string;
+  readonly run: () => Promise<T>;
+}): Promise<T> {
+  if (options.subject === undefined && options.sourceRunDirectory === undefined) {
+    return options.run();
+  }
+  const { AK_ROLE_AUDITOR_SUBJECT_ENV, AK_ROLE_AUDITOR_SOURCE_RUN_ENV } = await import(
+    "../auditor-soul.ts"
+  );
+  const priorSubject = process.env[AK_ROLE_AUDITOR_SUBJECT_ENV];
+  const priorSource = process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV];
+  if (options.subject !== undefined) {
+    process.env[AK_ROLE_AUDITOR_SUBJECT_ENV] = options.subject;
+  }
+  if (options.sourceRunDirectory !== undefined) {
+    process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV] = options.sourceRunDirectory;
+  }
+  try {
+    return await options.run();
+  } finally {
+    if (options.subject !== undefined) {
+      if (priorSubject === undefined) delete process.env[AK_ROLE_AUDITOR_SUBJECT_ENV];
+      else process.env[AK_ROLE_AUDITOR_SUBJECT_ENV] = priorSubject;
+    }
+    if (options.sourceRunDirectory !== undefined) {
+      if (priorSource === undefined) delete process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV];
+      else process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV] = priorSource;
+    }
+  }
+}
+
 export async function runPublicInstructionSeat(
   argv: readonly string[],
   env: InstructionSeatRunEnv,
@@ -114,10 +242,106 @@ export async function runPublicInstructionSeat(
   admitted?: AdmittedInstructionSeatInvocation;
   terminal?: TerminalResult;
 }> {
+  let parsed: ParseInstructionArgvResult;
+  try {
+    parsed = parseArgv(argv);
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      presentStructuralRejection(error, io);
+      return { exitCode: 2 };
+    }
+    throw error;
+  }
+
+  let auditorSubject: "judge" | "doctor" | undefined;
+  let auditorSourceRun: string | undefined;
+  let auditorSourceTicket: number | undefined;
+  let ticketProbe: InstructionTicketProbe | undefined;
+
+  // #637: same ticket → resume prior seat run with this summons' materials.
+  // Auditor inherits ticket from source-run (notary face); other instruction seats
+  // probe instruction (inspector face). No bare catch→fresh: lookup/resume failures
+  // surface; only true absence of a prior run mints new.
+  const projectRoot = parsed.project ?? env.cwd;
+  if (role === "auditor") {
+    if (parsed.subject !== "judge" && parsed.subject !== "doctor") {
+      presentStructuralRejection(
+        new CliUsageError("auditor --subject requires judge|doctor"),
+        io,
+      );
+      return { exitCode: 2 };
+    }
+    auditorSubject = parsed.subject;
+    const source = typeof parsed.sourceRun === "string" ? parsed.sourceRun.trim() : "";
+    if (source === "") {
+      presentStructuralRejection(
+        new CliUsageError("auditor --source-run requires a run locator"),
+        io,
+      );
+      return { exitCode: 2 };
+    }
+    try {
+      const { resolveNotarySourceRunLocator } = await import("../notary-source-run.ts");
+      const resolved = await resolveNotarySourceRunLocator({
+        projectRoot,
+        sourceRun: source,
+        home: env.home,
+      });
+      auditorSourceRun = resolved.runDirectory;
+      auditorSourceTicket = await readRunTicketNumber(resolved.runDirectory);
+    } catch (error) {
+      presentStructuralRejection(
+        new CliUsageError(error instanceof Error ? error.message : String(error)),
+        io,
+      );
+      return { exitCode: 2 };
+    }
+  } else {
+    // Inspector face: unconditional probe (same seam as inspector-run.ts).
+    ticketProbe = await probeInstructionTicket(
+      parsed.instruction,
+      projectRoot,
+      env,
+    );
+  }
+
+  const probedTicketNumber =
+    auditorSourceTicket
+    ?? (ticketProbe === undefined ? undefined : ticketNumberFromProbe(ticketProbe));
+
+  if (probedTicketNumber !== undefined) {
+    const summons: SameTicketSummonsMaterials = {
+      instruction: parsed.instruction,
+      instructionEmpty: parsed.instruction.trim() === "",
+      attachmentPaths: parsed.attachmentPaths,
+    };
+    const resumed = await withAuditorSoulEnv({
+      ...(auditorSubject === undefined ? {} : { subject: auditorSubject }),
+      ...(auditorSourceRun === undefined
+        ? {}
+        : { sourceRunDirectory: auditorSourceRun }),
+      run: () =>
+        tryResumeSameTicketSeatRun({
+          home: env.home,
+          projectRoot,
+          role,
+          ticketNumber: probedTicketNumber,
+          freshSummons: env.freshSummons,
+          summons,
+          resume: (runId, materials) =>
+            runPublicInstructionSeatResume(
+              { runId, ...(materials === undefined ? {} : { summons: materials }) },
+              env,
+              io,
+            ),
+        }),
+    });
+    if (resumed !== undefined) return resumed;
+  }
+
   let admitted: AdmittedInstructionSeatInvocation;
   try {
-    const parsed = parseArgv(argv);
-    const options = {
+    admitted = await admitInstructionSeat(role, {
       home: env.home,
       principalAuthority: env.principalAuthority,
       cwd: env.cwd,
@@ -127,11 +351,7 @@ export async function runPublicInstructionSeat(
       ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
       ...(env.model === undefined ? {} : { model: env.model }),
       ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
-    };
-    admitted =
-      role === "gatekeeper"
-        ? await admitGatekeeperInvocation(options)
-        : await admitNavigatorInvocation(options);
+    });
   } catch (error) {
     if (error instanceof CliUsageError) {
       presentStructuralRejection(error, io);
@@ -140,36 +360,55 @@ export async function runPublicInstructionSeat(
     throw error;
   }
 
-  await markRunAdmitted(admitted, env.principalAuthority);
-
-  const turnRequest = buildInstructionSeatTurnRequest(admitted, {
-    packageRoot: env.packageRoot,
-    home: env.home,
-    agentDir: env.agentDir,
-    ...(env.model === undefined ? {} : { model: env.model }),
-    ...(env.engine === undefined ? {} : { engine: env.engine }),
-    ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
-    ...(env.correlationId === undefined || env.correlationId.trim() === ""
+  return await withAuditorSoulEnv({
+    ...(auditorSubject === undefined ? {} : { subject: auditorSubject }),
+    ...(auditorSourceRun === undefined
       ? {}
-      : { correlationId: env.correlationId }),
-    continuation: {
-      kind: "initial",
-      prompt: buildInstructionTransportPrompt(
+      : { sourceRunDirectory: auditorSourceRun }),
+    run: async () => {
+      await markRunAdmitted(admitted, env.principalAuthority);
+
+      const turnRequest = buildInstructionSeatTurnRequest(admitted, {
+        packageRoot: env.packageRoot,
+        home: env.home,
+        agentDir: env.agentDir,
+        ...(env.model === undefined ? {} : { model: env.model }),
+        ...(env.engine === undefined ? {} : { engine: env.engine }),
+        ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
+        ...(env.correlationId === undefined || env.correlationId.trim() === ""
+          ? {}
+          : { correlationId: env.correlationId }),
+        continuation: {
+          kind: "initial",
+          prompt: buildInstructionTransportPrompt(
+            admitted,
+            engineSessionMaterialFromOptions({
+              ...(env.engine === undefined ? {} : { engine: env.engine }),
+              packageRoot: env.packageRoot,
+            }),
+          ),
+        },
+      });
+
+      return await runPostAdmissionOneShot({
         admitted,
-        engineSessionMaterialFromOptions({
-          ...(env.engine === undefined ? {} : { engine: env.engine }),
-          packageRoot: env.packageRoot,
+        env,
+        io,
+        request: turnRequest,
+        adapters: instructionSeatAdapters({
+          beforeDispatch: async (admittedSeat) => {
+            // #635/#637: ticket bind inside controlled-failure boundary.
+            // Auditor inherits source-run ticket (notary face).
+            // Other seats: same applyInstructionTicketProbe as inspector-run.
+            if (auditorSourceTicket !== undefined) {
+              await bindAdmittedTicketNumber(admittedSeat, auditorSourceTicket);
+            } else if (ticketProbe !== undefined) {
+              await applyInstructionTicketProbe(admittedSeat, ticketProbe);
+            }
+          },
         }),
-      ),
+        ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+      });
     },
   });
-
-  return await runPostAdmissionOneShot({
-    admitted,
-    env,
-    io,
-    request: turnRequest,
-    adapters: instructionSeatAdapters(),
-    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
-  });
 }

package/src/public-cli/invocation.ts

@@ -73,12 +73,7 @@ import {
   type OptionOwner,
   type PublicOptionDefinition,
 } from "./option-definitions.ts";
-import { loadPublicCliConfig } from "./config.ts";
 import type { PublicThinkingLevel } from "./registry.ts";
-import {
-  resolveInstitutionalSeatSelections,
-  writeInstitutionalResolutionPage,
-} from "../institutional-resolution.ts";
 
 export type FrozenAttachment = {
   /** Original caller path retained only as provenance. */
@@ -151,6 +146,14 @@ export type AdmittedNavigatorInvocation = AdmittedRoleInvocationBase & {
   readonly role: "navigator";
 };
 
+export type AdmittedAuditorInvocation = AdmittedRoleInvocationBase & {
+  readonly role: "auditor";
+};
+
+export type AdmittedEvidenceChildInvocation = AdmittedRoleInvocationBase & {
+  readonly role: "evidence-child";
+};
+
 export type AdmittedDiaristInvocation = AdmittedRoleInvocationBase & {
   readonly role: "diarist";
 };
@@ -238,6 +241,8 @@ export type AdmittedRoleInvocation =
   | AdmittedInspectorInvocation
   | AdmittedGatekeeperInvocation
   | AdmittedNavigatorInvocation
+  | AdmittedAuditorInvocation
+  | AdmittedEvidenceChildInvocation
   | AdmittedDiaristInvocation
   | AdmittedCoderInvocation
   | AdmittedFixerInvocation
@@ -367,10 +372,6 @@ async function writeRoleInvocationLedger(
     `${JSON.stringify(identity, null, 2)}\n`,
     "utf8",
   );
-  const home = homeFromRunDirectory(source.runDirectory);
-  const config = await loadPublicCliConfig(home);
-  const institutionalPage = resolveInstitutionalSeatSelections(config, effectiveModel);
-  await writeInstitutionalResolutionPage(source.runDirectory, institutionalPage);
 }
 
 /**
@@ -417,20 +418,6 @@ export async function recordEffectiveInvocationModel(
     `${JSON.stringify(next, null, 2)}\n`,
     "utf8",
   );
-  const effectiveModel: InvocationEffectiveModel | undefined =
-    typeof next.provider === "string" && typeof next.model === "string"
-      ? {
-          provider: next.provider,
-          model: next.model,
-          ...(typeof next.thinking === "string"
-            ? { thinking: next.thinking }
-            : {}),
-        }
-      : undefined;
-  const home = homeFromRunDirectory(runDirectory);
-  const config = await loadPublicCliConfig(home);
-  const institutionalPage = resolveInstitutionalSeatSelections(config, effectiveModel);
-  await writeInstitutionalResolutionPage(runDirectory, institutionalPage);
 }
 
 /** Merge observed launch-time fields into the single existing invocation.json identity page. */
@@ -583,6 +570,10 @@ export type ParseInstructionArgvResult = {
   instruction: string;
   attachmentPaths: string[];
   project?: string;
+  /** Auditor only — audited subject selecting soul materials (#675 owner). */
+  subject?: "judge" | "doctor";
+  /** Auditor source-run locator — same input surface for direct and nested (#675). */
+  sourceRun?: string;
 };
 
 /** Judge/Countersign 命令面同形：--project/--attach/opaque instruction。 */
@@ -612,10 +603,12 @@ export function parsePositiveTicketNumber(
 /** 共享解析体：同形 owner 的 argv → instruction/attachments/project。 */
 function parseInstructionArgv(
   args: readonly string[],
-  owner: "judge" | "countersign" | "inspector" | "gatekeeper" | "navigator" | "diarist",
+  owner: "judge" | "countersign" | "inspector" | "gatekeeper" | "navigator" | "auditor" | "evidence-child" | "diarist",
 ): ParseInstructionArgvResult {
   const attachmentPaths: string[] = [];
   let project: string | undefined;
+  let subject: "judge" | "doctor" | undefined;
+  let sourceRun: string | undefined;
   const positional: string[] = [];
   const tokens = [...args];
   const definitions = roleOptions(owner);
@@ -637,6 +630,24 @@ function parseInstructionArgv(
         project = requireOptionPath(taken.def.canonical, taken.value);
         continue;
       }
+      if (taken.def.id === "subject") {
+        const raw = typeof taken.value === "string" ? taken.value.trim() : "";
+        if (raw !== "judge" && raw !== "doctor") {
+          throw new CliUsageError(
+            `auditor --subject must be judge|doctor, got ${taken.value ?? "(missing)"}`,
+          );
+        }
+        subject = raw;
+        continue;
+      }
+      if (taken.def.id === "source-run") {
+        const raw = typeof taken.value === "string" ? taken.value.trim() : "";
+        if (raw === "") {
+          throw new CliUsageError("auditor --source-run requires a run locator");
+        }
+        sourceRun = raw;
+        continue;
+      }
       throw new CliUsageError(`unknown ${owner} option: ${taken.def.canonical}`);
     }
     const token = tokens.shift()!;
@@ -651,6 +662,8 @@ function parseInstructionArgv(
     instruction: positional.join(" "),
     attachmentPaths,
     ...(project === undefined ? {} : { project }),
+    ...(subject === undefined ? {} : { subject }),
+    ...(sourceRun === undefined ? {} : { sourceRun }),
   };
 }
 
@@ -852,6 +865,17 @@ export function parseNavigatorArgv(args: readonly string[]): ParseNavigatorArgvR
   return parseInstructionArgv(args, "navigator");
 }
 
+export type ParseAuditorArgvResult = ParseInstructionArgvResult;
+export type ParseEvidenceChildArgvResult = ParseInstructionArgvResult;
+
+export function parseAuditorArgv(args: readonly string[]): ParseAuditorArgvResult {
+  return parseInstructionArgv(args, "auditor");
+}
+
+export function parseEvidenceChildArgv(args: readonly string[]): ParseEvidenceChildArgvResult {
+  return parseInstructionArgv(args, "evidence-child");
+}
+
 export function parseDiaristArgv(args: readonly string[]): ParseDiaristArgvResult {
   return parseInstructionArgv(args, "diarist");
 }
@@ -1064,7 +1088,7 @@ export type AdmitDiaristInvocationOptions = AdmitInspectorInvocationOptions;
  * Ticket binding is post-admission via shared seat LLM path (#635).
  */
 async function admitStandardMaterialInvocation<
-  R extends "judge" | "inspector" | "gatekeeper" | "navigator" | "diarist",
+  R extends "judge" | "inspector" | "gatekeeper" | "navigator" | "auditor" | "evidence-child" | "diarist",
 >(
   role: R,
   options: AdmitJudgeInvocationOptions & { correlationId?: string },
@@ -1184,6 +1208,23 @@ export async function admitNavigatorInvocation(
   return admitStandardMaterialInvocation("navigator", options);
 }
 
+export type AdmitAuditorInvocationOptions = AdmitInspectorInvocationOptions;
+export type AdmitEvidenceChildInvocationOptions = AdmitInspectorInvocationOptions;
+
+/** Admit a public 审刑院 run (#675). */
+export async function admitAuditorInvocation(
+  options: AdmitAuditorInvocationOptions,
+): Promise<AdmittedAuditorInvocation> {
+  return admitStandardMaterialInvocation("auditor", options);
+}
+
+/** Admit a public evidence-child run (#675). */
+export async function admitEvidenceChildInvocation(
+  options: AdmitEvidenceChildInvocationOptions,
+): Promise<AdmittedEvidenceChildInvocation> {
+  return admitStandardMaterialInvocation("evidence-child", options);
+}
+
 /**
  * Admit a direct Diarist (起居郎) run (#708): freeze attachments, persist the
  * request, reserve session placement — same instruction-seat face.