@akagilnc/pi-workflow-roles 0.1.4021 → 0.1.4035

package/src/navigator-public-session.ts

@@ -8,9 +8,8 @@
 import { sitianReport } from "./sitian-facade.ts";
 import {
   NavigatorUnavailableError,
-  navigatorProviderFailureFromDiagnostics,
+  navigatorProviderFailureFromPublicTerminal,
   navigatorProviderFailureFromError,
-  navigatorProviderFailureFromStatus,
   navigatorUnavailableError,
   parseNavigatorModelSetting,
   resolveNavigatorSeatSelection,
@@ -18,43 +17,6 @@ import {
   type NavigatorSessionFactory,
 } from "./navigator-session-contracts.ts";
 import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
-import { lastRolePayloadRecord } from "./public-cli/terminal.ts";
-
-/**
- * Classify public-navigator failure terminal from structured decisiveFacts only
- * (httpStatus / diagnostics / secondaryEvidence on the terminal) — same fields
- * settlement already stamps from typed HTTP observation / provider stop.
- */
-function providerFailureFromPublicTerminal(outcome: {
-  readonly cause: string;
-  readonly diagnostic: string;
-  readonly decisiveFacts: Readonly<Record<string, unknown>>;
-}): NavigatorProviderFailureFact {
-  const facts = outcome.decisiveFacts;
-  const secondary =
-    typeof facts.secondaryEvidence === "object" && facts.secondaryEvidence !== null
-      ? (facts.secondaryEvidence as Record<string, unknown>)
-      : undefined;
-  const httpStatus =
-    typeof secondary?.httpStatus === "number"
-      ? secondary.httpStatus
-      : typeof facts.httpStatus === "number"
-        ? facts.httpStatus
-        : typeof facts.errorCode === "number"
-          ? facts.errorCode
-          : undefined;
-  const fromStatus = navigatorProviderFailureFromStatus(httpStatus);
-  if (fromStatus !== undefined) return fromStatus;
-  const diagnostics = secondary?.diagnostics ?? facts.diagnostics;
-  const fromDiagnostics = navigatorProviderFailureFromDiagnostics(diagnostics);
-  if (fromDiagnostics !== undefined) return fromDiagnostics;
-  const fromCode = navigatorProviderFailureFromError({
-    code: secondary?.code ?? facts.errorCode,
-  });
-  if (fromCode !== undefined) return fromCode;
-  if (outcome.cause === "provider") return { source: "transport", cause: "transport" };
-  return { source: "session", cause: "session" };
-}
 
 export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
   return async ({ context, subject, tool }) => {
@@ -122,14 +84,16 @@ export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
           const outcome = summoned.terminal?.roleOutcome;
           if (outcome === undefined) {
             const detail = summoned.stderr?.trim() || `exit ${summoned.exitCode}`;
-            providerFailure = { source: "transport", cause: "transport" };
+            // Known source is the public-summon transport path; unconfirmed cause stays unknown.
+            providerFailure = { source: "transport", cause: "unknown" };
             throw navigatorUnavailableError(
-              "transport",
+              providerFailure.source,
               new Error(`Navigator public summon produced no terminal (${detail})`),
+              providerFailure.cause,
             );
           }
           if (outcome.kind === "failure") {
-            providerFailure = providerFailureFromPublicTerminal(outcome);
+            providerFailure = navigatorProviderFailureFromPublicTerminal(outcome);
             throw navigatorUnavailableError(
               providerFailure.source,
               new Error(outcome.diagnostic),
@@ -147,23 +111,23 @@ export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
             // Not a shape-unusable judgment on the navigator reply (#757).
             return;
           }
-          const candidates = lastRolePayloadRecord(outcome.payloads ?? [])?.candidates;
-          if (!Array.isArray(candidates)) {
-            // Accepted reply without candidates array — no advice, no judgment.
-            return;
+          for (const payload of outcome.payloads ?? []) {
+            if (typeof payload !== "object" || payload === null || Array.isArray(payload)) continue;
+            const candidates = (payload as { candidates?: unknown }).candidates;
+            if (!Array.isArray(candidates)) continue;
+            await tool.execute(
+              "navigator-public-prepare",
+              { candidates },
+              undefined,
+              undefined,
+              context as never,
+            );
           }
-          // Rejoin attendance prepare tool sink (same candidate shape as public advice).
-          await tool.execute(
-            "navigator-public-prepare",
-            { candidates },
-            undefined,
-            undefined,
-            context as never,
-          );
         } catch (error) {
           if (error instanceof NavigatorUnavailableError) throw error;
           const fact = navigatorProviderFailureFromError(error);
-          providerFailure = fact ?? { source: "transport", cause: "transport" };
+          // Catch path is the public-summon seam (source transport); untyped cause stays unknown.
+          providerFailure = fact ?? { source: "transport", cause: "unknown" };
           throw navigatorUnavailableError(providerFailure.source, error, providerFailure.cause);
         }
         })();

package/src/navigator-session-contracts.ts

@@ -133,6 +133,45 @@ export function navigatorProviderFailureFromDiagnostics(diagnostics: unknown): N
   return undefined;
 }
 
+/**
+ * Classify a public-navigator failure terminal from structured facts only.
+ * Untyped cause stays unknown — never relabeled session.
+ */
+export function navigatorProviderFailureFromPublicTerminal(outcome: {
+  readonly cause?: string;
+  readonly diagnostic: string;
+  readonly decisiveFacts: Readonly<Record<string, unknown>>;
+}): NavigatorProviderFailureFact {
+  const facts = outcome.decisiveFacts;
+  const secondary =
+    typeof facts.secondaryEvidence === "object" && facts.secondaryEvidence !== null
+      ? (facts.secondaryEvidence as Record<string, unknown>)
+      : undefined;
+  const httpStatus =
+    typeof secondary?.httpStatus === "number"
+      ? secondary.httpStatus
+      : typeof facts.httpStatus === "number"
+        ? facts.httpStatus
+        : typeof facts.errorCode === "number"
+          ? facts.errorCode
+          : undefined;
+  const fromStatus = navigatorProviderFailureFromStatus(httpStatus);
+  if (fromStatus !== undefined) return fromStatus;
+  const diagnostics = secondary?.diagnostics ?? facts.diagnostics;
+  const fromDiagnostics = navigatorProviderFailureFromDiagnostics(diagnostics);
+  if (fromDiagnostics !== undefined) return fromDiagnostics;
+  const fromCode = navigatorProviderFailureFromError({
+    code: secondary?.code ?? facts.errorCode,
+  });
+  if (fromCode !== undefined) return fromCode;
+  // cause=provider names the known source region only; without status/diagnostics/code
+  // the specific cause stays unknown (#881 — never invent transport/session labels).
+  if (outcome.cause === "provider") return { source: "transport", cause: "unknown" };
+  const typed = navigatorUnavailableKey(outcome.cause);
+  if (typed !== undefined) return { source: typed, cause: typed };
+  return { source: "unknown", cause: "unknown" };
+}
+
 const navigatorProviderFailureSchema = Type.Object({
   source: Type.Union([
     Type.Literal("context"), Type.Literal("session"), Type.Literal("model"), Type.Literal("thinking"),

package/src/pi/known-failure.ts

@@ -49,9 +49,8 @@ function sessionStopDetails(input: {
 /**
  * Project a native session assistant stop onto the existing knownFailure chain.
  * Classification follows two-way testimony: typed HTTP status or SDK structure
- * keeps provider; stopReason, configured provider/model, or errorMessage prose
- * alone is the existing unrecognized value. Present upstream payload is preserved
- * in details without rewriting; missing fields are omitted.
+ * keeps provider; stopReason / errorMessage prose alone never invents a class (#881).
+ * Present upstream payload is preserved in details without rewriting; missing fields are omitted.
  */
 export function knownFailureFromProviderStop(input: {
   readonly stopReason?: string;
@@ -70,7 +69,7 @@ export function knownFailureFromProviderStop(input: {
   const diagnostic = nonEmptyString(input.errorMessage);
   const details = sessionStopDetails(input);
   return {
-    cause: hasUpstreamErrorTestimony(input) ? "provider" : "unrecognized",
+    ...(hasUpstreamErrorTestimony(input) ? { cause: "provider" as const } : {}),
     ...(diagnostic === undefined ? {} : { diagnostic }),
     ...(Object.keys(details).length === 0 ? {} : { details }),
   };

package/src/public-cli/auto-resume.ts

@@ -33,6 +33,7 @@ import {
 import { parseAutoResumeLimit } from "./config.ts";
 import { isLawfulTypedTerminalOutcome, formatTerminalResult, type TerminalArtifactRef, type TerminalResult, type TerminalRoleName } from "./terminal.ts";
 import {
+  attachRecordedSubmissions,
   presentFailureTerminal,
   presentStructuralRejection,
   resolveControlledFailureResumeObservation,
@@ -362,6 +363,33 @@ function unwrapTurnDispatchedFailure(error: unknown): unknown {
   return current;
 }
 
+async function attachDispatchExceptionTerminal(
+  admitted: {
+    readonly runDirectory: string;
+    readonly runId: string;
+    readonly projectRoot: string;
+  },
+  terminal: TerminalResult,
+  io: CliIo,
+): Promise<TerminalResult> {
+  try {
+    return await attachRecordedSubmissions(
+      {
+        projectRoot: admitted.projectRoot,
+        runId: admitted.runId,
+        runDirectory: admitted.runDirectory,
+      },
+      terminal,
+    );
+  } catch (error) {
+    // Existing diagnostic seam: attach true cause on stderr, original Terminal stays.
+    io.stderr(
+      `dispatch exception ledger attach failed (best-effort continue): ${describeErrorIdentity(error)}\n`,
+    );
+    return terminal;
+  }
+}
+
 /**
  * Typed failure terminal for a retry path that ended with only exceptions:
  * loud, non-lawful, carrying the last true cause and the pointers to the
@@ -384,8 +412,8 @@ function dispatchExceptionFailureTerminal(input: {
     ? "dispatch threw an exception on every attempt"
     : "the final dispatch threw an exception";
   const diagnostic = `${history} (${input.endReason}; resumes used ${input.autoResumeAttempts}); last cause: ${describeErrorIdentity(causeError)}`;
+  // #881: no fabricated cause class — original error identity + error-file pointers carry the fact.
   const decisiveFacts: Record<string, unknown> = {
-    cause: "unrecognized",
     diagnostic,
     resumesUsed: input.autoResumeAttempts,
     dispatchErrorFiles: [...input.errorFiles],
@@ -406,7 +434,6 @@ function dispatchExceptionFailureTerminal(input: {
     roleOutcome: {
       kind: "failure",
       role: input.role,
-      cause: "unrecognized",
       diagnostic,
       decisiveFacts,
     },
@@ -427,6 +454,8 @@ export async function runWithAutoResumeLoop<
     role: TerminalRoleName;
     runId: string;
     principal: DurablePrincipal;
+    /** Required: exception terminals attach the ledger via this existing admitted fact. */
+    projectRoot: string;
   };
   principalAuthority: DurablePrincipalAuthority;
   /**
@@ -571,15 +600,19 @@ export async function runWithAutoResumeLoop<
     } else {
       // Exception path: continue through the identical budget/session gates.
       if (autoResumeAttempts >= limit) {
-        const terminal = dispatchExceptionFailureTerminal({
-          role: options.admitted.role,
-          runId: options.admitted.runId,
-          causeError: lastThrownError,
-          errorFiles: retainedErrorFiles,
-          autoResumeAttempts,
-          endReason: "auto-resume budget exhausted",
-          everyAttemptThrew,
-        });
+        const terminal = await attachDispatchExceptionTerminal(
+          options.admitted,
+          dispatchExceptionFailureTerminal({
+            role: options.admitted.role,
+            runId: options.admitted.runId,
+            causeError: lastThrownError,
+            errorFiles: retainedErrorFiles,
+            autoResumeAttempts,
+            endReason: "auto-resume budget exhausted",
+            everyAttemptThrew,
+          }),
+          options.io,
+        );
         await finalizeExceptionRunBestEffort(options.admitted.runDirectory, options.io);
         presentTerminal(terminal, options.io);
         return {
@@ -588,15 +621,19 @@ export async function runWithAutoResumeLoop<
         } as T;
       }
       if (!(await isPrincipalAvailable(options.admitted.principal))) {
-        const terminal = dispatchExceptionFailureTerminal({
-          role: options.admitted.role,
-          runId: options.admitted.runId,
-          causeError: lastThrownError,
-          errorFiles: retainedErrorFiles,
-          autoResumeAttempts,
-          endReason: "session principal unavailable before further resume",
-          everyAttemptThrew,
-        });
+        const terminal = await attachDispatchExceptionTerminal(
+          options.admitted,
+          dispatchExceptionFailureTerminal({
+            role: options.admitted.role,
+            runId: options.admitted.runId,
+            causeError: lastThrownError,
+            errorFiles: retainedErrorFiles,
+            autoResumeAttempts,
+            endReason: "session principal unavailable before further resume",
+            everyAttemptThrew,
+          }),
+          options.io,
+        );
         await finalizeExceptionRunBestEffort(options.admitted.runDirectory, options.io);
         presentTerminal(terminal, options.io);
         return {

package/src/public-cli/cli.ts

@@ -1637,10 +1637,10 @@ export async function runAkRole(
       if (error.cause !== undefined) {
         const detail = formatErrorCauseDetail(error.cause);
         if (detail.trim().length > 0) {
-          label = `${label || error.name || "unrecognized exception"}; cause: ${detail}`;
+          label = `${label || error.name || "exception"}; cause: ${detail}`;
         }
       }
-      io.stderr(formatCliDiagnostic(label || error.name || "unrecognized exception"));
+      io.stderr(formatCliDiagnostic(label || error.name || "exception"));
       return { exitCode: 1 };
     }
     io.stderr(formatCliDiagnostic(String(error)));

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

@@ -142,7 +142,9 @@ function collectorAdapters(): PostAdmissionAdapters<AdmittedCollectorInvocation>
         (infrastructureFailure === undefined
           ? undefined
           : {
-              cause: infrastructureFailure.cause,
+              ...(infrastructureFailure.cause === undefined
+                ? {}
+                : { cause: infrastructureFailure.cause }),
               diagnostic: infrastructureFailure.diagnostic,
               ...(infrastructureFailure.identity === undefined
                 ? {}

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

@@ -54,7 +54,7 @@ import {
   trySettleCountersignTerminalResult,
 } from "./settlement.ts";
 import type { CliIo } from "./cli-io.ts";
-import { lastRolePayloadRecord, type TerminalResult } from "./terminal.ts";
+import type { TerminalResult, TerminalRoleOutcome } from "./terminal.ts";
 import {
   projectRoleTurnRequest,
   type RoleTurnRequestProjectionOptions,
@@ -96,7 +96,24 @@ export function buildCountersignTurnRequest(
 type CourtDiaristIdentity =
   | { readonly kind: "ticket"; readonly ticketNumber: number }
   | { readonly kind: "unbound" }
-  | { readonly kind: "escalate"; readonly reason: string };
+  | { readonly kind: "escalate" };
+
+type CourtDiaristInvocationResult = {
+  readonly identity: CourtDiaristIdentity;
+  readonly failedWithoutEscalate?: { readonly diagnostic: string };
+};
+
+/** Routing boolean over the child's own typed sequence — does not pick or rewrite a sole row. */
+function courtDiaristEscalated(roleOutcome: TerminalRoleOutcome | undefined): boolean {
+  if (roleOutcome === undefined) return false;
+  if (roleOutcome.kind === "audit_escalation") return true;
+  if (roleOutcome.kind !== "accepted") return false;
+  return (roleOutcome.payloads ?? []).some((payload) => {
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return false;
+    const record = payload as Record<string, unknown>;
+    return record.status === "escalate" || record.countersignStatus === "escalate";
+  });
+}
 
 /**
  * Invoke public 起居郎 under the court-pipeline quiet face.
@@ -112,10 +129,7 @@ async function invokeCourtDiarist(input: {
   readonly failureLabel: string;
   /** Already-verified typed key from countersign (refresh / post-assert handoff). */
   readonly boundTicketNumber?: number;
-}, env: CountersignRunEnv, io: CliIo): Promise<{
-  readonly identity: CourtDiaristIdentity;
-  readonly failedWithoutEscalate?: { readonly diagnostic: string };
-}> {
+}, env: CountersignRunEnv, io: CliIo): Promise<CourtDiaristInvocationResult> {
   // Quiet face: the countersign caller must not see diarist CLI chatter.
   const quietIo: CliIo = {
     stdout() {},
@@ -145,23 +159,12 @@ async function invokeCourtDiarist(input: {
   });
 
   const roleOutcome = result.terminal?.roleOutcome;
-  if (roleOutcome !== undefined && (roleOutcome.kind === "accepted" || roleOutcome.kind === "audit_escalation")) {
-    const facts = lastRolePayloadRecord(roleOutcome.payloads ?? []);
-    const status =
-      typeof facts?.status === "string"
-        ? facts.status
-        : typeof facts?.countersignStatus === "string"
-          ? facts.countersignStatus
-          : roleOutcome.kind === "audit_escalation"
-            ? "escalate"
-            : undefined;
-    if (status === "escalate") {
-      const reason =
-        typeof facts?.reason === "string"
-          ? facts.reason
-          : "diarist escalated without reason";
-      return { identity: { kind: "escalate", reason } };
-    }
+  // Escalate routing is a boolean over the preserved sequence (#881). Reasons and
+  // payload bodies stay on roleOutcome — never rewritten into a sole identity reason.
+  if (courtDiaristEscalated(roleOutcome)) {
+    return {
+      identity: { kind: "escalate" },
+    };
   }
 
   if (result.exitCode !== 0) {
@@ -183,9 +186,13 @@ async function invokeCourtDiarist(input: {
     Number.isSafeInteger(asserted) &&
     asserted >= 1
   ) {
-    return { identity: { kind: "ticket", ticketNumber: asserted } };
+    return {
+      identity: { kind: "ticket", ticketNumber: asserted },
+    };
   }
-  return { identity: { kind: "unbound" } };
+  return {
+    identity: { kind: "unbound" },
+  };
 }
 
 /**
@@ -226,7 +233,7 @@ export async function runCountersignCourtDiaristStation(
 
   if (outcome.identity.kind === "escalate") {
     throw new StationChildExhaustedError(
-      `court diarist station escalated (cannot identify court target): ${outcome.identity.reason}`,
+      "court diarist station escalated (cannot identify court target)",
     );
   }
   if (outcome.failedWithoutEscalate !== undefined) {
@@ -309,7 +316,7 @@ export async function runPublicCountersign(
           code: null,
           stderr: "",
           thrown: new Error(
-            `court diarist station escalated (cannot identify court target): ${outcome.identity.reason}`,
+            "court diarist station escalated (cannot identify court target)",
           ),
         },
         countersignAdapters(),

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

@@ -35,11 +35,12 @@ import {
   trySettleDiaristTerminalResult,
 } from "./settlement.ts";
 import type { CliIo } from "./cli-io.ts";
-import { lastRolePayloadRecord, type TerminalResult } from "./terminal.ts";
+import type { TerminalResult } from "./terminal.ts";
 import {
   projectRoleTurnRequest,
   type RoleTurnRequestProjectionOptions,
 } from "./turn-request.ts";
+import { readRunTicketNumber } from "../run-ticket-number.ts";
 
 export type DiaristRunEnv = PostAdmissionEnv & {
   principalAuthority: DurablePrincipalAuthority;
@@ -191,33 +192,15 @@ export async function runPublicDiarist(
     adapters: diaristAdapters(),
     ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   }).then(async (result) => {
-    // Accept may have bound ticket onto durable pages after LLM assertion.
-    // Mirror only lawful non-escalate accepted terminals — escalate must not
-    // leak an unverified ticketNumber into the caller-visible typed key.
+    // Accept hook binds ticket onto durable pages (#771). Mirror that page fact
+    // onto the caller-visible admitted object — never pick a ticketNumber out of
+    // the payload sequence (#881 sole-collapse ban on ticket/escalate).
     if (admitted.ticketNumber === undefined && result.admitted !== undefined) {
-      const roleOutcome = result.terminal?.roleOutcome;
-      const facts =
-        roleOutcome?.kind === "accepted"
-          ? lastRolePayloadRecord(roleOutcome.payloads ?? [])
-          : undefined;
-      if (
-        roleOutcome !== undefined &&
-        roleOutcome.kind === "accepted" &&
-        facts?.status !== "escalate"
-      ) {
-        const raw =
-          typeof facts?.ticketNumber === "number"
-            ? facts.ticketNumber
-            : typeof facts?.sitian === "object"
-              && facts.sitian !== null
-              && typeof (facts.sitian as { ticketNumber?: unknown }).ticketNumber === "number"
-              ? (facts.sitian as { ticketNumber: number }).ticketNumber
-              : undefined;
-        if (typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 1) {
-          (admitted as { ticketNumber?: number }).ticketNumber = raw;
-          if (result.admitted.ticketNumber === undefined) {
-            (result.admitted as { ticketNumber?: number }).ticketNumber = raw;
-          }
+      const fromPages = await readRunTicketNumber(admitted.runDirectory);
+      if (fromPages !== undefined) {
+        await bindAdmittedTicketNumber(admitted, fromPages);
+        if (result.admitted.ticketNumber === undefined) {
+          (result.admitted as { ticketNumber?: number }).ticketNumber = fromPages;
         }
       }
     }

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

@@ -122,7 +122,9 @@ function instructionSeatAdapters(options?: {
       return infrastructureFailure === undefined
         ? result.knownFailure
         : {
-            cause: infrastructureFailure.cause,
+            ...(infrastructureFailure.cause === undefined
+              ? {}
+              : { cause: infrastructureFailure.cause }),
             diagnostic: infrastructureFailure.diagnostic,
             ...(infrastructureFailure.identity === undefined
               ? {}

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

@@ -63,7 +63,9 @@ function judgeAdapters(): PostAdmissionAdapters<AdmittedJudgeInvocation> {
         (infrastructureFailure === undefined
           ? undefined
           : {
-              cause: infrastructureFailure.cause,
+              ...(infrastructureFailure.cause === undefined
+                ? {}
+                : { cause: infrastructureFailure.cause }),
               diagnostic: infrastructureFailure.diagnostic,
               ...(infrastructureFailure.identity === undefined
                 ? {}

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

@@ -104,7 +104,9 @@ function reviewerAdapters(
       return infrastructureFailure === undefined
         ? result.knownFailure
         : {
-            cause: infrastructureFailure.cause,
+            ...(infrastructureFailure.cause === undefined
+              ? {}
+              : { cause: infrastructureFailure.cause }),
             diagnostic: infrastructureFailure.diagnostic,
             ...(infrastructureFailure.identity === undefined
               ? {}