@brainervirus/workit-core 2.1.5 → 2.2.1

package/src/core/task-store.ts

@@ -1,7 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs";
-import { hostname } from "node:os";
 import path from "node:path";
 import * as z from "zod";
 import { packageRoot } from "./package-root";
@@ -17,6 +16,7 @@ import {
   intentSchema,
   newId,
   newRevision,
+  parseStoredRecord,
   provenanceSchema,
   refSchema,
   sha256,
@@ -33,6 +33,41 @@ import {
   type Utc,
   type WorkspaceRecord,
 } from "./task-contract";
+import {
+  classifyLockOwner,
+  defaultLockTimeout,
+  localLockHost,
+  clearAbandonedReclaimGuard,
+  parseMetadataLock,
+  parseMetadataLockOrNull,
+  processStartOf,
+  sameMetadataLock,
+  type MetadataLock,
+} from "./store-lock";
+
+export type { MetadataLock } from "./store-lock";
+/** Recovery copies kept per record (task or workspace); older copies are pruned. */
+export const RECOVERY_COPIES_PER_RECORD = 3;
+/** A temp file older than this was left by a crashed writer. */
+const STALE_TEMPORARY_MS = 60 * 60_000;
+const RECOVERY_NAME = /^(task|workspace)\.([^.]+)\.([0-9a-f]{64})\.json$/;
+export type GarbageReport = {
+  dryRun: boolean;
+  recovery: { removed: number; removedBytes: number; kept: number };
+  temporary: { removed: number };
+  candidates: {
+    removed: number;
+    tasks: Id[];
+    skippedActive: Id[];
+    skippedClosed: Id[];
+    failed: Id[];
+  };
+};
+export type TaskStoreOptions = {
+  /** Total time a mutation retries a lock held by a live writer before `busy`
+   * (default: `defaultLockTimeout()`, short for in-process hosts). */
+  lockTimeoutMs?: number;
+};
 
 export type MutationContext = { now: Utc; revision: Revision };
 export type TaskMutation = (task: TaskRecord, context: MutationContext) => Result<TaskRecord>;
@@ -72,13 +107,6 @@ export type RecoveryInput = {
     writer: WorkspaceRecord["writer"],
   ) => Result<ProcessEvidence>;
 };
-export type MetadataLock = {
-  pid: number;
-  processStart: string | null;
-  host: string;
-  nonce: string;
-  externalAction?: true;
-};
 export type ProcessEvidence = {
   state: "stopped" | "accounted_for";
   pid: number;
@@ -96,15 +124,6 @@ const processEvidenceSchema = z
       .nullable(),
   })
   .strict();
-const metadataLockSchema = z
-  .object({
-    pid: z.number().int().nonnegative().safe(),
-    processStart: z.string().nullable(),
-    host: z.string().min(1),
-    nonce: z.string().min(1),
-    externalAction: z.literal(true).optional(),
-  })
-  .strict();
 /** One task's listing facts, kept in `.workit/index.json` so per-turn host
  * hooks can find a session's task without parsing every full record. */
 export type TaskIndexEntry = {
@@ -224,22 +243,6 @@ const isObject = (value: unknown): value is Record<string, unknown> =>
 const validId = (value: string): boolean =>
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value);
 const validDigest = (value: string): boolean => /^[0-9a-f]{64}$/.test(value);
-const parseMetadataLock = (raw: string): MetadataLock => {
-  let value: unknown;
-  try {
-    value = JSON.parse(raw);
-  } catch {
-    throw Object.assign(new Error("metadata lock is invalid"), { code: "metadata_lock_invalid" });
-  }
-  const parsed = metadataLockSchema.safeParse(value);
-  if (!parsed.success)
-    throw Object.assign(new Error("metadata lock is invalid"), { code: "metadata_lock_invalid" });
-  return parsed.data;
-};
-const sameMetadataLock = (left: unknown, right: MetadataLock): boolean => {
-  const parsed = metadataLockSchema.safeParse(left);
-  return parsed.success && canonicalJson(parsed.data) === canonicalJson(right);
-};
 export const sameDirectoryIdentity = (left: string, right: string): boolean => {
   if (!path.isAbsolute(left) || !path.isAbsolute(right)) return false;
   const normalizedLeft = path.resolve(left);
@@ -268,13 +271,49 @@ export const sameDirectoryIdentity = (left: string, right: string): boolean => {
   }
 };
 type LockSnapshot = { raw: string; data: MetadataLock };
+const TRANSIENT_WINDOWS_CODES = new Set(["EPERM", "EACCES", "EBUSY"]);
+/** Windows briefly refuses to replace or open a file that another process is
+ * reading or renaming at that instant. That is contention, not damage: retry
+ * for about a second before surfacing the error. */
+const isTransientWindowsError = (error: unknown): boolean => {
+  if (process.platform !== "win32") return false;
+  const code = (error as { code?: unknown } | null)?.code;
+  return typeof code === "string" && TRANSIENT_WINDOWS_CODES.has(code);
+};
+const retryTransient = <T>(run: () => T): T => {
+  if (process.platform !== "win32") return run();
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return run();
+    } catch (error) {
+      if (attempt >= 20 || !isTransientWindowsError(error)) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5 * (attempt + 1));
+    }
+  }
+};
 const externalActionLockRoots = new AsyncLocalStorage<ReadonlySet<string>>();
+/** Roots whose metadata lock this process holds; waiting on them can only time out. */
+const heldInProcess = new Map<string, number>();
+const holdRoot = (root: string) => heldInProcess.set(root, (heldInProcess.get(root) ?? 0) + 1);
+const dropRoot = (root: string) => {
+  const count = (heldInProcess.get(root) ?? 1) - 1;
+  if (count > 0) heldInProcess.set(root, count);
+  else heldInProcess.delete(root);
+};
+
+/** Drop earlier copies of a repeated candidate ID; content is identical by ID. */
+const dedupeCandidates = (candidates: TaskRecord["candidates"]): TaskRecord["candidates"] => {
+  const last = new Map(candidates.map((candidate, index) => [candidate.id, index]));
+  return candidates.filter((candidate, index) => last.get(candidate.id) === index);
+};
 
 export class TaskStore {
   readonly root: string;
+  private readonly lockTimeoutMs: number;
 
-  constructor(root: string) {
+  constructor(root: string, options: TaskStoreOptions = {}) {
     this.root = fs.existsSync(root) ? fs.realpathSync(root) : path.resolve(root);
+    this.lockTimeoutMs = options.lockTimeoutMs ?? defaultLockTimeout();
   }
 
   readTask(taskId: Id): Result<TaskRecord> {
@@ -664,7 +703,8 @@ export class TaskStore {
       const current = this.readWorkspace();
       if (!current.ok) return current;
       if (!current.data) return failure("not_found", "workspace not found");
-      if (current.data.revision !== expected) return this.conflict(expected, current.data.revision);
+      if (current.data.revision !== expected)
+        return this.workspaceConflict(expected, current.data.revision);
       const previousBytes = this.snapshotBytes(this.workspacePath);
       if (!previousBytes)
         return failure("storage_error", "workspace snapshot disappeared during mutation");
@@ -702,7 +742,7 @@ export class TaskStore {
       if (!expected) return failure("invalid_input", "task revision is required");
       if (task.data.revision !== expected) return this.conflict(expected, task.data.revision);
       if (workspace.data.revision !== input.expectedWorkspaceRevision)
-        return this.conflict(input.expectedWorkspaceRevision, workspace.data.revision);
+        return this.workspaceConflict(input.expectedWorkspaceRevision, workspace.data.revision);
       const previousWorkspaceBytes = this.snapshotBytes(this.workspacePath);
       const previousTaskBytes = this.snapshotBytes(this.taskPath(input.taskId));
       if (!previousWorkspaceBytes || !previousTaskBytes)
@@ -792,7 +832,7 @@ export class TaskStore {
     try {
       const candidates: RecoveryCandidate[] = [];
       for (const name of fs.readdirSync(this.recoveryDir)) {
-        const match = /^(task|workspace)\.([^.]+)\.([0-9a-f]{64})\.json$/.exec(name);
+        const match = RECOVERY_NAME.exec(name);
         if (match)
           candidates.push({
             target: match[1] as "task" | "workspace",
@@ -853,8 +893,8 @@ export class TaskStore {
       }
       const selectedRecord =
         target === "workspace"
-          ? this.parseBytes<WorkspaceRecord>(selectedBytes, workspaceRecordSchema)
-          : this.parseBytes<TaskRecord>(selectedBytes, taskRecordSchema);
+          ? this.parseBytes<WorkspaceRecord>(selectedBytes, workspaceRecordSchema, "rewrite")
+          : this.parseBytes<TaskRecord>(selectedBytes, taskRecordSchema, "rewrite");
       if (!selectedRecord.ok) return selectedRecord;
       if (target === "workspace") {
         const parsed = selectedRecord as Result<WorkspaceRecord>;
@@ -914,13 +954,17 @@ export class TaskStore {
               return this.conflict(input.expectedWorkspaceRevision, currentWorkspace.data.revision);
           }
           if (target === "workspace") {
-            const parsed = this.parseBytes<WorkspaceRecord>(selectedBytes, workspaceRecordSchema);
+            const parsed = this.parseBytes<WorkspaceRecord>(
+              selectedBytes,
+              workspaceRecordSchema,
+              "rewrite",
+            );
             if (!parsed.ok) return parsed;
             const value = { ...parsed.data, revision: newRevision(), writer: null };
             const replaced = this.replaceSnapshot(file, value, reacquiredBytes);
             return replaced.ok ? success(value.revision, value.revision, value) : replaced;
           }
-          const parsed = this.parseBytes<TaskRecord>(selectedBytes, taskRecordSchema);
+          const parsed = this.parseBytes<TaskRecord>(selectedBytes, taskRecordSchema, "rewrite");
           if (!parsed.ok) return parsed;
           const value = {
             ...parsed.data,
@@ -932,6 +976,7 @@ export class TaskStore {
           return replaced.ok ? success(value.revision, null, value) : replaced;
         },
         this.recoveryLockOptions(lock.data, evidence.data, recoveryGate),
+        "recovery_required",
       );
       return result;
     } catch (error) {
@@ -989,24 +1034,76 @@ export class TaskStore {
     }
   }
 
+  /**
+   * Mutation lock: a holder that is gone (dead pid, reused pid, or a foreign or
+   * unreadable lock past its TTL) is reclaimed; a live holder is waited on
+   * briefly and then reported as retryable `busy`.
+   */
   private metadataLockOptions(): FileLockSyncAcquireOptions<MetadataLock> {
+    const inProcess = heldInProcess.has(this.root);
     return {
       lockPath: this.lockPath,
       staleMs: Number.MAX_SAFE_INTEGER,
-      timeoutMs: 0,
-      retry: { retries: 0 },
-      staleRecovery: "fail-closed",
-      shouldReclaim: () => false,
-      parsePayload: parseMetadataLock,
+      timeoutMs: inProcess ? 0 : this.lockTimeoutMs,
+      retry: inProcess
+        ? { retries: 0 }
+        : { minTimeout: 5, maxTimeout: 100, factor: 1.5, randomize: true },
+      staleRecovery: "remove-if-unchanged",
+      shouldReclaim: ({ payload, nowMs }) => {
+        let ageMs: number | null = null;
+        try {
+          ageMs = nowMs - fs.lstatSync(this.lockPath).mtimeMs;
+        } catch {}
+        return classifyLockOwner(payload, ageMs).state === "stale";
+      },
+      // The library re-checks the bytes before removal, so a lock replaced
+      // after classification is never deleted.
+      shouldRemoveStaleLock: () => true,
+      parsePayload: parseMetadataLockOrNull,
       payload: () => ({
         pid: process.pid,
-        processStart: this.processStart(process.pid),
-        host: hostname(),
+        processStart: processStartOf(process.pid),
+        host: localLockHost(),
         nonce: randomUUID(),
       }),
     };
   }
 
+  private acquireMetadataLock(
+    options: FileLockSyncAcquireOptions<MetadataLock>,
+  ): FileLockSyncHandle {
+    clearAbandonedReclaimGuard(this.lockPath);
+    // One budget for the whole acquisition: a lost reclaim race retries with
+    // the remaining time, never a fresh timeout.
+    const deadline = Date.now() + (options.timeoutMs ?? 0);
+    while (true) {
+      try {
+        return acquireFileLockSync(this.workspacePath, {
+          ...options,
+          timeoutMs: Math.max(0, deadline - Date.now()),
+        });
+      } catch (error) {
+        // Losing a reclaim race to another process, or Windows refusing the
+        // lock file while another process opens or deletes it, is contention.
+        const code = (error as { code?: unknown })?.code;
+        if (
+          (code !== "file_lock_stale" && !isTransientWindowsError(error)) ||
+          Date.now() >= deadline
+        )
+          throw error;
+        // Windows also denies the create while a just-released lock is still
+        // pending delete, and that entry is already invisible to lstat. So a
+        // denial with no visible holder is told apart by probing whether the
+        // directory accepts a new file: if it does not, this is a permission
+        // problem (read-only attribute, ACL) and fails fast.
+        if (code !== "file_lock_stale" && !this.lockHolderPresent() && !this.lockDirWritable())
+          throw error;
+        if (code !== "file_lock_stale")
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+      }
+    }
+  }
+
   private externalActionLockOptions(): FileLockSyncAcquireOptions<MetadataLock> {
     const options = this.metadataLockOptions();
     return { ...options, payload: () => ({ ...options.payload(), externalAction: true }) };
@@ -1032,10 +1129,11 @@ export class TaskStore {
     }
     let handle: FileLockSyncHandle;
     try {
-      handle = acquireFileLockSync(this.workspacePath, this.externalActionLockOptions());
+      handle = this.acquireMetadataLock(this.externalActionLockOptions());
     } catch (error) {
       return this.lockFailure(error);
     }
+    holdRoot(this.root);
     let result: Result<T>;
     try {
       if (!handle.verifyStillHeld())
@@ -1072,8 +1170,9 @@ export class TaskStore {
         path: this.lockPath,
       });
     }
+    dropRoot(this.root);
     try {
-      handle.release();
+      retryTransient(() => handle.release());
     } catch (error) {
       const released = this.lockFailure(error);
       const releaseError = released.ok ? "metadata lock release failed" : released.error;
@@ -1097,6 +1196,9 @@ export class TaskStore {
     gate: { reclaimed: boolean },
   ): FileLockSyncAcquireOptions<MetadataLock> {
     const options = this.metadataLockOptions();
+    options.timeoutMs = 0;
+    options.retry = { retries: 0 };
+    options.parsePayload = parseMetadataLock;
     options.staleRecovery = "remove-if-unchanged";
     options.shouldReclaim = ({ payload }) =>
       Boolean(
@@ -1127,6 +1229,7 @@ export class TaskStore {
   private withLock<T>(
     operation: (handle: FileLockSyncHandle) => Result<T>,
     options: FileLockSyncAcquireOptions<MetadataLock> = this.metadataLockOptions(),
+    contention: "busy" | "recovery_required" = "busy",
   ): Result<T> {
     try {
       this.initializeMutationStorage();
@@ -1141,10 +1244,11 @@ export class TaskStore {
       "metadata lock operation did not produce a result",
     );
     try {
-      handle = acquireFileLockSync(this.workspacePath, options);
+      handle = this.acquireMetadataLock(options);
     } catch (error) {
-      result = this.lockFailure(error);
+      result = this.lockFailure(error, contention);
     }
+    if (handle) holdRoot(this.root);
     if (handle) {
       try {
         if (!handle.verifyStillHeld())
@@ -1163,8 +1267,9 @@ export class TaskStore {
       }
     }
     if (handle) {
+      dropRoot(this.root);
       try {
-        handle.release();
+        retryTransient(() => handle.release());
       } catch (error) {
         const releaseFailure = this.lockFailure(error);
         const releaseError = releaseFailure.ok
@@ -1178,16 +1283,72 @@ export class TaskStore {
     return result;
   }
 
-  private lockFailure(error: unknown): Result<never> {
+  /** Whether the lock's directory accepts a new file right now. */
+  private lockDirWritable(): boolean {
+    const probe = `${this.lockPath}.${process.pid}.${randomUUID()}.probe`;
+    try {
+      fs.closeSync(fs.openSync(probe, "wx", 0o600));
+    } catch {
+      return false;
+    }
+    try {
+      fs.rmSync(probe, { force: true });
+    } catch {}
+    return true;
+  }
+
+  /** A lock file (or an entry Windows is still tearing down) exists. */
+  private lockHolderPresent(): boolean {
+    try {
+      fs.lstatSync(this.lockPath);
+      return true;
+    } catch (error) {
+      return (error as { code?: unknown } | null)?.code !== "ENOENT";
+    }
+  }
+
+  private lockFailure(
+    error: unknown,
+    contention: "busy" | "recovery_required" = "busy",
+  ): Result<never> {
     const value = error as { code?: unknown; message?: unknown };
     const code = typeof value?.code === "string" ? value.code : "";
-    if (code === "EEXIST" || code === "file_lock_timeout") {
-      const lock = this.readLockSnapshot();
-      if (lock.ok && lock.data?.data.externalAction)
+    // A sharing-class denial is contention only when someone holds the lock.
+    if (isTransientWindowsError(error) && !this.lockHolderPresent() && !this.lockDirWritable())
+      return failure(
+        "storage_error",
+        `cannot create the workspace metadata lock (${code}); no other Workit call holds it`,
+        {
+          path: this.lockPath,
+          guidance: `Check permissions and the read-only attribute on ${path.dirname(this.lockPath)}.`,
+        },
+      );
+    if (
+      code === "EEXIST" ||
+      code === "file_lock_timeout" ||
+      code === "file_lock_stale" ||
+      isTransientWindowsError(error)
+    ) {
+      let lock: MetadataLock | null = null;
+      try {
+        lock = parseMetadataLockOrNull(fs.readFileSync(this.lockPath, "utf8"));
+      } catch {}
+      if (lock?.externalAction)
         return failure("writer_conflict", "workspace is reserved by a managed external action", {
           outcome: "not_started",
           path: this.lockPath,
         });
+      if (contention === "busy")
+        return failure(
+          "busy",
+          `workspace metadata lock is held by another Workit call${lock ? ` (pid ${lock.pid} on ${lock.host})` : ""}; retry shortly`,
+          {
+            outcome: "not_started",
+            path: this.lockPath,
+            guidance:
+              "Retry the same call. If it stays busy, run `workit doctor --fix-lock` to clear a lock left by a dead process.",
+          },
+        );
     }
     const recovery =
       code === "EEXIST" ||
@@ -1204,9 +1365,16 @@ export class TaskStore {
   }
 
   private initializeMutationStorage() {
-    fs.mkdirSync(this.tasksDir, { recursive: true });
-    fs.mkdirSync(this.recoveryDir, { recursive: true });
-    fs.writeFileSync(this.gitignorePath, "*\n");
+    retryTransient(() => fs.mkdirSync(this.tasksDir, { recursive: true }));
+    retryTransient(() => fs.mkdirSync(this.recoveryDir, { recursive: true }));
+    // Rewriting an unchanged .gitignore on every call makes concurrent
+    // writers collide on it (Windows sharing violations); write it only when
+    // it is missing or different.
+    let current: string | null = null;
+    try {
+      current = retryTransient(() => fs.readFileSync(this.gitignorePath, "utf8"));
+    } catch {}
+    if (current !== "*\n") retryTransient(() => fs.writeFileSync(this.gitignorePath, "*\n"));
   }
 
   private replaceSnapshot(file: string, value: unknown, previous: unknown): Result<any> {
@@ -1224,7 +1392,7 @@ export class TaskStore {
       } finally {
         fs.closeSync(fd);
       }
-      fs.renameSync(temporary, file);
+      retryTransient(() => fs.renameSync(temporary!, file));
       temporary = undefined;
       this.fsyncDirectory(path.dirname(file));
       if (path.dirname(file) === this.tasksDir) this.indexTaskWrite(file, value as TaskRecord);
@@ -1283,7 +1451,7 @@ export class TaskStore {
         }),
         { mode: 0o600, flag: "wx" },
       );
-      fs.renameSync(temporary, this.indexPath);
+      retryTransient(() => fs.renameSync(temporary, this.indexPath));
     } catch {
       try {
         fs.unlinkSync(temporary);
@@ -1308,8 +1476,13 @@ export class TaskStore {
     const id = target === "task" ? path.basename(file, ".json") : "workspace";
     const destination = path.join(this.recoveryDir, `${target}.${id}.${digestBytes(bytes)}.json`);
     if (fs.existsSync(destination)) {
-      if (digestBytes(fs.readFileSync(destination)) === digestBytes(bytes)) return;
-      throw new Error("recovery copy already exists with different bytes");
+      if (digestBytes(retryTransient(() => fs.readFileSync(destination))) !== digestBytes(bytes))
+        throw new Error("recovery copy already exists with different bytes");
+      // Re-saved bytes are the newest copy again for pruning purposes.
+      const stamp = new Date();
+      retryTransient(() => fs.utimesSync(destination, stamp, stamp));
+      this.pruneRecovery(`${target}.${id}.`, destination);
+      return;
     }
     let temporary: string | undefined;
     try {
@@ -1321,9 +1494,10 @@ export class TaskStore {
       } finally {
         fs.closeSync(fd);
       }
-      fs.renameSync(temporary, destination);
+      retryTransient(() => fs.renameSync(temporary!, destination));
       temporary = undefined;
       this.fsyncDirectory(this.recoveryDir);
+      this.pruneRecovery(`${target}.${id}.`, destination);
     } finally {
       if (temporary)
         try {
@@ -1332,6 +1506,144 @@ export class TaskStore {
     }
   }
 
+  /**
+   * Keep the newest RECOVERY_COPIES_PER_RECORD copies of one record (always
+   * including `keep`, the copy just written). Pruning is best-effort: a
+   * failure never fails the mutation that triggered it.
+   */
+  private pruneRecovery(prefix: string, keep: string) {
+    try {
+      const copies = this.recoveryCopies(prefix);
+      const surplus = this.surplusCopies(copies, path.basename(keep));
+      for (const copy of surplus) fs.rmSync(copy.path, { force: true });
+    } catch {}
+  }
+
+  private recoveryCopies(
+    prefix = "",
+  ): { name: string; path: string; group: string; mtimeNs: bigint }[] {
+    if (!fs.existsSync(this.recoveryDir)) return [];
+    const copies = [];
+    for (const name of fs.readdirSync(this.recoveryDir)) {
+      if (!name.startsWith(prefix)) continue;
+      const match = RECOVERY_NAME.exec(name);
+      if (!match) continue;
+      const file = path.join(this.recoveryDir, name);
+      try {
+        const stat = fs.lstatSync(file, { bigint: true });
+        if (!stat.isFile()) continue;
+        copies.push({ name, path: file, group: `${match[1]}.${match[2]}`, mtimeNs: stat.mtimeNs });
+      } catch {}
+    }
+    return copies;
+  }
+
+  /** Copies of one record beyond the cap, oldest first out; `keep` is never surplus. */
+  private surplusCopies<T extends { name: string; mtimeNs: bigint }>(copies: T[], keep?: string) {
+    const ordered = copies.toSorted((left, right) =>
+      left.name === keep
+        ? -1
+        : right.name === keep
+          ? 1
+          : left.mtimeNs === right.mtimeNs
+            ? left.name.localeCompare(right.name)
+            : left.mtimeNs > right.mtimeNs
+              ? -1
+              : 1,
+    );
+    return ordered.slice(RECOVERY_COPIES_PER_RECORD);
+  }
+
+  /**
+   * `workit gc`: prune recovery copies beyond the per-record cap, remove temp
+   * files left by crashed writers, and collapse duplicate stored candidates in
+   * paused tasks. Live records (tasks/*.json, workspace.json) are never
+   * deleted; candidate dedupe keeps every candidate ID and the latest position.
+   * Closed tasks are history and are never rewritten. A dry run is read-only:
+   * no lock, no directory creation, no .gitignore rewrite.
+   */
+  collectGarbage(options: { dryRun?: boolean } = {}): Result<GarbageReport> {
+    const dryRun = options.dryRun === true;
+    const report: GarbageReport = {
+      dryRun,
+      recovery: { removed: 0, removedBytes: 0, kept: 0 },
+      temporary: { removed: 0 },
+      candidates: { removed: 0, tasks: [], skippedActive: [], skippedClosed: [], failed: [] },
+    };
+    if (!fs.existsSync(this.workitDir)) return success(null, null, report);
+    const sweep = (): Result<null> => {
+      try {
+        const groups = new Map<string, ReturnType<TaskStore["recoveryCopies"]>>();
+        for (const copy of this.recoveryCopies())
+          groups.set(copy.group, [...(groups.get(copy.group) ?? []), copy]);
+        for (const copies of groups.values()) {
+          const surplus = this.surplusCopies(copies);
+          report.recovery.kept += copies.length - surplus.length;
+          for (const copy of surplus) {
+            report.recovery.removed += 1;
+            try {
+              report.recovery.removedBytes += fs.statSync(copy.path).size;
+            } catch {}
+            if (!dryRun) fs.rmSync(copy.path, { force: true });
+          }
+        }
+        const nowMs = Date.now();
+        for (const directory of [this.recoveryDir, this.tasksDir, this.workitDir]) {
+          if (!fs.existsSync(directory)) continue;
+          for (const name of fs.readdirSync(directory)) {
+            if (!name.endsWith(".tmp") && !name.endsWith(".probe")) continue;
+            const file = path.join(directory, name);
+            const stat = fs.lstatSync(file);
+            if (!stat.isFile() || nowMs - stat.mtimeMs <= STALE_TEMPORARY_MS) continue;
+            report.temporary.removed += 1;
+            if (!dryRun) fs.rmSync(file, { force: true });
+          }
+        }
+        return success(null, null, null);
+      } catch (error) {
+        return failure("storage_error", `garbage collection failed: ${String(error)}`, {
+          path: this.recoveryDir,
+        });
+      }
+    };
+    // withLock initializes storage (mkdir, .gitignore); a dry run must not.
+    const pruned = dryRun ? sweep() : this.withLock<null>(sweep);
+    if (!pruned.ok) return pruned;
+    const tasks = this.listTasks();
+    if (!tasks.ok) return tasks;
+    for (const task of tasks.data) {
+      const deduped = dedupeCandidates(task.candidates);
+      const removed = task.candidates.length - deduped.length;
+      if (removed === 0) continue;
+      // An active task belongs to a live session; rewriting it would bump the
+      // revision under that session's feet.
+      if (task.status === "active") {
+        report.candidates.skippedActive.push(task.id);
+        continue;
+      }
+      // Closed records are immutable history (docs/workit-v1/contracts.md).
+      if (task.status === "closed") {
+        report.candidates.skippedClosed.push(task.id);
+        continue;
+      }
+      if (!dryRun) {
+        const written = this.mutateTask(task.id, task.revision, (current) =>
+          success(current.revision, null, {
+            ...current,
+            candidates: dedupeCandidates(current.candidates),
+          }),
+        );
+        if (!written.ok) {
+          report.candidates.failed.push(task.id);
+          continue;
+        }
+      }
+      report.candidates.removed += removed;
+      report.candidates.tasks.push(task.id);
+    }
+    return success(null, null, report);
+  }
+
   private findRecovery(
     target: "task" | "workspace",
     taskId: Id | null,
@@ -1398,15 +1710,15 @@ export class TaskStore {
 
   private snapshotBytes(file: string): Buffer | null {
     try {
-      return fs.readFileSync(file);
+      return retryTransient(() => fs.readFileSync(file));
     } catch {
       return null;
     }
   }
 
-  private readRecord<T>(file: string, schema: { safeParse(value: unknown): any }) {
+  private readRecord<T>(file: string, schema: z.ZodType) {
     try {
-      const bytes = fs.readFileSync(file, "utf8");
+      const bytes = retryTransient(() => fs.readFileSync(file, "utf8"));
       return { exists: true, result: this.parseBytes<T>(bytes, schema) };
     } catch (error: any) {
       if (error?.code === "ENOENT")
@@ -1420,9 +1732,12 @@ export class TaskStore {
     }
   }
 
+  /** `rewrite` refuses a record that only parses after dropping unknown keys:
+   * recovery copies a snapshot back verbatim and must not lose its fields. */
   private parseBytes<T>(
     bytes: string | Buffer,
-    schema: { safeParse(value: unknown): any },
+    schema: z.ZodType,
+    mode: "read" | "rewrite" = "read",
   ): Result<T> {
     let value: unknown;
     try {
@@ -1432,12 +1747,24 @@ export class TaskStore {
     }
     if (isObject(value) && "schemaVersion" in value && value.schemaVersion !== SCHEMA_VERSION)
       return failure("unsupported_version", "unsupported snapshot schema version");
-    const parsed = schema.safeParse(value);
-    if (parsed.success) return success(null, null, parsed.data);
+    const parsed = parseStoredRecord(schema, value);
+    if (parsed.success && (mode === "read" || parsed.stripped.length === 0))
+      return success(null, null, parsed.data as T);
     const writerVersion =
       isObject(value) && isObject((value as { runtime?: unknown }).runtime)
         ? (value as { runtime: { updatedWith?: unknown } }).runtime.updatedWith
         : null;
+    const upgrade = `upgrade Workit before ${parsed.success ? "recovering" : "mutating"} this checkout`;
+    if (parsed.success)
+      return failure(
+        "recovery_required",
+        `snapshot carries fields this Workit cannot preserve (${parsed.stripped.join(", ")}); ${upgrade}`,
+      );
+    if (parsed.critical.length > 0)
+      return failure(
+        "recovery_required",
+        `snapshot requires fields this Workit cannot read (${parsed.critical.join(", ")}); ${upgrade}`,
+      );
     if (typeof writerVersion === "string" && isNewerVersion(writerVersion, runtimeVersion()))
       return failure(
         "recovery_required",
@@ -1446,14 +1773,6 @@ export class TaskStore {
     return failure("recovery_required", "snapshot does not satisfy its schema");
   }
 
-  private processStart(pid: number): string | null {
-    try {
-      return fs.readFileSync(`/proc/${pid}/stat`, "utf8").split(" ")[21] ?? null;
-    } catch {
-      return null;
-    }
-  }
-
   private conflict(expected: Revision, actual: Revision): Result<never> {
     return failure(
       "revision_conflict",
@@ -1465,6 +1784,14 @@ export class TaskStore {
     );
   }
 
+  private workspaceConflict(expected: Revision, actual: Revision): Result<never> {
+    return failure(
+      "revision_conflict",
+      "workspace revision does not match; omit expectedWorkspaceRevision to use the current record",
+      { expectedWorkspaceRevision: expected, actualWorkspaceRevision: actual },
+    );
+  }
+
   private taskPath(taskId: Id) {
     return path.join(this.tasksDir, `${taskId}.json`);
   }