harnery 0.44.0 → 0.45.1

package/src/core/storage/durable-history.ts

@@ -521,28 +521,49 @@ function acquireLease(lease: string): LeaseOwner {
       pid: process.pid,
       acquired_at: new Date().toISOString(),
     };
-    let claimed: DirectoryIdentity | undefined;
+    if (claimLease(lease, parent, owner)) return owner;
+    if (recoverStaleLease(lease, DURABLE_HISTORY_LEASE_STALE_MS)) continue;
+    throw new Error(`durable history lease busy: ${lease}`);
+  }
+  throw new Error(`durable history lease busy: ${lease}`);
+}
+
+/**
+ * Publish a complete lease in one rename. The owner record is written and synced
+ * in a private claim directory first, so a writer stopped at any point leaves
+ * either no lease or one with an owner. A held lease always has an owner record,
+ * here and in the earlier create-then-write protocol, so a rename that replaces
+ * an empty lease directory never takes a held lease. A lease with any entry makes
+ * the rename fail and the caller reports it busy.
+ */
+function claimLease(lease: string, parent: DirectoryIdentity, owner: LeaseOwner): boolean {
+  const claim = `${lease}.claim-${process.pid}-${owner.owner_id}`;
+  try {
+    mkdirSync(claim, { mode: stateDirMode() });
+    assertDirectoryWithinParent(claim, parent);
+    const claimed = captureDirectoryIdentity(claim);
+    writeOwner(join(claim, "owner.json"), owner);
+    syncDirectory(claimed);
+    renameSync(claim, lease);
+  } catch {
+    return false;
+  } finally {
     try {
-      mkdirSync(lease, { mode: stateDirMode() });
-      assertDirectoryWithinParent(lease, parent);
-      claimed = captureDirectoryIdentity(lease);
-      writeOwner(join(lease, "owner.json"), owner);
-      syncDirectory(claimed);
-      return owner;
+      rmSync(claim, { recursive: true, force: true });
     } catch {
-      if (claimed) {
-        try {
-          assertDirectoryIdentity(claimed);
-          rmSync(lease, { recursive: true, force: false });
-        } catch {
-          // Never remove a lease after its directory identity changes.
-        }
-      }
-      if (recoverStaleLease(lease, DURABLE_HISTORY_LEASE_STALE_MS)) continue;
-      throw new Error(`durable history lease busy: ${lease}`);
+      // A leftover claim directory never blocks a lease.
     }
   }
-  throw new Error(`durable history lease busy: ${lease}`);
+  try {
+    assertDirectoryWithinParent(lease, parent);
+    const current = JSON.parse(completeJsonl(join(lease, "owner.json"))) as LeaseOwner;
+    if (current.owner_id !== owner.owner_id) return false;
+    syncDirectory(parent);
+    return true;
+  } catch {
+    releaseOwnedLease(lease, owner);
+    return false;
+  }
 }
 
 function writeOwner(path: string, owner: LeaseOwner): void {
@@ -595,7 +616,7 @@ function recoverStaleLease(lease: string, staleMs: number): boolean {
   try {
     assertDirectoryIdentity(leaseIdentity);
     if (completeJsonl(ownerPath) !== raw) return false;
-    rmSync(lease, { recursive: true, force: false });
+    retireLease(lease, randomUUID());
     return true;
   } catch {
     return false;
@@ -606,12 +627,23 @@ function releaseOwnedLease(lease: string, owner: LeaseOwner): void {
   try {
     const current = JSON.parse(completeJsonl(join(lease, "owner.json"))) as LeaseOwner;
     if (current.owner_id !== owner.owner_id) return;
-    rmSync(lease, { recursive: true, force: false });
+    retireLease(lease, owner.owner_id);
   } catch {
     // A missing or replaced lease does not belong to this operation.
   }
 }
 
+/**
+ * Move a lease aside before deleting it. Its path goes from held to absent in
+ * one rename and is never an empty directory that a concurrent claim could
+ * replace while a recursive removal is still running.
+ */
+function retireLease(lease: string, tag: string): void {
+  const retired = `${lease}.retired-${process.pid}-${tag}`;
+  renameSync(lease, retired);
+  rmSync(retired, { recursive: true, force: true });
+}
+
 function processIsAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);

package/src/core/storage/segments.ts

@@ -338,23 +338,20 @@ export async function withFamilyLease<T>(
   let owner: LeaseOwner | undefined;
   while (true) {
     try {
-      mkdirSync(lease, { mode: stateDirMode() });
-      const leaseIdentity = captureDirectoryIdentity(lease);
-      owner = {
-        owner_id: randomUUID(),
-        pid: process.pid,
-        acquired_at: new Date().toISOString(),
-      };
-      writeNewFile(join(lease, "owner.json"), Buffer.from(`${JSON.stringify(owner)}\n`));
-      assertDirectoryIdentity(leaseIdentity);
+      owner = claimLease(lease);
       break;
     } catch (error) {
-      if (pathExists(lease) && !safeLeaseDirectory(lease)) {
+      if (leaseHasWrongType(lease)) {
         throw new HarneryLogLeaseError("wrong_type", `log lease is not a directory: ${lease}`);
       }
       if (recoverStaleLease(lease, policy.lease_stale_ms)) continue;
       if (Date.now() - started >= policy.lease_timeout_ms) {
-        throw new HarneryLogLeaseError("timeout", `timed out acquiring log lease: ${lease}`);
+        throw new HarneryLogLeaseError(
+          "timeout",
+          leaseHasValidOwner(lease)
+            ? `timed out acquiring log lease: ${lease}`
+            : `timed out acquiring log lease with no valid owner; an interrupted writer left it, and it is never recovered automatically: ${lease}`,
+        );
       }
       await new Promise((resolve) => setTimeout(resolve, policy.lease_retry_ms));
       void error;
@@ -367,6 +364,41 @@ export async function withFamilyLease<T>(
   }
 }
 
+/**
+ * Publish a complete lease in one rename. The owner record is written and synced
+ * in a private claim directory first, so a writer stopped at any point leaves
+ * either no lease or one with an owner. A held lease always has an owner record,
+ * here and in the earlier create-then-write protocol, so a rename that replaces
+ * an empty lease directory never takes a held lease. A lease with any entry makes
+ * the rename fail, and the caller waits or recovers as before.
+ */
+function claimLease(lease: string): LeaseOwner {
+  const owner: LeaseOwner = {
+    owner_id: randomUUID(),
+    pid: process.pid,
+    acquired_at: new Date().toISOString(),
+  };
+  const content = `${JSON.stringify(owner)}\n`;
+  const claim = `${lease}.claim-${process.pid}-${owner.owner_id}`;
+  try {
+    mkdirSync(claim, { mode: stateDirMode() });
+    writeNewFile(join(claim, "owner.json"), Buffer.from(content));
+    renameSync(claim, lease);
+  } finally {
+    rmSync(claim, { recursive: true, force: true });
+  }
+  try {
+    captureDirectoryIdentity(lease);
+    if (readRegularFile(join(lease, "owner.json"), 4_096).toString("utf8") !== content) {
+      throw new Error(`log lease owner changed during claim: ${lease}`);
+    }
+  } catch (error) {
+    releaseOwnedLease(lease, owner);
+    throw error;
+  }
+  return owner;
+}
+
 function shouldRotate(
   active: string,
   incoming: readonly Buffer[],
@@ -476,6 +508,22 @@ interface LeaseOwner {
   acquired_at: string;
 }
 
+function leaseHasValidOwner(lease: string): boolean {
+  try {
+    const owner = JSON.parse(
+      readRegularFile(join(lease, "owner.json"), 4_096).toString("utf8"),
+    ) as LeaseOwner;
+    return (
+      typeof owner?.owner_id === "string" &&
+      owner.owner_id.length > 0 &&
+      Number.isSafeInteger(owner.pid) &&
+      Number.isFinite(Date.parse(owner.acquired_at))
+    );
+  } catch {
+    return false;
+  }
+}
+
 function recoverStaleLease(lease: string, maximumAgeMs: number): boolean {
   let identity: DirectoryIdentity;
   let raw: string;
@@ -504,7 +552,7 @@ function recoverStaleLease(lease: string, maximumAgeMs: number): boolean {
   try {
     assertDirectoryIdentity(identity);
     if (readRegularFile(join(lease, "owner.json"), 4_096).toString("utf8") !== raw) return false;
-    rmSync(lease, { recursive: true, force: false });
+    retireLease(lease, randomUUID());
     return true;
   } catch {
     return false;
@@ -517,12 +565,23 @@ function releaseOwnedLease(lease: string, owner: LeaseOwner): void {
       readRegularFile(join(lease, "owner.json"), 4_096).toString("utf8"),
     ) as LeaseOwner;
     if (current.owner_id !== owner.owner_id) return;
-    rmSync(lease, { recursive: true, force: false });
+    retireLease(lease, owner.owner_id);
   } catch {
     // A missing or replaced lease does not belong to this operation.
   }
 }
 
+/**
+ * Move a lease aside before deleting it. Its path goes from held to absent in
+ * one rename and is never an empty directory that a concurrent claim could
+ * replace while a recursive removal is still running.
+ */
+function retireLease(lease: string, tag: string): void {
+  const retired = `${lease}.retired-${process.pid}-${tag}`;
+  renameSync(lease, retired);
+  rmSync(retired, { recursive: true, force: true });
+}
+
 function processIsAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -699,11 +758,14 @@ function nativeWriteSync(fd: number, buffer: Buffer, offset: number, length: num
   return writeSync(fd, buffer, offset, length);
 }
 
-function safeLeaseDirectory(path: string): boolean {
+/** One lstat, so a lease released between checks reads as absent, not as a wrong type. */
+function leaseHasWrongType(path: string): boolean {
   try {
-    return !lstatSync(path).isSymbolicLink() && lstatSync(path).isDirectory();
-  } catch {
-    return false;
+    const stat = lstatSync(path);
+    return stat.isSymbolicLink() || !stat.isDirectory();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
   }
 }
 

package/src/core/supervisor/service.ts

@@ -17,6 +17,7 @@ import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
 import { collectCoordinationHealthSnapshot } from "../agents/health.ts";
 import {
+  type ProcessGenerationSignalDependencies,
   type ProcessGenerationVerdict,
   processStartToken,
   signalIfSameGeneration,
@@ -185,9 +186,7 @@ export interface SupervisorStopResult extends SupervisorStatus {
 
 export function requestSupervisorStop(
   coordRootRaw: string,
-  dependencies: SupervisorProcessDependencies & {
-    kill?: (pid: number, signal: NodeJS.Signals | number) => unknown;
-  } = {},
+  dependencies: SupervisorProcessDependencies & ProcessGenerationSignalDependencies = {},
 ): SupervisorStopResult {
   const coordRoot = resolve(coordRootRaw);
   const paths = supervisorPaths(coordRoot);

package/src/core/work/state.ts

@@ -20,7 +20,7 @@ import {
 import { stateDirMode, stateFileMode } from "../storage/modes.ts";
 import { readWorkflowApproval } from "../workflow/approvals.ts";
 import { stableDigest } from "../workflow/durable-record.ts";
-import { deriveRunFailureClass, readWorkflowProof } from "../workflow/proof.ts";
+import { readWorkflowProof } from "../workflow/proof.ts";
 import { readWorkflowRunManifest, workflowScriptDigest } from "../workflow/run-state.ts";
 import { WORKFLOW_TRANSCRIPT_EVENT_BYTES, workflowTranscriptPath } from "../workflow/transcript.ts";
 import { isWorkspaceBoundExecutionEvidence } from "../workflow/workspaces/validate.ts";
@@ -718,14 +718,14 @@ function inspectAttempt(
       proof.acceptance.summary.unknown === 0
         ? "succeeded"
         : "failed";
-    // Re-derive no-effect eligibility from every participant rather than
-    // trusting a persisted transport class. Missing evidence stays charged.
-    // The script's explicit decision authority remains a separate path.
+    // A failed attempt the run classified as uninformative about the work is
+    // uncharged (ADR 0046). Absent class ⇒ charged, as before. Read only for a
+    // failed attempt: a succeeded run never carries a class.
     if (
       attempt.status === "failed" &&
-      (proof.run.class === "decision" ||
-        ((proof.run.class === "environment" || proof.run.class === "upstream") &&
-          deriveRunFailureClass(proof.run.status, proof.agents) === proof.run.class))
+      (proof.run.class === "environment" ||
+        proof.run.class === "upstream" ||
+        proof.run.class === "decision")
     ) {
       attempt.uncharged = proof.run.class;
       if (proof.run.class === "decision" && typeof proof.run.decision_id === "string") {

package/src/core/workflow/engine.ts

@@ -45,16 +45,7 @@ import { freezeWorkflowAttemptContext } from "./attempt-context.ts";
 import { type BillingProbe, probeBilling } from "./billing.ts";
 import { stableDigest } from "./durable-record.ts";
 import { evidencePreflightError } from "./evidence-preflight.ts";
-import {
-  canRetryFailedSpawn,
-  observeSpawnFailure,
-  resolveFailureEvidence,
-} from "./failure-evidence.ts";
-import {
-  endWorkflowChildSessionV3,
-  recordWorkflowChildTerminalFailureV3,
-  startWorkflowChildSessionV3,
-} from "./live-session-v3.ts";
+import { endWorkflowChildSessionV3, startWorkflowChildSessionV3 } from "./live-session-v3.ts";
 import {
   buildWorkflowProof,
   createEvidenceRecord,
@@ -1038,38 +1029,22 @@ async function executeWorkflow(
     });
     agentProof.access = access;
 
-    let childGenerationId: string | undefined;
     let recordAgentEnd: (() => void) | undefined;
     const finalizeChild = (): void => {
       try {
-        if (childGenerationId)
-          endWorkflowChildSessionV3({
-            coordRoot: opts.coordRoot,
-            instanceId: childInstanceId(runId, id),
-            runId,
-            agentId: id,
-            adapter,
-            cleanExit: agentProof.status === "succeeded",
-            expectedGenerationId: childGenerationId,
-          });
-        // Result publication is the resume-cache boundary, after canonical custody.
+        // Record the canonical terminal first. agent.end is the resume-cache
+        // boundary, so a child whose end was not recorded never reports success.
+        endWorkflowChildSessionV3({
+          coordRoot: opts.coordRoot,
+          instanceId: childInstanceId(runId, id),
+          runId,
+          agentId: id,
+          adapter,
+          cleanExit: agentProof.status === "succeeded",
+        });
         recordAgentEnd?.();
       } catch (error) {
-        let reason = `V3 terminal recording failed: ${(error as Error).message}`;
-        try {
-          if (childGenerationId)
-            recordWorkflowChildTerminalFailureV3({
-              coordRoot: opts.coordRoot,
-              instanceId: childInstanceId(runId, id),
-              runId,
-              agentId: id,
-              adapter,
-              expectedGenerationId: childGenerationId,
-              reason,
-            });
-        } catch (visibilityError) {
-          reason += `; blocked lifecycle recording failed: ${(visibilityError as Error).message}`;
-        }
+        const reason = `V3 terminal recording failed: ${(error as Error).message}`;
         const failure = new Error(agentProof.error ? `${agentProof.error}; ${reason}` : reason, {
           cause: error,
         });
@@ -1102,7 +1077,7 @@ async function executeWorkflow(
       // Headless children do not reliably fire adapter hooks. The engine owns
       // their canonical V3 start so every dispatched child has an auditable
       // generation before it begins work.
-      const child = startWorkflowChildSessionV3({
+      startWorkflowChildSessionV3({
         coordRoot: opts.coordRoot,
         instanceId: childInstanceId(runId, id),
         runId,
@@ -1111,13 +1086,10 @@ async function executeWorkflow(
         label,
         model: agentOpts.model,
       });
-      if (!child.v3_generation_id) throw new Error("workflow_child_v3_generation_missing");
-      childGenerationId = child.v3_generation_id;
 
       let attemptPrompt = dispatchPrompt;
       let last: SpawnResult | null = null;
       let agentCostUsd = 0;
-      let informativeAttempt: ReturnType<typeof observeSpawnFailure> | undefined;
       for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         last = await spawner({
           prompt: attemptPrompt,
@@ -1140,30 +1112,14 @@ async function executeWorkflow(
         costUsd += last.costUsd ?? 0;
 
         if (!last.ok) {
-          const observed =
-            last.failureEvidence === undefined
-              ? observeSpawnFailure({}, last.text, "final_message")
-              : resolveFailureEvidence(last.failureEvidence);
-          agentProof.failure_evidence = informativeAttempt
-            ? {
-                ...observed,
-                effect: { state: "unknown" },
-                partial_output: informativeAttempt.partial_output,
-              }
-            : observed;
-          transcript("agent.attempt_failed", {
-            id,
-            attempt,
-            error: last.error,
-            failure_evidence: observed,
-            result_digest: digestResult(last.text, "text"),
-            text: last.text,
-          });
-          if (!canRetryFailedSpawn({ ...last, failureEvidence: agentProof.failure_evidence }))
-            break;
-          continue;
+          transcript("agent.attempt_failed", { id, attempt, error: last.error });
+          // ADR 0046: an environment failure (the binary was absent) cannot be
+          // helped by retrying an unchanged environment, so stop the in-agent
+          // retry too — not just the outer attempt/replan budget. An upstream
+          // refusal keeps retrying here: the vendor may recover mid-loop.
+          if (last.class === "environment") break;
+          continue; // spawn-level failure: retry with the original prompt
         }
-        informativeAttempt = observeSpawnFailure({}, last.text, "final_message");
         if (!agentOpts.schema) {
           agentProof.status = "succeeded";
           agentProof.cost_usd =
@@ -1217,14 +1173,7 @@ async function executeWorkflow(
           return parsed.value;
         }
 
-        agentProof.failure_evidence = informativeAttempt;
-        transcript("agent.schema_retry", {
-          id,
-          attempt,
-          problems,
-          rejected_text: last.text,
-          result_digest: digestResult(last.text, "text"),
-        });
+        transcript("agent.schema_retry", { id, attempt, problems });
         // Keep the original cache identity while making the actual output
         // contract explicit. A full bounded copy of the rejected value lets the
         // child repair omissions instead of reconstructing an unseen object.
@@ -1260,7 +1209,6 @@ async function executeWorkflow(
       try {
         finalizeChild();
       } finally {
-        // A slot is disposable; unresolved custody remains visible and failed.
         release();
       }
     }

package/src/core/workflow/index.ts

@@ -39,12 +39,23 @@ export {
   rollupAcceptance,
   writeWorkflowProof,
 } from "./proof.ts";
-export type { WorkflowRunManifest } from "./run-state.ts";
+export type {
+  WorkflowRecoveryAuthorization,
+  WorkflowRecoveryIntent,
+  WorkflowRecoveryRecord,
+} from "./recovery-audit.ts";
+export { beginWorkflowRecovery, readWorkflowRecoveryLedger } from "./recovery-audit.ts";
+export type {
+  WorkflowResumeRecoveryOptions,
+  WorkflowResumeRecoveryResult,
+  WorkflowRunManifest,
+} from "./run-state.ts";
 export {
   acquireWorkflowResumeLease,
   assertWorkflowRunResumable,
   assertWorkflowScriptUnchanged,
   readWorkflowRunManifest,
+  recoverWorkflowResumeLease,
   WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION,
   workflowRunManifestPath,
   workflowScriptDigest,

package/src/core/workflow/live-session-v3.ts

@@ -1,16 +1,9 @@
-import { randomUUID } from "node:crypto";
-import { existsSync, linkSync, readdirSync, readFileSync, renameSync, unlinkSync } from "node:fs";
-import { basename, dirname } from "node:path";
 import { type Adapter, adapterFromPlatform } from "../adapter.ts";
-import {
-  recordLiveLifecycleChangeV3,
-  recordLiveTaskChangeV3,
-} from "../agents/live-authority-v3.ts";
+import { recordLiveTaskChangeV3 } from "../agents/live-authority-v3.ts";
 import { endSessionExplicitV3 } from "../agents/session-finalizer-v3.ts";
-import { heartbeatPath } from "../agents/state/heartbeat-reader.ts";
 import {
+  clearCoordinationCache,
   type Heartbeat,
-  readHeartbeat,
   setIdentityCache,
 } from "../agents/state/heartbeat-writer.ts";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
@@ -19,17 +12,9 @@ import { assignName } from "../agents/state/names.ts";
 import { coordFreshnessSeconds } from "../config.ts";
 import { ensureEventLedgerV3 } from "../events/v3/bootstrap.ts";
 import {
-  readCoordinationViewV3,
-  requireAuthoritySafeCoordinationViewV3,
-} from "../events/v3/coordination-view.ts";
-import { withGenerationCustodyV3 } from "../events/v3/generation-custody.ts";
-import {
-  liveInstanceIdV3,
   recordLiveHookSignalV3,
   resolveLiveEventLedgerRouteV3,
 } from "../events/v3/live-routing.ts";
-import { readHookProducerStateV3 } from "../events/v3/producers/recorder.ts";
-import { fsyncParentDirectory } from "./durable-record.ts";
 import { stableScopeId } from "./scope-id.ts";
 
 export interface WorkflowChildSessionV3Input {
@@ -92,45 +77,16 @@ export function startWorkflowChildSessionV3(input: WorkflowChildSessionV3Input):
   }
   const projected = readLiveCoordinationRow(input.coordRoot, input.instanceId);
   if (!projected) throw new Error("workflow_child_v3_projection_missing");
-  const own = readHookProducerStateV3(input.coordRoot, adapter, sessionId);
-  if (!own || own.terminal || own.generation_id !== projected.v3_generation_id) {
-    throw new Error("workflow_child_v3_start_generation_changed");
-  }
   return projected;
 }
 
 /** Record the authoritative terminal before removing the disposable coordination cache. */
 export function endWorkflowChildSessionV3(
-  input: WorkflowChildSessionV3Input & { cleanExit: boolean; expectedGenerationId: string },
-): void {
-  withGenerationCustodyV3(input.coordRoot, [liveInstanceIdV3(input.instanceId)], () =>
-    endExpectedChild(input),
-  );
-}
-
-function endExpectedChild(
-  input: WorkflowChildSessionV3Input & { cleanExit: boolean; expectedGenerationId: string },
+  input: WorkflowChildSessionV3Input & { cleanExit: boolean },
 ): void {
   requireV3Route(input.coordRoot);
-  const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(input.coordRoot));
-  const instanceId = liveInstanceIdV3(input.instanceId);
-  const current = view.instances[instanceId];
-  const terminal = view.terminal_generations[input.expectedGenerationId];
-  if (terminal?.instance_id === instanceId) recoverHeldCaches(input);
-  if (current && current.generation_id !== input.expectedGenerationId) {
-    throw new Error("workflow_child_v3_generation_changed");
-  }
-  if (!current) {
-    if (!terminal || terminal.instance_id !== instanceId)
-      throw new Error("workflow_child_v3_generation_missing");
-    if (terminal.terminal?.outcome !== (input.cleanExit ? "succeeded" : "failed")) {
-      throw new Error("workflow_child_v3_terminal_outcome_changed");
-    }
-    clearExpectedCache(input);
-    return;
-  }
   const row = readLiveCoordinationRow(input.coordRoot, input.instanceId);
-  if (!row?.v3_instance_id || row.v3_generation_id !== input.expectedGenerationId) {
+  if (!row?.v3_instance_id || !row.v3_generation_id) {
     throw new Error("workflow_child_v3_generation_missing");
   }
   const result = endSessionExplicitV3({
@@ -145,104 +101,7 @@ function endExpectedChild(
       `workflow_child_v3_end_failed:${result.state}${"reason" in result ? `:${result.reason}` : ""}`,
     );
   }
-  clearExpectedCache(input);
-}
-
-/** Persist unresolved terminal custody only for the generation this dispatch owns. */
-export function recordWorkflowChildTerminalFailureV3(
-  input: WorkflowChildSessionV3Input & { expectedGenerationId: string; reason: string },
-): void {
-  withGenerationCustodyV3(input.coordRoot, [liveInstanceIdV3(input.instanceId)], () => {
-    const row = readLiveCoordinationRow(input.coordRoot, input.instanceId);
-    if (!row || row.v3_generation_id !== input.expectedGenerationId) return;
-    recordLiveLifecycleChangeV3({
-      coordRoot: input.coordRoot,
-      owner: input.instanceId,
-      nativeSessionId: input.sessionId ?? input.instanceId,
-      adapter: workflowAdapter(input.adapter),
-      expectedGenerationId: input.expectedGenerationId as `gen_${string}`,
-      state: "blocked",
-      reason: input.reason,
-    });
-  });
-}
-
-function heldPrefix(input: WorkflowChildSessionV3Input & { expectedGenerationId: string }): string {
-  if (!/^gen_[a-zA-Z0-9._-]{1,128}$/.test(input.expectedGenerationId))
-    throw new Error("workflow_child_v3_generation_invalid");
-  return `${basename(heartbeatPath(input.coordRoot, input.instanceId))}.terminal-${input.expectedGenerationId}-`;
-}
-
-function recoverHeldCaches(
-  input: WorkflowChildSessionV3Input & { expectedGenerationId: string },
-): void {
-  const path = heartbeatPath(input.coordRoot, input.instanceId);
-  if (!existsSync(dirname(path))) return;
-  const prefix = heldPrefix(input);
-  for (const name of readdirSync(dirname(path)).filter((value) => value.startsWith(prefix))) {
-    finishHeldCache(`${dirname(path)}/${name}`, path, input.expectedGenerationId);
-  }
-}
-
-function clearExpectedCache(
-  input: WorkflowChildSessionV3Input & { expectedGenerationId: string },
-): void {
-  recoverHeldCaches(input);
-  if (
-    readHeartbeat(input.coordRoot, input.instanceId)?.v3_generation_id !==
-    input.expectedGenerationId
-  )
-    return;
-  const path = heartbeatPath(input.coordRoot, input.instanceId);
-  const held = `${dirname(path)}/${heldPrefix(input)}${randomUUID()}`;
-  try {
-    // A unique held name pins the actual bytes atomically. Checking before
-    // unlink alone could consume a replacement published at this boundary.
-    renameSync(path, held);
-    fsyncParentDirectory(path);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
-    throw error;
-  }
-  finishHeldCache(held, path, input.expectedGenerationId);
-}
-
-function finishHeldCache(held: string, path: string, expectedGenerationId: string): void {
-  let removed = false;
-  let cleanupFailed = false;
-  let cleanupError: unknown;
-  try {
-    const cache = JSON.parse(readFileSync(held, "utf8")) as Heartbeat;
-    if (cache.v3_generation_id === expectedGenerationId) {
-      unlinkSync(held);
-      fsyncParentDirectory(held);
-      removed = true;
-    }
-  } catch (error) {
-    cleanupFailed = true;
-    cleanupError = error;
-  }
-  if (!removed) {
-    try {
-      // Never overwrite a later publication. Keep the held evidence when
-      // another cache already owns the live name.
-      linkSync(held, path);
-      fsyncParentDirectory(path);
-      unlinkSync(held);
-      fsyncParentDirectory(held);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
-        if (cleanupFailed) {
-          throw new AggregateError(
-            [cleanupError, error],
-            `workflow_child_v3_cache_cleanup_and_restore_failed: ${String(cleanupError)}; restoration: ${String(error)}`,
-          );
-        }
-        throw error;
-      }
-    }
-  }
-  if (cleanupFailed) throw cleanupError;
+  clearCoordinationCache(input.coordRoot, input.instanceId);
 }
 
 function requireV3Route(coordRoot: string) {