@akagilnc/pi-workflow-roles 0.1.2157 → 0.1.2173

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

@@ -1,15 +1,26 @@
 /**
  * Single generic auto-resume loop for #416 (owner scope = single LLM call).
- * Call-local retries, at most AUTO_RESUME_LIMIT times, in-place (same runId/session).
+ * Call-local retries, at most the effective autoResumeLimit times (injected once
+ * 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.
  */
 import { AUTO_RESUME_LIMIT, isSessionPrincipalAvailable, acquireRunWriterLease, RunWriterLeaseHeldError, type RunWriterLease } from "./run-lifecycle.ts";
+import { parseAutoResumeLimit } from "./config.ts";
 import { isLawfulTypedTerminalOutcome, formatTerminalResult, type TerminalResult } from "./terminal.ts";
 import { presentFailureTerminal, presentStructuralRejection } from "./settlement.ts";
 import type { CliIo } from "./cli-io.ts";
 
 const dummyIo: CliIo = { stdout: () => {}, stderr: () => {} };
 
+function presentTerminal(terminal: TerminalResult, io: CliIo): void {
+  if (terminal.roleOutcome.kind === "failure" || terminal.roleOutcome.kind === "no_receipt") {
+    presentFailureTerminal(terminal, io);
+  } else {
+    io.stdout(formatTerminalResult(terminal));
+  }
+}
+
 export type AutoResumeDispatchResult = {
   exitCode: number;
   terminal?: TerminalResult;
@@ -18,10 +29,21 @@ export type AutoResumeDispatchResult = {
 export async function runWithAutoResumeLoop<T extends AutoResumeDispatchResult>(options: {
   admitted: { sessionFile: string; runDirectory: string };
   io: CliIo;
+  /**
+   * Effective ceiling (#422), resolved by the caller before the loop; never re-read
+   * per round. undefined = package default (AUTO_RESUME_LIMIT). Domain-validated at
+   * this single entry point (#422): NaN/negative/fractional/Infinity reject loudly
+   * before the first dispatch instead of silently bypassing the ceiling comparison.
+   */
+  autoResumeLimit?: number | undefined;
   buildInitialArgs: () => string[];
   buildResumeArgs: () => string[];
   dispatch: (extraArgs: string[], lease: RunWriterLease, isFirst: boolean, attemptIo: CliIo) => Promise<T>;
 }): Promise<T> {
+  // #422 single-point resolution + domain validation. NaN would bypass every
+  // `attempts >= limit` comparison (always false) — reject here, before any dispatch.
+  const limit = options.autoResumeLimit ?? AUTO_RESUME_LIMIT;
+  parseAutoResumeLimit(limit);
   let autoResumeAttempts = 0;
   let isFirst = true;
   let currentExtraArgs = options.buildInitialArgs();
@@ -29,7 +51,9 @@ export async function runWithAutoResumeLoop<T extends AutoResumeDispatchResult>(
   while (true) {
     let lease: RunWriterLease;
     try {
-      lease = await acquireRunWriterLease(options.admitted.runDirectory);
+      lease = await acquireRunWriterLease(options.admitted.runDirectory, (diagnostic) =>
+        options.io.stderr(diagnostic),
+      );
     } catch (error) {
       if (error instanceof RunWriterLeaseHeldError) {
         presentStructuralRejection(error, options.io);
@@ -54,42 +78,12 @@ export async function runWithAutoResumeLoop<T extends AutoResumeDispatchResult>(
       return result;
     }
 
-    // Deterministic incomplete/audit_incomplete (merger/collector/judge) would duplicate callId bindings on retry and lose settlement
-    if (terminal !== undefined && (terminal.roleOutcome.kind === "incomplete" || terminal.roleOutcome.kind === "audit_incomplete")) {
-      if (terminal.roleOutcome.kind === "audit_incomplete") {
-        options.io.stdout(formatTerminalResult(terminal));
-      } else {
-        options.io.stdout(formatTerminalResult(terminal));
-      }
-      return result;
-    }
-    // Rich auditor retention detail would be lost on retry (stale child binding)
-    if (terminal !== undefined && terminal.roleOutcome.kind === "failure") {
-      const terminalJson = JSON.stringify(terminal);
-      if (terminalJson.includes("retentionFailure") || terminalJson.includes("ComplianceResponseRetentionError")) {
-        presentFailureTerminal(terminal, options.io);
-        return result;
-      }
-    }
-
-    if (autoResumeAttempts >= AUTO_RESUME_LIMIT) {
-      if (terminal !== undefined) {
-        if (terminal.roleOutcome.kind === "failure" || terminal.roleOutcome.kind === "no_receipt") {
-          presentFailureTerminal(terminal, options.io);
-        } else {
-          options.io.stdout(formatTerminalResult(terminal));
-        }
-      }
+    if (autoResumeAttempts >= limit) {
+      if (terminal !== undefined) presentTerminal(terminal, options.io);
       return result;
     }
     if (!(await isSessionPrincipalAvailable(options.admitted.sessionFile))) {
-      if (terminal !== undefined) {
-        if (terminal.roleOutcome.kind === "failure" || terminal.roleOutcome.kind === "no_receipt") {
-          presentFailureTerminal(terminal, options.io);
-        } else {
-          options.io.stdout(formatTerminalResult(terminal));
-        }
-      }
+      if (terminal !== undefined) presentTerminal(terminal, options.io);
       return result;
     }
 

package/src/public-cli/cli.ts

@@ -17,6 +17,7 @@ import {
   parseModelSpec,
   resolveEffectiveSeat,
   savePublicCliConfig,
+  setAutoResumeLimit,
   setPersistentSeatConfig,
   setPersistentSeatEngine,
   validatePublicCliConfigEngines,
@@ -58,7 +59,7 @@ import { runPublicJudge, runPublicResume } from "./judge-run.ts";
 import { runPublicMerger, runPublicMergerResume } from "./merger-run.ts";
 import { runPublicReviewer, runPublicReviewerResume } from "./reviewer-run.ts";
 import { runPublicTaishi } from "./taishi-run.ts";
-import { peekRoleRunRole } from "./run-lifecycle.ts";
+import { AUTO_RESUME_LIMIT, peekRoleRunRole } from "./run-lifecycle.ts";
 import {
   AUTOMATIC_NAVIGATOR_SEAT,
   INTERNAL_ROLE_ENTRYPOINT_RELATIVE,
@@ -527,6 +528,8 @@ function renderConfig(config: PublicCliConfig): string {
       lines.push(`${seat}\t${formatModelSpec(selection)}\t${engine}`);
     }
   }
+  // #422: show the effective auto-resume ceiling (configured value or default).
+  lines.push(`autoResumeLimit\t${config.autoResumeLimit ?? AUTO_RESUME_LIMIT}`);
   return `${lines.join("\n")}\n`;
 }
 
@@ -631,6 +634,39 @@ async function runConfigCommand(
     return 0;
   }
 
+  // #422: standalone verb per the set-engine/unset-engine precedent — the
+  // existing `config set` grammar stays strictly even-position seat/spec pairs.
+  if (args[0] === "set-auto-resume-limit") {
+    if (args.length !== 2) {
+      throw new CliUsageError(
+        "usage: ak-role config set-auto-resume-limit <N>",
+      );
+    }
+    const raw = args[1]!;
+    if (!/^[0-9]+$/.test(raw)) {
+      throw new CliUsageError(
+        `auto-resume limit must be a non-negative integer, got ${raw}`,
+      );
+    }
+    // #422 fidelity boundary (not an upper bound — ADR 0035 stays intact): the
+    // persisted representation is a JS number, and Number() silently rounds
+    // integers beyond 2^53-1 (e.g. 9007199254740993 → 9007199254740992). Refuse
+    // loudly instead of persisting a different N; every exactly-representable
+    // non-negative integer remains legal. The regex above guarantees pure
+    // digits, so BigInt(raw) has no leading-zero ambiguity.
+    const converted = Number(raw);
+    if (!Number.isFinite(converted) || BigInt(converted) !== BigInt(raw)) {
+      throw new CliUsageError(
+        `auto-resume limit ${raw} is not exactly representable as a number; refusing to silently round the value`,
+      );
+    }
+    let config = await loadAndValidateConfig(home, packageRoot);
+    config = setAutoResumeLimit(config, converted);
+    await savePublicCliConfig(config, home);
+    io.stdout(renderConfig(config));
+    return 0;
+  }
+
   throw new CliUsageError(`unknown config subcommand: ${args[0]}`);
 }
 
@@ -922,6 +958,10 @@ export async function runAkRole(
             ? {}
             : { timeoutMs: env.judgeTimeoutMs }),
           ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+          // #422: effective auto-resume ceiling resolved once here; the loop never re-reads disk.
+          ...(config.autoResumeLimit === undefined
+            ? {}
+            : { autoResumeLimit: config.autoResumeLimit }),
         },
         io,
         PUBLIC_ROLE_ARGV.judge.parse,
@@ -966,6 +1006,10 @@ export async function runAkRole(
             ? {}
             : { timeoutMs: env.coderTimeoutMs }),
           ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+          // #422: effective auto-resume ceiling resolved once here; the loop never re-reads disk.
+          ...(config.autoResumeLimit === undefined
+            ? {}
+            : { autoResumeLimit: config.autoResumeLimit }),
         },
         io,
         PUBLIC_ROLE_ARGV.coder.parse,
@@ -1010,6 +1054,10 @@ export async function runAkRole(
             ? {}
             : { timeoutMs: env.fixerTimeoutMs }),
           ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+          // #422: effective auto-resume ceiling resolved once here; the loop never re-reads disk.
+          ...(config.autoResumeLimit === undefined
+            ? {}
+            : { autoResumeLimit: config.autoResumeLimit }),
         },
         io,
         PUBLIC_ROLE_ARGV.fixer.parse,
@@ -1098,6 +1146,10 @@ export async function runAkRole(
             ? {}
             : { timeoutMs: env.reviewerTimeoutMs }),
           ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+          // #422: effective auto-resume ceiling resolved once here; the loop never re-reads disk.
+          ...(config.autoResumeLimit === undefined
+            ? {}
+            : { autoResumeLimit: config.autoResumeLimit }),
         },
         io,
         PUBLIC_ROLE_ARGV.reviewer.parse,
@@ -1186,6 +1238,10 @@ export async function runAkRole(
             ? {}
             : { timeoutMs: env.mergerTimeoutMs }),
           ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+          // #422: effective auto-resume ceiling resolved once here; the loop never re-reads disk.
+          ...(config.autoResumeLimit === undefined
+            ? {}
+            : { autoResumeLimit: config.autoResumeLimit }),
         },
         io,
         PUBLIC_ROLE_ARGV.merger.parse,

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

@@ -86,6 +86,8 @@ export type CoderRunEnv = {
   engine?: string;
   credentials?: CredentialProviders;
   createRunId?: () => string;
+  /** #422: effective single-call auto-resume ceiling; undefined = package default (AUTO_RESUME_LIMIT). */
+  autoResumeLimit?: number;
   extraPiArgs?: readonly string[];
   timeoutMs?: number;
 };
@@ -475,6 +477,8 @@ export async function runPublicCoder(
   return runWithAutoResumeLoop({
     admitted,
     io,
+    // #422: pass-through only; the loop entry resolves the default and validates the domain once.
+    autoResumeLimit: env.autoResumeLimit,
     buildInitialArgs: () =>
       buildCoderActivationExtraArgs(admitted, {
         packageRoot: env.packageRoot,
@@ -548,7 +552,7 @@ export async function runPublicCoderResume(
 
   let lease: RunWriterLease;
   try {
-    lease = await acquireRunWriterLease(admitted.runDirectory);
+    lease = await acquireRunWriterLease(admitted.runDirectory, (diagnostic) => io.stderr(diagnostic));
   } catch (error) {
     if (error instanceof RunWriterLeaseHeldError) {
       // Concurrent resume: reject without second writer or dispatch.

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

@@ -355,7 +355,7 @@ export async function runPublicCollector(
 
   let lease: RunWriterLease;
   try {
-    lease = await acquireRunWriterLease(admitted.runDirectory);
+    lease = await acquireRunWriterLease(admitted.runDirectory, (diagnostic) => io.stderr(diagnostic));
   } catch (error) {
     if (error instanceof RunWriterLeaseHeldError) {
       presentStructuralRejection(error, io);

package/src/public-cli/config.ts

@@ -33,6 +33,13 @@ export type PersistentSeatConfig = SeatModelConfig & {
 
 export type PublicCliConfig = {
   seats: Partial<Record<PublicConfigurableSeat, PersistentSeatConfig>>;
+  /**
+   * #422: single-call auto-resume retry ceiling, sibling of `seats`.
+   * Non-negative integer; 0 disables auto-resume (one dispatch per call).
+   * undefined = package default (AUTO_RESUME_LIMIT). No package-local upper
+   * bound (ADR 0035).
+   */
+  autoResumeLimit?: number;
 };
 
 export type EffectiveSource = "persistent" | "startup" | "invocation" | "unconfigured";
@@ -108,6 +115,9 @@ export function setPersistentSeatConfig(
 ): PublicCliConfig {
   const previous = config.seats[seat];
   return {
+    // Spread preserves sibling top-level keys such as autoResumeLimit (#422):
+    // a seat write must never silently drop them.
+    ...config,
     seats: {
       ...config.seats,
       [seat]: {
@@ -146,6 +156,7 @@ export function setPersistentSeatEngine(
   if (engine === undefined) {
     const { engine: _dropped, ...modelOnly } = previous;
     return {
+      ...config,
       seats: {
         ...config.seats,
         [seat]: modelOnly,
@@ -155,6 +166,7 @@ export function setPersistentSeatEngine(
   // Engine-name path-safety syntax is owned solely by assertLegalEngineName
   // (call-request + config-parse seams). Setter is pure seat mutation.
   return {
+    ...config,
     seats: {
       ...config.seats,
       [seat]: { ...previous, engine },
@@ -162,6 +174,32 @@ export function setPersistentSeatEngine(
   };
 }
 
+/**
+ * #422 value domain authority for the auto-resume ceiling: non-negative integer,
+ * no package-local upper bound (ADR 0035). `0` is legal and means auto-resume is
+ * disabled (a single dispatch, no in-place retry). Negative numbers, fractions,
+ * NaN, Infinity and non-number types are rejected loudly — never silently coerced.
+ */
+export function parseAutoResumeLimit(value: unknown): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `auto-resume limit must be a non-negative integer, got ${JSON.stringify(value)}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * #422: set the persistent autoResumeLimit top-level key. Pure mutation that
+ * preserves all sibling keys (seats included).
+ */
+export function setAutoResumeLimit(
+  config: PublicCliConfig,
+  limit: number,
+): PublicCliConfig {
+  return { ...config, autoResumeLimit: parseAutoResumeLimit(limit) };
+}
+
 /** Strip optional engine so activation model argv never sees the engine axis. */
 export function seatModelOnly(seat: PersistentSeatConfig): SeatModelConfig {
   return seat.thinking === undefined
@@ -261,9 +299,18 @@ function parsePublicCliConfig(value: unknown): PublicCliConfig {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     throw new Error("public CLI config must be an object");
   }
-  const record = value as { seats?: unknown };
+  const record = value as { seats?: unknown; autoResumeLimit?: unknown };
+  // #422 round-trip preservation: the sibling top-level key must survive every
+  // parse→save cycle; an unknown-key drop would silently erase it on any write.
+  let autoResumeLimit: number | undefined;
+  if (record.autoResumeLimit !== undefined) {
+    autoResumeLimit = parseAutoResumeLimit(record.autoResumeLimit);
+  }
   if (record.seats === undefined) {
-    return { seats: {} };
+    return {
+      seats: {},
+      ...(autoResumeLimit === undefined ? {} : { autoResumeLimit }),
+    };
   }
   if (
     record.seats === null ||
@@ -281,7 +328,10 @@ function parsePublicCliConfig(value: unknown): PublicCliConfig {
     }
     seats[key as PublicConfigurableSeat] = parseSeatModelConfig(raw, key);
   }
-  return { seats };
+  return {
+    seats,
+    ...(autoResumeLimit === undefined ? {} : { autoResumeLimit }),
+  };
 }
 
 function parseSeatModelConfig(value: unknown, seat: string): PersistentSeatConfig {

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

@@ -334,7 +334,7 @@ export async function runPublicDoctor(
 
   let lease: RunWriterLease;
   try {
-    lease = await acquireRunWriterLease(admitted.runDirectory);
+    lease = await acquireRunWriterLease(admitted.runDirectory, (diagnostic) => io.stderr(diagnostic));
   } catch (error) {
     if (error instanceof RunWriterLeaseHeldError) {
       presentStructuralRejection(error, io);

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

@@ -89,6 +89,8 @@ export type FixerRunEnv = {
   engine?: string;
   credentials?: CredentialProviders;
   createRunId?: () => string;
+  /** #422: effective single-call auto-resume ceiling; undefined = package default (AUTO_RESUME_LIMIT). */
+  autoResumeLimit?: number;
   extraPiArgs?: readonly string[];
   timeoutMs?: number;
 };
@@ -494,6 +496,8 @@ export async function runPublicFixer(
   return runWithAutoResumeLoop({
     admitted,
     io,
+    // #422: pass-through only; the loop entry resolves the default and validates the domain once.
+    autoResumeLimit: env.autoResumeLimit,
     buildInitialArgs: () =>
       buildFixerActivationExtraArgs(admitted, {
         packageRoot: env.packageRoot,
@@ -567,7 +571,7 @@ export async function runPublicFixerResume(
 
   let lease: RunWriterLease;
   try {
-    lease = await acquireRunWriterLease(admitted.runDirectory);
+    lease = await acquireRunWriterLease(admitted.runDirectory, (diagnostic) => io.stderr(diagnostic));
   } catch (error) {
     if (error instanceof RunWriterLeaseHeldError) {
       io.stderr(formatCliDiagnostic(error.message));

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

@@ -89,6 +89,8 @@ export type JudgeRunEnv = {
    */
   credentials?: CredentialProviders;
   createRunId?: () => string;
+  /** #422: effective single-call auto-resume ceiling; undefined = package default (AUTO_RESUME_LIMIT). */
+  autoResumeLimit?: number;
   /** Extra Pi args inserted before the prompt (tests: faux provider extension). */
   extraPiArgs?: readonly string[];
   /** Override default role-run timeout. */
@@ -463,6 +465,8 @@ export async function runPublicJudge(
   return runWithAutoResumeLoop({
     admitted,
     io,
+    // #422: pass-through only; the loop entry resolves the default and validates the domain once.
+    autoResumeLimit: env.autoResumeLimit,
     buildInitialArgs: () =>
       buildJudgeActivationExtraArgs(admitted, {
         packageRoot: env.packageRoot,
@@ -536,7 +540,7 @@ export async function runPublicResume(
 
   let lease: RunWriterLease;
   try {
-    lease = await acquireRunWriterLease(admitted.runDirectory);
+    lease = await acquireRunWriterLease(admitted.runDirectory, (diagnostic) => io.stderr(diagnostic));
   } catch (error) {
     if (error instanceof RunWriterLeaseHeldError) {
       // Concurrent resume: reject without second writer or dispatch.

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

@@ -90,6 +90,8 @@ export type MergerRunEnv = {
   engine?: string;
   credentials?: CredentialProviders;
   createRunId?: () => string;
+  /** #422: effective single-call auto-resume ceiling; undefined = package default (AUTO_RESUME_LIMIT). */
+  autoResumeLimit?: number;
   extraPiArgs?: readonly string[];
   timeoutMs?: number;
 };
@@ -575,6 +577,8 @@ export async function runPublicMerger(
   return runWithAutoResumeLoop({
     admitted,
     io,
+    // #422: pass-through only; the loop entry resolves the default and validates the domain once.
+    autoResumeLimit: env.autoResumeLimit,
     buildInitialArgs: () =>
       buildMergerActivationExtraArgs(admitted, {
         packageRoot: env.packageRoot,
@@ -648,7 +652,7 @@ export async function runPublicMergerResume(
 
   let lease: RunWriterLease;
   try {
-    lease = await acquireRunWriterLease(admitted.runDirectory);
+    lease = await acquireRunWriterLease(admitted.runDirectory, (diagnostic) => io.stderr(diagnostic));
   } catch (error) {
     if (error instanceof RunWriterLeaseHeldError) {
       io.stderr(formatCliDiagnostic(error.message));

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

@@ -1098,10 +1098,12 @@ const SUPPORT_COMMAND_HELP = {
       "ak-role config set <seat> <provider/model[:thinking]> [<seat> <spec> ...]",
       "ak-role config set-engine <seat> <name>",
       "ak-role config unset-engine <seat>",
+      "ak-role config set-auto-resume-limit <N>",
     ],
     examples: [
       "ak-role config set judge openai-codex/gpt-5.6-sol:high",
       "ak-role config set-engine judge opus",
+      "ak-role config set-auto-resume-limit 3",
     ],
   },
   help: {

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

@@ -91,6 +91,8 @@ export type ReviewerRunEnv = {
   engine?: string;
   credentials?: CredentialProviders;
   createRunId?: () => string;
+  /** #422: effective single-call auto-resume ceiling; undefined = package default (AUTO_RESUME_LIMIT). */
+  autoResumeLimit?: number;
   extraPiArgs?: readonly string[];
   timeoutMs?: number;
 };
@@ -514,6 +516,8 @@ export async function runPublicReviewer(
   return runWithAutoResumeLoop({
     admitted,
     io,
+    // #422: pass-through only; the loop entry resolves the default and validates the domain once.
+    autoResumeLimit: env.autoResumeLimit,
     buildInitialArgs: () =>
       buildReviewerActivationExtraArgs(admitted, {
         packageRoot: env.packageRoot,
@@ -587,7 +591,7 @@ export async function runPublicReviewerResume(
 
   let lease: RunWriterLease;
   try {
-    lease = await acquireRunWriterLease(admitted.runDirectory);
+    lease = await acquireRunWriterLease(admitted.runDirectory, (diagnostic) => io.stderr(diagnostic));
   } catch (error) {
     if (error instanceof RunWriterLeaseHeldError) {
       io.stderr(formatCliDiagnostic(error.message));

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

@@ -52,7 +52,10 @@ export type TypedHttp429Observation = {
   readonly provider: V1ResumableProvider;
 };
 
-/** Per single LLM call auto-resume retries (call-local, no persistence). See #416 scope correction 2026-08-22. */
+/** Default for the #422 configurable single-call auto-resume ceiling
+ * (public-cli.json top-level `autoResumeLimit`). No longer the runtime truth
+ * source: runWithAutoResumeLoop receives the effective value once per call.
+ */
 export const AUTO_RESUME_LIMIT = 2 as const;
 
 export type RoleRunRecord = {
@@ -340,13 +343,52 @@ export type RunWriterLease = {
   release(): Promise<void>;
 };
 
+/**
+ * True error identity for diagnostics — name/code/message as-is, never a
+ * guessed label (failure-honesty constitution).
+ */
+function describeErrorIdentity(error: unknown): string {
+  const candidate = error as { name?: unknown; code?: unknown; message?: unknown };
+  const name =
+    typeof candidate?.name === "string" && candidate.name !== ""
+      ? candidate.name
+      : typeof error;
+  const code =
+    typeof candidate?.code === "string" || typeof candidate?.code === "number"
+      ? ` code=${String(candidate.code)}`
+      : "";
+  const message =
+    typeof candidate?.message === "string" && candidate.message !== ""
+      ? `: ${candidate.message}`
+      : "";
+  return `${name}${code}${message}`;
+}
+
 /**
  * Acquire the one-writer lease for a Role run. Concurrent acquire rejects
  * without dispatch. Exclusive create — no second writer.
+ *
+ * `onCleanupFailure` receives a non-terminal diagnostic line when release-time
+ * lock cleanup fails. Release stays best-effort (a stale lock resurfaces as
+ * RunWriterLeaseHeldError on next acquire), but the true error identity must
+ * still land somewhere observable — silent swallowing is forbidden.
  */
 export async function acquireRunWriterLease(
   runDirectory: string,
+  onCleanupFailure?: (diagnostic: string) => void,
 ): Promise<RunWriterLease> {
+  const reportCleanupFailure = (error: unknown): void => {
+    // Sink isolation: a throwing onCleanupFailure must not propagate through
+    // release() — release stays best-effort by contract. The true cleanup
+    // cause has already been handed to the sink as its argument.
+    try {
+      onCleanupFailure?.(
+        `writer lease lock cleanup failed (best-effort continue; stale lock resurfaces as lease-held on next acquire) at ${join(runDirectory, WRITER_LOCK_FILE)}: ${describeErrorIdentity(error)}`,
+      );
+    } catch {
+      // diagnostic-sink failure is itself best-effort; never break release().
+    }
+  };
   const lockPath = join(runDirectory, WRITER_LOCK_FILE);
   try {
     const handle = await open(lockPath, "wx");
@@ -371,7 +413,14 @@ export async function acquireRunWriterLease(
             try {
               await chmod(runDirectory, 0o755);
               await unlink(lockPath);
-            } catch {}
+            } catch (retryError) {
+              // best-effort cleanup: stale lock will surface as lease-held on next acquire (exit 2),
+              // but the true chmod/unlink cause must be recorded, not swallowed.
+              reportCleanupFailure(retryError);
+            }
+          } else {
+            // non-EACCES unlink failure is best-effort settlement cleanup; record true cause.
+            reportCleanupFailure(error);
           }
         }
       },