@akagilnc/pi-workflow-roles 0.1.3565 → 0.1.3621

package/src/role-runtime.ts

@@ -70,6 +70,20 @@ import {
   type InspectorRuntimeDependencies,
 } from "./inspector-role.ts";
 import { INSPECTOR_ACCEPTED_TEXT } from "./inspector-contracts.ts";
+import {
+  DIARIST_TOOL_SPEC,
+  type DiaristRuntimeDependencies,
+} from "./diarist-role.ts";
+import {
+  DIARIST_ACCEPTED_TEXT,
+  DIARIST_SOURCES_FLAG,
+  projectDiaristSelections,
+} from "./diarist-contracts.ts";
+import {
+  commitDiaristSelections,
+  loadDiaristSourceCatalog,
+  type DiaristSourceCatalog,
+} from "./diarist.ts";
 import {
   GATEKEEPER_TOOL_SPEC,
   type GatekeeperRuntimeDependencies,
@@ -78,6 +92,16 @@ import {
   NAVIGATOR_TOOL_SPEC,
   type NavigatorRuntimeDependencies,
 } from "./navigator-role.ts";
+import {
+  AUDITOR_TOOL_SPEC,
+  type AuditorRuntimeDependencies,
+} from "./auditor-role.ts";
+import { AUDITOR_ACCEPTED_TEXT } from "./package-contracts/auditor-output.ts";
+import {
+  EVIDENCE_CHILD_TOOL_SPEC,
+  type EvidenceChildRuntimeDependencies,
+} from "./evidence-child-role.ts";
+import { EVIDENCE_CHILD_ACCEPTED_TEXT } from "./package-contracts/evidence-child-output.ts";
 import { GATEKEEPER_ACCEPTED_TEXT } from "./package-contracts/gatekeeper-output.ts";
 import { NAVIGATOR_ACCEPTED_TEXT } from "./package-contracts/navigator-output.ts";
 import { decorateSettlementWithNavigation, formatNavigatorReport, NAVIGATOR_EVENT_TYPE, navigatorSubjectKey, navigatorUnavailableError, subjectPath, type NavigatorAttendance, type NavigatorAttendanceOptions, type NavigatorEvent, type NavigatorPhase, type NavigatorReport, type NavigatorSettlement, type NavigatorSubjectProvenance, type NavigatorTargetRole, type NavigatorWorkContext } from "./navigator-attendance.ts";
@@ -159,6 +183,14 @@ const GLEANER_LEFT_TRANSPORT_FLAGS = Object.freeze([
   }),
 ] as const);
 
+/** Diarist private transport: frozen source catalog path (ADR 0018 / #708). */
+const DIARIST_TRANSPORT_FLAGS = Object.freeze([
+  Object.freeze({
+    name: DIARIST_SOURCES_FLAG.name,
+    definition: DIARIST_SOURCES_FLAG.definition,
+  }),
+] as const);
+
 /**
  * Decode private transport flags into frozen admitted inputs.
  * Envelope-owned; necessary JSON decode only (public --authority-ref owns grammar).
@@ -327,14 +359,11 @@ export {
   writeToolExecutionObservationRecord,
 } from "./tool-execution-observation.ts";
 export type { ToolExecutionObservationRecord, ToolExecutionObservationWriter } from "./tool-execution-observation.ts";
-export { executeAuditorChild } from "./evidence-child-executor.ts";
-export type { AuditorDecisionTool } from "./evidence-child-executor.ts";
 export {
   NOTARY_OUTPUT_TOOL,
   INSPECTOR_OUTPUT_TOOL,
   GatekeeperDecisionError,
   createGatekeeperOutputTool,
-  createOfficerDecisionTool,
   runGatekeeper,
 } from "./gatekeeper-role.ts";
 export type { GatekeeperResult, GatekeeperSubject, GatekeeperNonPassResult, RunGatekeeperOptions } from "./gatekeeper-role.ts";
@@ -375,7 +404,13 @@ export { fixerPrerequisiteSchema, fixerPrerequisitesSchema, parseFixerPrerequisi
 export type { FixerInvocationInput, FixerPrerequisite } from "./package-contracts/fixer-packet.ts";
 export { AUDIT_ESCALATION_KIND, buildAuditEscalationResult, disposeComplianceDecision, isAuditEscalationResult, projectAuditEscalation } from "./audit-escalation.ts";
 export type { AuditEscalationResult, AuditEscalationToolResult, ComplianceDecisionHandlers } from "./audit-escalation.ts";
-export { AUDITOR_SOUL_ROLES, loadAuditorSoul } from "./auditor-soul.ts";
+export {
+  AUDITOR_SOUL_ROLES,
+  AK_ROLE_AUDITOR_SUBJECT_ENV,
+  loadAuditorSoul,
+  loadAuditorSoulFromSubjectInput,
+  resolveAuditorSubject,
+} from "./auditor-soul.ts";
 export type { AuditorSoulRole } from "./auditor-soul.ts";
 export { JUDGE_AUDIT_TOOL_NAME, SOUL_AUDIT_TOOL_NAME, createPiJudgeAuditor } from "./judge-auditor.ts";
 export { DOCTOR_AUDIT_TOOL_NAME, createPiDoctorAuditor } from "./doctor-auditor.ts";
@@ -439,6 +474,9 @@ type ActivationRuntime = {
   inspector: { activate(): Promise<void> };
   gatekeeper: { activate(): Promise<void> };
   navigator: { activate(): Promise<void> };
+  auditor: { activate(): Promise<void> };
+  evidenceChild: { activate(): Promise<void> };
+  diarist: { activate(): Promise<void> };
   merger(): Promise<void>;
 };
 
@@ -487,6 +525,9 @@ function activationStage(role: PackagedRole, runtime: ActivationRuntime): { id:
     case "inspector": return { id: "load-and-install", run: async () => runtime.inspector.activate() };
     case "gatekeeper": return { id: "load-and-install", run: async () => runtime.gatekeeper.activate() };
     case "navigator": return { id: "load-and-install", run: async () => runtime.navigator.activate() };
+    case "auditor": return { id: "load-and-install", run: async () => runtime.auditor.activate() };
+    case "evidence-child": return { id: "load-and-install", run: async () => runtime.evidenceChild.activate() };
+    case "diarist": return { id: "load-and-install", run: async () => runtime.diarist.activate() };
     case "merger": return { id: "prepare-git-and-install", run: async () => runtime.merger() };
   }
 }
@@ -594,6 +635,9 @@ export type RoleRuntimeDependencies = {
   loadInspectorSoul?(): Promise<string>;
   loadGatekeeperSoul?(): Promise<string>;
   loadNavigatorSoul?(): Promise<string>;
+  loadAuditorSoul?(): Promise<string>;
+  loadEvidenceChildSoul?(): Promise<string>;
+  loadDiaristSoul?(): Promise<string>;
   loadDoctorCase?(path: string): Promise<import("./doctor-contracts.ts").DoctorCase>;
   loadMergerSoul?(): Promise<string>;
   loadMergerInput?(path: string): Promise<unknown>;
@@ -707,13 +751,17 @@ export async function projectClosedSubmissionLifecycle(
   await settle(publicNavigatorSettlement(projection.role, phase, closure));
 }
 
-/** Optional pre-accept hook on the shared filed-officer envelope (ADR 0075). */
+/**
+ * Optional pre-accept hook on the shared filed-officer envelope (ADR 0075).
+ * May return a details projection (envelope-owned machine facts recorded next to
+ * the submitted parameters); undefined keeps the parameters as submitted.
+ */
 type FiledOfficerBeforeAccept = (input: {
   readonly toolCallId: string;
   readonly parameters: unknown;
   readonly signal: AbortSignal | undefined;
   readonly ctx: HostContext;
-}) => Promise<void>;
+}) => Promise<unknown>;
 
 /**
  * Shared registration envelope for filed officers (ADR 0018 / #572):
@@ -749,14 +797,15 @@ function createFiledOfficerRuntime(
           parameters: spec.tool.parameters as never,
           async execute(toolCallId, parameters, signal, _onUpdate, ctx): Promise<HostToolResult<unknown>> {
             if (soul === undefined) throw new Error(`${spec.role} 职分未装载`);
-            if (spec.beforeAccept !== undefined) {
-              await spec.beforeAccept({ toolCallId, parameters, signal, ctx });
-            }
+            const projected =
+              spec.beforeAccept === undefined
+                ? undefined
+                : await spec.beforeAccept({ toolCallId, parameters, signal, ctx });
             // Accept-as-is + terminate only. Shape is not an admission gate
             // (第 0 条 / ADR 0055); sole-final barrier is ledger-owned (#575).
             return {
               content: [{ type: "text" as const, text: spec.acceptedText }],
-              details: parameters,
+              details: projected === undefined ? parameters : projected,
               terminate: true as const,
             };
           },
@@ -849,6 +898,125 @@ export function createNavigatorRoleRuntime(
   );
 }
 
+/** #675: public 审刑院 seat on the shared filed-officer envelope. */
+export function createAuditorRoleRuntime(
+  roleHost: RoleHost,
+  dependencies: AuditorRuntimeDependencies,
+) {
+  const base = createFiledOfficerRuntime(
+    roleHost,
+    {
+      role: "auditor",
+      tool: AUDITOR_TOOL_SPEC,
+      acceptedText: AUDITOR_ACCEPTED_TEXT,
+      soulTag: "auditor",
+    },
+    dependencies,
+  );
+  return {
+    async activate() {
+      await base.activate();
+      // Same tools whether nested or direct (#675): dossier tool always registered.
+      // Source run: only the shared --source-run input face (never own-run fallback).
+      const { createAuditorDossierTool, AUDITOR_DOSSIER_TOOL_NAME } =
+        await import("./auditor-dossier-tool.ts");
+      const { AK_ROLE_AUDITOR_SOURCE_RUN_ENV } = await import("./auditor-soul.ts");
+      const already = roleHost.getAllTools().some((tool) => tool.name === AUDITOR_DOSSIER_TOOL_NAME);
+      if (already) return;
+      const sourceRun =
+        typeof process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV] === "string"
+        && process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV].trim() !== ""
+          ? process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV].trim()
+          : undefined;
+      roleHost.registerTool(createAuditorDossierTool(sourceRun) as never);
+    },
+  };
+}
+
+/**
+ * #708: 起居郎 public seat on the shared filed-officer envelope.
+ * Semantic collection happened in this role's own turn; the accept hook runs the
+ * mechanical band (verbatim reverse-verify → idempotent sitian append →
+ * watermark) and records the resulting sitian facts next to the receipt.
+ * Machine facts never come from model self-report (锚定宪法).
+ */
+export function createDiaristRoleRuntime(
+  roleHost: RoleHost,
+  dependencies: DiaristRuntimeDependencies,
+  getSourcesFlag: () => unknown,
+) {
+  // This turn's catalog, snapshotted at activate: the candidateIndexes the role
+  // saw and the rows accept commits are the same bytes. Accept never re-reads
+  // the file, so anything written to it mid-turn cannot become a diary entry.
+  let catalog: DiaristSourceCatalog | undefined;
+  const runtime = createFiledOfficerRuntime(
+    roleHost,
+    {
+      role: "diarist",
+      tool: DIARIST_TOOL_SPEC,
+      acceptedText: DIARIST_ACCEPTED_TEXT,
+      soulTag: "diarist",
+      beforeAccept: async ({ parameters }) => {
+        const submitted =
+          parameters !== null && typeof parameters === "object" && !Array.isArray(parameters)
+            ? (parameters as Record<string, unknown>)
+            : undefined;
+        // True-unbound summons: no ticket, no catalog, no diary committed — so
+        // this turn produced no sitian facts. A self-reported `sitian` is not
+        // one (锚定宪法); drop it rather than let it ride into decisiveFacts.
+        // Carrying the field is not a reason to bounce the receipt (第 0 条).
+        if (catalog === undefined) {
+          if (submitted === undefined || !("sitian" in submitted)) return undefined;
+          const stripped = { ...submitted };
+          delete stripped.sitian;
+          return stripped;
+        }
+        const facts = await commitDiaristSelections({
+          catalog,
+          selections: projectDiaristSelections(parameters),
+        });
+        return { ...(submitted ?? { receipt: parameters }), sitian: facts };
+      },
+    },
+    dependencies,
+  );
+  return {
+    async activate() {
+      catalog = loadFrozenDiaristCatalog(getSourcesFlag);
+      return runtime.activate();
+    },
+  };
+}
+
+/** Envelope-owned decode + one-shot load of the frozen catalog (ADR 0018). */
+function loadFrozenDiaristCatalog(
+  getFlag: () => unknown,
+): DiaristSourceCatalog | undefined {
+  const raw = getFlag();
+  if (raw === undefined) return undefined;
+  if (typeof raw !== "string" || raw.trim() === "") {
+    throw new Error("Diarist source catalog flag must be a nonempty path");
+  }
+  return loadDiaristSourceCatalog(raw);
+}
+
+/** #675: public evidence-child seat on the shared filed-officer envelope. */
+export function createEvidenceChildRoleRuntime(
+  roleHost: RoleHost,
+  dependencies: EvidenceChildRuntimeDependencies,
+) {
+  return createFiledOfficerRuntime(
+    roleHost,
+    {
+      role: "evidence-child",
+      tool: EVIDENCE_CHILD_TOOL_SPEC,
+      acceptedText: EVIDENCE_CHILD_ACCEPTED_TEXT,
+      soulTag: "evidence-child",
+    },
+    dependencies,
+  );
+}
+
 export function createCountersignRoleRuntime(
   roleHost: RoleHost,
   dependencies: CountersignRuntimeDependencies,
@@ -905,6 +1073,9 @@ export function createRoleRuntimeExtension(
     for (const flag of GLEANER_LEFT_TRANSPORT_FLAGS) {
       roleHost.registerFlag(flag.name, flag.definition);
     }
+    for (const flag of DIARIST_TRANSPORT_FLAGS) {
+      roleHost.registerFlag(flag.name, flag.definition);
+    }
 
     let admitted = false;
     let selectedRole: string | undefined;
@@ -927,6 +1098,9 @@ export function createRoleRuntimeExtension(
     // terminating-tool rejections and mechanical delivery requests share two turns.
     let receiptDelivery = createReceiptDeliveryPolicy();
     let noReceiptRecorded = false;
+    // Public-run fetch observation (in-process-session statusAwareFetch face).
+    let priorFetch: typeof globalThis.fetch | undefined;
+    let fetchWrapped = false;
     const settleNavigatorProjection = async (settlement: NavigatorSettlement | undefined) => {
       const attendance = navigatorAttendance;
       if (settlement === undefined || attendance === undefined) return;
@@ -937,6 +1111,9 @@ export function createRoleRuntimeExtension(
           return;
         }
         const settlePromise = attendance.settle(settlement);
+        // Attach catch immediately so a late rejection after grace timeout cannot
+        // surface as unhandledRejection / stale-ctx after session dispose (#675).
+        void settlePromise.catch(() => undefined);
         const raced = await raceNavigatorGrace(settlePromise, NAVIGATOR_POST_ROLE_GRACE_MS);
         if (raced.status !== "timeout") return;
         if (pendingNavigatorPresentation === undefined) {
@@ -963,7 +1140,6 @@ export function createRoleRuntimeExtension(
           pendingNavigatorPresentation = { event, report };
         }
         await attendance.dispose();
-        void settlePromise.catch(() => undefined);
       })();
       pendingNavigatorSettlement = pending;
       await pending;
@@ -1190,6 +1366,11 @@ export function createRoleRuntimeExtension(
     roleHost.on("session_shutdown", async () => {
       // #351: stop OAuth keepalive first so shutdown yields zero further ticks.
       envelopeHost.stopKeepalive();
+      if (fetchWrapped && priorFetch !== undefined) {
+        globalThis.fetch = priorFetch;
+        priorFetch = undefined;
+        fetchWrapped = false;
+      }
       // Flush any still-pending affirmative attendance before teardown. Accepted
       // grace-timeout paths normally emit on agent_settled; abort can skip that hook.
       const presentation = pendingNavigatorPresentation;
@@ -1358,6 +1539,28 @@ export function createRoleRuntimeExtension(
         return dependencies.loadNavigatorSoul();
       },
     });
+    const auditor = createAuditorRoleRuntime(roleHost, {
+      async loadSoul() {
+        if (!dependencies.loadAuditorSoul) throw new Error("Auditor runtime dependencies are not configured");
+        return dependencies.loadAuditorSoul();
+      },
+    });
+    const evidenceChild = createEvidenceChildRoleRuntime(roleHost, {
+      async loadSoul() {
+        if (!dependencies.loadEvidenceChildSoul) throw new Error("Evidence-child runtime dependencies are not configured");
+        return dependencies.loadEvidenceChildSoul();
+      },
+    });
+    const diarist = createDiaristRoleRuntime(
+      roleHost,
+      {
+        async loadSoul() {
+          if (!dependencies.loadDiaristSoul) throw new Error("Diarist runtime dependencies are not configured");
+          return dependencies.loadDiaristSoul();
+        },
+      },
+      () => envelopeHost.host.getFlag(DIARIST_SOURCES_FLAG.name),
+    );
     let sessionMergerGitState = dependencies.mergerGitState;
     const merger = createMergerRoleRuntime(roleHost, {
       async loadSoul() { if (!dependencies.loadMergerSoul) throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerSoul(); },
@@ -1443,20 +1646,19 @@ export function createRoleRuntimeExtension(
     });
 
     // Public Role run: record typed non-success HTTP for error evidence + v1 resume.
-    // 2xx clears prior observation (see recordTypedProviderHttpStatus). Non-success
-    // write failure must surface — never silently drop authorized error evidence.
-    roleHost.on("after_provider_response", async (event, ctx) => {
+    // Same observation owner as in-process-session statusAwareFetch → typed-provider-http
+    // sidecar (settlement already merges observation.httpStatus into knownFailure).
+    // after_provider_response covers the success-path onResponse face; fetch wrap covers
+    // non-2xx Responses where openai-completions throws before onResponse (#675).
+    const recordHttpObservation = async (
+      status: number,
+      provider: string,
+      ctx: HostContext,
+    ): Promise<void> => {
       const runDir = process.env.AK_ROLE_RUN_DIR;
       if (typeof runDir !== "string" || runDir.trim() === "") return;
-      const provider = ctx.model?.provider;
-      if (typeof provider !== "string" || provider.trim() === "") return;
-      const status = event.status;
-      if (typeof status !== "number") return;
       try {
-        await recordTypedProviderHttpStatus(runDir, {
-          httpStatus: status,
-          provider,
-        });
+        await recordTypedProviderHttpStatus(runDir, { httpStatus: status, provider });
       } catch (error) {
         if (
           status >= 200 &&
@@ -1469,9 +1671,49 @@ export function createRoleRuntimeExtension(
         }
         failInfrastructure(error, ctx);
       }
+    };
+    roleHost.on("after_provider_response", async (event, ctx) => {
+      const status = event.status;
+      if (typeof status !== "number") return;
+      const fromCtx = ctx.model?.provider;
+      const provider =
+        typeof fromCtx === "string" && fromCtx.trim() !== ""
+          ? fromCtx
+          : "unknown";
+      await recordHttpObservation(status, provider, ctx);
     });
 
     roleHost.on("session_start", async (event, ctx) => {
+      // Scope fetch observation to this public run (in-process-session statusAwareFetch face).
+      if (!fetchWrapped && typeof globalThis.fetch === "function") {
+        priorFetch = globalThis.fetch.bind(globalThis);
+        const underlying = priorFetch;
+        globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+          const response = await underlying(input, init);
+          const runDir = process.env.AK_ROLE_RUN_DIR;
+          if (
+            typeof runDir === "string"
+            && runDir.trim() !== ""
+            && typeof response?.status === "number"
+            && (response.status < 200 || response.status >= 300)
+          ) {
+            const provider =
+              typeof ctx.model?.provider === "string" && ctx.model.provider.trim() !== ""
+                ? ctx.model.provider
+                : "unknown";
+            try {
+              await recordTypedProviderHttpStatus(runDir, {
+                httpStatus: response.status,
+                provider,
+              });
+            } catch {
+              // Observation must not break the provider stream (same as in-process-session).
+            }
+          }
+          return response;
+        }) as typeof globalThis.fetch;
+        fetchWrapped = true;
+      }
       admitted = false;
       selectedRole = undefined;
       activeReviewerParent = undefined;
@@ -1524,6 +1766,9 @@ export function createRoleRuntimeExtension(
         inspector,
         gatekeeper,
         navigator,
+        auditor,
+        evidenceChild,
+        diarist,
         merger: async () => {
           if (dependencies.mergerGitState === undefined) {
             sessionMergerGitState = dependencies.createMergerGitState?.(ctx.cwd);
@@ -1542,7 +1787,14 @@ export function createRoleRuntimeExtension(
         const ledgerHome = resolveActivationLedgerHomeForPath(sessionFile);
         const session = durableSessionPointer(ctx.sessionManager);
 
-        if (dependencies.createNavigatorAttendance !== undefined) {
+        // Same public activation face for every role (#675 / owner 09-06): no nested-env
+        // skip, no work-role whitelist. Attendance attaches when the envelope supplies it.
+        // Navigator seat never re-attaches itself — prepare turns already ARE the navigator
+        // public activation (prevents summonPublicRole navigator ↔ attendance recursion).
+        if (
+          dependencies.createNavigatorAttendance !== undefined
+          && entry.role !== "navigator"
+        ) {
           let work: NavigatorWorkContext;
           let contextError: unknown;
           if (dependencies.loadNavigatorWorkContext === undefined) {

package/src/session-assistant-usage.ts

@@ -0,0 +1,119 @@
+/**
+ * Sum assistant-message usage rows from a session.jsonl (nested public summons).
+ * Accumulates real cost when rows carry it; never invents cost zeros (#675).
+ */
+import type { Usage } from "@earendil-works/pi-ai";
+import { join } from "node:path";
+
+import type { PublicSummonResult } from "./public-role-summons.ts";
+
+export async function readAssistantUsageFromSessionFile(
+  sessionFile: string,
+): Promise<Usage | undefined> {
+  const { readFile } = await import("node:fs/promises");
+  let text: string;
+  try {
+    text = await readFile(sessionFile, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return undefined;
+    throw error;
+  }
+  let rows: Array<{ type?: string; message?: { role?: string; usage?: Usage } }>;
+  try {
+    rows = text
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as {
+        type?: string;
+        message?: { role?: string; usage?: Usage };
+      });
+  } catch (error) {
+    throw new Error(
+      `session usage parse failed (${sessionFile}): ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+  let total = 0;
+  let input = 0;
+  let output = 0;
+  let cacheRead = 0;
+  let cacheWrite = 0;
+  let costInput = 0;
+  let costOutput = 0;
+  let costCacheRead = 0;
+  let costCacheWrite = 0;
+  let costTotal = 0;
+  let sawCost = false;
+  for (const row of rows) {
+    if (row.type !== "message" || row.message?.role !== "assistant") continue;
+    const usage = row.message.usage;
+    if (usage === undefined) continue;
+    total += usage.totalTokens ?? 0;
+    input += usage.input ?? 0;
+    output += usage.output ?? 0;
+    cacheRead += usage.cacheRead ?? 0;
+    cacheWrite += usage.cacheWrite ?? 0;
+    if (usage.cost !== undefined) {
+      sawCost = true;
+      costInput += usage.cost.input ?? 0;
+      costOutput += usage.cost.output ?? 0;
+      costCacheRead += usage.cost.cacheRead ?? 0;
+      costCacheWrite += usage.cost.cacheWrite ?? 0;
+      costTotal += usage.cost.total ?? 0;
+    }
+  }
+  if (total <= 0 && input <= 0 && output <= 0) return undefined;
+  const base = {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    totalTokens: total > 0 ? total : input + output + cacheRead + cacheWrite,
+  };
+  // Cost only when session rows carried it — unknown stays absent (not zero).
+  if (!sawCost) return base as Usage;
+  return {
+    ...base,
+    cost: {
+      input: costInput,
+      output: costOutput,
+      cacheRead: costCacheRead,
+      cacheWrite: costCacheWrite,
+      total: costTotal,
+    },
+  };
+}
+
+/**
+ * Resolve the independent role run's session.jsonl from a public summon result.
+ * Prefers explicit runDirectory, then terminal artifacts, then no_receipt runPointer.
+ */
+export function sessionFileFromPublicSummon(
+  summoned: PublicSummonResult,
+): string | undefined {
+  if (typeof summoned.runDirectory === "string" && summoned.runDirectory.trim() !== "") {
+    return join(summoned.runDirectory, "session", "session.jsonl");
+  }
+  const fromArtifacts = summoned.terminal?.artifacts
+    ?.map((a) => (a as { path?: string }).path)
+    .find((p): p is string => typeof p === "string" && p.endsWith("session.jsonl"));
+  if (fromArtifacts !== undefined) return fromArtifacts;
+  const outcome = summoned.terminal?.roleOutcome;
+  if (outcome === undefined) return undefined;
+  const facts = (outcome as { decisiveFacts?: Record<string, unknown> }).decisiveFacts;
+  const pointer = facts?.runPointer;
+  if (typeof pointer === "string" && pointer.trim() !== "") {
+    return join(pointer, "session", "session.jsonl");
+  }
+  return undefined;
+}
+
+/** Shared usage projection for nested public summons — undefined when unknown. */
+export async function usageFromPublicSummon(
+  summoned: PublicSummonResult,
+): Promise<Usage | undefined> {
+  const sessionFile = sessionFileFromPublicSummon(summoned);
+  if (sessionFile === undefined) return undefined;
+  return readAssistantUsageFromSessionFile(sessionFile);
+}

package/src/session-opening-materials.ts

@@ -3,7 +3,7 @@
  * errors. Main-role materials derive from PUBLIC_ROLE_RECORDS (including
  * gatekeeper and navigator). Province map reuses that public gatekeeper record
  * plus officer material constants (notary shared). Auditor composition stays in
- * loadAuditorSoul; loaders share joinPackageMaterials.
+ * loadAuditorSoul(subject); loaders share joinPackageMaterials.
  */
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";

package/src/shape-unreadable-failure.ts

@@ -0,0 +1,49 @@
+/**
+ * Single authoritative shape-unreadable marker (#675 / ADR 0055).
+ * Settlement stamps it; consumers only read it — never re-derive from cause=output.
+ */
+
+export const SHAPE_UNREADABLE_KEY = "shapeUnreadable" as const;
+
+export type ShapeUnreadableStamp = {
+  readonly [SHAPE_UNREADABLE_KEY]: true;
+  readonly candidate: unknown;
+  readonly acceptedReceipt: false;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Settlement seat path: stamp retained candidate as shape-unreadable (not infrastructure). */
+export function stampShapeUnreadableDetails(candidate: unknown): ShapeUnreadableStamp {
+  return {
+    [SHAPE_UNREADABLE_KEY]: true,
+    candidate,
+    acceptedReceipt: false,
+  };
+}
+
+/**
+ * Marker presence, decided independently of the candidate value: a stamped
+ * `undefined` candidate is a shape-unreadable decision, not an absent marker.
+ */
+export type RetainedShapeUnreadable = { readonly candidate: unknown };
+
+/**
+ * Read the settlement-stamped shape candidate from a failure decisiveFacts payload.
+ * Looks at root and secondaryEvidence only for the typed marker — no cause inference.
+ */
+export function retainedShapeUnreadable(decisiveFacts: unknown): RetainedShapeUnreadable | undefined {
+  if (!isRecord(decisiveFacts)) return undefined;
+  if (decisiveFacts[SHAPE_UNREADABLE_KEY] === true) {
+    return { candidate: decisiveFacts.candidate };
+  }
+  const secondary = isRecord(decisiveFacts.secondaryEvidence)
+    ? decisiveFacts.secondaryEvidence
+    : undefined;
+  if (secondary !== undefined && secondary[SHAPE_UNREADABLE_KEY] === true) {
+    return { candidate: secondary.candidate };
+  }
+  return undefined;
+}

package/src/submission-errors.ts

@@ -5,6 +5,9 @@ function gatekeeperNonPassMessage(result: GatekeeperNonPassResult): string {
     const findings = result.findings.length === 0 ? "（无 findings）" : result.findings.join("; ");
     return `门下省打回重写，findings：${findings}`;
   }
+  if (result.status === "unreadable") {
+    return `门下省官回执形状不可读（${result.officer}）：${result.reason}`;
+  }
   return `门下省 ${result.status}（${result.stage}）：${result.reason}`;
 }
 

package/src/ticket-provenance-contracts.ts

@@ -66,6 +66,7 @@ export type TicketProvenanceEntry = {
  * Separated by recordClass discriminator — never disguised as a source entry.
  */
 export type TicketProvenanceDiagnosticKind =
+  /** Historical rows only — the diarist turn's own failure settles the run (#708). */
   | "collector-failed"
   | "issue-source-failed"
   | "quote-verify-failed";