@akagilnc/pi-workflow-roles 0.1.2177 → 0.1.2193

package/dist/public-cli/main.js

@@ -22627,6 +22627,10 @@ var init_settlement = __esm({
 });
 
 // src/public-cli/auto-resume.ts
+import { constants as fsConstants2 } from "node:fs";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { appendFile as appendFile2, lstat as lstat4, mkdir as mkdir4, open as open3, readFile as readFile10 } from "node:fs/promises";
+import { join as join12 } from "node:path";
 function presentTerminal(terminal, io) {
   if (terminal.roleOutcome.kind === "failure" || terminal.roleOutcome.kind === "no_receipt") {
     presentFailureTerminal(terminal, io);
@@ -22634,12 +22638,204 @@ function presentTerminal(terminal, io) {
     io.stdout(formatTerminalResult(terminal));
   }
 }
+async function finalizeExceptionRunBestEffort(runDirectory, io) {
+  try {
+    await markRunTerminal(runDirectory);
+  } catch (error) {
+    io.stderr(
+      `run terminal-state finalization failed (best-effort continue): ${describeErrorIdentity(error)}
+`
+    );
+  }
+}
+function runArtifactsDirectory(runDirectory) {
+  return join12(runDirectory, "artifacts");
+}
+async function ensureRealArtifactsDirectory(runDirectory) {
+  const runStat = await lstat4(runDirectory);
+  if (runStat.isSymbolicLink() || !runStat.isDirectory()) {
+    throw new Error("dispatch error retention: run directory is not a real directory");
+  }
+  const artifactsDir = runArtifactsDirectory(runDirectory);
+  try {
+    const existing = await lstat4(artifactsDir);
+    if (existing.isSymbolicLink() || !existing.isDirectory()) {
+      throw new Error("dispatch error retention: artifacts path is not a real directory");
+    }
+  } catch (error) {
+    if (!isMissingPathError3(error)) throw error;
+    await mkdir4(artifactsDir, { recursive: true });
+    const created = await lstat4(artifactsDir);
+    if (created.isSymbolicLink() || !created.isDirectory()) {
+      throw new Error("dispatch error retention: artifacts directory is not a real directory");
+    }
+  }
+  return artifactsDir;
+}
+function serializeThrownValue(value, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value instanceof Error) {
+    if (seen.has(value)) return "[circular]";
+    seen.add(value);
+    const transferred = {};
+    for (const key of Object.getOwnPropertyNames(value)) {
+      transferred[key] = transferNestedValue(
+        value[key],
+        depth + 1,
+        seen
+      );
+    }
+    return {
+      errorKind: "Error",
+      constructorName: value.constructor?.name,
+      ...transferred,
+      ...value.cause === void 0 ? {} : {
+        causeChain: depth >= 10 ? "[cause-chain-depth-limit]" : serializeThrownValue(value.cause, depth + 1, seen)
+      }
+    };
+  }
+  return value;
+}
+function isMissingPathError3(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function transferNestedValue(value, depth, seen) {
+  if (value instanceof Error) return serializeThrownValue(value, depth, seen);
+  if (depth >= 10) return "[nested-depth-limit]";
+  if (Array.isArray(value)) {
+    return value.map((item) => transferNestedValue(item, depth + 1, seen));
+  }
+  if (value !== null && typeof value === "object") {
+    if (seen.has(value)) return "[circular]";
+    seen.add(value);
+    const transferred = {};
+    for (const key of Object.getOwnPropertyNames(value)) {
+      transferred[key] = transferNestedValue(
+        value[key],
+        depth + 1,
+        seen
+      );
+    }
+    return transferred;
+  }
+  return value;
+}
+function jsonSafeReplacer() {
+  const seen = /* @__PURE__ */ new WeakSet();
+  return (_key, value) => {
+    if (typeof value === "bigint") return `${value}n`;
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) return "[circular]";
+      seen.add(value);
+    }
+    return value;
+  };
+}
+async function retainDispatchError(admitted, attempt, error) {
+  const artifactsDir = await ensureRealArtifactsDirectory(admitted.runDirectory);
+  const filePath = join12(
+    artifactsDir,
+    `dispatch-error-attempt-${attempt}-${randomUUID2()}.json`
+  );
+  const payload = `${JSON.stringify(
+    {
+      version: 1,
+      attempt,
+      recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      error: serializeThrownValue(error)
+    },
+    jsonSafeReplacer(),
+    2
+  )}
+`;
+  const noFollowFlag = typeof fsConstants2.O_NOFOLLOW === "number" ? fsConstants2.O_NOFOLLOW : 0;
+  const handle = await open3(
+    filePath,
+    fsConstants2.O_WRONLY | fsConstants2.O_CREAT | fsConstants2.O_EXCL | noFollowFlag,
+    384
+  );
+  try {
+    await handle.writeFile(payload, "utf8");
+  } finally {
+    await handle.close();
+  }
+  let pointerLease;
+  try {
+    pointerLease = await acquireRunWriterLease(admitted.runDirectory);
+  } catch (error2) {
+    if (error2 instanceof RunWriterLeaseHeldError) return { file: filePath };
+    throw error2;
+  }
+  let pointerError;
+  try {
+    const text = await readFile10(admitted.sessionFile, "utf8");
+    let parentId = null;
+    for (const line2 of text.trim().split("\n").filter(Boolean)) {
+      const entry = JSON.parse(line2);
+      if (typeof entry.id === "string" && entry.type !== "session") parentId = entry.id;
+    }
+    const timestamp2 = (/* @__PURE__ */ new Date()).toISOString();
+    const pointerLine = `${JSON.stringify({
+      type: "custom",
+      customType: DISPATCH_ERROR_RETENTION_ENTRY_TYPE,
+      data: { version: 1, attempt, file: filePath, recordedAt: timestamp2 },
+      id: randomUUID2(),
+      parentId,
+      timestamp: timestamp2
+    })}
+`;
+    await appendFile2(admitted.sessionFile, pointerLine, "utf8");
+  } catch (error2) {
+    pointerError = error2;
+  } finally {
+    await pointerLease.release();
+  }
+  return pointerError === void 0 ? { file: filePath } : { file: filePath, pointerError };
+}
+function dispatchExceptionFailureTerminal(input) {
+  const history = input.everyAttemptThrew ? "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(input.causeError)}`;
+  const decisiveFacts = {
+    cause: "unrecognized",
+    diagnostic,
+    resumesUsed: input.autoResumeAttempts,
+    dispatchErrorFiles: [...input.errorFiles]
+  };
+  if (input.errorFiles.length > 0) {
+    decisiveFacts.lastDispatchErrorFile = input.errorFiles[input.errorFiles.length - 1];
+  }
+  const candidate = input.causeError;
+  if (typeof candidate?.name === "string") decisiveFacts.errorName = candidate.name;
+  if (typeof candidate?.code === "string" || typeof candidate?.code === "number") {
+    decisiveFacts.errorCode = candidate.code;
+  }
+  const artifacts = input.errorFiles.map((path) => ({
+    kind: "error",
+    path
+  }));
+  return {
+    roleOutcome: {
+      kind: "failure",
+      role: input.role,
+      cause: "unrecognized",
+      diagnostic,
+      decisiveFacts
+    },
+    navigator: { disposition: "no-advice" },
+    artifacts,
+    runId: input.runId,
+    autoResumeCount: input.autoResumeAttempts
+  };
+}
 async function runWithAutoResumeLoop(options) {
   const limit = options.autoResumeLimit ?? AUTO_RESUME_LIMIT;
   parseAutoResumeLimit(limit);
   let autoResumeAttempts = 0;
   let isFirst = true;
   let currentExtraArgs = options.buildInitialArgs();
+  let dispatchOrdinal = 0;
+  let lastThrownError;
+  let everyAttemptThrew = true;
+  const retainedErrorFiles = [];
   while (true) {
     let lease;
     try {
@@ -22654,32 +22850,96 @@ async function runWithAutoResumeLoop(options) {
       }
       throw error;
     }
-    const result2 = await options.dispatch(currentExtraArgs, lease, isFirst, dummyIo);
-    const terminal = result2.terminal;
-    if (terminal !== void 0) {
-      terminal.autoResumeCount = autoResumeAttempts;
+    let result2;
+    try {
+      result2 = await options.dispatch(currentExtraArgs, lease, isFirst, dummyIo);
+    } catch (error) {
+      lastThrownError = error;
+      const attempt = dispatchOrdinal;
+      try {
+        const { file, pointerError } = await retainDispatchError(options.admitted, attempt, error);
+        retainedErrorFiles.push(file);
+        options.io.stderr(
+          `dispatch attempt ${attempt} threw (${describeErrorIdentity(error)}); full error retained at ${file}
+`
+        );
+        if (pointerError !== void 0) {
+          options.io.stderr(
+            `dispatch error retention failed (best-effort continue): ${describeErrorIdentity(pointerError)}
+`
+          );
+        }
+      } catch (retentionError) {
+        options.io.stderr(
+          `dispatch error retention failed (best-effort continue): ${describeErrorIdentity(retentionError)}
+`
+        );
+      }
     }
-    const lawful = terminal !== void 0 && isLawfulTypedTerminalOutcome(terminal.roleOutcome);
-    if (lawful) {
+    dispatchOrdinal += 1;
+    if (result2 !== void 0) {
+      everyAttemptThrew = false;
+      const terminal = result2.terminal;
       if (terminal !== void 0) {
-        options.io.stdout(formatTerminalResult(terminal));
+        terminal.autoResumeCount = autoResumeAttempts;
+      }
+      const lawful = terminal !== void 0 && isLawfulTypedTerminalOutcome(terminal.roleOutcome);
+      if (lawful) {
+        if (terminal !== void 0) {
+          options.io.stdout(formatTerminalResult(terminal));
+        }
+        return result2;
+      }
+      if (autoResumeAttempts >= limit) {
+        if (terminal !== void 0) presentTerminal(terminal, options.io);
+        return result2;
+      }
+      if (!await isSessionPrincipalAvailable(options.admitted.sessionFile)) {
+        if (terminal !== void 0) presentTerminal(terminal, options.io);
+        return result2;
+      }
+    } else {
+      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
+        });
+        await finalizeExceptionRunBestEffort(options.admitted.runDirectory, options.io);
+        presentTerminal(terminal, options.io);
+        return {
+          exitCode: 1,
+          terminal
+        };
+      }
+      if (!await isSessionPrincipalAvailable(options.admitted.sessionFile)) {
+        const terminal = dispatchExceptionFailureTerminal({
+          role: options.admitted.role,
+          runId: options.admitted.runId,
+          causeError: lastThrownError,
+          errorFiles: retainedErrorFiles,
+          autoResumeAttempts,
+          endReason: "session principal unavailable before further resume",
+          everyAttemptThrew
+        });
+        await finalizeExceptionRunBestEffort(options.admitted.runDirectory, options.io);
+        presentTerminal(terminal, options.io);
+        return {
+          exitCode: 1,
+          terminal
+        };
       }
-      return result2;
-    }
-    if (autoResumeAttempts >= limit) {
-      if (terminal !== void 0) presentTerminal(terminal, options.io);
-      return result2;
-    }
-    if (!await isSessionPrincipalAvailable(options.admitted.sessionFile)) {
-      if (terminal !== void 0) presentTerminal(terminal, options.io);
-      return result2;
     }
     autoResumeAttempts++;
     currentExtraArgs = options.buildResumeArgs();
     isFirst = false;
   }
 }
-var dummyIo;
+var dummyIo, DISPATCH_ERROR_RETENTION_ENTRY_TYPE;
 var init_auto_resume = __esm({
   "src/public-cli/auto-resume.ts"() {
     "use strict";
@@ -22690,12 +22950,13 @@ var init_auto_resume = __esm({
     dummyIo = { stdout: () => {
     }, stderr: () => {
     } };
+    DISPATCH_ERROR_RETENTION_ENTRY_TYPE = "ak_run_dispatch_error_retention";
   }
 });
 
 // src/public-cli/coder-run.ts
 import { writeFile as writeFile6 } from "node:fs/promises";
-import { join as join12 } from "node:path";
+import { join as join13 } from "node:path";
 function buildCoderActivationExtraArgs(admitted, options) {
   const prompt = buildCoderTransportPrompt(
     admitted,
@@ -22857,7 +23118,7 @@ async function dispatchAdmittedCoder(input) {
     }
     try {
       await writeFile6(
-        join12(admitted.runDirectory, "stderr.log"),
+        join13(admitted.runDirectory, "stderr.log"),
         result2.stderr,
         "utf8"
       );
@@ -23088,7 +23349,7 @@ var init_coder_run = __esm({
 
 // src/public-cli/collector-run.ts
 import { writeFile as writeFile7 } from "node:fs/promises";
-import { join as join13 } from "node:path";
+import { join as join14 } from "node:path";
 function buildCollectorActivationExtraArgs(admitted, options = {}) {
   const prompt = buildCollectorTransportPrompt(
     admitted,
@@ -23193,7 +23454,7 @@ async function dispatchAdmittedCollector(input) {
     }
     try {
       await writeFile7(
-        join13(admitted.runDirectory, "stderr.log"),
+        join14(admitted.runDirectory, "stderr.log"),
         result2.stderr,
         "utf8"
       );
@@ -23324,7 +23585,7 @@ var init_collector_run = __esm({
 
 // src/public-cli/doctor-run.ts
 import { writeFile as writeFile8 } from "node:fs/promises";
-import { join as join14 } from "node:path";
+import { join as join15 } from "node:path";
 function buildDoctorActivationExtraArgs(admitted, options = {}) {
   const prompt = buildDoctorTransportPrompt(
     admitted,
@@ -23422,7 +23683,7 @@ async function dispatchAdmittedDoctor(input) {
     }
     try {
       await writeFile8(
-        join14(admitted.runDirectory, "stderr.log"),
+        join15(admitted.runDirectory, "stderr.log"),
         result2.stderr,
         "utf8"
       );
@@ -23556,7 +23817,7 @@ var init_doctor_run = __esm({
 
 // src/public-cli/fixer-run.ts
 import { writeFile as writeFile9 } from "node:fs/promises";
-import { join as join15 } from "node:path";
+import { join as join16 } from "node:path";
 function buildFixerActivationExtraArgs(admitted, options) {
   const prompt = buildFixerTransportPrompt(
     admitted,
@@ -23727,7 +23988,7 @@ async function dispatchAdmittedFixer(input) {
     }
     try {
       await writeFile9(
-        join15(admitted.runDirectory, "stderr.log"),
+        join16(admitted.runDirectory, "stderr.log"),
         result2.stderr,
         "utf8"
       );
@@ -23965,7 +24226,7 @@ var init_fixer_run = __esm({
 
 // src/public-cli/judge-run.ts
 import { writeFile as writeFile10 } from "node:fs/promises";
-import { join as join16 } from "node:path";
+import { join as join17 } from "node:path";
 function buildJudgeActivationExtraArgs(admitted, options = {}) {
   const prompt = buildJudgeTransportPrompt(
     admitted,
@@ -24113,7 +24374,7 @@ async function dispatchAdmittedJudge(input) {
     }
     try {
       await writeFile10(
-        join16(admitted.runDirectory, "stderr.log"),
+        join17(admitted.runDirectory, "stderr.log"),
         result2.stderr,
         "utf8"
       );
@@ -24311,8 +24572,8 @@ var init_judge_run = __esm({
 });
 
 // src/public-cli/merger-run.ts
-import { mkdir as mkdir4, writeFile as writeFile11 } from "node:fs/promises";
-import { join as join17, resolve as resolve6 } from "node:path";
+import { mkdir as mkdir5, writeFile as writeFile11 } from "node:fs/promises";
+import { join as join18, resolve as resolve6 } from "node:path";
 function buildMergerActivationExtraArgs(admitted, options) {
   const prompt = buildMergerTransportPrompt(
     admitted,
@@ -24472,7 +24733,7 @@ async function dispatchAdmittedMerger(input) {
     }
     try {
       await writeFile11(
-        join17(admitted.runDirectory, "stderr.log"),
+        join18(admitted.runDirectory, "stderr.log"),
         result2.stderr,
         "utf8"
       );
@@ -24545,7 +24806,7 @@ async function admitMergerShellForActivationFailure(options) {
   const runId = (options.createRunId ?? uuidv7)();
   const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } = roleRunSessionCoordinates({ cwd: projectRoot, runId, role: "merger", home: options.home });
   ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  await mkdir4(runDirectory, { recursive: true });
+  await mkdir5(runDirectory, { recursive: true });
   const emptyDerived = {
     targetObjectId: "",
     sourceObjectId: "",
@@ -24553,8 +24814,8 @@ async function admitMergerShellForActivationFailure(options) {
     expectedConflictPaths: [],
     resolutionScope: []
   };
-  const admittedRequestPath = join17(runDirectory, "admitted-request.json");
-  const mergerInputPath = join17(runDirectory, "merger-input.json");
+  const admittedRequestPath = join18(runDirectory, "admitted-request.json");
+  const mergerInputPath = join18(runDirectory, "merger-input.json");
   await writeFile11(
     admittedRequestPath,
     `${JSON.stringify(
@@ -24784,7 +25045,7 @@ var init_merger_run = __esm({
 
 // src/public-cli/reviewer-run.ts
 import { writeFile as writeFile12 } from "node:fs/promises";
-import { join as join18 } from "node:path";
+import { join as join19 } from "node:path";
 function buildReviewerTicketNumberArgs(ticketNumber) {
   return ticketNumber === void 0 ? [] : ["--ak-review-ticket-number", String(ticketNumber)];
 }
@@ -24953,7 +25214,7 @@ async function dispatchAdmittedReviewer(input) {
     }
     try {
       await writeFile12(
-        join18(admitted.runDirectory, "stderr.log"),
+        join19(admitted.runDirectory, "stderr.log"),
         result2.stderr,
         "utf8"
       );
@@ -25197,12 +25458,12 @@ var init_reviewer_run = __esm({
 });
 
 // src/atomic-write.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { rename, rm, writeFile as writeFile13 } from "node:fs/promises";
-import { dirname as dirname7, join as join19 } from "node:path";
+import { dirname as dirname7, join as join20 } from "node:path";
 async function writeFileAtomically(destination, contents) {
   const parent = dirname7(destination);
-  const temporary = join19(parent, `.atomic-write-${randomUUID2()}.tmp`);
+  const temporary = join20(parent, `.atomic-write-${randomUUID3()}.tmp`);
   try {
     await writeFile13(temporary, contents);
     await rename(temporary, destination);
@@ -25218,8 +25479,8 @@ var init_atomic_write = __esm({
 });
 
 // src/taishi-index.ts
-import { open as open3, readFile as readFile10, unlink as unlink4 } from "node:fs/promises";
-import { dirname as dirname8, join as join20 } from "node:path";
+import { open as open4, readFile as readFile11, unlink as unlink4 } from "node:fs/promises";
+import { dirname as dirname8, join as join21 } from "node:path";
 function sleep(ms) {
   return new Promise((resolve8) => {
     setTimeout(resolve8, ms);
@@ -25228,12 +25489,12 @@ function sleep(ms) {
 async function withTaishiLibraryIndexLock(ledgerHome, fn) {
   const indexPath = taishiLibraryIndexPath(ledgerHome);
   ensureRealDirectoryTree(ledgerHome, dirname8(indexPath));
-  const lockPath = join20(dirname8(indexPath), LIBRARY_INDEX_LOCK_NAME);
+  const lockPath = join21(dirname8(indexPath), LIBRARY_INDEX_LOCK_NAME);
   assertLedgerFileInsideHome(lockPath, ledgerHome);
   const startedAt = Date.now();
   while (true) {
     try {
-      const handle = await open3(lockPath, "wx");
+      const handle = await open4(lockPath, "wx");
       try {
         await handle.writeFile(`${process.pid}
 `, "utf8");
@@ -25255,7 +25516,7 @@ async function withTaishiLibraryIndexLock(ledgerHome, fn) {
   }
 }
 function taishiLibraryIndexPath(ledgerHome) {
-  return join20(ledgerHome, "taishi", "library-index.json");
+  return join21(ledgerHome, "taishi", "library-index.json");
 }
 function rowFromIssueMetricsPage(page) {
   return {
@@ -25334,7 +25595,7 @@ async function readTaishiLibraryIndexPage(ledgerHome) {
   const path = taishiLibraryIndexPath(ledgerHome);
   let raw;
   try {
-    raw = await readFile10(path, "utf8");
+    raw = await readFile11(path, "utf8");
   } catch (error) {
     if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
       return void 0;
@@ -25495,12 +25756,12 @@ var init_taishi_cohort = __esm({
 });
 
 // src/ledger-session-read.ts
-import { readFile as readFile11 } from "node:fs/promises";
+import { readFile as readFile12 } from "node:fs/promises";
 function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 async function readLedgerSessionJsonl(path) {
-  const text = await readFile11(path, "utf8");
+  const text = await readFile12(path, "utf8");
   const lines = text.split("\n");
   const rows = [];
   for (let index = 0; index < lines.length; index += 1) {
@@ -25610,8 +25871,8 @@ function extractSessionToolIntervals(rows) {
       if (resultTimestamp === void 0 || resultTimestamp.length === 0) {
         throw new Error(`toolResult ${message.toolCallId} missing timestamp`);
       }
-      const open4 = openById.get(message.toolCallId);
-      if (open4 === void 0) {
+      const open5 = openById.get(message.toolCallId);
+      if (open5 === void 0) {
         const toolName = typeof message.toolName === "string" && message.toolName.length > 0 ? message.toolName : "unknown";
         order.push({
           toolCallId: message.toolCallId,
@@ -25621,10 +25882,10 @@ function extractSessionToolIntervals(rows) {
         });
         continue;
       }
-      if (open4.endedAt !== void 0) {
+      if (open5.endedAt !== void 0) {
         throw new Error(`duplicate toolResult for toolCallId ${message.toolCallId}`);
       }
-      open4.endedAt = resultTimestamp;
+      open5.endedAt = resultTimestamp;
     }
   }
   return order.map((interval) => {
@@ -25657,9 +25918,9 @@ var init_ledger_session_read = __esm({
 });
 
 // src/run-terminal-artifacts.ts
-import { readdir as readdir4, readFile as readFile12 } from "node:fs/promises";
-import { basename as basename4, dirname as dirname9, join as join21 } from "node:path";
-function isMissingPathError3(error) {
+import { readdir as readdir4, readFile as readFile13 } from "node:fs/promises";
+import { basename as basename4, dirname as dirname9, join as join22 } from "node:path";
+function isMissingPathError4(error) {
   return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
 }
 function errorText2(error) {
@@ -25689,9 +25950,9 @@ function readUsableTerminalArtifactBody(body) {
 async function readTerminalArtifactAtPath(path, file) {
   let raw;
   try {
-    raw = await readFile12(path, "utf8");
+    raw = await readFile13(path, "utf8");
   } catch (error) {
-    if (isMissingPathError3(error)) return void 0;
+    if (isMissingPathError4(error)) return void 0;
     return {
       status: "unreadable",
       file,
@@ -25728,12 +25989,12 @@ async function listUniqueErrorFallbackPaths(directories) {
     try {
       names = await readdir4(dir);
     } catch (error) {
-      if (isMissingPathError3(error)) continue;
+      if (isMissingPathError4(error)) continue;
       throw error;
     }
     for (const name of names.sort((a, b) => a.localeCompare(b))) {
       if (!UNIQUE_ERROR_FALLBACK_NAME.test(name)) continue;
-      found.push(join21(dir, name));
+      found.push(join22(dir, name));
     }
   }
   return found;
@@ -25749,14 +26010,14 @@ function presentUniqueFallbackBoundToRun(body, expectedRunId) {
   return typeof body.runId === "string" && body.runId === expectedRunId;
 }
 async function readRunTerminalArtifact(runDirectory) {
-  const artifactsDir = join21(runDirectory, "artifacts");
+  const artifactsDir = join22(runDirectory, "artifacts");
   for (const file of RUN_TERMINAL_ARTIFACT_FILES) {
-    const path = join21(artifactsDir, file);
+    const path = join22(artifactsDir, file);
     const read3 = await readTerminalArtifactAtPath(path, file);
     if (read3 !== void 0) return read3;
   }
   for (const relative3 of RUN_TERMINAL_ERROR_FALLBACK_RELATIVE_PATHS) {
-    const path = join21(runDirectory, relative3);
+    const path = join22(runDirectory, relative3);
     const read3 = await readTerminalArtifactAtPath(path, "error.json");
     if (read3 !== void 0) return read3;
   }
@@ -25793,9 +26054,9 @@ var init_run_terminal_artifacts = __esm({
 });
 
 // src/taishi-ledger.ts
-import { readdir as readdir5, readFile as readFile13 } from "node:fs/promises";
-import { join as join22 } from "node:path";
-function isMissingPathError4(error) {
+import { readdir as readdir5, readFile as readFile14 } from "node:fs/promises";
+import { join as join23 } from "node:path";
+function isMissingPathError5(error) {
   return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
 }
 function errorText3(error) {
@@ -25807,7 +26068,7 @@ function isRecord8(value) {
 async function readExistingRunLifecycleState(runDirectory) {
   try {
     const raw = JSON.parse(
-      await readFile13(join22(runDirectory, "run-state.json"), "utf8")
+      await readFile14(join23(runDirectory, "run-state.json"), "utf8")
     );
     if (!isRecord8(raw) || typeof raw.state !== "string") return void 0;
     return raw.state;
@@ -25832,16 +26093,16 @@ async function listLedgerBookNames(booksRoot) {
     const entries = await readdir5(booksRoot, { withFileTypes: true });
     return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
   } catch (error) {
-    if (isMissingPathError4(error)) return [];
+    if (isMissingPathError5(error)) return [];
     throw error;
   }
 }
 async function readInvocationScopeFields(runDirectory) {
   let raw;
   try {
-    raw = await readFile13(join22(runDirectory, "invocation.json"), "utf8");
+    raw = await readFile14(join23(runDirectory, "invocation.json"), "utf8");
   } catch (error) {
-    if (isMissingPathError4(error)) return void 0;
+    if (isMissingPathError5(error)) return void 0;
     throw error;
   }
   const parsed = JSON.parse(raw);
@@ -25871,15 +26132,15 @@ function decideIssueScope(input) {
 }
 async function resolveSessionFile(runDirectory) {
   try {
-    const raw = await readFile13(join22(runDirectory, "invocation.json"), "utf8");
+    const raw = await readFile14(join23(runDirectory, "invocation.json"), "utf8");
     const parsed = JSON.parse(raw);
     if (isRecord8(parsed) && typeof parsed.sessionFile === "string" && parsed.sessionFile.trim() !== "") {
       return parsed.sessionFile;
     }
   } catch (error) {
-    if (!isMissingPathError4(error)) throw error;
+    if (!isMissingPathError5(error)) throw error;
   }
-  return join22(runDirectory, "session", "session.jsonl");
+  return join23(runDirectory, "session", "session.jsonl");
 }
 async function classifyScopedRun(input) {
   const missingSources = [];
@@ -26003,7 +26264,7 @@ async function classifyScopedRun(input) {
 async function scanTaishiIssueRuns(input) {
   const ledgerHome = resolveActivationLedgerHome();
   const scopeTicketNumber = input.ticketNumber;
-  const booksRoot = join22(ledgerHome, "books");
+  const booksRoot = join23(ledgerHome, "books");
   let wholeBook = false;
   let scopeRootIdentity;
   let bookNames;
@@ -26030,19 +26291,19 @@ async function scanTaishiIssueRuns(input) {
   const unreadable = [];
   const scopeConflicts = [];
   for (const book of bookNames) {
-    const runsDir = join22(booksRoot, book, "runs");
+    const runsDir = join23(booksRoot, book, "runs");
     let runNames;
     try {
       const entries = await readdir5(runsDir, { withFileTypes: true });
       runNames = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
     } catch (error) {
-      if (isMissingPathError4(error)) continue;
+      if (isMissingPathError5(error)) continue;
       throw error;
     }
     for (const runName of runNames) {
       const parsed = parseRunDirectoryName(runName);
       if (parsed === void 0) continue;
-      const runDirectory = join22(runsDir, runName);
+      const runDirectory = join23(runsDir, runName);
       let scopeFields;
       try {
         scopeFields = await readInvocationScopeFields(runDirectory);
@@ -26817,7 +27078,7 @@ var init_taishi_metric_family = __esm({
 
 // src/taishi-page.ts
 import { createHash as createHash4 } from "node:crypto";
-import { dirname as dirname10, join as join23 } from "node:path";
+import { dirname as dirname10, join as join24 } from "node:path";
 function taishiIssuePageKey(address) {
   const parts = ["book", address.bookKey];
   if (address.issueNumber !== void 0) {
@@ -26828,7 +27089,7 @@ function taishiIssuePageKey(address) {
   return createHash4("sha256").update(parts.join("\0")).digest("hex").slice(0, 32);
 }
 function taishiIssuePagePath(ledgerHome, address) {
-  return join23(ledgerHome, "taishi", "issues", `${taishiIssuePageKey(address)}.json`);
+  return join24(ledgerHome, "taishi", "issues", `${taishiIssuePageKey(address)}.json`);
 }
 function taishiIssuePageAddressFromPage(page) {
   return {
@@ -26964,8 +27225,8 @@ var init_taishi_page = __esm({
 });
 
 // src/taishi-entry.ts
-import { readFile as readFile14 } from "node:fs/promises";
-function isMissingPathError5(error) {
+import { readFile as readFile15 } from "node:fs/promises";
+function isMissingPathError6(error) {
   return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
 }
 function cachedPageMatchesRequestedScope(page, input) {
@@ -27003,13 +27264,13 @@ async function readOrComputeTaishiIssuePage(input) {
     ...issueNumber === void 0 && input.bookKey === void 0 ? { scopeRootIdentity: projectRoot } : {}
   });
   try {
-    const raw = await readFile14(pagePath, "utf8");
+    const raw = await readFile15(pagePath, "utf8");
     const page = JSON.parse(raw);
     if (cachedPageMatchesRequestedScope(page, { bookKey, ...input })) {
       return { mode: "issue", page, pagePath };
     }
   } catch (error) {
-    if (!isMissingPathError5(error)) {
+    if (!isMissingPathError6(error)) {
       throw new TaishiIssueComputeError({
         bookKey,
         projectRoot,
@@ -27096,10 +27357,10 @@ async function runTaishiModelGroupsMode(input) {
       scopeRootIdentity: projectRoot
     });
     try {
-      const raw = await readFile14(pagePath, "utf8");
+      const raw = await readFile15(pagePath, "utf8");
       JSON.parse(raw);
     } catch (error) {
-      if (!isMissingPathError5(error)) {
+      if (!isMissingPathError6(error)) {
         throw new TaishiIssueComputeError({ bookKey, projectRoot, cause: error });
       }
       try {
@@ -27194,7 +27455,7 @@ var init_taishi_entry = __esm({
 });
 
 // src/public-cli/taishi-run.ts
-import { readFile as readFile15 } from "node:fs/promises";
+import { readFile as readFile16 } from "node:fs/promises";
 import { isAbsolute as isAbsolute5, resolve as resolve7 } from "node:path";
 function resolveTaishiIssueBookKeyFromCwd(cwd = process.cwd()) {
   try {
@@ -27247,7 +27508,7 @@ async function buildTaishiSweepModeInputFromAttachmentPaths(attachmentPaths) {
   const absolute = isAbsolute5(sourcePath) ? sourcePath : resolve7(sourcePath);
   let bytes;
   try {
-    bytes = await readFile15(absolute);
+    bytes = await readFile16(absolute);
   } catch (error) {
     throw new CliUsageError(
       `taishi sweep attachment is not a readable regular file: ${sourcePath}`,
@@ -27349,7 +27610,7 @@ __export(cli_exports, {
 });
 import { realpath as realpath5 } from "node:fs/promises";
 import { homedir as homedir3 } from "node:os";
-import { join as join24 } from "node:path";
+import { join as join25 } from "node:path";
 function takePublicGlobalFlag(argv, index, options) {
   const tokens = argv.slice(index);
   const taken = options.takeDashed(tokens);
@@ -27395,7 +27656,7 @@ function resolveHome(env) {
   return env.home ?? process.env.HOME ?? homedir3();
 }
 function resolveAgentDir(env, home) {
-  return env.agentDir ?? process.env.PI_CODING_AGENT_DIR ?? join24(home, ".pi", "agent");
+  return env.agentDir ?? process.env.PI_CODING_AGENT_DIR ?? join25(home, ".pi", "agent");
 }
 function parseThinking(value) {
   if (!THINKING_LEVELS2.has(value)) {
@@ -28265,7 +28526,7 @@ var init_cli = __esm({
 
 // src/public-cli/main.ts
 import { existsSync as existsSync3 } from "node:fs";
-import { dirname as dirname11, join as join25 } from "node:path";
+import { dirname as dirname11, join as join26 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/public-cli/host-pi-runtime.ts
@@ -28354,8 +28615,8 @@ function linkPackage(packageRoot2, name, targetDir) {
 // src/public-cli/main.ts
 var here = dirname11(fileURLToPath2(import.meta.url));
 function resolvePackageRoot(binDir) {
-  const canonical = join25(binDir, "..", "..");
-  if (existsSync3(join25(canonical, "package.json"))) {
+  const canonical = join26(binDir, "..", "..");
+  if (existsSync3(join26(canonical, "package.json"))) {
     return canonical;
   }
   return binDir;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.2177",
+  "version": "0.1.2193",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",
@@ -41,7 +41,7 @@
   "scripts": {
     "build": "tsx scripts/generate-tool-execution-observation-schema.ts && tsc -p tsconfig.build.json && node scripts/build-package.mjs",
     "prepack": "npm run build",
-    "test": "pnpm run test:all",
+    "test": "node --import tsx --test test/unit/**/*.test.ts test/contract/**/*.test.ts",
     "test:fast": "node --import tsx --test test/unit/**/*.test.ts test/contract/**/*.test.ts",
     "test:integration": "node --import tsx --test test/unit/**/*.test.ts test/contract/**/*.test.ts test/integration/**/*.test.ts",
     "test:all": "node scripts/run-test-all.mjs",

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

@@ -4,10 +4,29 @@
  * per call by the caller, #422 — never re-read from disk inside the loop),
  * in-place (same runId/session).
  * Unifies presentation: intermediate attempts use dummyIo, only final Terminal is presented.
+ *
+ * Owner 2026-08-23: a dispatch that exits by throwing used to bypass the entire
+ * retry mechanism (the throw escaped the while-loop before the count check ever
+ * ran). Every exception is now retained whole, in place, and the ordinary retry
+ * path continues: same budget, same call-local count semantics. No failure-type
+ * classification — every thrown value is treated identically.
  */
-import { AUTO_RESUME_LIMIT, isSessionPrincipalAvailable, acquireRunWriterLease, RunWriterLeaseHeldError, type RunWriterLease } from "./run-lifecycle.ts";
+import { constants as fsConstants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { appendFile, lstat, mkdir, open, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  AUTO_RESUME_LIMIT,
+  describeErrorIdentity,
+  isSessionPrincipalAvailable,
+  acquireRunWriterLease,
+  markRunTerminal,
+  RunWriterLeaseHeldError,
+  type RunWriterLease,
+} from "./run-lifecycle.ts";
 import { parseAutoResumeLimit } from "./config.ts";
-import { isLawfulTypedTerminalOutcome, formatTerminalResult, type TerminalResult } from "./terminal.ts";
+import { isLawfulTypedTerminalOutcome, formatTerminalResult, type TerminalArtifactRef, type TerminalResult, type TerminalRoleName } from "./terminal.ts";
 import { presentFailureTerminal, presentStructuralRejection } from "./settlement.ts";
 import type { CliIo } from "./cli-io.ts";
 
@@ -21,13 +40,305 @@ function presentTerminal(terminal: TerminalResult, io: CliIo): void {
   }
 }
 
+/**
+ * Best-effort finalization of the durable run state before an exception-path
+ * synthetic failure terminal is returned (#426 review: taishi-ledger classifies
+ * running runs as live — an exhausted invocation must not remain live
+ * indefinitely). Finalization failure must not mask the real cause.
+ */
+async function finalizeExceptionRunBestEffort(runDirectory: string, io: CliIo): Promise<void> {
+  try {
+    await markRunTerminal(runDirectory);
+  } catch (error) {
+    io.stderr(
+      `run terminal-state finalization failed (best-effort continue): ${describeErrorIdentity(error)}\n`,
+    );
+  }
+}
+
 export type AutoResumeDispatchResult = {
   exitCode: number;
   terminal?: TerminalResult;
 };
 
+/** Session custom-entry type carrying the pointer to one dispatch error file. */
+export const DISPATCH_ERROR_RETENTION_ENTRY_TYPE = "ak_run_dispatch_error_retention" as const;
+
+/** Artifacts subdirectory of a run directory (established run-artifacts location). */
+function runArtifactsDirectory(runDirectory: string): string {
+  return join(runDirectory, "artifacts");
+}
+
+/**
+ * #182-A hardened path identity, mirrored from settlement.ts's
+ * ensureAuditEvidenceDirectory: a planted symlink at the run directory or the
+ * artifacts path must not receive the dispatch error dump (O_NOFOLLOW only
+ * protects the final file name; recursive mkdir would accept a symlinked
+ * parent). Fails loudly with the true cause instead.
+ */
+async function ensureRealArtifactsDirectory(runDirectory: string): Promise<string> {
+  const runStat = await lstat(runDirectory);
+  if (runStat.isSymbolicLink() || !runStat.isDirectory()) {
+    throw new Error("dispatch error retention: run directory is not a real directory");
+  }
+  const artifactsDir = runArtifactsDirectory(runDirectory);
+  try {
+    const existing = await lstat(artifactsDir);
+    if (existing.isSymbolicLink() || !existing.isDirectory()) {
+      throw new Error("dispatch error retention: artifacts path is not a real directory");
+    }
+  } catch (error) {
+    if (!isMissingPathError(error)) throw error;
+    await mkdir(artifactsDir, { recursive: true });
+    const created = await lstat(artifactsDir);
+    if (created.isSymbolicLink() || !created.isDirectory()) {
+      throw new Error("dispatch error retention: artifacts directory is not a real directory");
+    }
+  }
+  return artifactsDir;
+}
+
+/**
+ * Whole-object transfer of a thrown value (owner 2026-08-23: 「记录所有错误信息。
+ * 不能丢详细情况」). Every own property of the Error object — enumerable or not,
+ * which is how message/stack and any attached identity land verbatim — plus the
+ * constructor name and the full cause chain. No field list is prescribed or
+ * filtered: whatever the exception object carries goes into the file as-is.
+ */
+function serializeThrownValue(value: unknown, depth = 0, seen = new WeakSet<object>()): unknown {
+  if (value instanceof Error) {
+    if (seen.has(value)) return "[circular]";
+    seen.add(value);
+    const transferred: Record<string, unknown> = {};
+    for (const key of Object.getOwnPropertyNames(value)) {
+      transferred[key] = transferNestedValue(
+        (value as unknown as Record<string, unknown>)[key],
+        depth + 1,
+        seen,
+      );
+    }
+    return {
+      errorKind: "Error",
+      constructorName: value.constructor?.name,
+      ...transferred,
+      ...(value.cause === undefined
+        ? {}
+        : {
+            causeChain:
+              depth >= 10
+                ? "[cause-chain-depth-limit]"
+                : serializeThrownValue(value.cause, depth + 1, seen),
+          }),
+    };
+  }
+  return value;
+}
+
+/** ENOENT identity shared with settlement.ts's hardened audit-artifact path. */
+function isMissingPathError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "ENOENT"
+  );
+}
+
+/**
+ * Recursive Error-property transfer (#426 review: nested Errors must not be
+ * passed raw to JSON.stringify — their non-enumerable message/stack would
+ * serialize as {}). Depth-limited; cycle-safe via the seen set so the recursive
+ * construction itself cannot diverge before stringify runs.
+ */
+function transferNestedValue(value: unknown, depth: number, seen: WeakSet<object>): unknown {
+  if (value instanceof Error) return serializeThrownValue(value, depth, seen);
+  if (depth >= 10) return "[nested-depth-limit]";
+  if (Array.isArray(value)) {
+    return value.map((item) => transferNestedValue(item, depth + 1, seen));
+  }
+  if (value !== null && typeof value === "object") {
+    if (seen.has(value)) return "[circular]";
+    seen.add(value);
+    const transferred: Record<string, unknown> = {};
+    for (const key of Object.getOwnPropertyNames(value)) {
+      transferred[key] = transferNestedValue(
+        (value as unknown as Record<string, unknown>)[key],
+        depth + 1,
+        seen,
+      );
+    }
+    return transferred;
+  }
+  return value;
+}
+
+/** Cycle- and bigint-safe JSON replacer so serialization itself cannot drop data. */
+function jsonSafeReplacer(): (key: string, value: unknown) => unknown {
+  const seen = new WeakSet<object>();
+  return (_key: string, value: unknown): unknown => {
+    if (typeof value === "bigint") return `${value}n`;
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) return "[circular]";
+      seen.add(value);
+    }
+    return value;
+  };
+}
+
+/**
+ * Retain one throwing dispatch attempt's complete exception as an independent
+ * per-attempt file under the run's artifacts directory, then leave an
+ * addressable pointer in the session principal (custom entry). Exclusive-create
+ * open (O_EXCL) with a per-attempt unique name enforces 史必追加 (#419): a later
+ * attempt can never overwrite an earlier attempt's file.
+ */
+async function retainDispatchError(
+  admitted: { sessionFile: string; runDirectory: string },
+  attempt: number,
+  error: unknown,
+): Promise<{ file: string; pointerError?: unknown }> {
+  const artifactsDir = await ensureRealArtifactsDirectory(admitted.runDirectory);
+  const filePath = join(
+    artifactsDir,
+    `dispatch-error-attempt-${attempt}-${randomUUID()}.json`,
+  );
+  // Whole-object dump: everything the thrown value carries, nothing picked.
+  const payload = `${JSON.stringify(
+    {
+      version: 1,
+      attempt,
+      recordedAt: new Date().toISOString(),
+      error: serializeThrownValue(error),
+    },
+    jsonSafeReplacer(),
+    2,
+  )}\n`;
+  // O_EXCL: exclusive create — the retention history is append-only by
+  // construction; a colliding name fails loudly instead of overwriting.
+  // O_NOFOLLOW when the platform provides it keeps a planted symlink from
+  // being followed; on platforms without it, exclusivity still holds.
+  const noFollowFlag =
+    typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+  const handle = await open(
+    filePath,
+    fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | noFollowFlag,
+    0o600,
+  );
+  try {
+    await handle.writeFile(payload, "utf8");
+  } finally {
+    await handle.close();
+  }
+  // Addressable pointer in the dossier (卷宗): reuses the session principal's
+  // appended custom-entry shape (mirrors pi SessionManager.appendCustomEntry,
+  // same mechanism as #419 attempt history — no second ledger introduced).
+  // The one-writer lease is held for the append (#426 review: production
+  // dispatchers release the lease in their finally before the rejection reaches
+  // this point); if a concurrent writer already holds it, the append is skipped
+  // gracefully — the error file itself is already durably retained.
+  let pointerLease: RunWriterLease;
+  try {
+    pointerLease = await acquireRunWriterLease(admitted.runDirectory);
+  } catch (error) {
+    if (error instanceof RunWriterLeaseHeldError) return { file: filePath };
+    throw error;
+  }
+  // Pointer-stage failure (#426 fix_now #5) is separated from the file write:
+  // once the error file is durably on disk, a failed readFile/JSON.parse/
+  // appendFile must not reject through here and orphan it — the file path is
+  // still handed back to the caller (retainedErrorFiles → terminal
+  // dispatchErrorFiles/artifacts), and the pointer failure is reported
+  // separately by the caller.
+  let pointerError: unknown;
+  try {
+    const text = await readFile(admitted.sessionFile, "utf8");
+    // Session headers are not branch entries (#419 precedent in
+    // appendRunAttemptHistory excludes type === "session"); leave parentId null
+    // until a non-header entry exists so the pointer stays addressable.
+    let parentId: string | null = null;
+    for (const line of text.trim().split("\n").filter(Boolean)) {
+      const entry = JSON.parse(line) as { id?: unknown; type?: unknown };
+      if (typeof entry.id === "string" && entry.type !== "session") parentId = entry.id;
+    }
+    const timestamp = new Date().toISOString();
+    const pointerLine = `${JSON.stringify({
+      type: "custom",
+      customType: DISPATCH_ERROR_RETENTION_ENTRY_TYPE,
+      data: { version: 1, attempt, file: filePath, recordedAt: timestamp },
+      id: randomUUID(),
+      parentId,
+      timestamp,
+    })}\n`;
+    await appendFile(admitted.sessionFile, pointerLine, "utf8");
+  } catch (error) {
+    pointerError = error;
+  } finally {
+    await pointerLease.release();
+  }
+  return pointerError === undefined ? { file: filePath } : { file: filePath, pointerError };
+}
+
+/**
+ * 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
+ * full per-attempt error files. Never rethrows the raw exception at callers.
+ */
+function dispatchExceptionFailureTerminal(input: {
+  role: TerminalRoleName;
+  runId: string;
+  causeError: unknown;
+  errorFiles: readonly string[];
+  autoResumeAttempts: number;
+  endReason: string;
+  /** True only when every attempt threw; otherwise describe just the final attempt. */
+  everyAttemptThrew: boolean;
+}): TerminalResult {
+  // #426 review: this terminal fires whenever the FINAL dispatch throws, not
+  // only when every attempt threw — do not misrepresent a mixed retry history.
+  const history = input.everyAttemptThrew
+    ? "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(input.causeError)}`;
+  const decisiveFacts: Record<string, unknown> = {
+    cause: "unrecognized",
+    diagnostic,
+    resumesUsed: input.autoResumeAttempts,
+    dispatchErrorFiles: [...input.errorFiles],
+  };
+  if (input.errorFiles.length > 0) {
+    decisiveFacts.lastDispatchErrorFile = input.errorFiles[input.errorFiles.length - 1];
+  }
+  const candidate = input.causeError as { name?: unknown; code?: unknown };
+  if (typeof candidate?.name === "string") decisiveFacts.errorName = candidate.name;
+  if (typeof candidate?.code === "string" || typeof candidate?.code === "number") {
+    decisiveFacts.errorCode = candidate.code;
+  }
+  const artifacts: TerminalArtifactRef[] = input.errorFiles.map((path) => ({
+    kind: "error",
+    path,
+  }));
+  return {
+    roleOutcome: {
+      kind: "failure",
+      role: input.role,
+      cause: "unrecognized",
+      diagnostic,
+      decisiveFacts,
+    },
+    navigator: { disposition: "no-advice" },
+    artifacts,
+    runId: input.runId,
+    autoResumeCount: input.autoResumeAttempts,
+  };
+}
+
 export async function runWithAutoResumeLoop<T extends AutoResumeDispatchResult>(options: {
-  admitted: { sessionFile: string; runDirectory: string };
+  admitted: {
+    sessionFile: string;
+    runDirectory: string;
+    /** Identity for the loop-owned typed failure terminal (dispatch-exception exhaustion). */
+    role: TerminalRoleName;
+    runId: string;
+  };
   io: CliIo;
   /**
    * Effective ceiling (#422), resolved by the caller before the loop; never re-read
@@ -47,6 +358,10 @@ export async function runWithAutoResumeLoop<T extends AutoResumeDispatchResult>(
   let autoResumeAttempts = 0;
   let isFirst = true;
   let currentExtraArgs = options.buildInitialArgs();
+  let dispatchOrdinal = 0;
+  let lastThrownError: unknown;
+  let everyAttemptThrew = true;
+  const retainedErrorFiles: string[] = [];
 
   while (true) {
     let lease: RunWriterLease;
@@ -62,29 +377,99 @@ export async function runWithAutoResumeLoop<T extends AutoResumeDispatchResult>(
       throw error;
     }
 
-    const result = await options.dispatch(currentExtraArgs, lease, isFirst, dummyIo);
-
-    const terminal = (result as { terminal?: TerminalResult }).terminal;
-    if (terminal !== undefined) {
-      (terminal as { autoResumeCount?: number }).autoResumeCount = autoResumeAttempts;
+    let result: T | undefined;
+    try {
+      result = await options.dispatch(currentExtraArgs, lease, isFirst, dummyIo);
+    } catch (error) {
+      // Owner 2026-08-23: 「出了异常，就原地记录错误信息，然后重试。」
+      // Retain the whole exception in place (per-attempt full file + dossier
+      // pointer); recording failure must not break the retry path (PR #418
+      // diagnostic-sink-isolation precedent). The dispatcher owns lease release
+      // in its own finally, so the retry round starts with the lock free.
+      lastThrownError = error;
+      const attempt = dispatchOrdinal;
+      try {
+        // Track the file as soon as it is durably written (#426 review):
+        // a pointer-stage failure comes back separately (pointerError) and must
+        // never orphan the retained file (#426 fix_now #5).
+        const { file, pointerError } = await retainDispatchError(options.admitted, attempt, error);
+        retainedErrorFiles.push(file);
+        options.io.stderr(
+          `dispatch attempt ${attempt} threw (${describeErrorIdentity(error)}); full error retained at ${file}\n`,
+        );
+        if (pointerError !== undefined) {
+          options.io.stderr(
+            `dispatch error retention failed (best-effort continue): ${describeErrorIdentity(pointerError)}\n`,
+          );
+        }
+      } catch (retentionError) {
+        options.io.stderr(
+          `dispatch error retention failed (best-effort continue): ${describeErrorIdentity(retentionError)}\n`,
+        );
+      }
     }
+    dispatchOrdinal += 1;
 
-    const lawful = terminal !== undefined && isLawfulTypedTerminalOutcome(terminal.roleOutcome);
-    if (lawful) {
+    if (result !== undefined) {
+      everyAttemptThrew = false;
+      const terminal = (result as { terminal?: TerminalResult }).terminal;
       if (terminal !== undefined) {
-        // Present lawful terminal once to real io (dummy was used inside dispatch)
-        options.io.stdout(formatTerminalResult(terminal));
+        (terminal as { autoResumeCount?: number }).autoResumeCount = autoResumeAttempts;
       }
-      return result;
-    }
 
-    if (autoResumeAttempts >= limit) {
-      if (terminal !== undefined) presentTerminal(terminal, options.io);
-      return result;
-    }
-    if (!(await isSessionPrincipalAvailable(options.admitted.sessionFile))) {
-      if (terminal !== undefined) presentTerminal(terminal, options.io);
-      return result;
+      const lawful = terminal !== undefined && isLawfulTypedTerminalOutcome(terminal.roleOutcome);
+      if (lawful) {
+        if (terminal !== undefined) {
+          // Present lawful terminal once to real io (dummy was used inside dispatch)
+          options.io.stdout(formatTerminalResult(terminal));
+        }
+        return result;
+      }
+
+      if (autoResumeAttempts >= limit) {
+        if (terminal !== undefined) presentTerminal(terminal, options.io);
+        return result;
+      }
+      if (!(await isSessionPrincipalAvailable(options.admitted.sessionFile))) {
+        if (terminal !== undefined) presentTerminal(terminal, options.io);
+        return result;
+      }
+    } 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,
+        });
+        await finalizeExceptionRunBestEffort(options.admitted.runDirectory, options.io);
+        presentTerminal(terminal, options.io);
+        return {
+          exitCode: 1,
+          terminal,
+        } as T;
+      }
+      if (!(await isSessionPrincipalAvailable(options.admitted.sessionFile))) {
+        const terminal = dispatchExceptionFailureTerminal({
+          role: options.admitted.role,
+          runId: options.admitted.runId,
+          causeError: lastThrownError,
+          errorFiles: retainedErrorFiles,
+          autoResumeAttempts,
+          endReason: "session principal unavailable before further resume",
+          everyAttemptThrew,
+        });
+        await finalizeExceptionRunBestEffort(options.admitted.runDirectory, options.io);
+        presentTerminal(terminal, options.io);
+        return {
+          exitCode: 1,
+          terminal,
+        } as T;
+      }
     }
 
     autoResumeAttempts++;

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

@@ -347,7 +347,7 @@ export type RunWriterLease = {
  * True error identity for diagnostics — name/code/message as-is, never a
  * guessed label (failure-honesty constitution).
  */
-function describeErrorIdentity(error: unknown): string {
+export function describeErrorIdentity(error: unknown): string {
   const candidate = error as { name?: unknown; code?: unknown; message?: unknown };
   const name =
     typeof candidate?.name === "string" && candidate.name !== ""