@akagilnc/pi-workflow-roles 0.1.2521 → 0.1.2535

package/src/inspector-role.ts

@@ -0,0 +1,20 @@
+import { Type } from "typebox";
+
+import { INSPECTOR_OUTPUT_TOOL_NAME } from "./inspector-contracts.ts";
+import { openToolObject } from "./open-tool-schema.ts";
+import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.ts";
+
+export { INSPECTOR_OUTPUT_TOOL_NAME as INSPECTOR_OUTPUT_TOOL };
+
+export const inspectorOutputSchema = withInfrastructureFailureDeclaration(openToolObject(Type.Object({
+  status: Type.Unknown({ description: "pass | bounce — 取值形状指引，不作拒收依据" }),
+  findings: Type.Unknown({ description: "随交卷留存的问题记录" }),
+})));
+
+export function projectInspectorReceipt(parameters: unknown) {
+  return {
+    content: [{ type: "text" as const, text: "给事中回执已受理" }],
+    details: parameters,
+    terminate: true as const,
+  };
+}

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

@@ -25,6 +25,7 @@ import {
   type RuntimeReviewerReceiptV2,
 } from "./reviewer-output.ts";
 import { isAuditEscalationResult } from "../audit-escalation.ts";
+import { INSPECTOR_OUTPUT_TOOL_NAME } from "../inspector-contracts.ts";
 import { DOCTOR_ACCEPTED_TEXT, DOCTOR_OUTPUT_TOOL_NAME, validateDoctorSubmissionShape, validateRecordedDoctorOutput, type DoctorOutput, type DoctorSubmission } from "../doctor-contracts.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";
@@ -82,6 +83,7 @@ export const TERMINATING_TOOL_NAMES = [
   DOCTOR_OUTPUT_TOOL_NAME,
   MERGER_OUTPUT_TOOL_NAME,
   NOTARY_OUTPUT_TOOL_NAME,
+  INSPECTOR_OUTPUT_TOOL_NAME,
 ] as const;
 
 export type TerminatingToolName = (typeof TERMINATING_TOOL_NAMES)[number];
@@ -93,7 +95,8 @@ export type AcceptedDetails =
   | CollectorReceipt
   | DoctorOutput
   | MergerOutput
-  | NotaryOutput;
+  | NotaryOutput
+  | Readonly<Record<string, unknown>>;
 
 export function isTerminatingToolName(
   name: string,
@@ -119,6 +122,8 @@ export function acceptedTextFor(toolName: TerminatingToolName): string {
       return MERGER_ACCEPTED_TEXT;
     case NOTARY_OUTPUT_TOOL_NAME:
       return NOTARY_ACCEPTED_TEXT;
+    case INSPECTOR_OUTPUT_TOOL_NAME:
+      return "给事中回执已受理";
   }
 }
 
@@ -165,6 +170,7 @@ export function validateAcceptedDetails(
     [DOCTOR_OUTPUT_TOOL_NAME]: ["completed", "refused"],
     [MERGER_OUTPUT_TOOL_NAME]: ["completed", "escalate"],
     [NOTARY_OUTPUT_TOOL_NAME]: ["pass", "bounce"],
+    [INSPECTOR_OUTPUT_TOOL_NAME]: ["pass", "bounce"],
   };
   const collectorDiscriminator = toolName === COLLECTOR_OUTPUT_TOOL && Array.isArray(candidate?.groups);
   const baseDiscriminator = discriminator;
@@ -195,6 +201,8 @@ export function validateAcceptedDetails(
       return validateMergerOutput(details);
     case NOTARY_OUTPUT_TOOL_NAME:
       return validateRecordedNotaryOutput(details);
+    case INSPECTOR_OUTPUT_TOOL_NAME:
+      return candidate as Readonly<Record<string, unknown>>;
     }
   } catch (error) {
     if (error instanceof Error && error.constructor === Error) throw new AcceptedDetailsContractError(error.message, { cause: error });
@@ -239,7 +247,8 @@ export function acceptedFacts(toolName: TerminatingToolName, details: AcceptedDe
     case FIXER_OUTPUT_TOOL_NAME:
     case REVIEWER_OUTPUT_TOOL_NAME:
     case DOCTOR_OUTPUT_TOOL_NAME:
-    case NOTARY_OUTPUT_TOOL_NAME: return { status: (details as { status: string }).status };
+    case NOTARY_OUTPUT_TOOL_NAME:
+    case INSPECTOR_OUTPUT_TOOL_NAME: return { status: (details as { status: string }).status };
     case JUDGE_OUTPUT_TOOL_NAME: return { status: (details as { judgeStatus: string }).judgeStatus };
     case MERGER_OUTPUT_TOOL_NAME: {
       const output = details as unknown as Record<string, unknown>;

package/src/packaged-role-registry.ts

@@ -6,6 +6,7 @@ import { CODER_OUTPUT_TOOL_NAME, FIXER_OUTPUT_TOOL_NAME } from "./package-contra
 import { DOCTOR_OUTPUT_TOOL_NAME } from "./doctor-contracts.ts";
 import { MERGER_OUTPUT_TOOL_NAME } from "./merger-contracts.ts";
 import { NOTARY_OUTPUT_TOOL_NAME } from "./notary-contracts.ts";
+import { INSPECTOR_OUTPUT_TOOL_NAME } from "./inspector-contracts.ts";
 
 export const PACKAGED_ROLE_REGISTRY = [
   { role: "judge", phases: [null], outputTool: JUDGE_OUTPUT_TOOL_NAME, inputFlag: undefined, phaseFlag: undefined, activationStage: "load-and-install" },
@@ -17,6 +18,7 @@ export const PACKAGED_ROLE_REGISTRY = [
   { role: "doctor", phases: [null], outputTool: DOCTOR_OUTPUT_TOOL_NAME, inputFlag: "ak-doctor-case", phaseFlag: undefined, activationStage: "load-and-install" },
   { role: "merger", phases: [null], outputTool: MERGER_OUTPUT_TOOL_NAME, inputFlag: "ak-merger-input", phaseFlag: undefined, activationStage: "prepare-git-and-install" },
   { role: "notary", phases: [null], outputTool: NOTARY_OUTPUT_TOOL_NAME, inputFlag: "ak-notary-source-run", phaseFlag: undefined, activationStage: "load-and-install" },
+  { role: "inspector", phases: [null], outputTool: INSPECTOR_OUTPUT_TOOL_NAME, inputFlag: undefined, phaseFlag: undefined, activationStage: "load-and-install" },
 ] as const;
 
 export type PackagedRole = (typeof PACKAGED_ROLE_REGISTRY)[number]["role"];

package/src/public-cli/cli.ts

@@ -40,6 +40,7 @@ import {
   parseDoctorArgv,
   parseFixerArgv,
   parseJudgeArgv,
+  parseInspectorArgv,
   parseMergerArgv,
   parseNotaryArgv,
   parseReviewerArgv,
@@ -60,6 +61,7 @@ import { runPublicCollector } from "./collector-run.ts";
 import { runPublicDoctor } from "./doctor-run.ts";
 import { runPublicFixer, runPublicFixerResume } from "./fixer-run.ts";
 import { runPublicNotary } from "./notary-run.ts";
+import { runPublicInspector } from "./inspector-run.ts";
 import { runPublicJudge, runPublicResume } from "./judge-run.ts";
 import { runPublicMerger, runPublicMergerResume } from "./merger-run.ts";
 import { runPublicReviewer, runPublicReviewerResume } from "./reviewer-run.ts";
@@ -104,6 +106,7 @@ export const PUBLIC_ROLE_ARGV = {
   doctor: { parse: parseDoctorArgv, options: optionsForOwner("doctor") },
   merger: { parse: parseMergerArgv, options: optionsForOwner("merger") },
   notary: { parse: parseNotaryArgv, options: optionsForOwner("notary") },
+  inspector: { parse: parseInspectorArgv, options: optionsForOwner("inspector") },
   reviewer: { parse: parseReviewerArgv, options: optionsForOwner("reviewer") },
   /** Deterministic analysis seat (#336) — argv parse only; no LLM admission. */
   analyst: { parse: parseAnalystArgv, options: optionsForOwner("analyst") },
@@ -1317,6 +1320,23 @@ export async function runAkRole(
       };
     }
 
+    if (parsed.command === "inspector") {
+      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 seat = resolveEffectiveSeat(config, "inspector", credentials, invocationFromParsed(parsed));
+      const result = await runPublicInspector(parsed.args, {
+        home, agentDir, packageRoot: env.packageRoot, cwd, credentials,
+        ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
+        ...(env.piRunner === undefined ? {} : { piRunner: env.piRunner }),
+        ...(seat.selection === undefined ? {} : { model: seat.selection }),
+        ...projectSeatEngine(seat),
+        ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+      }, io, PUBLIC_ROLE_ARGV.inspector.parse);
+      return { exitCode: result.exitCode, ...(result.terminal === undefined ? {} : { terminal: result.terminal }) };
+    }
+
     // Merger public run path: derive active-merge envelope + forced merge-only method (#114).
     if (parsed.command === "merger") {
       const agentDir = resolveAgentDir(env, home);

package/src/public-cli/config.ts

@@ -42,8 +42,8 @@ export type SeatModelConfig = ModelRef;
 
 /**
  * Persistent seat row (#356/#384/#453): model fields and engine are independent
- * axes. Engine-only residual is legal only for notary after model clear so direct
- * notary activation keeps its labor engine while province inheritance resumes.
+ * axes. Direct Inspector and Notary seats may retain an engine after model clear so
+ * officer activation keeps its labor engine while province inheritance resumes.
  * All other seats keep the baseline provider/model required contract.
  */
 export type PersistentSeatConfig = {
@@ -154,9 +154,9 @@ export function setPersistentSeatConfig(
 /**
  * Clear a gate officer's persistent model override (#453).
  * Scope is GateOfficerSeat only — non-province seats have no destructive clear seam.
- * Only notary may retain an engine-only residual so direct notary activation keeps
+ * Directly callable gate officers may retain an engine-only residual so activation keeps
  * its labor engine while model resolution returns to startup / province inheritance.
- * gatekeeper/inspector drop the whole row. Already-absent seats are a no-op.
+ * Gatekeeper drops the whole row. Already-absent seats are a no-op.
  */
 export function clearPersistentSeatConfig(
   config: PublicCliConfig,
@@ -164,13 +164,13 @@ export function clearPersistentSeatConfig(
 ): PublicCliConfig {
   const previous = config.seats[seat];
   if (previous === undefined) return config;
-  // Engine-only residual ownership is notary-only — never widen to other officers.
-  if (seat === "notary" && previous.engine !== undefined) {
+  // Direct officer engine ownership survives an independent model clear.
+  if ((seat === "notary" || seat === "inspector") && previous.engine !== undefined) {
     return {
       ...config,
       seats: {
         ...config.seats,
-        notary: { engine: previous.engine },
+        [seat]: { engine: previous.engine },
       },
     };
   }
@@ -204,8 +204,8 @@ export function isEngineAxisSeat(seat: string): seat is PublicCallableRole {
 
 /**
  * Set or clear persistent engine on a callable role seat (#356 / #378 / #391 / #453).
- * First engine still requires an existing seat row (model, or notary engine residual).
- * Clearing engine from a notary engine-only residual drops the empty row; clearing
+ * First engine still requires an existing seat row (model, or direct-officer engine residual).
+ * Clearing engine from an engine-only residual drops the empty row; clearing
  * engine from a model+engine row leaves model-only. Seat type is PublicCallableRole
  * (navigator excluded at the type boundary).
  */
@@ -427,10 +427,10 @@ function parseSeatModelConfig(value: unknown, seat: string): PersistentSeatConfi
     // validatePublicCliConfigEngines → assertLegalEngineName (single authority).
     throw new Error(`config seat ${seat} engine must be a string`);
   }
-  // #453: engine-only residual is legal only for notary after model clear.
+  // Direct officer engine-only residual remains legal after model clear.
   // All other seats keep the baseline provider/model required contract.
   if (!hasProvider) {
-    if (seat === "notary" && typeof raw.engine === "string") {
+    if ((seat === "notary" || seat === "inspector") && typeof raw.engine === "string") {
       if (raw.thinking !== undefined) {
         throw new Error(`config seat ${seat} thinking requires provider/model`);
       }

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

@@ -0,0 +1,61 @@
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
+import { CliUsageError } from "./cli-errors.ts";
+import {
+  admitInspectorInvocation,
+  buildInspectorTransportPrompt,
+  type AdmittedInspectorInvocation,
+  type ParseInspectorArgvResult,
+} from "./invocation.ts";
+import { buildSeatModelCliArgs, type SeatModelConfig } from "./config.ts";
+import { runAdmittedOneShotRole, type OneShotRunEnv } from "./one-shot-dispatch.ts";
+import { presentStructuralRejection, trySettleInspectorTerminalResult } from "./settlement.ts";
+import type { CliIo } from "./cli-io.ts";
+import type { TerminalResult } from "./terminal.ts";
+
+export type InspectorRunEnv = OneShotRunEnv & { createRunId?: () => string; extraPiArgs?: readonly string[] };
+
+export function buildInspectorActivationExtraArgs(
+  admitted: AdmittedInspectorInvocation,
+  options: { model?: SeatModelConfig; engine?: string; packageRoot?: string; extraPiArgs?: readonly string[] } = {},
+): string[] {
+  return [
+    "--no-skills", "--no-prompt-templates", "--no-themes", "--no-context-files",
+    "--session", admitted.sessionFile, "--session-dir", admitted.sessionDirectory,
+    ...(options.extraPiArgs ?? []), "--ak-role", "inspector", "--mode", "json",
+    ...buildSeatModelCliArgs(options.model),
+    buildInspectorTransportPrompt(admitted, engineSessionMaterialFromOptions(options)),
+  ];
+}
+
+export async function runPublicInspector(
+  argv: readonly string[], env: InspectorRunEnv, io: CliIo,
+  parse: (args: readonly string[]) => ParseInspectorArgvResult,
+): Promise<{ exitCode: number; admitted?: AdmittedInspectorInvocation; terminal?: TerminalResult }> {
+  let admitted: AdmittedInspectorInvocation;
+  try {
+    const parsed = parse(argv);
+    admitted = await admitInspectorInvocation({
+      home: env.home, cwd: env.cwd, instruction: parsed.instruction, attachmentPaths: parsed.attachmentPaths,
+      ...(parsed.project === undefined ? {} : { project: parsed.project }),
+      ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+      ...(env.model === undefined ? {} : { model: env.model }),
+    });
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      presentStructuralRejection(error, io);
+      return { exitCode: 2 };
+    }
+    throw error;
+  }
+  const extraArgs = buildInspectorActivationExtraArgs(admitted, {
+    packageRoot: env.packageRoot,
+    ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.engine === undefined ? {} : { engine: env.engine }),
+    ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+  });
+  return runAdmittedOneShotRole({
+    admitted, env, io, extraArgs,
+    adapters: { trySettle: trySettleInspectorTerminalResult, shouldPresentSettled: () => true },
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+  });
+}

package/src/public-cli/invocation.ts

@@ -111,6 +111,10 @@ export type AdmittedJudgeInvocation = AdmittedRoleInvocationBase & {
   readonly role: "judge";
 };
 
+export type AdmittedInspectorInvocation = AdmittedRoleInvocationBase & {
+  readonly role: "inspector";
+};
+
 export type CoderPhase = "plan" | "apply";
 
 export type AdmittedCoderInvocation = AdmittedRoleInvocationBase & {
@@ -189,6 +193,7 @@ export type AdmittedMergerInvocation = AdmittedRoleInvocationBase & {
 
 export type AdmittedRoleInvocation =
   | AdmittedJudgeInvocation
+  | AdmittedInspectorInvocation
   | AdmittedCoderInvocation
   | AdmittedFixerInvocation
   | AdmittedCollectorInvocation
@@ -377,6 +382,8 @@ export type ParseJudgeArgvResult = {
   project?: string;
 };
 
+export type ParseInspectorArgvResult = ParseJudgeArgvResult;
+
 export type ParseCoderArgvResult = {
   phase: CoderPhase;
   instruction: string;
@@ -536,51 +543,41 @@ export function requireAuthorityRef(value: string | undefined): string {
  * Parse Judge-specific argv after the `judge` token.
  * Spellings from PUBLIC_OPTION_TABLE.judge; rejects burden family (#342).
  */
-export function parseJudgeArgv(args: readonly string[]): ParseJudgeArgvResult {
+function parseStandardMaterialArgv(
+  owner: "judge" | "inspector",
+  args: readonly string[],
+): ParseJudgeArgvResult {
   const attachmentPaths: string[] = [];
   let project: string | undefined;
   const positional: string[] = [];
   const tokens = [...args];
-  const definitions = roleOptions("judge");
-  const options = createTypedOptionConsumer(definitions);
-
+  const options = createTypedOptionConsumer(roleOptions(owner));
   while (tokens.length > 0) {
-    if (tokens[0] === "--") {
-      tokens.shift();
-      positional.push(...tokens);
-      break;
-    }
+    if (tokens[0] === "--") { tokens.shift(); positional.push(...tokens); break; }
     const taken = options.takeDashed(tokens);
     if (taken !== undefined) {
-      if (taken.def.id === "attach") {
-        attachmentPaths.push(requireOptionPath(taken.def.canonical, taken.value));
-        continue;
-      }
-      if (taken.def.id === "project") {
-        project = requireOptionPath(taken.def.canonical, taken.value);
-        continue;
-      }
-      throw new CliUsageError(`unknown judge option: ${taken.def.canonical}`);
+      if (taken.def.id === "attach") attachmentPaths.push(requireOptionPath(taken.def.canonical, taken.value));
+      else if (taken.def.id === "project") project = requireOptionPath(taken.def.canonical, taken.value);
+      else throw new CliUsageError(`unknown ${owner} option: ${taken.def.canonical}`);
+      continue;
     }
     const token = tokens.shift()!;
-    // Judge owns burden inference — rejected spellings from REJECTED_PUBLIC_SPELLINGS.
-    if (isRejectedPublicSpelling("judge", token)) {
-      throw new CliUsageError(
-        "judge does not accept a public burden selector; Judge infers its own burden",
-      );
-    }
-    if (token.startsWith("-") && token !== "-") {
-      throw new CliUsageError(`unknown judge option: ${token}`);
+    if (owner === "judge" && isRejectedPublicSpelling("judge", token)) {
+      throw new CliUsageError("judge does not accept a public burden selector; Judge infers its own burden");
     }
+    if (token.startsWith("-") && token !== "-") throw new CliUsageError(`unknown ${owner} option: ${token}`);
     positional.push(token);
   }
-
   options.assertRequired();
-  return {
-    instruction: positional.join(" "),
-    attachmentPaths,
-    ...(project === undefined ? {} : { project }),
-  };
+  return { instruction: positional.join(" "), attachmentPaths, ...(project === undefined ? {} : { project }) };
+}
+
+export function parseJudgeArgv(args: readonly string[]): ParseJudgeArgvResult {
+  return parseStandardMaterialArgv("judge", args);
+}
+
+export function parseInspectorArgv(args: readonly string[]): ParseInspectorArgvResult {
+  return parseStandardMaterialArgv("inspector", args);
 }
 
 /**
@@ -771,84 +768,65 @@ export type AdmitJudgeInvocationOptions = {
  * Atomically admit a Judge Role run: freeze Attachments, persist the request,
  * and reserve session placement under the #78 ledger book.
  */
-export async function admitJudgeInvocation(
+async function admitStandardMaterialInvocation<R extends "judge" | "inspector">(
+  role: R,
   options: AdmitJudgeInvocationOptions,
-): Promise<AdmittedJudgeInvocation> {
-  // Empty project override must not reach resolve("") → cwd (silent default).
-  if (options.project !== undefined) {
-    requireOptionPath("--project", options.project);
-  }
+): Promise<AdmittedRoleInvocationBase & { readonly role: R }> {
+  if (options.project !== undefined) requireOptionPath("--project", options.project);
   const projectRoot = resolve(options.project ?? options.cwd);
   const runId = (options.createRunId ?? uuidv7)();
   const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } =
-    roleRunSessionCoordinates({ cwd: projectRoot, runId, role: "judge", home: options.home });
+    roleRunSessionCoordinates({ cwd: projectRoot, runId, role, home: options.home });
   const attachmentsDirectory = join(runDirectory, "attachments");
   ensureRealDirectoryTree(ledgerHome, sessionDirectory);
   ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
-
-  const { attachments, ticketNumber } = await freezeAttachmentsWithTicketNumber(
-    options.attachmentPaths,
-    attachmentsDirectory,
-  );
+  const { attachments, ticketNumber } = await freezeAttachmentsWithTicketNumber(options.attachmentPaths, attachmentsDirectory);
   const ticketFields = ticketAdmissionFields(ticketNumber);
-
   const instruction = options.instruction;
-  const instructionEmpty = instruction.trim() === "";
   const admitted = {
-    role: "judge" as const,
-    runId,
-    bookKey,
-    projectRoot,
-    runDirectory,
-    sessionDirectory,
-    sessionFile,
-    ...ticketFields,
-    instruction,
-    instructionEmpty,
-    attachments: attachments.map((a) => ({
-      provenancePath: a.provenancePath,
-      frozenPath: a.frozenPath,
-      byteLength: a.byteLength,
-      sha256: a.sha256,
-      mediaKind: a.mediaKind,
-    })),
+    role, runId, bookKey, projectRoot, runDirectory, sessionDirectory, sessionFile,
+    ...ticketFields, instruction, instructionEmpty: instruction.trim() === "",
+    attachments: attachments.map((attachment) => ({ ...attachment })),
   };
   const admittedRequestPath = join(runDirectory, "admitted-request.json");
   await writeFile(admittedRequestPath, `${JSON.stringify(admitted, null, 2)}\n`, "utf8");
-  await writeRoleInvocationLedger(admitted, admitted.role, options.model);
+  await writeRoleInvocationLedger(admitted, role, options.model);
+  return { ...admitted, attachments, admittedRequestPath };
+}
 
-  return {
-    role: "judge",
-    runId,
-    bookKey,
-    projectRoot,
-    instruction,
-    instructionEmpty,
-    attachments,
-    runDirectory,
-    sessionDirectory,
-    sessionFile,
-    admittedRequestPath,
-    ...ticketFields,
-  };
+export async function admitJudgeInvocation(options: AdmitJudgeInvocationOptions): Promise<AdmittedJudgeInvocation> {
+  return admitStandardMaterialInvocation("judge", options);
 }
 
-/** Build the Pi prompt transport for an admitted Judge request. */
-export function buildJudgeTransportPrompt(
-  admitted: AdmittedJudgeInvocation,
+export type AdmitInspectorInvocationOptions = AdmitJudgeInvocationOptions;
+
+export async function admitInspectorInvocation(options: AdmitInspectorInvocationOptions): Promise<AdmittedInspectorInvocation> {
+  return admitStandardMaterialInvocation("inspector", options);
+}
+
+function buildStandardMaterialTransportPrompt(
+  admitted: AdmittedJudgeInvocation | AdmittedInspectorInvocation,
   engineMaterial?: EngineSessionMaterial,
 ): string {
   const lines: string[] = [admitted.instructionEmpty ? "" : admitted.instruction];
   if (admitted.attachments.length > 0) {
-    lines.push("");
-    lines.push("已受理附件（冻结快照路径）：");
-    for (const attachment of admitted.attachments) {
-      lines.push(`- ${attachment.frozenPath}`);
-    }
+    lines.push("", "已受理附件（冻结快照路径）：", ...admitted.attachments.map((attachment) => `- ${attachment.frozenPath}`));
   }
   return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
 }
 
+export function buildInspectorTransportPrompt(admitted: AdmittedInspectorInvocation, engineMaterial?: EngineSessionMaterial): string {
+  return buildStandardMaterialTransportPrompt(admitted, engineMaterial);
+}
+
+/** Build the Pi prompt transport for an admitted Judge request. */
+export function buildJudgeTransportPrompt(
+  admitted: AdmittedJudgeInvocation,
+  engineMaterial?: EngineSessionMaterial,
+): string {
+  return buildStandardMaterialTransportPrompt(admitted, engineMaterial);
+}
+
 /** Load admitted-request.json written at admission (Navigator work-context seam). */
 export async function loadAdmittedJudgeRequest(
   runDirectory: string,

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

@@ -29,6 +29,7 @@ export type OptionOwner =
   | "doctor"
   | "merger"
   | "notary"
+  | "inspector"
   | "analyst";
 
 /**
@@ -369,6 +370,11 @@ const JUDGE_OPTIONS = [
   bindOwner("judge", SHARED_ATTACH_SEMANTICS),
 ] as const satisfies readonly PublicOptionDefinition[];
 
+const INSPECTOR_OPTIONS = [
+  bindOwner("inspector", SHARED_PROJECT_SEMANTICS),
+  bindOwner("inspector", SHARED_ATTACH_SEMANTICS),
+] as const satisfies readonly PublicOptionDefinition[];
+
 const CODER_OPTIONS = [
   {
     id: "phase",
@@ -721,6 +727,7 @@ export const PUBLIC_OPTION_TABLE = {
   doctor: DOCTOR_OPTIONS,
   merger: MERGER_OPTIONS,
   notary: NOTARY_OPTIONS,
+  inspector: INSPECTOR_OPTIONS,
   analyst: ANALYST_OPTIONS,
 } as const satisfies Record<OptionOwner, readonly PublicOptionDefinition[]>;
 
@@ -736,6 +743,7 @@ export const PUBLIC_ROLE_OPTION_OWNERS = [
   "doctor",
   "merger",
   "notary",
+  "inspector",
   "analyst",
 ] as const satisfies readonly PublicRoleOptionOwner[];
 
@@ -1097,6 +1105,12 @@ const ROLE_COMMAND_HELP = {
       "ak-role notary --source-run 01a034f1-75bf-71a6-bcf5-d1299145b1a5@judge",
     ],
   },
+  inspector: {
+    command: "inspector",
+    summary: "Direct complexity and test-quality inspection.",
+    usage: ["ak-role inspector [options] [instruction]"],
+    examples: ['ak-role inspector --attach ./change.patch "Review this material."'],
+  },
   analyst: {
     command: "analyst",
     summary: "Deterministic analysis seat (issue / sweep / cohort).",

package/src/public-cli/registry.ts

@@ -19,14 +19,12 @@ export type PublicCallableRole = (typeof PUBLIC_CALLABLE_ROLES)[number];
 /** Automatic attendance seat — configurable, never a caller-selected command. */
 export const AUTOMATIC_NAVIGATOR_SEAT = "navigator" as const;
 
-/** Automatic gate seats — configurable model only; never caller commands (#453). */
+/** Automatic province seat — configurable model only; never a caller command. */
 export const AUTOMATIC_GATEKEEPER_SEAT = "gatekeeper" as const;
-export const AUTOMATIC_INSPECTOR_SEAT = "inspector" as const;
 
-/** All automatic configurable seats (no independent public activation command). */
+/** Automatic-only configurable seats. Inspector remains automatic-capable via its callable seat. */
 export const AUTOMATIC_CONFIGURABLE_SEATS = [
   AUTOMATIC_GATEKEEPER_SEAT,
-  AUTOMATIC_INSPECTOR_SEAT,
   AUTOMATIC_NAVIGATOR_SEAT,
 ] as const;
 

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

@@ -68,7 +68,8 @@ export type RoleRunRecord = {
     | "doctor"
     | "reviewer"
     | "merger"
-    | "notary";
+    | "notary"
+    | "inspector";
   readonly state: RoleRunState;
   readonly bookKey: string;
   readonly projectRoot: string;
@@ -179,7 +180,8 @@ export async function readRoleRunState(
       record.role !== "doctor" &&
       record.role !== "reviewer" &&
       record.role !== "merger" &&
-      record.role !== "notary"
+      record.role !== "notary" &&
+      record.role !== "inspector"
     ) {
       return undefined;
     }
@@ -523,7 +525,8 @@ const WRITER_LEASE_RECLAIM_ROUNDS = 3;
  * race repeatedly lost) surfaces the same typed error instead of spinning.
  *
  * `onCleanupFailure` receives a non-terminal diagnostic line when release-time
- * lock cleanup fails or a contested lock cannot be read. Release stays
+ * lock cleanup fails, a contested lock cannot be read, or a stale lock is
+ * reclaimed (the #556 orphan-pi residual declaration). Release stays
  * best-effort (a stale lock is reclaimed by the next acquire's autopsy), but
  * the true error identity must still land somewhere observable — silent
  * swallowing is forbidden.
@@ -532,18 +535,24 @@ export async function acquireRunWriterLease(
   runDirectory: string,
   onCleanupFailure?: (diagnostic: string) => void,
 ): Promise<RunWriterLease> {
-  const reportCleanupFailure = (error: unknown): void => {
-    // Sink isolation: a throwing onCleanupFailure must not propagate through
-    // release() — release stays best-effort by contract. The true cleanup
-    // cause has already been handed to the sink as its argument.
+  const reportDiagnostic = (diagnostic: string): void => {
+    // Single sink exit for every non-terminal writer-lease diagnostic (#556):
+    // a throwing onCleanupFailure must not propagate through release() or
+    // acquire() — both are best-effort by contract. Template wording stays at
+    // the call sites, never inside this wrapper. The default io.stderr writes
+    // raw, so this exit guarantees the line delimiter.
+    const line = diagnostic.endsWith("\n") ? diagnostic : `${diagnostic}\n`;
     try {
-      onCleanupFailure?.(
-        `writer lease lock cleanup failed (best-effort continue; stale lock is reclaimed by the next acquire's holder autopsy) at ${join(runDirectory, WRITER_LOCK_FILE)}: ${describeErrorIdentity(error)}`,
-      );
+      onCleanupFailure?.(line);
     } catch {
-      // diagnostic-sink failure is itself best-effort; never break release().
+      // diagnostic-sink failure is itself best-effort; never break acquire()/release().
     }
   };
+  const reportCleanupFailure = (error: unknown): void => {
+    reportDiagnostic(
+      `writer lease lock cleanup failed (best-effort continue; stale lock is reclaimed by the next acquire's holder autopsy) at ${join(runDirectory, WRITER_LOCK_FILE)}: ${describeErrorIdentity(error)}`,
+    );
+  };
   const lockPath = join(runDirectory, WRITER_LOCK_FILE);
   let lastAutopsy: WriterLockAutopsy = { verdict: "absent" };
   // The reclaim budget: every successful reclaim is immediately followed by a
@@ -585,6 +594,12 @@ export async function acquireRunWriterLease(
         `stale writer lease reclaim failed at ${lockPath} (autopsy: ${describeAutopsy(lastAutopsy)}): ${describeErrorIdentity(reclaimError)}`,
       );
     }
+    // #556 residual declaration, facts only: the pid-only autopsy proves the
+    // CLI holder died; its pi child may outlive it and keep writing this run.
+    // Declare — do not guard.
+    reportDiagnostic(
+      `stale writer lease reclaimed at ${lockPath} (holder pid ${lastAutopsy.pid} verified dead): the killed holder may have left an orphaned pi child still writing this run — check for a surviving pi process on this run before continuing`,
+    );
   }
   throw new RunWriterLeaseHeldError(
     `role run writer lease stayed contested at ${lockPath} after ${WRITER_LEASE_RECLAIM_ROUNDS} reclaims (last autopsy: ${describeAutopsy(lastAutopsy)})`,
@@ -1150,6 +1165,7 @@ export async function peekRoleRunRole(
   | "reviewer"
   | "merger"
   | "notary"
+  | "inspector"
   | undefined
 > {
   const runDirectory = await findRunDirectoryById(home, runId);