harnery 0.45.1 → 0.46.0

package/src/core/supervisor/service.ts

@@ -1,32 +1,26 @@
 import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import {
-  closeSync,
-  existsSync,
-  mkdirSync,
-  openSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { hostname } from "node:os";
 import { resolve } from "node:path";
 import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
 import { collectCoordinationHealthSnapshot } from "../agents/health.ts";
+import { processStartToken } from "../agents/state/proc-start.ts";
 import {
-  type ProcessGenerationSignalDependencies,
-  type ProcessGenerationVerdict,
-  processStartToken,
-  signalIfSameGeneration,
-} from "../agents/state/proc-start.ts";
+  acquireServiceLease,
+  requestServiceStop,
+  type ServiceLiveness,
+  type ServiceProcessDependencies,
+  type ServiceStopFields,
+  serviceLeaseOwner,
+  serviceStartRefusal,
+} from "../agents/state/service-process.ts";
 import { resolveBinName } from "../config.ts";
 import { pressureHistoryFromSupervisor } from "../diagnostics/advice.ts";
 import { assessPressure } from "../diagnostics/pressure.ts";
 import { readEventV3ControlState } from "../events/v3/control.ts";
 import { janitorLiveDisplayV3 } from "../events/v3/live-feed.ts";
+import { installedHarneryBuild } from "../events/v3/runtime-build.ts";
 import type { ResourceSamplerState } from "../resources/contract.ts";
 import { sampleResources } from "../resources/sampler.ts";
 import { requestResourceServiceStop } from "../resources/service.ts";
@@ -34,7 +28,7 @@ import { readResourceServiceStatus } from "../resources/service-status.ts";
 import { resourcePaths } from "../resources/storage.ts";
 import { writePrivateJsonAtomic } from "../storage/atomic-json.ts";
 import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.ts";
-import { stateDirMode, stateFileMode } from "../storage/modes.ts";
+import { stateDirMode } from "../storage/modes.ts";
 import { collectSupervisorActivitySnapshot } from "./activity.ts";
 import {
   SUPERVISOR_PRESSURE_SCHEMA_VERSION,
@@ -58,12 +52,7 @@ import type {
 } from "./ledger-state.ts";
 import { SupervisorLogCollector } from "./log-feed.ts";
 import { collectServiceHealth } from "./services.ts";
-import {
-  installedSupervisorBuild,
-  readSupervisorStatus,
-  type SupervisorProcessDependencies,
-  supervisorProcessLiveness,
-} from "./status.ts";
+import { readSupervisorStatus } from "./status.ts";
 import {
   readSupervisorFindings,
   readSupervisorHistory,
@@ -80,14 +69,6 @@ const SUPERVISOR_MIN_IDLE_EXIT_MS = 5_000;
 const SUPERVISOR_MAX_IDLE_EXIT_MS = 24 * 60 * 60_000;
 const LIVE_DISPLAY_SWEEP_INTERVAL_MS = 5 * 60_000;
 
-interface SupervisorLease {
-  pid: number;
-  start_token?: string;
-  host: string;
-  nonce: string;
-  created_at: string;
-}
-
 export interface RunSupervisorInput {
   coordRoot: string;
   intervalMs?: number;
@@ -108,12 +89,10 @@ export async function spawnSupervisor(
 ): Promise<SupervisorStatus> {
   const coordRoot = resolve(coordRootRaw);
   const current = readSupervisorStatus(coordRoot);
-  if (current.liveness === "unknown") throw unknownOwnerError();
-  if (current.liveness === "running") {
-    throw new Error(`local supervisor is already running under pid ${current.record?.pid}`);
-  }
+  if (current.liveness !== "stopped") throw startRefusal(current.record?.pid, current.liveness);
   const paths = supervisorPaths(coordRoot);
-  assertLeaseAvailable(paths.lease);
+  const lease = serviceLeaseOwner(paths.lease);
+  if (lease.liveness !== "stopped") throw startRefusal(lease.lease?.pid, lease.liveness);
   await stopLegacyResourceObserver(coordRoot);
   const intervalMs = normalizeInterval(options.intervalMs);
   const idleExitMs = normalizeIdleExit(options.idleExitMs);
@@ -179,44 +158,21 @@ export async function ensureSupervisorRunning(coordRoot: string): Promise<Ensure
   }
 }
 
-export interface SupervisorStopResult extends SupervisorStatus {
-  signal_sent: boolean;
-  signal_verdict: ProcessGenerationVerdict;
-}
+export type SupervisorStopResult = SupervisorStatus & ServiceStopFields;
 
+/** Windows has no graceful SIGTERM, so the durable request alone stops it there. */
 export function requestSupervisorStop(
   coordRootRaw: string,
-  dependencies: SupervisorProcessDependencies & ProcessGenerationSignalDependencies = {},
+  dependencies: ServiceProcessDependencies = {},
 ): SupervisorStopResult {
   const coordRoot = resolve(coordRootRaw);
-  const paths = supervisorPaths(coordRoot);
-  const status = readSupervisorStatus(coordRoot, Date.now(), dependencies);
-  mkdirSync(paths.root, { recursive: true, mode: stateDirMode() });
-  writePrivateJsonAtomic(paths.stop, {
-    requested_at: new Date().toISOString(),
-    requested_by_pid: process.pid,
-  });
   const legacyPaths = resourcePaths(coordRoot);
   if (existsSync(legacyPaths.service) || existsSync(legacyPaths.lease))
     requestResourceServiceStop(coordRoot, dependencies);
-  let signal = { sent: false, verdict: status.generation };
-  if (
-    status.liveness === "running" &&
-    status.record?.host === hostname() &&
-    process.platform !== "win32"
-  ) {
-    signal = signalIfSameGeneration(
-      status.record.pid,
-      status.record.start_token,
-      "SIGTERM",
-      dependencies,
-    );
-  }
-  return {
-    ...readSupervisorStatus(coordRoot, Date.now(), dependencies),
-    signal_sent: signal.sent,
-    signal_verdict: signal.verdict,
-  };
+  const read = () => readSupervisorStatus(coordRoot, Date.now(), dependencies);
+  return requestServiceStop(read(), read, supervisorPaths(coordRoot).stop, dependencies, {
+    signal: process.platform !== "win32",
+  });
 }
 
 export async function runSupervisor(
@@ -224,17 +180,14 @@ export async function runSupervisor(
 ): Promise<SupervisorServiceStatusRecord> {
   const coordRoot = resolve(input.coordRoot);
   const current = readSupervisorStatus(coordRoot);
-  if (current.liveness === "unknown") throw unknownOwnerError();
-  if (current.liveness === "running") {
-    throw new Error(`local supervisor is already running under pid ${current.record?.pid}`);
-  }
+  if (current.liveness !== "stopped") throw startRefusal(current.record?.pid, current.liveness);
   const paths = supervisorPaths(coordRoot);
   const intervalMs = normalizeInterval(input.intervalMs);
   const idleExitMs = normalizeIdleExit(input.idleExitMs);
   const keepAlive = input.keepAlive ?? false;
   const now = input.now ?? (() => new Date());
   const wait = input.wait ?? delay;
-  const lease = acquireLease(coordRoot, now());
+  const lease = acquireServiceLease(paths.lease, startRefusal);
   rmSync(paths.stop, { force: true });
   const startedAt = now().toISOString();
   const startToken = processStartToken(process.pid);
@@ -242,7 +195,7 @@ export async function runSupervisor(
     schema_version: SUPERVISOR_STATUS_SCHEMA_VERSION,
     pid: process.pid,
     ...(startToken ? { start_token: startToken } : {}),
-    running_build: installedSupervisorBuild(),
+    running_build: installedHarneryBuild(),
     host: hostname(),
     nonce: lease.nonce,
     state: "starting",
@@ -488,7 +441,7 @@ export async function runSupervisor(
     try {
       await closeProcessLoggers();
     } finally {
-      releaseLease(paths.lease, lease.nonce);
+      lease.release();
     }
   }
   return status;
@@ -533,44 +486,6 @@ function observeLedgerControlState(
   }
 }
 
-function acquireLease(coordRoot: string, now: Date): SupervisorLease {
-  const paths = supervisorPaths(coordRoot);
-  mkdirSync(paths.root, { recursive: true, mode: stateDirMode() });
-  for (let attempt = 0; attempt < 2; attempt++) {
-    const startToken = processStartToken(process.pid);
-    const lease: SupervisorLease = {
-      pid: process.pid,
-      ...(startToken ? { start_token: startToken } : {}),
-      host: hostname(),
-      nonce: randomUUID(),
-      created_at: now.toISOString(),
-    };
-    try {
-      const fd = openSync(paths.lease, "wx", stateFileMode());
-      try {
-        writeFileSync(fd, `${JSON.stringify(lease)}\n`, "utf8");
-      } finally {
-        closeSync(fd);
-      }
-      return lease;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-      const existing = readLease(paths.lease);
-      const liveness = existing ? leaseIsLive(existing) : "unknown";
-      if (liveness === "unknown") throw unknownOwnerError();
-      if (existing && liveness === "running") {
-        throw new Error(`local supervisor lease is held by pid ${existing.pid}`);
-      }
-      try {
-        unlinkSync(paths.lease);
-      } catch {
-        // A concurrent starter may have replaced or removed the stale lease.
-      }
-    }
-  }
-  throw new Error("local supervisor could not acquire its singleton lease");
-}
-
 function pruneProjectionDirectory(
   directory: string,
   retainedFindingIds: ReadonlySet<string>,
@@ -582,49 +497,12 @@ function pruneProjectionDirectory(
   }
 }
 
-function releaseLease(path: string, nonce: string): void {
-  const current = readLease(path);
-  if (current?.nonce !== nonce) return;
-  try {
-    unlinkSync(path);
-  } catch {
-    // A missing lease is already released.
-  }
-}
-
-function readLease(path: string): SupervisorLease | undefined {
-  try {
-    const value = JSON.parse(readFileSync(path, "utf8")) as SupervisorLease;
-    return value &&
-      Number.isSafeInteger(value.pid) &&
-      value.pid > 0 &&
-      typeof value.host === "string" &&
-      value.host.length > 0 &&
-      typeof value.nonce === "string" &&
-      value.nonce.length > 0
-      ? value
-      : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function leaseIsLive(lease: SupervisorLease): SupervisorStatus["liveness"] {
-  return supervisorProcessLiveness(lease).liveness;
-}
-
-function assertLeaseAvailable(path: string): void {
-  if (!existsSync(path)) return;
-  const lease = readLease(path);
-  const liveness = lease ? leaseIsLive(lease) : "unknown";
-  if (liveness === "unknown") throw unknownOwnerError();
-  if (liveness === "running")
-    throw new Error(`local supervisor lease is held by pid ${lease?.pid}`);
-}
-
-function unknownOwnerError(): Error {
-  return new Error(
-    `local supervisor process identity is unknown; run ${resolveBinName()} supervisor stop to write the durable stop request before starting again`,
+function startRefusal(pid: number | undefined, liveness: ServiceLiveness): Error {
+  return serviceStartRefusal(
+    "local supervisor",
+    `${resolveBinName()} supervisor stop`,
+    pid,
+    liveness,
   );
 }
 

package/src/core/supervisor/services.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { hostname } from "node:os";
 import { join } from "node:path";
-import { checkPidToken, processStartToken } from "../agents/state/proc-start.ts";
+import { processStartToken, verifyProcessGeneration } from "../agents/state/proc-start.ts";
 import { readGovernorServiceStatus } from "../governor/service-read.ts";
 import { writePrivateJsonAtomic } from "../storage/atomic-json.ts";
 import {
@@ -105,7 +105,7 @@ function consumerAlive(record: SupervisorConsumerRecord): boolean {
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== "EPERM") return false;
   }
-  return checkPidToken(record.pid, record.start_token) !== "mismatch";
+  return verifyProcessGeneration(record.pid, record.start_token) !== "different";
 }
 
 interface DetachedServiceRecord {

package/src/core/supervisor/status.ts

@@ -1,14 +1,11 @@
-import { existsSync, readFileSync } from "node:fs";
-import { hostname } from "node:os";
-import { join } from "node:path";
+import { existsSync } from "node:fs";
 import {
-  type ProcessGenerationVerdict,
-  verifyProcessGeneration,
-} from "../agents/state/proc-start.ts";
-import { currentHarneryRuntimeBuild, harneryPackageRoot } from "../events/v3/runtime-build.ts";
+  observeServiceProcess,
+  type ServiceProcessDependencies,
+} from "../agents/state/service-process.ts";
+import { serviceBuildStatus } from "../events/v3/runtime-build.ts";
 import {
   SUPERVISOR_STATUS_SCHEMA_VERSION,
-  type SupervisorBuild,
   type SupervisorServiceStatusRecord,
   type SupervisorStatus,
 } from "./contract.ts";
@@ -16,49 +13,14 @@ import { readSupervisorServiceRecord, supervisorPaths } from "./storage.ts";
 
 const STALE_HEARTBEAT_MS = 15_000;
 
-export interface SupervisorProcessDependencies {
-  readToken?: (pid: number) => string | null;
-  probePid?: (pid: number) => unknown;
-}
-
-export function installedSupervisorBuild(): SupervisorBuild {
-  let version = "unknown";
-  let revision = "unknown";
-  try {
-    const pkg = JSON.parse(readFileSync(join(harneryPackageRoot(), "package.json"), "utf8"));
-    if (typeof pkg.version === "string") version = pkg.version;
-    revision = currentHarneryRuntimeBuild();
-  } catch {
-    // Missing build evidence must still produce an inspectable status.
-  }
-  return { version, revision };
-}
-
 export function readSupervisorStatus(
   coordRoot: string,
   nowMs = Date.now(),
-  dependencies: SupervisorProcessDependencies = {},
+  dependencies: ServiceProcessDependencies = {},
 ): SupervisorStatus {
   const paths = supervisorPaths(coordRoot);
   const record = readSupervisorServiceRecord(coordRoot);
-  const installedBuild = installedSupervisorBuild();
-  const runningBuild = validBuild(record?.running_build) ? record.running_build : null;
-  const restartNeeded =
-    !runningBuild ||
-    installedBuild.version === "unknown" ||
-    installedBuild.revision === "unknown" ||
-    runningBuild.version !== installedBuild.version ||
-    runningBuild.revision !== installedBuild.revision;
-  const build = {
-    running_build: runningBuild,
-    installed_build: installedBuild,
-    restart_needed: restartNeeded,
-    build_status: !runningBuild
-      ? "running build unknown; restart needed"
-      : restartNeeded
-        ? "restart needed"
-        : "current",
-  };
+  const build = serviceBuildStatus(record?.running_build);
   if (!validRecord(record)) {
     return {
       running: false,
@@ -72,13 +34,11 @@ export function readSupervisorStatus(
   }
   const heartbeatAt = Date.parse(record.heartbeat_at);
   const stale = !Number.isFinite(heartbeatAt) || nowMs - heartbeatAt > STALE_HEARTBEAT_MS;
-  const owner = supervisorProcessLiveness(record, dependencies);
-  const liveness =
-    owner.generation === "same" && record.state === "stopped" ? "stopped" : owner.liveness;
+  const { generation, liveness } = observeServiceProcess(record, dependencies);
   return {
-    running: liveness === "running" && !stale && record.state !== "stopped",
+    running: liveness === "running" && !stale,
     stale,
-    generation: owner.generation,
+    generation,
     liveness,
     ...build,
     record,
@@ -99,38 +59,3 @@ function validRecord(
     typeof value.keep_alive === "boolean"
   );
 }
-
-/** A stale heartbeat does not prove that a process has exited. */
-export function supervisorProcessLiveness(
-  owner: { pid: number; host: string; start_token?: string },
-  dependencies: SupervisorProcessDependencies = {},
-): { liveness: SupervisorStatus["liveness"]; generation: ProcessGenerationVerdict } {
-  if (owner.host !== hostname()) return { liveness: "unknown", generation: "unknown" };
-  try {
-    (dependencies.probePid ?? ((pid) => process.kill(pid, 0)))(owner.pid);
-  } catch (error) {
-    return {
-      liveness: (error as NodeJS.ErrnoException).code === "ESRCH" ? "stopped" : "unknown",
-      generation: "unknown",
-    };
-  }
-  const generation = verifyProcessGeneration(owner.pid, owner.start_token, dependencies.readToken);
-  return {
-    generation,
-    liveness:
-      generation === "same" ? "running" : generation === "different" ? "stopped" : "unknown",
-  };
-}
-
-function validBuild(value: unknown): value is SupervisorBuild {
-  if (!value || typeof value !== "object") return false;
-  const build = value as Partial<SupervisorBuild>;
-  return (
-    typeof build.version === "string" &&
-    !!build.version &&
-    build.version !== "unknown" &&
-    typeof build.revision === "string" &&
-    !!build.revision &&
-    build.revision !== "unknown"
-  );
-}

package/src/core/workflow/engine.ts

@@ -53,8 +53,8 @@ import {
   normalizeWorkflowMeta,
   writeWorkflowProof,
 } from "./proof.ts";
+import { acquireWorkflowResumeLease } from "./resume-lock.ts";
 import {
-  acquireWorkflowResumeLease,
   assertWorkflowRunResumable,
   assertWorkflowScriptUnchanged,
   WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION,

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/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,
@@ -399,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({
@@ -528,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) {
@@ -564,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,
@@ -577,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,
@@ -633,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,