@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/src/package-contracts/terminating-tools.ts

@@ -29,6 +29,8 @@ import { CorrectableSubmissionError } from "../submission-correctable-error.ts";
 import { DOCTOR_ACCEPTED_TEXT, DOCTOR_OUTPUT_TOOL_NAME, validateDoctorSubmissionShape, validateRecordedDoctorOutput, type DoctorOutput, type DoctorSubmission } from "../doctor-contracts.ts";
 import { GATEKEEPER_ACCEPTED_TEXT, GATEKEEPER_OUTPUT_TOOL_NAME, validateRecordedGatekeeperOutput, type GatekeeperDirectOutput } from "./gatekeeper-output.ts";
 import { NAVIGATOR_ACCEPTED_TEXT, NAVIGATOR_OUTPUT_TOOL_NAME, validateRecordedNavigatorOutput, type NavigatorAdvice } from "./navigator-output.ts";
+import { AUDITOR_ACCEPTED_TEXT, AUDITOR_OUTPUT_TOOL_NAME, validateRecordedAuditorOutput, type AuditorOutput } from "./auditor-output.ts";
+import { EVIDENCE_CHILD_ACCEPTED_TEXT, EVIDENCE_CHILD_OUTPUT_TOOL_NAME, validateRecordedEvidenceChildOutput, type EvidenceChildOutput } from "./evidence-child-output.ts";
 import { MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, validateMergerOutput, type MergerOutput } from "../merger-contracts.ts";
 import { NOTARY_ACCEPTED_TEXT, NOTARY_OUTPUT_TOOL_NAME, validateRecordedNotaryOutput, type NotaryOutput } from "../notary-contracts.ts";
 import { COUNTERSIGN_ACCEPTED_TEXT, COUNTERSIGN_OUTPUT_TOOL_NAME, validateRecordedCountersignOutput, type CountersignVerdict } from "../countersign-contracts.ts";
@@ -72,6 +74,8 @@ export {
   validateRecordedInspectorOutput,
   validateRecordedGatekeeperOutput,
   validateRecordedNavigatorOutput,
+  validateRecordedAuditorOutput,
+  validateRecordedEvidenceChildOutput,
   validateRecordedDiaristOutput,
 };
 export type {
@@ -89,6 +93,8 @@ export type {
   InspectorOutput,
   GatekeeperDirectOutput,
   NavigatorAdvice,
+  AuditorOutput,
+  EvidenceChildOutput,
   DiaristOutput,
 };
 
@@ -106,6 +112,8 @@ export const TERMINATING_TOOL_NAMES = [
   INSPECTOR_OUTPUT_TOOL_NAME,
   GATEKEEPER_OUTPUT_TOOL_NAME,
   NAVIGATOR_OUTPUT_TOOL_NAME,
+  AUDITOR_OUTPUT_TOOL_NAME,
+  EVIDENCE_CHILD_OUTPUT_TOOL_NAME,
   DIARIST_OUTPUT_TOOL_NAME,
 ] as const;
 
@@ -124,6 +132,8 @@ export type AcceptedDetails =
   | InspectorOutput
   | GatekeeperDirectOutput
   | NavigatorAdvice
+  | AuditorOutput
+  | EvidenceChildOutput
   | DiaristOutput;
 
 export function isTerminatingToolName(
@@ -160,6 +170,10 @@ export function acceptedTextFor(toolName: TerminatingToolName): string {
       return GATEKEEPER_ACCEPTED_TEXT;
     case NAVIGATOR_OUTPUT_TOOL_NAME:
       return NAVIGATOR_ACCEPTED_TEXT;
+    case AUDITOR_OUTPUT_TOOL_NAME:
+      return AUDITOR_ACCEPTED_TEXT;
+    case EVIDENCE_CHILD_OUTPUT_TOOL_NAME:
+      return EVIDENCE_CHILD_ACCEPTED_TEXT;
     case DIARIST_OUTPUT_TOOL_NAME:
       return DIARIST_ACCEPTED_TEXT;
   }
@@ -220,16 +234,24 @@ export function validateAcceptedDetails(
     [INSPECTOR_OUTPUT_TOOL_NAME]: ["pass", "bounce"],
     [GATEKEEPER_OUTPUT_TOOL_NAME]: ["dispatch", "pass"],
     [NAVIGATOR_OUTPUT_TOOL_NAME]: ["advice"],
+    [AUDITOR_OUTPUT_TOOL_NAME]: ["pass", "revise", "escalate"],
+    [EVIDENCE_CHILD_OUTPUT_TOOL_NAME]: [],
     [DIARIST_OUTPUT_TOOL_NAME]: ["completed"],
   };
   const collectorDiscriminator = toolName === COLLECTOR_OUTPUT_TOOL && Array.isArray(candidate?.groups);
+  // Evidence-child: any object is a candidate body — no report-field presence gate (#675 / ADR 0055).
+  const evidenceChildDiscriminator =
+    toolName === EVIDENCE_CHILD_OUTPUT_TOOL_NAME
+    && candidate !== null
+    && typeof candidate === "object"
+    && !Array.isArray(candidate);
   const baseDiscriminator = discriminator;
   const runtimeBindingMissing =
     (toolName === DOCTOR_OUTPUT_TOOL_NAME && baseDiscriminator === "completed" && !(candidate?.cost !== null && typeof candidate?.cost === "object")) ||
     (toolName === REVIEWER_OUTPUT_TOOL_NAME && candidate?.version !== 2);
   if (
     runtimeBindingMissing ||
-    (!collectorDiscriminator && (typeof discriminator !== "string" || !lawfulStatuses[toolName].includes(baseDiscriminator as string)))
+    (!collectorDiscriminator && !evidenceChildDiscriminator && (typeof discriminator !== "string" || !lawfulStatuses[toolName].includes(baseDiscriminator as string)))
   ) {
     throw new AcceptedDetailsContractError("terminating receipt has no recognized execution discriminator");
   }
@@ -261,6 +283,10 @@ export function validateAcceptedDetails(
       return validateRecordedGatekeeperOutput(details);
     case NAVIGATOR_OUTPUT_TOOL_NAME:
       return validateRecordedNavigatorOutput(details);
+    case AUDITOR_OUTPUT_TOOL_NAME:
+      return validateRecordedAuditorOutput(details);
+    case EVIDENCE_CHILD_OUTPUT_TOOL_NAME:
+      return validateRecordedEvidenceChildOutput(details);
     case DIARIST_OUTPUT_TOOL_NAME:
       return validateRecordedDiaristOutput(details);
     }
@@ -321,6 +347,10 @@ export function acceptedFacts(toolName: TerminatingToolName, details: AcceptedDe
     case INSPECTOR_OUTPUT_TOOL_NAME:
     case GATEKEEPER_OUTPUT_TOOL_NAME:
     case NAVIGATOR_OUTPUT_TOOL_NAME:
+    case AUDITOR_OUTPUT_TOOL_NAME:
+      return { status: (details as { status: string }).status };
+    case EVIDENCE_CHILD_OUTPUT_TOOL_NAME:
+      return { status: "report" };
     case DIARIST_OUTPUT_TOOL_NAME: return { status: (details as { status: string }).status };
     case JUDGE_OUTPUT_TOOL_NAME: return { status: (details as { judgeStatus: string }).judgeStatus };
     case COUNTERSIGN_OUTPUT_TOOL_NAME: return { status: (details as { countersignStatus: string }).countersignStatus };

package/src/packaged-role-registry.ts

@@ -11,6 +11,8 @@ import { NOTARY_OUTPUT_TOOL_NAME } from "./notary-contracts.ts";
 import { COUNTERSIGN_OUTPUT_TOOL_NAME } from "./countersign-contracts.ts";
 import { GLEANER_LEFT_OUTPUT_TOOL_NAME } from "./gleaner-left-contracts.ts";
 import { INSPECTOR_OUTPUT_TOOL_NAME } from "./inspector-contracts.ts";
+import { AUDITOR_OUTPUT_TOOL_NAME } from "./package-contracts/auditor-output.ts";
+import { EVIDENCE_CHILD_OUTPUT_TOOL_NAME } from "./package-contracts/evidence-child-output.ts";
 import {
   DIARIST_OUTPUT_TOOL_NAME,
   DIARIST_SOURCES_FLAG,
@@ -33,6 +35,28 @@ export const INSPECTOR_SESSION_MATERIALS = [
   "souls/gate-output-guide.md",
 ] as const;
 
+/**
+ * Public 审刑院 shipping roster (#675 owner).
+ * Runtime assembly is subject-selected via AUDITOR_SESSION_MATERIALS
+ * (judge-auditor.md / doctor-auditor.md) — never a generic auditor.md.
+ * This list is the union of files that must ship; load path is loadAuditorSoul(subject).
+ */
+export const AUDITOR_PUBLIC_SESSION_MATERIALS = [
+  "CLAUDE.md",
+  "souls/judge-auditor.md",
+  "souls/doctor-auditor.md",
+  "souls/audit-law.md",
+  "souls/quality-law.md",
+] as const;
+
+/** Public evidence-child materials (#675). audit-law supplies lawful 取证授权; seat identity only in evidence-child.md. */
+export const EVIDENCE_CHILD_SESSION_MATERIALS = [
+  "CLAUDE.md",
+  "souls/evidence-child.md",
+  "souls/audit-law.md",
+  "souls/quality-law.md",
+] as const;
+
 /**
  * One record per public callable role (#639: includes gatekeeper and navigator).
  */
@@ -189,6 +213,25 @@ export const PUBLIC_ROLE_RECORDS = [
     activationStage: "load-and-install",
     sessionMaterials: ["CLAUDE.md", "souls/navigator.md"],
   },
+  // #675: 审刑院 / evidence-child are roles like any other — public ak-role entries.
+  {
+    role: "auditor",
+    phases: [null],
+    outputTool: AUDITOR_OUTPUT_TOOL_NAME,
+    inputFlag: undefined,
+    phaseFlag: undefined,
+    activationStage: "load-and-install",
+    sessionMaterials: AUDITOR_PUBLIC_SESSION_MATERIALS,
+  },
+  {
+    role: "evidence-child",
+    phases: [null],
+    outputTool: EVIDENCE_CHILD_OUTPUT_TOOL_NAME,
+    inputFlag: undefined,
+    phaseFlag: undefined,
+    activationStage: "load-and-install",
+    sessionMaterials: EVIDENCE_CHILD_SESSION_MATERIALS,
+  },
   // #708 / ADR 0075 `diarist-is-role`: 起居郎 is a seat like any other. The
   // frozen source catalog rides the shared input-flag seam; it is absent for a
   // true-unbound summons (no ticket → no diary).

package/src/pi/adapter.ts

@@ -7,7 +7,8 @@ import {
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import type { Static, TSchema } from "typebox";
-import { requireGatekeeperPass, type GatekeeperNonPassResult, type GatekeeperSubject } from "../gatekeeper-role.ts";
+import type { GatekeeperNonPassResult, GatekeeperSubject } from "../gatekeeper-role.ts";
+import { requireGatekeeperPass } from "../gatekeeper-pass-envelope.ts";
 import type {
   HostContext,
   HostEventRegistration,

package/src/pi/in-process-session.ts

@@ -207,7 +207,7 @@ export type OpenPiInstitutionalSessionResult = {
   readonly streamFailure: unknown;
 };
 
-export async function openPiInstitutionalSession(
+export async function openPiInProcessSession(
   options: OpenPiInstitutionalSessionOptions,
 ): Promise<OpenPiInstitutionalSessionResult> {
   const label = options.label ?? "Institutional sub-session";
@@ -237,7 +237,7 @@ export async function openPiInstitutionalSession(
       ? childRegistry.find(selection.provider, selection.model)
       : undefined;
 
-    const withTypedReason = (error: Error, reason: "auth" | "model"): Error =>
+    const withTypedReason = (error: Error, reason: "auth" | "model" | "thinking"): Error =>
       Object.assign(error, { reason });
 
     // Existing Navigator/model contract (pre-#590): unknown provider or model is
@@ -633,15 +633,26 @@ export async function openPiInstitutionalSession(
       }
     }
 
-    // 7. Create AgentSession — thinking is opaque pass-through. Absent selection
-    // omits thinkingLevel (Pi owns default). Pi clamps unsupported levels itself;
-    // we do not re-check or invent package defaults.
+    // 7. Create AgentSession
+    // Thinking is opaque pass-through (#683 / #675 ⑥). Absent selection omits
+    // thinkingLevel (Pi owns default). Pi clamps unsupported levels itself;
+    // we do not re-check or invent package defaults. When reusing a session file,
+    // re-apply seat model after open so Pi cannot restore a stale model over
+    // selection (#675 ⑤ / #697).
+    const requestedThinking = selection.thinking;
+    const priorEntries =
+      typeof (sessionManager as { getEntries?: () => readonly unknown[] }).getEntries === "function"
+        ? (sessionManager as { getEntries: () => readonly unknown[] }).getEntries()
+        : [];
+    const reusedSession = priorEntries.some((entry) => {
+      if (typeof entry !== "object" || entry === null) return false;
+      const type = (entry as { type?: unknown }).type;
+      return type === "message" || type === "model_change" || type === "thinking_level_change";
+    });
     const { session } = await createAgentSession({
       cwd: options.cwd,
       model: effectiveModel,
-      ...(options.selection.thinking === undefined
-        ? {}
-        : { thinkingLevel: options.selection.thinking as any }),
+      ...(requestedThinking === undefined ? {} : { thinkingLevel: requestedThinking as any }),
       modelRuntime: runtime,
       sessionManager,
       settingsManager: settings,
@@ -651,9 +662,23 @@ export async function openPiInstitutionalSession(
       ...(options.toolsAllowlist === undefined ? {} : { tools: options.toolsAllowlist as string[] }),
       ...(customTools.length === 0 ? {} : { customTools }),
     });
-    await session.setModel(effectiveModel);
-    if (options.selection.thinking !== undefined) {
-      session.setThinkingLevel(options.selection.thinking as any);
+    if (reusedSession) {
+      try {
+        await session.setModel(effectiveModel);
+        if (requestedThinking !== undefined) {
+          session.setThinkingLevel(requestedThinking as any);
+        }
+      } catch (error) {
+        session.dispose();
+        throw withTypedReason(
+          error instanceof Error
+            ? error
+            : new Error(
+              `${label} failed to apply seat model/thinking for ${selection.provider}/${selection.model}`,
+            ),
+          requestedThinking !== undefined ? "thinking" : "model",
+        );
+      }
     }
 
     // 8. Event subscriptions
@@ -832,4 +857,5 @@ export async function openPiInstitutionalSession(
     }
     throw openError;
   }
-}
+}
+

package/src/pi/role-turn-host.ts

@@ -146,6 +146,10 @@ function buildActivationFlagArgs(activation: RoleTurnActivation): string[] {
       return ["--ak-role", "gatekeeper"];
     case "navigator":
       return ["--ak-role", "navigator"];
+    case "auditor":
+      return ["--ak-role", "auditor"];
+    case "evidence-child":
+      return ["--ak-role", "evidence-child"];
     case "diarist":
       return [
         "--ak-role",
@@ -213,6 +217,8 @@ export type PiSpawnRunner = (
     cwd: string;
     env: NodeJS.ProcessEnv;
     timeoutMs?: number;
+    /** Parent cancellation; the child gets the same graceful SIGTERM as a budget. */
+    signal?: AbortSignal;
   },
 ) => Promise<{
   code: number | null;
@@ -346,9 +352,17 @@ export function createDefaultPiSpawnRunner(options: {
           child.kill("SIGTERM");
         }, spawnOptions.timeoutMs);
       };
+      // Parent cancellation reaches the nested activation: same graceful SIGTERM,
+      // same single close settlement. SIGKILL stays forbidden (#675 / ADR 0010).
+      const parentSignal = spawnOptions.signal;
+      const terminateForParentAbort = (): void => {
+        child.kill("SIGTERM");
+      };
+      parentSignal?.addEventListener("abort", terminateForParentAbort, { once: true });
       let identityRecorded: Promise<void> = Promise.resolve();
       child.once("spawn", () => {
         hasSpawned = true;
+        if (parentSignal?.aborted === true) terminateForParentAbort();
         armTimeoutAfterChildReady();
         const runDirectory = spawnOptions.env.AK_ROLE_RUN_DIR;
         if (
@@ -371,11 +385,13 @@ export function createDefaultPiSpawnRunner(options: {
           return;
         }
         if (timer !== undefined) clearTimeout(timer);
+        parentSignal?.removeEventListener("abort", terminateForParentAbort);
         settled = true;
         reject(error);
       });
       child.on("close", (code) => {
         if (timer !== undefined) clearTimeout(timer);
+        parentSignal?.removeEventListener("abort", terminateForParentAbort);
         void identityRecorded.then(
           () => {
             if (settled) return;
@@ -447,10 +463,27 @@ export function createPiRoleTurnHost(config: PiRoleTurnHostConfig): RoleTurnHost
         HOME: request.home,
         PI_CODING_AGENT_DIR: request.agentDir,
         AK_ROLE_RUN_DIR: request.runDirectory,
+        // Nested public summons resolve package root without import.meta under jiti (#675).
+        // Child-process scoped only — not written back onto the parent process.env.
+        AK_ROLE_PACKAGE_ROOT: config.packageRoot,
       };
       if (request.courtAttemptId === undefined) delete env.AK_ROLE_COURT_ATTEMPT;
       else env.AK_ROLE_COURT_ATTEMPT = request.courtAttemptId;
       applyEngineChildEnv(env, request.engine);
+      // Nested auditor dossier tool binds the parent run pointer when published.
+      if (
+        typeof process.env.AK_ROLE_AUDITOR_SOURCE_RUN === "string"
+        && process.env.AK_ROLE_AUDITOR_SOURCE_RUN.trim() !== ""
+      ) {
+        env.AK_ROLE_AUDITOR_SOURCE_RUN = process.env.AK_ROLE_AUDITOR_SOURCE_RUN;
+      }
+      // Audited-subject input selects soul materials (same for nested and direct).
+      if (
+        typeof process.env.AK_ROLE_AUDITOR_SUBJECT === "string"
+        && process.env.AK_ROLE_AUDITOR_SUBJECT.trim() !== ""
+      ) {
+        env.AK_ROLE_AUDITOR_SUBJECT = process.env.AK_ROLE_AUDITOR_SUBJECT;
+      }
       if (request.correlationId !== undefined && request.correlationId.trim() !== "") {
         env.AK_CORRELATION_ID = request.correlationId;
       }
@@ -468,6 +501,7 @@ export function createPiRoleTurnHost(config: PiRoleTurnHostConfig): RoleTurnHost
         cwd: request.cwd,
         env,
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(request.signal === undefined ? {} : { signal: request.signal }),
       });
     },
   };

package/src/public-cli/cli.ts

@@ -60,6 +60,8 @@ import {
   parseInspectorArgv,
   parseMergerArgv,
   parseNavigatorArgv,
+  parseAuditorArgv,
+  parseEvidenceChildArgv,
   parseNotaryArgv,
   parseReviewerArgv,
   recordLaunchedPiIdentity,
@@ -128,6 +130,8 @@ const RESUME_SEAT_DISPATCH: Record<
   inspector: { seat: "inspector", run: runPublicInspectorResume },
   gatekeeper: { seat: "gatekeeper", run: runPublicInstructionSeatResume },
   navigator: { seat: "navigator", run: runPublicInstructionSeatResume },
+  auditor: { seat: "auditor", run: runPublicInstructionSeatResume },
+  "evidence-child": { seat: "evidence-child", run: runPublicInstructionSeatResume },
   diarist: { seat: "diarist", run: runPublicDiaristResume },
 };
 import {
@@ -171,6 +175,8 @@ export const PUBLIC_ROLE_ARGV = {
   reviewer: { parse: parseReviewerArgv, options: optionsForOwner("reviewer") },
   gatekeeper: { parse: parseGatekeeperArgv, options: optionsForOwner("gatekeeper") },
   navigator: { parse: parseNavigatorArgv, options: optionsForOwner("navigator") },
+  auditor: { parse: parseAuditorArgv, options: optionsForOwner("auditor") },
+  "evidence-child": { parse: parseEvidenceChildArgv, options: optionsForOwner("evidence-child") },
   diarist: { parse: parseDiaristArgv, options: optionsForOwner("diarist") },
   /** Deterministic analysis seat (#336) — argv parse only; no LLM admission. */
   analyst: { parse: parseAnalystArgv, options: optionsForOwner("analyst") },
@@ -1539,9 +1545,13 @@ export async function runAkRole(
       };
     }
 
-    // Gatekeeper/Navigator direct public run paths (#639) — instruction seats,
-    // a role like any other; one parameterized branch for both.
-    if (parsed.command === "gatekeeper" || parsed.command === "navigator") {
+    // Instruction seats (#639 / #675): gatekeeper / navigator / auditor / evidence-child.
+    if (
+      parsed.command === "gatekeeper"
+      || parsed.command === "navigator"
+      || parsed.command === "auditor"
+      || parsed.command === "evidence-child"
+    ) {
       const agentDir = resolveAgentDir(env, home);
       const cwd = env.cwd ?? process.cwd();
       const config = await loadAndValidateConfig(home, env.packageRoot);
@@ -1558,9 +1568,7 @@ export async function runAkRole(
         createRoleEnvironment(env, { role: parsed.command, home, agentDir, cwd, credentials, seat, config }),
         io,
         parsed.command,
-        parsed.command === "gatekeeper"
-          ? PUBLIC_ROLE_ARGV.gatekeeper.parse
-          : PUBLIC_ROLE_ARGV.navigator.parse,
+        PUBLIC_ROLE_ARGV[parsed.command].parse,
       );
       return {
         exitCode: result.exitCode,