@akagilnc/pi-workflow-roles 0.1.3902 → 0.1.3936

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

@@ -25,6 +25,7 @@ import {
   AUTO_RESUME_LIMIT,
   describeErrorIdentity,
   acquireRunWriterLease,
+  markRunResumable,
   markRunTerminal,
   RunWriterLeaseHeldError,
   type RunWriterLease,
@@ -34,12 +35,42 @@ import { isLawfulTypedTerminalOutcome, formatTerminalResult, type TerminalArtifa
 import {
   presentFailureTerminal,
   presentStructuralRejection,
+  resolveControlledFailureResumeObservation,
   type SealedAcceptanceRedispatchDisposition,
 } from "./settlement.ts";
 import type { CliIo } from "./cli-io.ts";
 
 const dummyIo: CliIo = { stdout: () => {}, stderr: () => {} };
 
+/**
+ * Persist run-state after a host-turn result, outside the retried dispatch try.
+ * Lawful settlement always seals terminal — a typed 429 observation must not
+ * win (#416 成功即停). 429 only marks resumable on the controlled-failure path.
+ * Write failure must escape the retried dispatch try instead of becoming a
+ * synthetic host-turn terminal.
+ */
+export async function persistReturnedRunState(
+  admitted: { runDirectory: string; principal?: DurablePrincipal },
+  authority: Pick<DurablePrincipalAuthority, "isAvailable">,
+  options?: { readonly lawful?: boolean },
+): Promise<void> {
+  if (options?.lawful === true) {
+    await markRunTerminal(admitted.runDirectory);
+    return;
+  }
+  const resumeObservation = await resolveControlledFailureResumeObservation({
+    runDirectory: admitted.runDirectory,
+  });
+  const typedHttp429 = resumeObservation.typedHttp429;
+  if (admitted.principal !== undefined && typedHttp429 !== undefined) {
+    if (await authority.isAvailable(admitted.principal)) {
+      await markRunResumable(admitted.runDirectory, typedHttp429);
+      return;
+    }
+  }
+  await markRunTerminal(admitted.runDirectory);
+}
+
 function presentTerminal(terminal: TerminalResult, io: CliIo): void {
   if (terminal.roleOutcome.kind === "failure" || terminal.roleOutcome.kind === "no_receipt") {
     presentFailureTerminal(terminal, io);
@@ -67,8 +98,48 @@ async function finalizeExceptionRunBestEffort(runDirectory: string, io: CliIo):
 export type AutoResumeDispatchResult = {
   exitCode: number;
   terminal?: TerminalResult;
+  /**
+   * Pre-turn settlement under the writer lease (station child exhausted).
+   * Loop presents this result and must not redispatch (#840 父子不层叠).
+   */
+  skipAutoResume?: true;
+  /**
+   * Host turn actually started. Absent on beforeDispatch / pre-turn settlement
+   * so the loop retries the initial payload instead of a session resume.
+   */
+  turnDispatched?: true;
+  /**
+   * Dispatch skipped run-state persist so this loop seam owns it.
+   * Absent when dispatch already persisted or never produced a terminal.
+   */
+  needsPersist?: true;
 };
 
+/**
+ * Thrown by dispatchPostAdmissionTurn when a failure happens inside its own
+ * settlement authority (presentControlledFailure) after the host turn
+ * genuinely started — never to fabricate a replacement terminal (ADR 0080
+ * single-settlement-disposition: settlement stays exactly presentControlledFailure
+ * / settleFailureTerminalResult, or — once the retry budget is exhausted —
+ * this loop's own dispatchExceptionFailureTerminal). Its only job is to carry
+ * the "turn already started" fact across the throw boundary so this loop
+ * selects a resume payload on the next attempt instead of replaying the
+ * initial one (#840 r9 判词 class 1 boundary — 覆盖 executeTurn 已启动后至
+ * 返回带 turnDispatched 结果前的全部异常). `cause` is the true failure;
+ * retention below serializes it whole via the standard Error.cause chain.
+ */
+export class TurnDispatchedFailure extends Error {
+  override readonly name = "TurnDispatchedFailure";
+  constructor(cause: unknown) {
+    super(
+      `settlement failed after the host turn genuinely started: ${
+        cause instanceof Error ? cause.message : String(cause)
+      }`,
+      { cause },
+    );
+  }
+}
+
 /** 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;
 
@@ -80,27 +151,30 @@ function runArtifactsDirectory(runDirectory: string): string {
 /**
  * #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
+ * artifacts path must not receive a durable run artifact (O_NOFOLLOW only
  * protects the final file name; recursive mkdir would accept a symlinked
- * parent). Fails loudly with the true cause instead.
+ * parent). Fails loudly with the true cause instead. Shared by every caller
+ * that needs a durable run-artifacts write independent of session/dossier
+ * health — dispatch-error retention here, and post-admission's best-effort
+ * cleanup diagnostic (#840 bounce class 2).
  */
-async function ensureRealArtifactsDirectory(runDirectory: string): Promise<string> {
+export 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");
+    throw new Error("run artifact 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");
+      throw new Error("run artifact 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");
+      throw new Error("run artifact retention: artifacts directory is not a real directory");
     }
   }
   return artifactsDir;
@@ -268,6 +342,23 @@ async function retainDispatchError(
   return pointerError === undefined ? { file: filePath } : { file: filePath, pointerError };
 }
 
+/**
+ * Unwrap TurnDispatchedFailure before this loop's own final presentation
+ * (#840 r9 判词 class 1 — the auto-resume.ts final presentation boundary).
+ * The wrapper only carries the "turn already genuinely started" signal
+ * across the throw boundary so the loop above selects a resume payload; the
+ * typed decisiveFacts and diagnostic text below must name the real cause it
+ * wraps (接住可以，洗白不行 — 未识别异常不得冒用具体标签，真因必须落痕), not
+ * the internal signal's own identity.
+ */
+function unwrapTurnDispatchedFailure(error: unknown): unknown {
+  let current = error;
+  while (current instanceof TurnDispatchedFailure) {
+    current = current.cause;
+  }
+  return current;
+}
+
 /**
  * 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
@@ -283,12 +374,13 @@ function dispatchExceptionFailureTerminal(input: {
   /** True only when every attempt threw; otherwise describe just the final attempt. */
   everyAttemptThrew: boolean;
 }): TerminalResult {
+  const causeError = unwrapTurnDispatchedFailure(input.causeError);
   // #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 diagnostic = `${history} (${input.endReason}; resumes used ${input.autoResumeAttempts}); last cause: ${describeErrorIdentity(causeError)}`;
   const decisiveFacts: Record<string, unknown> = {
     cause: "unrecognized",
     diagnostic,
@@ -298,7 +390,7 @@ function dispatchExceptionFailureTerminal(input: {
   if (input.errorFiles.length > 0) {
     decisiveFacts.lastDispatchErrorFile = input.errorFiles[input.errorFiles.length - 1];
   }
-  const candidate = input.causeError as { name?: unknown; code?: unknown };
+  const candidate = 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;
@@ -334,6 +426,16 @@ export async function runWithAutoResumeLoop<
     principal: DurablePrincipal;
   };
   principalAuthority: DurablePrincipalAuthority;
+  /**
+   * Host-aware "can this principal's turn still be resumed" probe (#840 P1).
+   * Callers that know the selected host pass
+   * session-identity.ts's resolveHostAwareSessionAvailability(host,
+   * principalAuthority) so an ACP/headless turn's own binding file — not
+   * pi's session.jsonl — decides continuation for that host. Defaults to
+   * principalAuthority.isAvailable (pi-only check) when omitted, so a
+   * caller that never leaves the pi host keeps identical behavior.
+   */
+  isPrincipalAvailable?: (principal: DurablePrincipal) => Promise<boolean>;
   io: CliIo;
   sessionAppender: SessionCustomEntryAppender;
   /**
@@ -358,6 +460,9 @@ export async function runWithAutoResumeLoop<
   // `attempts >= limit` comparison (always false) — reject here, before any dispatch.
   const limit = options.autoResumeLimit ?? AUTO_RESUME_LIMIT;
   parseAutoResumeLimit(limit);
+  const isPrincipalAvailable =
+    options.isPrincipalAvailable ??
+    ((principal: DurablePrincipal) => options.principalAuthority.isAvailable(principal));
   let autoResumeAttempts = 0;
   let isFirst = true;
   let currentPayload = options.buildInitialPayload();
@@ -381,6 +486,11 @@ export async function runWithAutoResumeLoop<
     }
 
     let result: T | undefined;
+    // Set only when the caught throw is a TurnDispatchedFailure (#840 r9 判词
+    // class 1): the host turn genuinely started this attempt even though
+    // dispatch produced no result — the next payload must still be a resume,
+    // not a replay of the initial one.
+    let turnStartedBeforeThrow = false;
     try {
       result = await options.dispatch(currentPayload, lease, isFirst, dummyIo);
     } catch (error) {
@@ -390,6 +500,7 @@ export async function runWithAutoResumeLoop<
       // diagnostic-sink-isolation precedent). The dispatcher owns lease release
       // in its own finally, so the retry round starts with the lock free.
       lastThrownError = error;
+      turnStartedBeforeThrow = error instanceof TurnDispatchedFailure;
       const attempt = dispatchOrdinal;
       try {
         // Track the file as soon as it is durably written (#426 review):
@@ -419,6 +530,7 @@ export async function runWithAutoResumeLoop<
     }
     dispatchOrdinal += 1;
 
+    let persistFailure: { readonly error: unknown } | undefined;
     if (result !== undefined) {
       everyAttemptThrew = false;
       const terminal = (result as { terminal?: TerminalResult }).terminal;
@@ -427,6 +539,23 @@ export async function runWithAutoResumeLoop<
       }
 
       const lawful = terminal !== undefined && isLawfulTypedTerminalOutcome(terminal.roleOutcome);
+      if (result.needsPersist === true) {
+        // Persist on the loop seam, not inside retried dispatch.
+        try {
+          await persistReturnedRunState(
+            options.admitted,
+            { isAvailable: isPrincipalAvailable },
+            lawful ? { lawful: true } : undefined,
+          );
+        } catch (persistError) {
+          // Lawful persist stays loud (no fake terminal). Non-lawful persist is
+          // not a host-turn failure — do not auto-resume it — but sealed stop
+          // must still see the already-settled result (#648).
+          if (lawful) throw persistError;
+          persistFailure = { error: persistError };
+          lastThrownError = persistError;
+        }
+      }
       if (lawful) {
         if (terminal !== undefined) {
           // Present lawful terminal once to real io (dummy was used inside dispatch)
@@ -434,6 +563,10 @@ export async function runWithAutoResumeLoop<
         }
         return result;
       }
+      if (result.skipAutoResume === true) {
+        if (terminal !== undefined) presentTerminal(terminal, options.io);
+        return result;
+      }
     }
 
     // Settlement-owned sealed disposition before any redispatch (#648 / #672):
@@ -471,13 +604,20 @@ export async function runWithAutoResumeLoop<
       }
     }
 
+    if (persistFailure !== undefined) {
+      throw persistFailure.error;
+    }
+
     if (result !== undefined) {
       const terminal = (result as { terminal?: TerminalResult }).terminal;
       if (autoResumeAttempts >= limit) {
         if (terminal !== undefined) presentTerminal(terminal, options.io);
         return result;
       }
-      if (!(await options.principalAuthority.isAvailable(options.admitted.principal))) {
+      if (
+        result.turnDispatched === true
+        && !(await isPrincipalAvailable(options.admitted.principal))
+      ) {
         if (terminal !== undefined) presentTerminal(terminal, options.io);
         return result;
       }
@@ -500,7 +640,7 @@ export async function runWithAutoResumeLoop<
           terminal,
         } as T;
       }
-      if (!(await options.principalAuthority.isAvailable(options.admitted.principal))) {
+      if (!(await isPrincipalAvailable(options.admitted.principal))) {
         const terminal = dispatchExceptionFailureTerminal({
           role: options.admitted.role,
           runId: options.admitted.runId,
@@ -520,7 +660,13 @@ export async function runWithAutoResumeLoop<
     }
 
     autoResumeAttempts++;
-    currentPayload = options.buildResumePayload();
+    // Resume payload only after a host turn actually started — either a
+    // returned result says so, or the attempt threw a TurnDispatchedFailure
+    // after genuinely starting the turn (#840 r9 判词 class 1). Pre-turn
+    // throws and beforeDispatch failures retry the initial payload (#840 / #416).
+    if (result?.turnDispatched === true || turnStartedBeforeThrow) {
+      currentPayload = options.buildResumePayload();
+    }
     isFirst = false;
   }
 }

package/src/public-cli/cli.ts

@@ -44,14 +44,16 @@ import { CliUsageError } from "./cli-errors.ts";
 import type { CliIo } from "./cli-io.ts";
 import type { PostAdmissionEnv } from "./post-admission.ts";
 import type { RoleTurnHost } from "../host-contracts.ts";
-import { packagedExternalHostNames } from "../host-descriptions.ts";
-import { createLazyProductionExternalHost } from "./load-production-external-host.ts";
+import { appendPiSessionCustomEntry } from "../pi/role-turn-host.ts";
 import {
-  createPiRoleTurnHost,
-  appendPiSessionCustomEntry,
-} from "../pi/role-turn-host.ts";
+  composeRoleTurnHostAdapters,
+  formatHostSelectionFailure,
+  HostSelectionError,
+  selectRoleTurnHost,
+  type HostSelectionFailure,
+  type NamedRoleTurnHostAdapter,
+} from "./role-turn-host-resolution.ts";
 import {
-  observeLaunchedRolePackageIdentity,
   parseAnalystArgv,
   parseCoderArgv,
   parseCollectorArgv,
@@ -68,8 +70,6 @@ import {
   parseAuditorArgv,
   parseNotaryArgv,
   parseReviewerArgv,
-  recordLaunchedPiIdentity,
-  recordLaunchedRolePackageIdentity,
 } from "./invocation.ts";
 import {
   createTypedOptionConsumer,
@@ -237,24 +237,7 @@ function takePublicGlobalFlag(
   return undefined;
 }
 
-export type HostSelectionFailure = {
-  readonly kind: "host-unregistered" | "host-model-mismatch";
-  readonly host: string;
-  readonly seat: PublicCallableRole;
-  readonly model: string;
-  readonly registeredHosts: readonly string[];
-};
-
-export type NamedRoleTurnHostAdapter = {
-  readonly name: string;
-  readonly create: (input: { role: PublicCallableRole; model: EffectiveSeat["selection"] }) =>
-    | { readonly ok: true; readonly host: RoleTurnHost }
-    | { readonly ok: false };
-};
-
-class HostSelectionError extends Error {
-  constructor(readonly failure: HostSelectionFailure) { super(failure.kind); }
-}
+export type { HostSelectionFailure, NamedRoleTurnHostAdapter };
 
 export type CliEnv = {
   home?: string;
@@ -315,59 +298,7 @@ export type CliEnv = {
   freshSummons?: true;
 };
 
-/** Compose the Pi turn host for one role dispatch (sole public-cli → pi contact). */
-function resolveRoleTurnHost(
-  env: CliEnv,
-  options: {
-    role: PublicCallableRole;
-    seat: EffectiveSeat;
-    principalAuthority: DurablePrincipalAuthority;
-    extraPiArgs?: readonly string[];
-    timeoutMs?: number;
-  },
-): RoleTurnHost {
-  const piHost = env.roleTurnHost ?? createPiRoleTurnHost({
-    packageRoot: env.packageRoot,
-    principalAuthority: options.principalAuthority,
-    ...(options.extraPiArgs === undefined ? {} : { extraPiArgs: options.extraPiArgs }),
-    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
-    recordLaunchedPiIdentity,
-    recordLaunchedRolePackageIdentity,
-    observeLaunchedRolePackageIdentity,
-  });
-  // Composition-root adapter table: pi (in-process default) + one lazy external host per description-table key (#820).
-  const adapters: readonly NamedRoleTurnHostAdapter[] = env.hostAdapters ?? [
-    { name: "pi", create: () => ({ ok: true as const, host: piHost }) },
-    ...packagedExternalHostNames().map((name) => ({
-      name,
-      create: () => ({
-        ok: true as const,
-        // Factory loads outside the public bin static graph (ADR 0052 peer-free discovery).
-        host: createLazyProductionExternalHost({
-          packageRoot: env.packageRoot,
-          hostName: name,
-          principalAuthority: options.principalAuthority,
-        }),
-      }),
-    })),
-  ];
-  const hostName = options.seat.host;
-  const adapter = adapters.find((candidate) => candidate.name === hostName);
-  const model = options.seat.selection === undefined ? "unconfigured" : `${options.seat.selection.provider}/${options.seat.selection.model}`;
-  const registeredHosts = adapters.map(({ name }) => name);
-  if (adapter === undefined) {
-    throw new HostSelectionError(
-      { kind: "host-unregistered", host: hostName, seat: options.role, model, registeredHosts },
-    );
-  }
-  const selected = adapter.create({ role: options.role, model: options.seat.selection });
-  if (!selected.ok) {
-    throw new HostSelectionError(
-      { kind: "host-model-mismatch", host: hostName, seat: options.role, model, registeredHosts },
-    );
-  }
-  return selected.host;
-}
+
 
 type RoleEnvironmentOptions = {
   role: PublicCallableRole;
@@ -426,12 +357,21 @@ function createRoleEnvironment(
   // #788 expectation 2: select a registered host first; only then project the
   // host-facing provider (table > unique directory > fail). Bad host never
   // reaches model resolution.
-  const roleTurnHost = resolveRoleTurnHost(env, {
+  // Nested summons reuse this table and select by the child seat — never the
+  // already-selected parent adapter (#840 / ADR 0082 host-flag-two-channels).
+  const hostAdapters = composeRoleTurnHostAdapters(
+    {
+      packageRoot: env.packageRoot,
+      ...(env.roleTurnHost === undefined ? {} : { roleTurnHost: env.roleTurnHost }),
+      ...(env.hostAdapters === undefined ? {} : { hostAdapters: env.hostAdapters }),
+      ...(extraPiArgs === undefined ? {} : { extraPiArgs }),
+      ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    },
+    env.principalAuthority!,
+  );
+  const roleTurnHost = selectRoleTurnHost(hostAdapters, {
     role,
     seat: options.seat,
-    principalAuthority: env.principalAuthority!,
-    ...(extraPiArgs === undefined ? {} : { extraPiArgs }),
-    ...(timeoutMs === undefined ? {} : { timeoutMs }),
   });
   const hostFacingSelection =
     options.seat.selection === undefined
@@ -449,6 +389,7 @@ function createRoleEnvironment(
     sessionAppender: appendPiSessionCustomEntry,
     packageRoot: env.packageRoot,
     roleTurnHost,
+    hostAdapters,
     cwd: options.cwd,
     ...(options.credentials === undefined ? {} : { credentials: options.credentials }),
     ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
@@ -1606,8 +1547,7 @@ export async function runAkRole(
     throw new CliUsageError(`unknown command: ${parsed.command}`);
   } catch (error) {
     if (error instanceof HostSelectionError) {
-      const registered = error.failure.registeredHosts.join(", ");
-      io.stderr(formatCliDiagnostic(`${error.failure.kind}: ${error.failure.host}; registered: ${registered}`));
+      io.stderr(formatCliDiagnostic(formatHostSelectionFailure(error.failure)));
       return { exitCode: 1, hostFailure: error.failure };
     }
     if (error instanceof CliUsageError) {

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

@@ -29,7 +29,6 @@ import {
   admitCountersignInvocation,
   bindAdmittedTicketNumber,
   buildCountersignTransportPrompt,
-  parseDiaristArgv,
   type AdmittedCountersignInvocation,
   type ParseCountersignArgvResult,
 } from "./invocation.ts";
@@ -40,6 +39,7 @@ import {
   type PostAdmissionEnv,
   runPostAdmissionSeatResume,
   resumeTurnRequestProjectionOptions,
+  StationChildExhaustedError,
 } from "./post-admission.ts";
 import {
   loadResumableCountersignRun,
@@ -125,32 +125,24 @@ async function invokeCourtDiarist(input: {
     },
   };
 
-  const { runPublicDiarist } = await import("./diarist-run.ts");
-  const result = await runPublicDiarist(
-    ["--project", input.projectRoot, input.instruction],
-    {
-      home: env.home,
-      agentDir: env.agentDir,
-      packageRoot: env.packageRoot,
-      cwd: env.cwd,
-      principalAuthority: env.principalAuthority,
-      roleTurnHost: env.roleTurnHost,
-      sessionAppender: env.sessionAppender,
-      ...(env.model === undefined ? {} : { model: env.model }),
-      ...(env.engine === undefined ? {} : { engine: env.engine }),
-      ...(env.host === undefined ? {} : { host: env.host }),
-      ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
-      ...(env.credentials === undefined ? {} : { credentials: env.credentials }),
-      ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
-      ...(env.signal === undefined ? {} : { signal: env.signal }),
-      // Typed handoff only — never derived from summons prose.
-      ...(input.boundTicketNumber === undefined
-        ? {}
-        : { boundTicketNumber: input.boundTicketNumber }),
-    },
-    quietIo,
-    parseDiaristArgv,
-  );
+  const { summonPublicRole } = await import("../public-role-summons.ts");
+  const result = await summonPublicRole({
+    role: "diarist",
+    argv: ["--project", input.projectRoot, input.instruction],
+    cwd: env.cwd,
+    home: env.home,
+    agentDir: env.agentDir,
+    packageRoot: env.packageRoot,
+    io: quietIo,
+    ...(env.credentials === undefined ? {} : { credentials: env.credentials }),
+    ...(env.signal === undefined ? {} : { signal: env.signal }),
+    ...(input.boundTicketNumber === undefined
+      ? {}
+      : { boundTicketNumber: input.boundTicketNumber }),
+    // Child seat selects from the composition-root table. Do not pass the
+    // already-selected parent adapter (#840 / ADR 0082 host-flag-two-channels).
+    ...(env.hostAdapters === undefined ? {} : { hostAdapters: env.hostAdapters }),
+  });
 
   const roleOutcome = result.terminal?.roleOutcome;
   // Discriminated union: only non-failure arms carry status (failure uses cause).
@@ -168,7 +160,7 @@ async function invokeCourtDiarist(input: {
     const diagnostic =
       roleOutcome?.kind === "failure"
         ? roleOutcome.diagnostic
-        : `exit ${result.exitCode}`;
+        : result.stderr?.trim() || `exit ${result.exitCode}`;
     return {
       identity: { kind: "unbound" },
       failedWithoutEscalate: {
@@ -177,7 +169,7 @@ async function invokeCourtDiarist(input: {
     };
   }
 
-  const asserted = result.admitted?.ticketNumber;
+  const asserted = (result.admitted as { ticketNumber?: number } | undefined)?.ticketNumber;
   if (
     typeof asserted === "number" &&
     Number.isSafeInteger(asserted) &&
@@ -225,12 +217,12 @@ export async function runCountersignCourtDiaristStation(
   );
 
   if (outcome.identity.kind === "escalate") {
-    throw new Error(
+    throw new StationChildExhaustedError(
       `court diarist station escalated (cannot identify court target): ${outcome.identity.reason}`,
     );
   }
   if (outcome.failedWithoutEscalate !== undefined) {
-    throw new Error(outcome.failedWithoutEscalate.diagnostic);
+    throw new StationChildExhaustedError(outcome.failedWithoutEscalate.diagnostic);
   }
 }
 
@@ -282,8 +274,9 @@ export async function runPublicCountersign(
   // (never mechanical matching of summons text). Resolve that typed key after
   // admit so the countersign run page exists first; same-ticket re-summons
   // resume the prior run on the typed key (unused mint is abandoned). The test
-  // seam `runCourtDiaristStation` defers identity to beforeDispatch and
-  // therefore skips auto-resume under the seam alone.
+  // seam `runCourtDiaristStation` defers identity to beforeDispatch; generic
+  // hook failures stay on the parent call-local budget, exhausted nested
+  // station children still skip parent auto-resume (#840 父子不层叠).
   let typedTicket: number | undefined;
   let identityDiaristRan = false;
 

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

@@ -1141,7 +1141,7 @@ export type PublicCommandHelpFacts = {
  * the role list like every other role).
  */
 export const PUBLIC_NAVIGATOR_HELP_NOTE =
-  "Navigator also attends automatically on every run; that sidecar is unchanged by direct `ak-role navigator` calls." as const;
+  "Navigator also attends automatically on top-level public entry legs; that sidecar is unchanged by direct `ak-role navigator` calls." as const;
 
 const TOP_LEVEL_HELP = {
   command: "top",