@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/src/auditor-soul.ts

@@ -15,6 +15,21 @@ export const AUDITOR_SOUL_ROLES = [
 
 export type AuditorSoulRole = (typeof AUDITOR_SOUL_ROLES)[number];
 
+/**
+ * Audited-subject input for public 审刑院 (#675 owner):
+ * 「审的是谁」is an input selecting judge-auditor.md / doctor-auditor.md —
+ * not a caller-identity fork. Same env for direct `ak-role auditor --subject`
+ * and nested compliance summons.
+ */
+export const AK_ROLE_AUDITOR_SUBJECT_ENV = "AK_ROLE_AUDITOR_SUBJECT" as const;
+
+/**
+ * Audited source-run input for public 审刑院 (#675):
+ * same --source-run face for direct `ak-role auditor` and nested compliance summons.
+ * Never falls back to the auditor's own run directory.
+ */
+export const AK_ROLE_AUDITOR_SOURCE_RUN_ENV = "AK_ROLE_AUDITOR_SOURCE_RUN" as const;
+
 function auditorSoulRelativePath(role: AuditorSoulRole): string {
   return `souls/${role}-auditor.md`;
 }
@@ -23,6 +38,7 @@ function auditorSoulRelativePath(role: AuditorSoulRole): string {
  * #470 auditor session materials. Judge carries audit-law + quality-law; doctor does
  * not (御批四: 参审席 = 大理寺主会话 + 其审计席; 太医线不动).
  * Reviewer auditor roster removed with #495 S6 gate retirement.
+ * #675 owner: no generic auditor.md — subject selects this table.
  */
 export const AUDITOR_SESSION_MATERIALS = {
   judge: [
@@ -37,9 +53,30 @@ export const AUDITOR_SESSION_MATERIALS = {
   readonly [string, string, ...(readonly string[])]
 >;
 
+export function isAuditorSoulRole(value: unknown): value is AuditorSoulRole {
+  return value === "judge" || value === "doctor";
+}
+
+/** Resolve audited subject from explicit value or the subject-input env. */
+export function resolveAuditorSubject(raw?: string): AuditorSoulRole {
+  const value =
+    typeof raw === "string" && raw.trim() !== ""
+      ? raw.trim()
+      : typeof process.env[AK_ROLE_AUDITOR_SUBJECT_ENV] === "string"
+        ? process.env[AK_ROLE_AUDITOR_SUBJECT_ENV].trim()
+        : "";
+  if (!isAuditorSoulRole(value)) {
+    throw new Error(
+      `auditor subject must be judge|doctor (input --subject / ${AK_ROLE_AUDITOR_SUBJECT_ENV}), got ${value === "" ? "(missing)" : value}`,
+    );
+  }
+  return value;
+}
+
 /**
  * Load one complete auditor session afresh for each audit invocation.
  * Blank-soul identity stays owned here; composition reuses joinPackageMaterials.
+ * Subject selects the materials table (#675 owner — same for direct and nested).
  */
 export async function loadAuditorSoul(role: AuditorSoulRole): Promise<string> {
   const materials = AUDITOR_SESSION_MATERIALS[role];
@@ -50,3 +87,8 @@ export async function loadAuditorSoul(role: AuditorSoulRole): Promise<string> {
   }
   return joinPackageMaterials(materials);
 }
+
+/** Runtime loader: subject input decides which soul file to assemble. */
+export async function loadAuditorSoulFromSubjectInput(raw?: string): Promise<string> {
+  return loadAuditorSoul(resolveAuditorSubject(raw));
+}

package/src/compliance-transport.ts

@@ -1,13 +1,12 @@
-import type { AssistantMessage, Usage } from "@earendil-works/pi-ai";
-import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { Usage } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import {
-  executeAuditorChild,
-} from "./evidence-child-executor.ts";
-import { createAuditorDossierTool } from "./auditor-dossier-tool.ts";
+import type { AuditorSoulRole } from "./auditor-soul.ts";
+import { auditorRunDirectory } from "./auditor-dossier-tool.ts";
 import type { DossierObservation } from "./dossier-resolution.ts";
 import type { HostContext } from "./host-contracts.ts";
 import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
+import type { PublicSummonResult } from "./public-role-summons.ts";
+import { retainedShapeUnreadable } from "./shape-unreadable-failure.ts";
 
 export type ComplianceArgumentRootType = "null" | "array" | "undefined" | "string" | "number" | "boolean" | "bigint" | "symbol" | "function";
 export type ComplianceAuditObservation =
@@ -15,9 +14,25 @@ export type ComplianceAuditObservation =
   | { kind: "object-status-unreadable"; status: "missing" | "unknown" }
   | DossierObservation;
 export type ComplianceNoReceipt = NoReceiptLifecycleFacts & { status: "no-receipt"; usage?: Usage };
-export type ComplianceDecision = { status: "pass"; usage?: Usage } | { status: "revise"; violations: readonly unknown[]; usage?: Usage } | { status: "escalate"; conflicts?: unknown; decisionGate?: unknown; usage?: Usage } | ComplianceNoReceipt;
+/** Shape-unreadable audit leg — parent work stands with typed fact, never forged pass (ADR 0055). */
+export type ComplianceUnreadable = {
+  readonly status: "unreadable";
+  readonly observation: ComplianceAuditObservation;
+  readonly candidate: unknown;
+  readonly usage?: Usage;
+};
+export type ComplianceDecision =
+  | { status: "pass"; usage?: Usage }
+  | { status: "revise"; violations: readonly unknown[]; usage?: Usage }
+  | { status: "escalate"; conflicts?: unknown; decisionGate?: unknown; usage?: Usage }
+  | ComplianceNoReceipt
+  | ComplianceUnreadable;
 
-/** Unreadable compliance candidate — infrastructure failure, not a judgment status (#475). */
+/**
+ * Unreadable compliance candidate observation carrier.
+ * Shape-unreadable must not abort the parent run (CLAUDE.md §0 / ADR 0055).
+ * Callers read observation+candidate; projection keeps typed unreadable — never forged pass.
+ */
 export class ComplianceCandidateUnreadableError extends Error {
   readonly observation: ComplianceAuditObservation;
   readonly candidate: unknown;
@@ -43,19 +58,19 @@ export const AUDITOR_DOSSIER_PROMPT = "本 run 卷宗已就绪。" as const;
 
 const nonblank = Type.String({ minLength: 1, pattern: "\\S" });
 const decisionGateSchema = Type.Object({ question: nonblank, options: Type.Array(nonblank, { minItems: 1 }) }, { additionalProperties: false });
-// Transport retains malformed candidates on ComplianceCandidateUnreadableError so
-// the existing failure channel can publish observation + candidate (#475).
-// Status values are guidance, not a schema gate.
 export const complianceDecisionSchema = Type.Object({ status: Type.Unknown({ description: "pass | revise | escalate — 形状指引，非 schema 闸" }), violations: Type.Array(nonblank, { description: "观察到的合规违规" }), conflicts: Type.Array(nonblank, { description: "未决权威或执行冲突" }), decisionGate: Type.Union([decisionGateSchema, Type.Null()], { description: "升级问题与可选选项" }) }, { additionalProperties: true, required: [] });
 
-export function createComplianceDecisionTool(name: string, description: string) {
-  return { name, description, parameters: complianceDecisionSchema, async execute(_id: string, params: unknown): Promise<AgentToolResult<unknown>> { return { content: [{ type: "text", text: "审计决议已收" }], details: params, terminate: true }; } };
-}
-
 export const COMPLIANCE_RESPONSE_ENTRY_TYPE = "ak_compliance_response" as const;
 export const AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE = "ak_auditor_parent_attempt_binding" as const;
 export const AUDITOR_COMPLIANCE_FAILURE_ENTRY_TYPE = "ak_auditor_compliance_failure" as const;
 
+export class ComplianceResponseRetentionError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ComplianceResponseRetentionError";
+  }
+}
+
 export type AuditorParentAttemptBinding = {
   readonly version: 1;
   readonly parent: {
@@ -64,34 +79,37 @@ export type AuditorParentAttemptBinding = {
     readonly attemptEntryId?: string;
   };
 };
-import { attachDirectErrnoCode, sitianReport } from "./sitian-facade.ts";
 
-export class ComplianceResponseRetentionError extends Error {
-  constructor(message: string, options?: ErrorOptions) {
-    super(message, options);
-    this.name = "ComplianceResponseRetentionError";
-    attachDirectErrnoCode(this, options?.cause);
+function readListField(value: unknown): readonly unknown[] { return Array.isArray(value) ? value : value === undefined ? [] : [value]; }
+
+/** Try to project a lawful compliance decision; undefined when shape is not a known release. */
+export function tryReadComplianceCandidate(arguments_: unknown, usage?: Usage): ComplianceDecision | undefined {
+  if (typeof arguments_ !== "object" || arguments_ === null || Array.isArray(arguments_)) {
+    return undefined;
   }
-}
-function retainComplianceResponse(context: HostContext, response: AssistantMessage): void {
-  try {
-    sitianReport({
-      level: "event",
-      kind: "auditor",
-      cwd: context.cwd,
-      sessionParent: context.sessionManager.getSessionFile(),
-      payload: { version: 1, response },
-      source: "compliance-transport",
-    });
-  } catch (error) {
-    throw new ComplianceResponseRetentionError(
-      `compliance response retention failed: ${error instanceof Error ? error.message : String(error)}`,
-      { cause: error },
-    );
+  const args = arguments_ as Record<string, unknown>;
+  const status = args.status;
+  if (status === "pass") return { status, ...(usage === undefined ? {} : { usage }) };
+  if (status === "revise") return { status, violations: readListField(args.violations), ...(usage === undefined ? {} : { usage }) };
+  if (status === "escalate") {
+    return {
+      status,
+      ...(Object.hasOwn(args, "conflicts") ? { conflicts: args.conflicts } : {}),
+      ...(Object.hasOwn(args, "decisionGate") ? { decisionGate: args.decisionGate } : {}),
+      ...(usage === undefined ? {} : { usage }),
+    };
   }
+  return undefined;
 }
-function readListField(value: unknown): readonly unknown[] { return Array.isArray(value) ? value : value === undefined ? [] : [value]; }
+
+/**
+ * Read a compliance candidate. Unreadable shape throws ComplianceCandidateUnreadableError
+ * with observation+candidate retained — callers must not map that throw onto parent abort
+ * (CLAUDE.md §0 / ADR 0055). Prefer tryReadComplianceCandidate at parent projection seams.
+ */
 export function readComplianceCandidate(arguments_: unknown, usage?: Usage): ComplianceDecision {
+  const projected = tryReadComplianceCandidate(arguments_, usage);
+  if (projected !== undefined) return projected;
   if (typeof arguments_ !== "object" || arguments_ === null || Array.isArray(arguments_)) {
     throw new ComplianceCandidateUnreadableError(
       { kind: "non-object-arguments", type: arguments_ === null ? "null" : Array.isArray(arguments_) ? "array" : typeof arguments_ as ComplianceArgumentRootType },
@@ -99,10 +117,7 @@ export function readComplianceCandidate(arguments_: unknown, usage?: Usage): Com
       usage,
     );
   }
-  const args = arguments_ as Record<string, unknown>; const status = args.status;
-  if (status === "pass") return { status, ...(usage === undefined ? {} : { usage }) };
-  if (status === "revise") return { status, violations: readListField(args.violations), ...(usage === undefined ? {} : { usage }) };
-  if (status === "escalate") return { status, ...(Object.hasOwn(args, "conflicts") ? { conflicts: args.conflicts } : {}), ...(Object.hasOwn(args, "decisionGate") ? { decisionGate: args.decisionGate } : {}), ...(usage === undefined ? {} : { usage }) };
+  const status = (arguments_ as Record<string, unknown>).status;
   throw new ComplianceCandidateUnreadableError(
     { kind: "object-status-unreadable", status: status === undefined ? "missing" : "unknown" },
     arguments_,
@@ -110,38 +125,134 @@ export function readComplianceCandidate(arguments_: unknown, usage?: Usage): Com
   );
 }
 
+/**
+ * Public auditor summon for compliance (#675 / ADR 0062 / owner r11).
+ * 审刑院 is the independent audit role; subject (who is audited) selects soul files.
+ * Same public path whether nested or direct `ak-role auditor --subject … --source-run …`.
+ */
+export type AuditorSummon = (
+  subject: AuditorSoulRole,
+  sourceRunDirectory: string,
+  /** Parent cancellation forwarded to the nested activation (#675). */
+  signal?: AbortSignal,
+) => Promise<PublicSummonResult>;
+
 export type RunComplianceAuditOptions = {
-  tool: ReturnType<typeof createComplianceDecisionTool>;
-  systemPrompt: string;
-  /** @deprecated Fixer-lane hand-delivery only (#242 retires). Prefer omitting for zero-projection auditors. */
-  serializedInput?: string;
-  roleLabel: string;
-  invalidDecisionLabel: string;
+  /** Who is being audited — selects judge-auditor.md / doctor-auditor.md. */
+  readonly subject: AuditorSoulRole;
   context: HostContext;
-  /** Exact machine-owned run binding; never sourced from AK_ROLE_RUN_DIR. */
   runDirectory?: string | undefined;
   signal?: AbortSignal;
+  /** Test seam — production uses summonPublicRole({ role: "auditor", argv: ["--subject", subject, "--source-run", …] }). */
+  summonAuditor?: AuditorSummon;
 };
 
-export async function runComplianceAudit(options: RunComplianceAuditOptions): Promise<ComplianceDecision> {
-  const prompt = options.serializedInput ?? AUDITOR_DOSSIER_PROMPT;
-  const receipt = await executeAuditorChild({
-    tool: options.tool,
-    dossierTool: createAuditorDossierTool(options.runDirectory),
-    systemPrompt: options.systemPrompt,
-    prompt,
-    roleLabel: options.roleLabel,
-    context: options.context,
-    retainResponse: (response) => retainComplianceResponse(options.context, response),
-    ...(options.runDirectory === undefined ? {} : { runDirectory: options.runDirectory }),
-    ...(options.signal === undefined ? {} : { signal: options.signal }),
-  });
-  if (receipt.noReceiptLifecycle !== undefined) {
+async function usageFromSummonedSession(summoned: PublicSummonResult): Promise<Usage | undefined> {
+  const { usageFromPublicSummon } = await import("./session-assistant-usage.ts");
+  return usageFromPublicSummon(summoned);
+}
+
+function observationFromUnreadableCandidate(candidate: unknown): ComplianceAuditObservation {
+  if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) {
+    return {
+      kind: "non-object-arguments",
+      type: candidate === null ? "null" : Array.isArray(candidate) ? "array" : typeof candidate as ComplianceArgumentRootType,
+    };
+  }
+  const status = (candidate as Record<string, unknown>).status;
+  return {
+    kind: "object-status-unreadable",
+    status: status === undefined ? "missing" : "unknown",
+  };
+}
+
+function unreadableDecision(
+  candidate: unknown,
+  usage: Usage | undefined,
+): ComplianceUnreadable {
+  return {
+    status: "unreadable",
+    observation: observationFromUnreadableCandidate(candidate),
+    candidate,
+    ...(usage === undefined ? {} : { usage }),
+  };
+}
+
+/**
+ * Project a public auditor terminal onto the parent compliance decision.
+ * Lawful pass/revise/escalate/no-receipt flow through.
+ * Shape-unreadable keeps original candidate + typed observation (ADR 0055 / §0) —
+ * never forged pass, never parent abort. Real provider/engine/disk failures stay loud.
+ * Accepted audits always carry real session usage when present (#675 metering).
+ */
+async function projectAuditorTerminal(summoned: PublicSummonResult): Promise<ComplianceDecision> {
+  const outcome = summoned.terminal?.roleOutcome;
+  if (outcome === undefined) {
+    throw new Error(`Auditor public summon produced no terminal (exit ${summoned.exitCode})`);
+  }
+  const usage = await usageFromSummonedSession(summoned);
+  if (outcome.kind === "no_receipt") {
+    const { status: _ignored, kind: _kind, role: _role, decisiveFacts: _facts, ...facts } = outcome;
     return {
       status: "no-receipt",
-      ...receipt.noReceiptLifecycle,
-      ...(receipt.response.usage === undefined ? {} : { usage: receipt.response.usage }),
+      ...facts,
+      ...(usage === undefined ? {} : { usage }),
     };
   }
-  return readComplianceCandidate(receipt.decision, receipt.response.usage);
+  if (outcome.kind === "failure") {
+    // Single settlement marker only (ADR 0055 / #675) — no cause=output re-derivation.
+    const shape = retainedShapeUnreadable(outcome.decisiveFacts);
+    if (shape !== undefined) {
+      return unreadableDecision(shape.candidate, usage);
+    }
+    throw new Error(outcome.diagnostic);
+  }
+  if (outcome.kind === "accepted") {
+    const candidate = {
+      status: outcome.status,
+      ...outcome.decisiveFacts,
+    };
+    const projected = tryReadComplianceCandidate(candidate, usage);
+    if (projected !== undefined) return projected;
+    // Accepted-once but not a lawful release: retain candidate as typed unreadable.
+    return unreadableDecision(candidate, usage);
+  }
+  throw new Error("Auditor public summon returned unusable terminal kind");
+}
+
+export async function runComplianceAudit(options: RunComplianceAuditOptions): Promise<ComplianceDecision> {
+  const runDirectory = options.runDirectory ?? auditorRunDirectory(options.context);
+  if (runDirectory === undefined) {
+    throw new Error("Compliance audit requires a parent run directory pointer");
+  }
+  const subject = options.subject;
+  const summon =
+    options.summonAuditor
+    ?? (async (
+      auditSubject: AuditorSoulRole,
+      sourceRunDirectory: string,
+      auditSignal?: AbortSignal,
+    ) => {
+      // Dynamic import avoids compliance ↔ public-cli circular init (TDZ).
+      const { summonPublicRole } = await import("./public-role-summons.ts");
+      const { homeFromRunDirectory } = await import("./activation-ledger-topology.ts");
+      const home = homeFromRunDirectory(sourceRunDirectory);
+      // Same input surface as direct `ak-role auditor --subject … --source-run …`
+      // (no ambient env binding for nested-only source).
+      return await summonPublicRole({
+        role: "auditor",
+        argv: [
+          "--subject",
+          auditSubject,
+          "--source-run",
+          sourceRunDirectory,
+          AUDITOR_DOSSIER_PROMPT,
+        ],
+        cwd: options.context.cwd ?? process.cwd(),
+        home,
+        ...(auditSignal === undefined ? {} : { signal: auditSignal }),
+      });
+    });
+  const summoned = await summon(subject, runDirectory, options.signal);
+  return await projectAuditorTerminal(summoned);
 }

package/src/doctor-auditor.ts

@@ -1,8 +1,7 @@
 import { auditorRunDirectory } from "./auditor-dossier-tool.ts";
-import { loadAuditorSoul } from "./auditor-soul.ts";
 import {
-  createComplianceDecisionTool,
   runComplianceAudit,
+  type AuditorSummon,
   type ComplianceDecision,
 } from "./compliance-transport.ts";
 import {
@@ -17,16 +16,13 @@ export const DOCTOR_AUDIT_TOOL_NAME = "ak_doctor_audit_decision";
 export type DoctorAuditOptions = {
   context: HostContext;
   signal?: AbortSignal;
+  /** Same seam as runComplianceAudit options — offline tracers only. */
+  summonAuditor?: AuditorSummon;
 };
 
-const tool = createComplianceDecisionTool(
-  DOCTOR_AUDIT_TOOL_NAME,
-  "提交 typed pass/revise/escalate 决议（太医署审刑）。",
-);
-
 /**
- * Doctor auditor: zero hand-delivered materials.
- * Candidate testimony must already be on the parent-session books.
+ * Doctor compliance via public auditor activation (#675 / ADR 0062 / owner r11).
+ * 审刑院 is an independent role; subject=doctor selects souls/doctor-auditor.md.
  */
 export function createPiDoctorAuditor(): (options: DoctorAuditOptions) => Promise<ComplianceDecision> {
   return async (options) => {
@@ -36,13 +32,13 @@ export function createPiDoctorAuditor(): (options: DoctorAuditOptions) => Promis
     requireAuditMaterials(subjects);
 
     return runComplianceAudit({
-      tool,
-      systemPrompt: await loadAuditorSoul("doctor"),
-      roleLabel: "Doctor Soul compliance audit",
-      invalidDecisionLabel: "invalid Doctor audit decision",
+      subject: "doctor",
       context: options.context,
-      ...(auditorRunDirectory(options.context) === undefined ? {} : { runDirectory: auditorRunDirectory(options.context) }),
+      ...(auditorRunDirectory(options.context) === undefined
+        ? {}
+        : { runDirectory: auditorRunDirectory(options.context) }),
       ...(options.signal === undefined ? {} : { signal: options.signal }),
+      ...(options.summonAuditor === undefined ? {} : { summonAuditor: options.summonAuditor }),
     });
   };
 }

package/src/doctor-contracts.ts

@@ -7,6 +7,7 @@ export const DOCTOR_EVIDENCE_TOOL_NAME = "ak_doctor_evidence";
 export const DOCTOR_OUTPUT_TOOL_NAME = "ak_doctor_output";
 export const DOCTOR_ACCEPTED_TEXT = "太医署回执已接受";
 export const DOCTOR_ACCEPTED_AUDIT_NO_RECEIPT_TEXT = "太医署回执已接受；审计无回执";
+export const DOCTOR_ACCEPTED_AUDIT_UNREADABLE_TEXT = "太医署回执已接受；审计形状不可读";
 export const DOCTOR_OUTPUT_TOOL_DESCRIPTION = "提交唯一终局单案证词；completed 允许空 findings；runtime 补记派生成本入回执。";
 export const DOCTOR_TARGET_KINDS = ["law", "gate", "template", "station", "seat"] as const;
 export type DoctorTargetKind = typeof DOCTOR_TARGET_KINDS[number];

package/src/doctor-role.ts

@@ -2,7 +2,7 @@ import type { RoleHost, HostContext, HostToolResult } from "./host-contracts.ts"
 import { disposeComplianceDecision } from "./audit-escalation.ts";
 import { ComplianceResponseRetentionError, type ComplianceDecision } from "./compliance-transport.ts";
 import { DOCTOR_CANDIDATE_ENTRY_TYPE } from "./dossier-resolution.ts";
-import { DOCTOR_ACCEPTED_AUDIT_NO_RECEIPT_TEXT, DOCTOR_ACCEPTED_TEXT, DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_DESCRIPTION, DOCTOR_OUTPUT_TOOL_NAME, DoctorEvidenceStore, doctorEvidenceReadSchema, doctorSubmissionSchema, validateDoctorOutput, type DoctorCase } from "./doctor-contracts.ts";
+import { DOCTOR_ACCEPTED_AUDIT_NO_RECEIPT_TEXT, DOCTOR_ACCEPTED_AUDIT_UNREADABLE_TEXT, DOCTOR_ACCEPTED_TEXT, DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_DESCRIPTION, DOCTOR_OUTPUT_TOOL_NAME, DoctorEvidenceStore, doctorEvidenceReadSchema, doctorSubmissionSchema, validateDoctorOutput, type DoctorCase } from "./doctor-contracts.ts";
 
 import { sitianReport } from "./sitian-facade.ts";
 
@@ -35,7 +35,7 @@ export function createDoctorRoleRuntime(pi: RoleHost, dependencies: DoctorRoleDe
   let activation: { soul: string; patient: DoctorCase; store: DoctorEvidenceStore } | undefined; let registered = false; pi.registerFlag(DOCTOR_CASE_FLAG.name, DOCTOR_CASE_FLAG.definition);
   return { async activate() { const path = pi.getFlag(DOCTOR_CASE_FLAG.name); if (typeof path !== "string" || !path.trim()) throw new Error("Doctor requires --ak-doctor-case"); const soul = (await dependencies.loadSoul()).trim(); if (!soul) throw new Error("Doctor soul is empty"); const patient = await dependencies.loadCase(path); activation = { soul, patient, store: new DoctorEvidenceStore(patient) };
     if (!registered) { registered = true; pi.registerTool({ name: DOCTOR_EVIDENCE_TOOL_NAME, label: "太医署证据", description: "分页读取留存的 Pi session 字节。", parameters: doctorEvidenceReadSchema, async execute(_id: string, params: { evidenceId: string; offset?: number; limit?: number }) { if (!activation) throw new Error("太医署未激活"); const details = activation.store.read(params.evidenceId, params.offset, params.limit); return { content: [{ type: "text" as const, text: JSON.stringify(details) }], details }; } });
-      pi.registerTool({ name: DOCTOR_OUTPUT_TOOL_NAME, label: "太医署输出", description: DOCTOR_OUTPUT_TOOL_DESCRIPTION, parameters: doctorSubmissionSchema, async execute(id: string, params: unknown, signal: AbortSignal | undefined, _update: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> { if (!activation) throw new Error("太医署未激活"); const testimony = validateDoctorOutput(params, activation.patient, activation.store); try { appendCandidate(ctx, { version: 1, testimony, readRecord: activation.store.readRecord(), patientIdentity: activation.patient.identity }); } catch (error) { host.failInfrastructure(error, ctx, id); } let audit: ComplianceDecision; try { audit = await dependencies.auditCompliance(signal === undefined ? { context: ctx } : { context: ctx, signal }); } catch (error) { host.failInfrastructure(error, ctx, id); } const details = testimony.status === "completed" ? { ...testimony, cost: activation.patient.cost } : testimony; const acceptedDetails = details; return disposeComplianceDecision<HostToolResult<unknown>>(audit, { pass: (usage) => ({ content: [{ type: "text" as const, text: DOCTOR_ACCEPTED_TEXT }], details: acceptedDetails, terminate: true as const, ...(usage === undefined ? {} : { usage }) }), noReceipt: (auditNoReceipt, usageProjection) => ({ content: [{ type: "text" as const, text: DOCTOR_ACCEPTED_AUDIT_NO_RECEIPT_TEXT }], details: { ...acceptedDetails, auditNoReceipt }, terminate: true as const, ...usageProjection }), revise: (violations) => { throw new Error(`太医署回执违 soul：${violations.join("; ")}`); }, escalate: (result) => result }, acceptedDetails); } });
+      pi.registerTool({ name: DOCTOR_OUTPUT_TOOL_NAME, label: "太医署输出", description: DOCTOR_OUTPUT_TOOL_DESCRIPTION, parameters: doctorSubmissionSchema, async execute(id: string, params: unknown, signal: AbortSignal | undefined, _update: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> { if (!activation) throw new Error("太医署未激活"); const testimony = validateDoctorOutput(params, activation.patient, activation.store); try { appendCandidate(ctx, { version: 1, testimony, readRecord: activation.store.readRecord(), patientIdentity: activation.patient.identity }); } catch (error) { host.failInfrastructure(error, ctx, id); } let audit: ComplianceDecision; try { audit = await dependencies.auditCompliance(signal === undefined ? { context: ctx } : { context: ctx, signal }); } catch (error) { host.failInfrastructure(error, ctx, id); } const details = testimony.status === "completed" ? { ...testimony, cost: activation.patient.cost } : testimony; const acceptedDetails = details; return disposeComplianceDecision<HostToolResult<unknown>>(audit, { pass: (usage) => ({ content: [{ type: "text" as const, text: DOCTOR_ACCEPTED_TEXT }], details: acceptedDetails, terminate: true as const, ...(usage === undefined ? {} : { usage }) }), noReceipt: (auditNoReceipt, usageProjection) => ({ content: [{ type: "text" as const, text: DOCTOR_ACCEPTED_AUDIT_NO_RECEIPT_TEXT }], details: { ...acceptedDetails, auditNoReceipt }, terminate: true as const, ...usageProjection }), unreadable: (auditUnreadable, usageProjection) => ({ content: [{ type: "text" as const, text: DOCTOR_ACCEPTED_AUDIT_UNREADABLE_TEXT }], details: { ...acceptedDetails, auditUnreadable }, terminate: true as const, ...usageProjection }), revise: (violations) => { throw new Error(`太医署回执违 soul：${violations.join("; ")}`); }, escalate: (result) => result }, acceptedDetails); } });
       pi.on("before_agent_start", (event) => { if (!activation) throw new Error("太医署未激活"); const catalog = { version: activation.patient.version, identity: activation.patient.identity, admittedMetrics: { provenance: "由留存 session 字节推导，封入受理回执。", cost: activation.patient.cost }, lawfulTargetKeys: ["case", ...activation.patient.cost.invocations.sources], evidence: activation.patient.evidence.map(({ id, kind, sha256, byteLength, contentLength }) => ({ id, kind, sha256, byteLength, contentLength })) }; return { systemPrompt: `${event.systemPrompt}\n\n<doctor_soul>\n${activation.soul}\n</doctor_soul>\n\n<doctor_case>\n${JSON.stringify(catalog)}\n</doctor_case>` }; }); }
     const required = [DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME]; const names = pi.getAllTools().map((tool) => tool.name); for (const name of required) if (names.filter((item) => item === name).length !== 1) throw new Error(`Doctor required tool collision or missing: ${name}`); pi.setActiveTools(required); const active = pi.getActiveTools?.() ?? required; if (active.length !== 2 || !required.every((name) => active.includes(name))) throw new Error("Doctor active tool narrowing failed"); } };
 }

package/src/evidence-child-role.ts

@@ -0,0 +1,22 @@
+/**
+ * Public Evidence-Child role — filed-officer envelope (#675).
+ */
+import {
+  EVIDENCE_CHILD_ACCEPTED_TEXT,
+  EVIDENCE_CHILD_OUTPUT_TOOL_NAME,
+  evidenceChildOutputSchema,
+} from "./package-contracts/evidence-child-output.ts";
+
+export { EVIDENCE_CHILD_ACCEPTED_TEXT, EVIDENCE_CHILD_OUTPUT_TOOL_NAME };
+
+export type EvidenceChildRuntimeDependencies = {
+  loadSoul(): Promise<string>;
+};
+
+export const EVIDENCE_CHILD_TOOL_SPEC = {
+  name: EVIDENCE_CHILD_OUTPUT_TOOL_NAME,
+  label: "取证输出",
+  description: "提交取证报告。",
+  promptSnippet: "提交取证报告",
+  parameters: evidenceChildOutputSchema,
+} as const;

package/src/gatekeeper-pass-envelope.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared submit-path envelope for 门下省 gates (ADR 0018 / #675).
+ * Owns officer-pointer book + host abort/non-pass faces.
+ * Role modules only project via projectGatekeeperRun / runGatekeeper — no book, no catch.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { bookDirectOfficerRunPointer } from "./archivist-record-entry.ts";
+import type { HostContext } from "./host-contracts.ts";
+import {
+  GatekeeperDecisionError,
+  GatekeeperEscalationError,
+  projectGatekeeperRun,
+  type GatekeeperPassHostActions,
+  type GatekeeperResult,
+  type GatekeeperSubject,
+  type GateOfficerSummon,
+} from "./gatekeeper-role.ts";
+import type { PublicSummonResult } from "./public-role-summons.ts";
+import { sessionFileFromPublicSummon } from "./session-assistant-usage.ts";
+
+/**
+ * Book a typed pointer under parent session/auditor-roles (archivist-owned write).
+ * Offline mocks without a real session leave no nested volume (lawful zero).
+ */
+function bookDirectOfficerPointer(
+  context: ExtensionContext | HostContext,
+  officer: "inspector" | "notary",
+  result: GatekeeperResult,
+  summoned: PublicSummonResult,
+): void {
+  if (
+    result.status !== "pass"
+    && result.status !== "bounce"
+    && result.status !== "escalate"
+    && result.status !== "unreadable"
+  ) {
+    return;
+  }
+  const parentFile = context.sessionManager?.getSessionFile?.();
+  if (typeof parentFile !== "string" || parentFile.trim() === "") return;
+  const sessionFile = sessionFileFromPublicSummon(summoned);
+  if (sessionFile === undefined) {
+    // No independent 正本 to point at — do not synthesize a parallel session.
+    return;
+  }
+  bookDirectOfficerRunPointer({
+    parentSessionFile: parentFile,
+    officer,
+    sessionFile,
+    ...(typeof summoned.runDirectory === "string" && summoned.runDirectory.trim() !== ""
+      ? { runDirectory: summoned.runDirectory }
+      : {}),
+  });
+}
+
+/**
+ * Shared envelope: project gate, book officer pointer, map onto host actions.
+ * unreadable = parent stands (ADR 0055); never mechanical NonPass reject.
+ */
+export async function requireGatekeeperPass(options: {
+  readonly context: ExtensionContext | HostContext;
+  readonly subject: GatekeeperSubject;
+  readonly signal?: AbortSignal;
+  readonly hostActions: GatekeeperPassHostActions;
+  readonly toolCallId: string;
+  /** Lowest seam: same as runGatekeeper options.summonOfficer — offline tracers only. */
+  readonly summonOfficer?: GateOfficerSummon;
+}): Promise<void> {
+  const projected = await projectGatekeeperRun({
+    context: options.context,
+    subject: options.subject,
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+    ...(options.summonOfficer === undefined ? {} : { summonOfficer: options.summonOfficer }),
+  });
+  const gatekeeper = projected.result;
+  // Envelope-owned pointer book. Failure is host infrastructure — single face.
+  if (projected.summoned !== undefined) {
+    try {
+      bookDirectOfficerPointer(
+        options.context,
+        projected.officer,
+        gatekeeper,
+        projected.summoned,
+      );
+    } catch (error) {
+      options.hostActions.failInfrastructure(error, options.context, options.toolCallId);
+    }
+  }
+  if (gatekeeper.status === "pass") return;
+  // ADR 0055 / #675: shape-unreadable officer output must not mechanically reject parent.
+  if (gatekeeper.status === "unreadable") return;
+  if (gatekeeper.status === "transport_failure") {
+    const error = new Error(`交卷闸 transport_failure（${gatekeeper.stage}）：${gatekeeper.reason}`) as Error & {
+      stage: typeof gatekeeper.stage;
+      reason: string;
+      submission?: unknown;
+    };
+    error.stage = gatekeeper.stage;
+    error.reason = gatekeeper.reason;
+    if (gatekeeper.submission !== undefined) error.submission = gatekeeper.submission;
+    options.hostActions.failInfrastructure(error, options.context, options.toolCallId);
+  }
+  if (gatekeeper.status === "escalate") {
+    throw new GatekeeperEscalationError(gatekeeper);
+  }
+  // bounce / no_receipt: typed non-pass — envelope owns execute→tool_result bridge.
+  options.hostActions.bindSubmissionNonPass(options.toolCallId, gatekeeper);
+  throw new GatekeeperDecisionError(gatekeeper);
+}