harnery 0.45.0 → 0.45.2

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,
@@ -62,8 +53,8 @@ import {
   normalizeWorkflowMeta,
   writeWorkflowProof,
 } from "./proof.ts";
+import { acquireWorkflowResumeLease } from "./resume-lock.ts";
 import {
-  acquireWorkflowResumeLease,
   assertWorkflowRunResumable,
   assertWorkflowScriptUnchanged,
   WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION,
@@ -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,23 +39,12 @@ export {
   rollupAcceptance,
   writeWorkflowProof,
 } from "./proof.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 } from "./resume-lock.ts";
+export type { 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) {

package/src/core/workflow/proof.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
-import { observationsComparable, type RepoSnapshot } from "../context/observation.ts";
+import { join } from "node:path";
+import { type RepoSnapshot, repoComparisonProblems } from "../context/observation.ts";
 import { DIAGNOSTIC_ADVICE_SCHEMA_VERSION } from "../diagnostics/contract.ts";
 import type {
   NormalizedPolicy,
@@ -12,7 +12,6 @@ import type {
 import { policyDigest } from "../policy/index.ts";
 import { isCanonicalWorkflowAttemptContext } from "./attempt-context.ts";
 import { stableDigest, writeImmutableJson } from "./durable-record.ts";
-import { failureEvidenceAllowsUncharged, isSpawnFailureEvidence } from "./failure-evidence.ts";
 import { readWorkflowRunManifest } from "./run-state.ts";
 import type {
   AcceptanceCriterion,
@@ -243,25 +242,17 @@ export function digestResult(value: unknown, kind?: "text" | "json"): ResultDige
  *    attempt was informative about the work — charge it. This also keeps a
  *    resumed run whose earlier segment did real work from being written off by
  *    a later environment failure.
- * 3. Every participant must have failed with positive no-effect evidence,
- *    observed absent output and no refusal. A class alone is insufficient.
- *    Among those eligible failures, environment is the hard stop.
+ * 3. Otherwise, among the failed agents, environment wins over upstream: a
+ *    missing binary means nothing ran at all, and it is the operator-chosen
+ *    hard stop.
  * 4. Anything else is undefined ⇒ a charged work failure, exactly as today.
  */
 export function deriveRunFailureClass(
   status: "succeeded" | "failed",
-  agents: readonly Pick<WorkflowAgentProof, "status" | "class" | "failure_evidence">[],
+  agents: readonly Pick<WorkflowAgentProof, "status" | "class">[],
 ): SpawnFailureClass | undefined {
   if (status !== "failed") return undefined;
-  if (
-    agents.length === 0 ||
-    agents.some(
-      (agent) =>
-        agent.status !== "failed" ||
-        (agent.class !== "environment" && agent.class !== "upstream") ||
-        !failureEvidenceAllowsUncharged(agent.failure_evidence),
-    )
-  ) {
+  if (agents.some((agent) => agent.status === "succeeded" || agent.status === "cached")) {
     return undefined;
   }
   const failed = agents.filter((agent) => agent.status === "failed");
@@ -394,13 +385,6 @@ export function readWorkflowProof(coordRoot: string, runId: string): WorkflowPro
       proof.run.class !== "environment" &&
       proof.run.class !== "upstream" &&
       proof.run.class !== "decision") ||
-    !Array.isArray(proof.agents) ||
-    proof.agents.some(
-      (agent) =>
-        !agent ||
-        typeof agent !== "object" ||
-        (agent.failure_evidence !== undefined && !isSpawnFailureEvidence(agent.failure_evidence)),
-    ) ||
     (proof.run.work_context !== undefined &&
       (!proof.run.work_item_id ||
         proof.run.work_context.id !== proof.run.work_item_id ||
@@ -415,15 +399,8 @@ export function readWorkflowProof(coordRoot: string, runId: string): WorkflowPro
   ) {
     throw new Error(`workflow proof at ${path} has an unsupported or mismatched schema`);
   }
-  if (
-    repoComparisonProblem(proof.repository.before, proof.repository.after) !== undefined ||
-    proof.repository.before.dirty_paths_truncated ||
-    proof.repository.after.dirty_paths_truncated ||
-    !proof.repository.before.branch?.trim() ||
-    !proof.repository.after.branch?.trim() ||
-    !proof.repository.before.head?.trim() ||
-    !proof.repository.after.head?.trim()
-  ) {
+  // Packets written before observation checks may carry unproven drift.
+  if (repoProblems(proof.repository).length > 0) {
     proof.repository = buildRepoEvidence(proof.repository.before, proof.repository.after);
     proof.unknowns = proof.unknowns.filter((item) => item.code !== "repository_drift_incomplete");
     proof.unknowns.push({
@@ -544,29 +521,16 @@ export function renderWorkflowProof(proof: WorkflowProof): string {
         : "admission: shadow not needed; no real child dispatch",
     );
   }
-  const comparable =
-    repoComparisonProblem(proof.repository.before, proof.repository.after) === undefined;
-  const repo =
-    comparable &&
-    !proof.repository.before.dirty_paths_truncated &&
-    !proof.repository.after.dirty_paths_truncated &&
-    proof.repository.before.branch?.trim() &&
-    proof.repository.after.branch?.trim() &&
-    proof.repository.before.head?.trim() &&
-    proof.repository.after.head?.trim()
-      ? proof.repository
-      : buildRepoEvidence(proof.repository.before, proof.repository.after);
-  const drift = repo.drift;
-  if (!comparable) {
-    lines.push(`repository: drift unknown. ${drift.note}`);
+  const problems = repoProblems(proof.repository);
+  if (problems.length > 0) {
+    lines.push(`repository: drift unknown. ${unverifiedDrift(problems)}`);
   } else {
-    const paths =
-      drift.dirty_paths_added === null || drift.dirty_paths_cleared === null
-        ? "dirty-path drift unknown"
-        : `${drift.dirty_paths_added.length} dirty added, ${drift.dirty_paths_cleared.length} cleared`;
+    const { before, after, drift } = proof.repository;
     lines.push(
-      `repository: branch ${repo.before.branch ?? "unknown"} -> ${repo.after.branch ?? "unknown"}; ` +
-        `HEAD ${short(repo.before.head)} -> ${short(repo.after.head)}; ${paths}`,
+      `repository: branch ${before.branch} -> ${after.branch}; ` +
+        `HEAD ${short(before.head)} -> ${short(after.head)}; ` +
+        `${drift.dirty_paths_added?.length ?? "unknown"} dirty added, ` +
+        `${drift.dirty_paths_cleared?.length ?? "unknown"} cleared`,
     );
   }
   if (proof.unknowns.length > 0) {
@@ -580,8 +544,8 @@ export function renderWorkflowProof(proof: WorkflowProof): string {
 function buildRepoEvidence(beforeRaw: RepoSnapshot, afterRaw: RepoSnapshot): WorkflowRepoEvidence {
   const before = normalizeRepoSnapshot(beforeRaw);
   const after = normalizeRepoSnapshot(afterRaw);
-  const problem = repoComparisonProblem(before, after);
-  if (problem !== undefined) {
+  const problems = repoProblems({ before, after });
+  if (problems.length > 0) {
     return {
       source: "engine",
       before,
@@ -593,47 +557,43 @@ function buildRepoEvidence(beforeRaw: RepoSnapshot, afterRaw: RepoSnapshot): Wor
         dirty_paths_cleared: null,
         dirty_paths_retained: null,
         incomplete: true,
-        note: `Repository drift could not be verified: ${problem}. Re-check before editing.`,
+        note: unverifiedDrift(problems),
       },
     };
   }
-  const pathsComparable = !before.dirty_paths_truncated && !after.dirty_paths_truncated;
-  const branchKnown = Boolean(before.branch && after.branch);
-  const headKnown = Boolean(before.head && after.head);
   const beforeDirty = new Set(before.dirty_paths);
   const afterDirty = new Set(after.dirty_paths);
   const retained = after.dirty_paths.filter((path) => beforeDirty.has(path));
-  const notes = [
-    ...(!pathsComparable
-      ? ["Dirty-path drift is unknown because a snapshot list was truncated."]
-      : []),
-    ...(!branchKnown ? ["Branch drift is unknown because a snapshot has no branch."] : []),
-    ...(!headKnown ? ["HEAD drift is unknown because a snapshot has no HEAD."] : []),
-    ...(pathsComparable && retained.length > 0
-      ? ["Snapshots cannot prove whether retained dirty paths changed during the run."]
-      : []),
-  ];
-  const incomplete = notes.length > 0;
+  const incomplete = retained.length > 0;
   return {
     source: "engine",
     before,
     after,
     drift: {
-      branch_changed: branchKnown ? before.branch !== after.branch : null,
-      head_changed: headKnown ? before.head !== after.head : null,
-      dirty_paths_added: pathsComparable
-        ? after.dirty_paths.filter((path) => !beforeDirty.has(path))
-        : null,
-      dirty_paths_cleared: pathsComparable
-        ? before.dirty_paths.filter((path) => !afterDirty.has(path))
-        : null,
-      dirty_paths_retained: pathsComparable ? retained : null,
+      branch_changed: before.branch !== after.branch,
+      head_changed: before.head !== after.head,
+      dirty_paths_added: after.dirty_paths.filter((path) => !beforeDirty.has(path)),
+      dirty_paths_cleared: before.dirty_paths.filter((path) => !afterDirty.has(path)),
+      dirty_paths_retained: retained,
       incomplete,
-      note: incomplete ? notes.join(" ") : undefined,
+      note: incomplete
+        ? "Snapshots cannot prove whether retained dirty paths changed during the run."
+        : undefined,
     },
   };
 }
 
+function repoProblems(repository: {
+  before: WorkflowRepoSnapshot;
+  after: WorkflowRepoSnapshot;
+}): string[] {
+  return repoComparisonProblems(repository.before, repository.after, ["before", "after"]);
+}
+
+function unverifiedDrift(problems: string[]): string {
+  return `Repository drift could not be verified: ${problems.join("; ")}. Re-check before editing.`;
+}
+
 function normalizeRepoSnapshot(snapshot: RepoSnapshot): WorkflowRepoSnapshot {
   return {
     cwd: snapshot.cwd,
@@ -649,30 +609,6 @@ function normalizeRepoSnapshot(snapshot: RepoSnapshot): WorkflowRepoSnapshot {
   };
 }
 
-function snapshotFailure(label: string, snapshot: WorkflowRepoSnapshot): string {
-  return `${label} snapshot is ${snapshot.observation}${snapshot.observation_detail ? ` (${snapshot.observation_detail})` : ""}`;
-}
-
-function repoComparisonProblem(
-  before: WorkflowRepoSnapshot,
-  after: WorkflowRepoSnapshot,
-): string | undefined {
-  if (!observationsComparable(before, after)) {
-    return [
-      ...(before.observation !== "ok" ? [snapshotFailure("before", before)] : []),
-      ...(after.observation !== "ok" ? [snapshotFailure("after", after)] : []),
-    ].join("; ");
-  }
-  const unknownRoots = [
-    ...(!before.root || !isAbsolute(before.root) ? ["before"] : []),
-    ...(!after.root || !isAbsolute(after.root) ? ["after"] : []),
-  ];
-  if (unknownRoots.length > 0)
-    return `${unknownRoots.join(" and ")} snapshot repository root is unknown`;
-  if (before.root !== after.root) return "snapshots name different repository roots";
-  return undefined;
-}
-
 function buildAdapterCoverage(
   agents: WorkflowAgentProof[],
   claims: Readonly<Record<string, AdapterEvidenceCapability | undefined>> | undefined,