@brainervirus/workit-core 3.0.0 → 5.0.0

package/src/core/task-store.ts

@@ -1,14 +1,39 @@
-import { createHash, randomUUID } from "node:crypto";
+// The task store (design §4.1; D3, D13, D17).
+//
+// Layout under the store directory (`<git common dir>/workit`, or
+// `<root>/.workit` outside git; see store/paths.ts):
+//
+//   store.json                       format marker (a newer format fails closed)
+//   checkouts/<slug>/workspace.json  this checkout's workspace record
+//   checkouts/<slug>/metadata.lock   checkout lock: workspace writes, task
+//                                    creation and managed external actions
+//   tasks/<id>/events.jsonl          the task's append-only event log
+//   tasks/<id>/snapshot.json         rebuildable cache of the reduced state
+//   tasks/<id>/lock                  task lock: one append at a time
+//   task-index.json                  rebuildable listing cache for hooks
+//   blobs/candidates/<sha256>.json   stored candidates, written once by content
+//   legacy/<slug>/v2/                backup of a migrated 2.x `.workit` store
+//
+// Each task mutation appends one event holding a structural patch of the
+// record, so state grows with the change, never with full-file copies, and
+// there is no recovery directory: the log is the history. `workit gc` folds
+// old events into a checkpoint. A checkout's work belongs to an implicit task
+// keyed by its branch (detached HEAD: by worktree; outside git: by directory);
+// the first mutation creates it.
+//
+// A 2.x store in `<root>/.workit` is migrated on first use (idempotent, under
+// the checkout lock, backup kept). The migrated `.workit/workspace.json` is
+// replaced by a marker that 2.x readers reject with an upgrade message.
 import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import path from "node:path";
-import * as z from "zod";
-import { packageRoot } from "./package-root";
 import {
   acquireFileLockSync,
   type FileLockSyncHandle,
   type FileLockSyncAcquireOptions,
 } from "@openclaw/fs-safe/file-lock";
+import { packageRoot } from "./package-root";
 import {
   SCHEMA_VERSION,
   canonicalJson,
@@ -18,14 +43,12 @@ import {
   newRevision,
   parseStoredRecord,
   provenanceSchema,
-  refSchema,
   sha256,
   success,
   taskRecordSchema,
   workspaceRecordSchema,
   type Id,
   type Intent,
-  type Ref,
   type Provenance,
   type Result,
   type Revision,
@@ -35,38 +58,91 @@ import {
 } from "./task-contract";
 import {
   classifyLockOwner,
+  clearAbandonedReclaimGuard,
   defaultLockTimeout,
   localLockHost,
-  clearAbandonedReclaimGuard,
-  parseMetadataLock,
   parseMetadataLockOrNull,
   processStartOf,
-  sameMetadataLock,
   type MetadataLock,
 } from "./store-lock";
+import {
+  EVENT_VERSION,
+  LogDamage,
+  appendEvent,
+  isTransientWindowsError,
+  readLog,
+  replaceFile,
+  retryTransient,
+  type EventActor,
+  type LogRead,
+  type StoreEvent,
+} from "../store/event-log";
+import { diff } from "../store/patch";
+import {
+  checkoutRootOf,
+  checkoutSlug,
+  branchRenames,
+  followRenames,
+  resolveStore,
+  resolveTaskKey,
+  type StoreLocation,
+  type TaskKey,
+} from "../store/paths";
+import {
+  OPENING_TYPES,
+  encodeOps,
+  encodeRecord,
+  eventType,
+  reduce,
+  type BlobStore,
+  type LegacyOrigin,
+  type ReducedTask,
+} from "../store/reduce";
+
+import { migrationReporterInstalled, reportMigration } from "../store/notes";
+
+/** Prefix of the `needs_input` error a read gets while a migration is pending. */
+export const MIGRATION_PENDING = "workit migration pending";
+
+export type { TaskKey } from "../store/paths";
 
-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. */
+/** The store format this runtime writes; a newer marker fails closed. */
+export const STORE_FORMAT = 3;
+/** The runtime version 2.x readers are told to upgrade to. */
+const STORE_MIN_RUNTIME = "3.0.0";
+/** A snapshot is written after this many events since the last one. */
+export const SNAPSHOT_EVERY = 32;
+/** `gc` compacts a log longer than this many events ... */
+export const COMPACT_ABOVE = 200;
+/** ... and keeps this many recent events after the checkpoint. */
+export const COMPACT_KEEP = 50;
+/** An append that leaves the log larger than this compacts it on the spot. */
+export const AUTO_COMPACT_BYTES = 2 * 1024 * 1024;
+/** readV2Workspace's answer for a 3.x marker at `.workit/workspace.json`. */
+const TOMBSTONE = Symbol("tombstone");
+/** A temp file or unreferenced blob 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 };
+  compacted: { tasks: Id[]; eventsFolded: number; bytesBefore: number; bytesAfter: number };
+  blobs: { removed: number; removedBytes: number; kept: number };
   temporary: { removed: number };
-  candidates: {
-    removed: number;
-    tasks: Id[];
-    skippedActive: Id[];
-    skippedClosed: Id[];
-    failed: Id[];
-  };
+  /** A 2.x `.workit/recovery` directory left by migration (deleted only with pruneRecovery). */
+  legacyRecovery: { path: string; files: number; bytes: number; removed: boolean } | null;
+  /** Logs another writer changed mid-compaction: left for the next run (benign). */
+  retried: 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;
+  /** Who the events are attributed to (default: WORKIT_HOST/WORKIT_SESSION_ID/WORKIT_AGENT_ID). */
+  actor?: EventActor;
+  /** Migrate a pending 2.x store on reads too (default: only when a host
+   * installed a migration reporter, i.e. the CLI; writes always migrate). */
+  migrateOnRead?: boolean;
 };
 
 export type MutationContext = { now: Utc; revision: Revision };
@@ -96,36 +172,18 @@ export type ImportInput = {
   workspaceId?: Id;
   now?: Utc;
 };
-export type RecoveryInput = {
-  expectedBytes: string;
-  snapshotDigest: string;
-  reason: string;
-  authorityRefs: Ref[];
-  expectedWorkspaceRevision: Revision;
-  processEvidence: (
-    lock: MetadataLock | null,
-    writer: WorkspaceRecord["writer"],
-  ) => Result<ProcessEvidence>;
-};
-export type ProcessEvidence = {
-  state: "stopped" | "accounted_for";
-  pid: number;
-  processStart: string | null;
-  ownerDigest: string | null;
+export type ImplicitInput = {
+  provenance: Provenance;
+  /** Objective for a task this call creates (default: names the branch). */
+  objective?: string;
+  now?: Utc;
+  /** False: only find the task, never create it. */
+  create?: boolean;
 };
-const processEvidenceSchema = z
-  .object({
-    state: z.enum(["stopped", "accounted_for"]),
-    pid: z.number().int().nonnegative(),
-    processStart: z.string().nullable(),
-    ownerDigest: z
-      .string()
-      .regex(/^[0-9a-f]{64}$/)
-      .nullable(),
-  })
-  .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 ImplicitTask = { task: TaskRecord; created: boolean; key: TaskKey };
+
+/** One task's listing facts, kept in `task-index.json` so per-turn host
+ * hooks can find a session's task without replaying every log. */
 export type TaskIndexEntry = {
   id: Id;
   revision: Revision;
@@ -137,10 +195,22 @@ export type TaskIndexEntry = {
   progress: { summary: string; nextAction: string | null };
   /** Host sessions bound to the task: the intent session (workerId null) and worker sessions. */
   sessions: { host: string; handle: string; workerId: Id | null }[];
-  /** Stat signature of the task file the entry was derived from. */
+  /** The checkout workspace the task belongs to. */
+  workspaceId: Id;
+  /** The implicit-task key (branch) the task is bound to, if any. */
+  key: string | null;
+  branch: string | null;
+  /** When the task was bound to `key`. */
+  boundAt: string | null;
+  /** Migrated from a 2.x store. */
+  legacy: boolean;
+  /** Stat signature of the task's event log the entry was derived from. */
   file: string;
 };
-const INDEX_VERSION = 1;
+const INDEX_VERSION = 3;
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
 const hostSession = (value: unknown): { host: string; handle: string } | null =>
   isObject(value) &&
   value.kind === "host" &&
@@ -148,7 +218,12 @@ const hostSession = (value: unknown): { host: string; handle: string } | null =>
   typeof value.handle === "string"
     ? { host: value.host, handle: value.handle }
     : null;
-const indexEntry = (task: TaskRecord, file: string): TaskIndexEntry => {
+const indexEntry = (
+  task: TaskRecord,
+  key: TaskKey | null,
+  legacy: boolean,
+  file: string,
+): TaskIndexEntry => {
   const sessions: TaskIndexEntry["sessions"] = [];
   const intent = hostSession(task.intent.provenance.session);
   if (intent) sessions.push({ ...intent, workerId: null });
@@ -166,12 +241,17 @@ const indexEntry = (task: TaskRecord, file: string): TaskIndexEntry => {
     source: { host: task.intent.provenance.host, kind: task.intent.provenance.kind },
     progress: { summary: task.progress.summary, nextAction: task.progress.nextAction },
     sessions,
+    workspaceId: task.workspaceId,
+    key: key?.key ?? null,
+    branch: key?.branch ?? null,
+    boundAt: key?.boundAt ?? null,
+    legacy,
     file,
   };
 };
-/** Cheap change detector. Atomic replacement can reuse inodes and file
- * timestamps are often only jiffy-granular, so a signature alone may repeat
- * across rapid rewrites; see `racySignature`. */
+
+/** Cheap change detector for a file. An append-only log changes size on
+ * every write; see `racySignature` for the timestamp-granularity caveat. */
 export const fileSignature = (file: string): string | null => {
   try {
     const stat = fs.statSync(file, { bigint: true });
@@ -191,17 +271,13 @@ export const racySignature = (signature: string): boolean => {
   return BigInt(Date.now()) * 1_000_000n - changed < RACY_WINDOW_NS;
 };
 
-export type RecoveryCandidate = {
-  target: "task" | "workspace";
-  path: string;
-  digest: string;
-};
-
 const now = (): Utc => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+const oldestFirst = (left: TaskIndexEntry, right: TaskIndexEntry): number =>
+  left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id);
 
 let cachedRuntimeVersion: string | null = null;
 /** Version of the package that hosts this runtime; recorded with state so a
- * bug report can identify the writer version without reading raw .workit. */
+ * bug report can identify the writer version without reading raw state. */
 export const runtimeVersion = (): string => {
   if (cachedRuntimeVersion === null) {
     try {
@@ -235,14 +311,8 @@ const isNewerVersion = (candidate: string, current: string): boolean => {
   }
   return false;
 };
-const jsonBytes = (value: unknown): string => `${canonicalJson(value)}\n`;
-const digestBytes = (value: string | Buffer): string =>
-  createHash("sha256").update(value).digest("hex");
-const isObject = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null;
 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);
 export const sameDirectoryIdentity = (left: string, right: string): boolean => {
   if (!path.isAbsolute(left) || !path.isAbsolute(right)) return false;
   const normalizedLeft = path.resolve(left);
@@ -270,171 +340,331 @@ export const sameDirectoryIdentity = (left: string, right: string): boolean => {
     return false;
   }
 };
-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. */
+/** Locks 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);
+const hold = (lock: string) => heldInProcess.set(lock, (heldInProcess.get(lock) ?? 0) + 1);
+const drop = (lock: string) => {
+  const count = (heldInProcess.get(lock) ?? 1) - 1;
+  if (count > 0) heldInProcess.set(lock, count);
+  else heldInProcess.delete(lock);
 };
 
-/** 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);
+const envActor = (): EventActor => {
+  const value = (key: string) => process.env[key]?.trim() || null;
+  return {
+    host: value("WORKIT_HOST") ?? "runtime",
+    session: value("WORKIT_SESSION_ID"),
+    agentId: value("WORKIT_AGENT_ID"),
+  };
+};
+
+/** The reduced, validated state of one task plus where its log stands. */
+type Loaded = {
+  record: TaskRecord;
+  key: TaskKey | null;
+  legacy: LegacyOrigin | null;
+  seq: number;
+  lastId: string;
+  lastStart: number;
+  end: number;
+  size: number;
+  /** Seq the current snapshot was taken at (0: none). */
+  snapshotSeq: number;
+};
+
+type Snapshot = {
+  v: 1;
+  task: Id;
+  seq: number;
+  lastId: string;
+  lastStart: number;
+  end: number;
+  key: TaskKey | null;
+  legacy: LegacyOrigin | null;
+  record: unknown;
 };
 
 export class TaskStore {
+  /** The checkout this store serves: the worktree top level in a git
+   * repository (every subdirectory is the same checkout), else the
+   * directory. Git operations run here. */
   readonly root: string;
+  /** The directory the store was opened from (a 2.x store may live there). */
+  private readonly origin: string;
   private readonly lockTimeoutMs: number;
+  private readonly actor: EventActor;
+  private readonly migrateOnRead: boolean | undefined;
+  private located: StoreLocation | Error | undefined;
+  private migrationChecked = false;
+  /** Task logs past AUTO_COMPACT_BYTES, folded after the writing lock is released. */
+  private readonly compactDue = new Set<Id>();
 
   constructor(root: string, options: TaskStoreOptions = {}) {
-    this.root = fs.existsSync(root) ? fs.realpathSync(root) : path.resolve(root);
+    const resolved = path.resolve(root);
+    this.origin = fs.existsSync(resolved) ? fs.realpathSync(resolved) : resolved;
+    this.located = resolveStore(this.origin);
+    this.root = checkoutRootOf(this.origin, this.located);
     this.lockTimeoutMs = options.lockTimeoutMs ?? defaultLockTimeout();
+    this.actor = options.actor ?? envActor();
+    this.migrateOnRead = options.migrateOnRead;
   }
 
-  readTask(taskId: Id): Result<TaskRecord> {
-    if (!validId(taskId)) return failure("invalid_input", "task ID is invalid", { taskId });
-    const result = this.readRecord<TaskRecord>(
-      path.join(this.tasksDir, `${taskId}.json`),
-      taskRecordSchema,
-    );
-    if (!result.exists) return failure("not_found", "task not found", { taskId });
-    if (result.result.ok && result.result.data.id !== taskId)
-      return failure("recovery_required", "task filename and record ID differ", { taskId });
-    if (result.result.ok) {
-      const workspace = this.readWorkspace();
-      if (!workspace.ok) return workspace;
-      if (!workspace.data || result.result.data.workspaceId !== workspace.data.id)
-        return failure("recovery_required", "task workspace binding is invalid", { taskId });
+  /** Where this checkout's store lives. */
+  location(): Result<StoreLocation> {
+    // A directory that became a repository (`git init`) moves to the git store.
+    if (
+      this.located !== undefined &&
+      !(this.located instanceof Error) &&
+      !this.located.shared &&
+      fs.existsSync(path.join(this.root, ".git"))
+    ) {
+      this.located = undefined;
+      this.migrationChecked = false;
     }
-    return result.result;
+    if (this.located === undefined) this.located = resolveStore(this.root);
+    return this.located instanceof Error
+      ? failure("storage_error", this.located.message, { path: this.root })
+      : success(null, null, this.located);
   }
 
-  listTasks(): Result<TaskRecord[]> {
-    if (!fs.existsSync(this.tasksDir)) return success(null, null, []);
-    let names: string[];
-    try {
-      names = fs.readdirSync(this.tasksDir).filter((name) => name.endsWith(".json"));
-    } catch (error) {
-      return failure("storage_error", `unable to list tasks: ${String(error)}`, {
-        path: this.tasksDir,
-      });
-    }
+  /** The implicit-task key of this checkout right now. */
+  currentKey(): Result<TaskKey> {
+    const location = this.location();
+    if (!location.ok) return location;
+    return success(null, null, resolveTaskKey(this.root, location.data));
+  }
+
+  // -------------------------------------------------------------------------
+  // reads
+
+  readTask(taskId: Id): Result<TaskRecord> {
+    if (!validId(taskId)) return failure("invalid_input", "task ID is invalid", { taskId });
+    const ready = this.ready();
+    if (!ready.ok) return ready;
+    const loaded = this.load(taskId);
+    if (!loaded.ok) return loaded;
+    if (!loaded.data) return failure("not_found", "task not found", { taskId });
     const workspace = this.readWorkspace();
     if (!workspace.ok) return workspace;
-    if (!workspace.data)
-      return failure("recovery_required", "task workspace binding is invalid", {
-        path: this.workspacePath,
-      });
+    const bound = this.bindingError(loaded.data.record, workspace.data);
+    return bound ?? success(null, null, loaded.data.record);
+  }
+
+  /** This checkout's tasks (oldest id first). */
+  listTasks(): Result<TaskRecord[]> {
+    const listed = this.listTaskIndex();
+    if (!listed.ok) return listed;
     const tasks: TaskRecord[] = [];
-    for (const name of names.toSorted()) {
-      const item = this.readRecord<TaskRecord>(path.join(this.tasksDir, name), taskRecordSchema);
-      if (!item.exists) continue;
-      if (!item.result.ok) return item.result;
-      if (!validId(name.slice(0, -5)) || item.result.data.id !== name.slice(0, -5))
-        return failure("recovery_required", "task filename and record ID differ", { path: name });
-      if (item.result.data.workspaceId !== workspace.data.id)
-        return failure("recovery_required", "task workspace binding is invalid", { path: name });
-      tasks.push(item.result.data);
+    for (const entry of listed.data.toSorted((left, right) => left.id.localeCompare(right.id))) {
+      const loaded = this.load(entry.id);
+      if (!loaded.ok) return loaded;
+      if (loaded.data) tasks.push(loaded.data.record);
     }
     return success(null, null, tasks);
   }
 
+  /** Listing facts for this checkout's tasks, from the index cache. */
+  listTaskIndex(): Result<TaskIndexEntry[]> {
+    const all = this.listStoreIndex();
+    if (!all.ok) return all;
+    const workspace = this.readWorkspace();
+    if (!workspace.ok) return workspace;
+    if (!workspace.data) return success(null, null, []);
+    const id = workspace.data.id;
+    return success(
+      null,
+      null,
+      all.data.filter((entry) => entry.workspaceId === id),
+    );
+  }
+
   /**
-   * List tasks from `.workit/index.json` without parsing full records. Each
-   * entry is checked against its task file's stat signature; missing, stale,
-   * or corrupt entries are rebuilt from the full (validated) record and the
-   * index is rewritten best-effort. Errors match `listTasks()`.
+   * Listing facts for every task in the store (all checkouts). Each cached
+   * entry is checked against its log's stat signature; changed or missing
+   * entries are rebuilt from the log and the index is rewritten best-effort.
    */
-  listTaskIndex(): Result<TaskIndexEntry[]> {
-    if (!fs.existsSync(this.tasksDir)) return success(null, null, []);
+  listStoreIndex(): Result<TaskIndexEntry[]> {
+    const ready = this.ready();
+    if (!ready.ok) return ready;
+    const tasksDir = this.paths().tasks;
     let names: string[];
     try {
-      names = fs.readdirSync(this.tasksDir).filter((name) => name.endsWith(".json"));
+      names = fs.existsSync(tasksDir)
+        ? fs.readdirSync(tasksDir).filter((name) => validId(name))
+        : [];
     } catch (error) {
       return failure("storage_error", `unable to list tasks: ${String(error)}`, {
-        path: this.tasksDir,
+        path: tasksDir,
       });
     }
-    const workspace = this.readWorkspace();
-    if (!workspace.ok) return workspace;
-    if (!workspace.data)
-      return failure("recovery_required", "task workspace binding is invalid", {
-        path: this.workspacePath,
-      });
-    const stored = this.readIndex(workspace.data.id);
+    const stored = this.readIndex();
     const entries: TaskIndexEntry[] = [];
     let changed = Object.keys(stored).length !== names.length;
     for (const name of names.toSorted()) {
-      const file = path.join(this.tasksDir, name);
-      const signature = fileSignature(file);
+      const signature = fileSignature(this.eventsPath(name));
       if (signature === null) {
         changed = true;
         continue;
       }
-      const cached = stored[name.slice(0, -5)];
+      const cached = stored[name];
       if (cached && cached.file === signature && !racySignature(signature)) {
         entries.push(cached);
         continue;
       }
-      const item = this.readRecord<TaskRecord>(file, taskRecordSchema);
-      if (!item.exists) continue;
-      if (!item.result.ok) return item.result;
-      if (!validId(name.slice(0, -5)) || item.result.data.id !== name.slice(0, -5))
-        return failure("recovery_required", "task filename and record ID differ", { path: name });
-      if (item.result.data.workspaceId !== workspace.data.id)
-        return failure("recovery_required", "task workspace binding is invalid", { path: name });
-      const entry = indexEntry(item.result.data, signature);
+      const loaded = this.load(name);
+      if (!loaded.ok) return loaded;
+      if (!loaded.data) continue;
+      const entry = indexEntry(
+        loaded.data.record,
+        loaded.data.key,
+        loaded.data.legacy !== null,
+        signature,
+      );
       if (!cached || canonicalJson(cached) !== canonicalJson(entry)) changed = true;
       entries.push(entry);
     }
-    if (changed) this.writeIndex(workspace.data.id, entries);
+    if (changed) this.writeIndex(entries);
     return success(null, null, entries);
   }
 
   readWorkspace(): Result<WorkspaceRecord | null> {
-    const item = this.readRecord<WorkspaceRecord>(this.workspacePath, workspaceRecordSchema);
-    if (!item.exists) return success(null, null, null);
-    if (
-      item.result.ok &&
-      item.result.data.root !== this.root &&
-      !sameDirectoryIdentity(item.result.data.root, this.root)
-    )
-      return failure("recovery_required", "workspace root binding is invalid", {
-        path: this.workspacePath,
+    const ready = this.ready();
+    if (!ready.ok) return ready;
+    const file = this.paths().workspace;
+    let bytes: string;
+    try {
+      bytes = retryTransient(() => fs.readFileSync(file, "utf8"));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return success(null, null, null);
+      return failure("recovery_required", `workspace record cannot be read: ${String(error)}`, {
+        path: file,
       });
-    return item.result;
+    }
+    const parsed = this.parseRecord<WorkspaceRecord>(bytes, workspaceRecordSchema, "workspace");
+    if (!parsed.ok) return parsed;
+    if (parsed.data.root !== this.root && !sameDirectoryIdentity(parsed.data.root, this.root))
+      return failure("recovery_required", "workspace root binding is invalid", { path: file });
+    return parsed;
+  }
+
+  /**
+   * The open task bound to this checkout's implicit key (branch, detached
+   * worktree, or directory), created when `create` is not false and there is
+   * none. A task bound to the key from another checkout of the same repo
+   * (e.g. a removed worktree) is moved to this checkout.
+   */
+  implicitTask(input: ImplicitInput): Result<ImplicitTask | null> {
+    const ready = this.ready(input.create !== false);
+    if (!ready.ok) return ready;
+    const key = this.currentKey();
+    if (!key.ok) return key;
+    const found = this.openTaskForKey(key.data.key);
+    if (!found.ok) return found;
+    const workspace = this.readWorkspace();
+    if (!workspace.ok) return workspace;
+    if (
+      found.data &&
+      workspace.data &&
+      found.data.workspaceId === workspace.data.id &&
+      (found.data.key === key.data.key || input.create === false)
+    ) {
+      const task = this.readTask(found.data.id);
+      return task.ok
+        ? success(task.revision, null, { task: task.data, created: false, key: key.data })
+        : task;
+    }
+    if (input.create === false) {
+      // A lookup never binds or moves anything.
+      if (!found.data) return success(null, null, null);
+      const loaded = this.load(found.data.id);
+      if (!loaded.ok) return loaded;
+      return loaded.data
+        ? success(null, null, { task: loaded.data.record, created: false, key: key.data })
+        : success(null, null, null);
+    }
+    return this.withLock<ImplicitTask | null>(this.paths().checkoutLock, () =>
+      this.withKeyLock(key.data.key, () => this.implicitLocked(input, key.data)),
+    );
+  }
+
+  /** Find, move or create the implicit task (under the checkout and key locks). */
+  private implicitLocked(input: ImplicitInput, key: TaskKey): Result<ImplicitTask | null> {
+    {
+      const again = this.openTaskForKey(key.key);
+      if (!again.ok) return again;
+      if (again.data) {
+        const moved = this.bindLocked(again.data.id, key, input.now);
+        return moved.ok
+          ? success(moved.data.revision, null, { task: moved.data, created: false, key })
+          : moved;
+      }
+      const label =
+        key.kind === "branch"
+          ? `branch ${key.branch}`
+          : key.kind === "detached"
+            ? "a detached HEAD"
+            : path.basename(this.root) || this.root;
+      const intent: Intent = {
+        objective: input.objective?.trim() || `Work on ${label}`,
+        scope: { description: `the checkout (${label})`, paths: ["."], exclusions: [] },
+        authorityRefs: [],
+      };
+      const created = this.createLocked(
+        { intent, provenance: input.provenance, expectedWorkspaceRevision: null, now: input.now },
+        false,
+        key,
+        false,
+      );
+      return created.ok
+        ? success(created.data.revision, null, { task: created.data, created: true, key })
+        : created;
+    }
+  }
+
+  /** Bind task `taskId` (any checkout, not closed) to this checkout's implicit key. */
+  adoptTask(taskId: Id): Result<TaskRecord> {
+    if (!validId(taskId)) return failure("invalid_input", "task ID is invalid", { taskId });
+    const ready = this.ready(true);
+    if (!ready.ok) return ready;
+    const key = this.currentKey();
+    if (!key.ok) return key;
+    return this.withLock(this.paths().checkoutLock, () =>
+      this.withKeyLock(key.data.key, () => {
+        const holder = this.openTaskForKey(key.data.key);
+        if (!holder.ok) return holder;
+        if (holder.data && holder.data.id !== taskId)
+          return failure(
+            "invalid_transition",
+            `${key.data.key} already has open task ${holder.data.id}; close it (\`workit task close\`) before adopting another`,
+            { taskId: holder.data.id },
+          );
+        return this.bindLocked(taskId, key.data);
+      }),
+    );
+  }
+
+  /**
+   * What `workit task status` reports about the current key: every open task
+   * bound to it (more than one is a duplicate; the oldest is the one used).
+   */
+  keyReport(): Result<{ key: TaskKey; bound: TaskIndexEntry[] }> {
+    const key = this.currentKey();
+    if (!key.ok) return key;
+    const bound = this.openTasksForKey(key.data.key);
+    if (!bound.ok) return bound;
+    return success(null, null, { key: key.data, bound: bound.data });
   }
 
+  // -------------------------------------------------------------------------
+  // writes
+
   create(
     input: CreateInput | Intent,
     provenance?: Provenance,
     expectedWorkspaceRevision?: Revision | null,
-  ) {
+  ): Result<TaskRecord> {
     const value: CreateInput =
       "intent" in input
         ? input
@@ -443,109 +673,15 @@ export class TaskStore {
             provenance: provenance!,
             expectedWorkspaceRevision: expectedWorkspaceRevision ?? null,
           };
-    return this.withLock<TaskRecord>(() => {
-      const current = this.readWorkspace();
-      if (!current.ok) return current;
-      if (
-        current.data
-          ? value.expectedWorkspaceRevision !== current.data.revision
-          : value.expectedWorkspaceRevision !== null
-      ) {
-        return failure(
-          "revision_conflict",
-          "workspace revision does not match; omit expectedWorkspaceRevision to use the current record",
-          {
-            expectedWorkspaceRevision: value.expectedWorkspaceRevision,
-            actualWorkspaceRevision: current.data?.revision ?? null,
-          },
-        );
-      }
-      if (!value.provenance) return failure("invalid_input", "provenance is required");
-      if (
-        !intentSchema.safeParse(value.intent).success ||
-        !provenanceSchema.safeParse(value.provenance).success
-      )
-        return failure("invalid_input", "task intent or provenance is invalid");
-      const previousWorkspaceBytes = current.data ? this.snapshotBytes(this.workspacePath) : null;
-      if (current.data && !previousWorkspaceBytes)
-        return failure("storage_error", "workspace snapshot disappeared during creation");
-      const workspace: WorkspaceRecord = current.data
-        ? {
-            ...current.data,
-            revision: newRevision(),
-            root: this.root,
-            runtime: stampNew(current.data),
-          }
-        : {
-            schemaVersion: SCHEMA_VERSION,
-            id: newId(),
-            revision: newRevision(),
-            root: this.root,
-            runtime: { createdWith: runtimeVersion(), updatedWith: runtimeVersion() },
-            writer: null,
-          };
-      const timestamp = value.now ?? now();
-      const task: TaskRecord = {
-        schemaVersion: SCHEMA_VERSION,
-        id: newId(),
-        workspaceId: workspace.id,
-        revision: newRevision(),
-        createdAt: timestamp,
-        updatedAt: timestamp,
-        origin: null,
-        intent: {
-          id: newId(),
-          recordedAt: timestamp,
-          provenance: value.provenance,
-          data: value.intent,
-        },
-        constraints: [],
-        status: "active",
-        closure: null,
-        progress: { summary: "", nextAction: null, blockers: [] },
-        runtime: { createdWith: runtimeVersion(), updatedWith: runtimeVersion() },
-        assessments: [],
-        policy: null,
-        policyChanges: [],
-        candidates: [],
-        evidence: [],
-        decisions: [],
-        findings: [],
-        workers: [],
-      };
-      const writtenWorkspace = this.replaceSnapshot(
-        this.workspacePath,
-        workspace,
-        previousWorkspaceBytes,
-      );
-      if (!writtenWorkspace.ok) return writtenWorkspace;
-      const writtenTask = this.replaceSnapshot(this.taskPath(task.id), task, null);
-      if (!writtenTask.ok) {
-        if (current.data && previousWorkspaceBytes) {
-          const restored = this.replaceSnapshot(
-            this.workspacePath,
-            current.data,
-            this.snapshotBytes(this.workspacePath),
-          );
-          if (!restored.ok)
-            return failure(
-              "external_outcome_unknown",
-              "task creation failed and workspace restoration is uncertain",
-              { operation: "create", outcome: "unknown" },
-            );
-        }
-        return failure(
-          "external_outcome_unknown",
-          "workspace created but task write is uncertain",
-          { operation: "create", outcome: "unknown" },
-        );
-      }
-      return success(task.revision, workspace.revision, task);
-    });
+    const ready = this.ready(true);
+    if (!ready.ok) return ready;
+    return this.withLock(this.paths().checkoutLock, () => this.createLocked(value, true, null));
   }
 
   importTask(input: ImportInput): Result<TaskRecord> {
-    return this.withLock<TaskRecord>(() => {
+    const ready = this.ready(true);
+    if (!ready.ok) return ready;
+    return this.withLock<TaskRecord>(this.paths().checkoutLock, () => {
       const current = this.readWorkspace();
       if (!current.ok) return current;
       const origin = input.task.origin;
@@ -592,25 +728,8 @@ export class TaskStore {
             actualWorkspaceRevision: current.data?.revision ?? null,
           },
         );
-      const previousWorkspaceBytes = current.data ? this.snapshotBytes(this.workspacePath) : null;
-      if (current.data && !previousWorkspaceBytes)
-        return failure("storage_error", "workspace snapshot disappeared during import");
       const timestamp = input.now ?? now();
-      const workspace: WorkspaceRecord = current.data
-        ? {
-            ...current.data,
-            revision: newRevision(),
-            root: this.root,
-            runtime: stampNew(current.data),
-          }
-        : {
-            schemaVersion: SCHEMA_VERSION,
-            id: input.workspaceId ?? newId(),
-            revision: newRevision(),
-            root: this.root,
-            runtime: { createdWith: runtimeVersion(), updatedWith: runtimeVersion() },
-            writer: null,
-          };
+      const workspace = this.nextWorkspace(current.data, input.workspaceId);
       const task = {
         ...input.task,
         workspaceId: workspace.id,
@@ -625,38 +744,9 @@ export class TaskStore {
       const validTask = taskRecordSchema.safeParse(task);
       if (!validTask.success)
         return failure("invalid_input", "imported task does not satisfy its schema");
-      const writtenWorkspace = this.replaceSnapshot(
-        this.workspacePath,
-        workspace,
-        previousWorkspaceBytes,
-      );
-      if (!writtenWorkspace.ok) return writtenWorkspace;
-      const writtenTask = this.replaceSnapshot(this.taskPath(task.id), validTask.data, null);
-      if (!writtenTask.ok) {
-        if (current.data && previousWorkspaceBytes) {
-          const restored = this.replaceSnapshot(
-            this.workspacePath,
-            current.data,
-            this.snapshotBytes(this.workspacePath),
-          );
-          if (!restored.ok)
-            return failure(
-              "external_outcome_unknown",
-              "import failed and workspace restoration is uncertain",
-              { operation: "import", outcome: "unknown" },
-            );
-        }
-        return failure(
-          "external_outcome_unknown",
-          `workspace created but task import is uncertain: ${writtenTask.error}`,
-          {
-            operation: "import",
-            outcome: "unknown",
-            path: writtenTask.details.path,
-          },
-        );
-      }
-      return success(validTask.data.revision, workspace.revision, validTask.data);
+      return this.writeNewTask(current.data, workspace, validTask.data, "task.imported", null, {
+        operation: "import",
+      });
     });
   }
 
@@ -666,48 +756,41 @@ export class TaskStore {
     update: TaskMutation,
     timestamp?: Utc,
   ): Result<TaskRecord> {
-    return this.withLock(() => {
-      const current = this.readTask(taskId);
-      if (!current.ok) return current;
-      if (current.data.revision !== expected) return this.conflict(expected, current.data.revision);
-      const previousBytes = this.snapshotBytes(this.taskPath(taskId));
-      if (!previousBytes)
-        return failure("storage_error", "task snapshot disappeared during mutation");
+    if (!validId(taskId)) return failure("invalid_input", "task ID is invalid", { taskId });
+    const ready = this.ready(true);
+    if (!ready.ok) return ready;
+    const result = this.withLock(this.taskLockPath(taskId), () => {
+      const loaded = this.loadBound(taskId);
+      if (!loaded.ok) return loaded;
+      if (loaded.data.record.revision !== expected)
+        return this.conflict(expected, loaded.data.record.revision);
       const context = { now: timestamp ?? now(), revision: newRevision() };
       let changed: Result<TaskRecord>;
       try {
-        changed = update(current.data, Object.freeze({ ...context }));
+        // A copy: updates may edit in place, and the patch diffs against the original.
+        changed = update(structuredClone(loaded.data.record), Object.freeze({ ...context }));
       } catch (error) {
         return failure("storage_error", `task mutation failed: ${String(error)}`);
       }
       if (!changed.ok) return changed;
-      const record = {
-        ...changed.data,
-        id: taskId,
-        workspaceId: current.data.workspaceId,
-        createdAt: current.data.createdAt,
-        revision: context.revision,
-        updatedAt: context.now,
-        runtime: stampNew(current.data),
-      };
-      const valid = taskRecordSchema.safeParse(record);
-      if (!valid.success)
-        return failure("invalid_input", "task mutation produced an invalid record");
-      const written = this.replaceSnapshot(this.taskPath(taskId), valid.data, previousBytes);
-      return written.ok ? success(valid.data.revision, null, valid.data) : written;
+      const valid = this.nextTask(loaded.data.record, changed.data, context);
+      if (!valid) return failure("invalid_input", "task mutation produced an invalid record");
+      const written = this.appendPatch(loaded.data, valid);
+      return written.ok ? success(valid.revision, null, valid) : written;
     });
+    this.compactPending();
+    return result;
   }
 
   mutateWorkspace(expected: Revision, update: WorkspaceMutation): Result<WorkspaceRecord> {
-    return this.withLock(() => {
+    const ready = this.ready(true);
+    if (!ready.ok) return ready;
+    return this.withLock(this.paths().checkoutLock, () => {
       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.workspaceConflict(expected, current.data.revision);
-      const previousBytes = this.snapshotBytes(this.workspacePath);
-      if (!previousBytes)
-        return failure("storage_error", "workspace snapshot disappeared during mutation");
       const context = { now: now(), revision: newRevision() };
       let changed: Result<WorkspaceRecord>;
       try {
@@ -716,430 +799,128 @@ export class TaskStore {
         return failure("storage_error", `workspace mutation failed: ${String(error)}`);
       }
       if (!changed.ok) return changed;
-      const record = {
+      const valid = workspaceRecordSchema.safeParse({
         ...changed.data,
         id: current.data.id,
         root: this.root,
         revision: context.revision,
         runtime: stampNew(current.data),
-      };
-      const valid = workspaceRecordSchema.safeParse(record);
+      });
       if (!valid.success)
         return failure("invalid_input", "workspace mutation produced an invalid record");
-      const written = this.replaceSnapshot(this.workspacePath, valid.data, previousBytes);
+      const written = this.writeWorkspace(valid.data);
       return written.ok ? success(valid.data.revision, valid.data.revision, valid.data) : written;
     });
   }
 
   mutateTaskAndWorkspace(input: CoupledMutation): Result<CoupledSnapshot> {
-    return this.withLock(() => {
-      const task = this.readTask(input.taskId);
-      if (!task.ok) return task;
-      const workspace = this.readWorkspace();
-      if (!workspace.ok) return workspace;
-      if (!workspace.data) return failure("not_found", "workspace not found");
-      const expected = input.expectedRevision;
-      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.workspaceConflict(input.expectedWorkspaceRevision, workspace.data.revision);
-      const previousWorkspaceBytes = this.snapshotBytes(this.workspacePath);
-      const previousTaskBytes = this.snapshotBytes(this.taskPath(input.taskId));
-      if (!previousWorkspaceBytes || !previousTaskBytes)
-        return failure("storage_error", "snapshot disappeared during coupled mutation");
-      const workspaceContext = { now: input.now ?? now(), revision: newRevision() };
-      let changedWorkspace: Result<WorkspaceRecord>;
-      try {
-        changedWorkspace = input.workspace(workspace.data, Object.freeze({ ...workspaceContext }));
-      } catch (error) {
-        return failure("storage_error", `workspace mutation failed: ${String(error)}`);
-      }
-      if (!changedWorkspace.ok) return changedWorkspace;
-      const nextWorkspace = workspaceRecordSchema.safeParse({
-        ...changedWorkspace.data,
-        id: workspace.data.id,
-        root: this.root,
-        revision: workspaceContext.revision,
-        runtime: stampNew(workspace.data),
-      });
-      if (!nextWorkspace.success)
-        return failure("invalid_input", "workspace mutation produced an invalid record");
-      const reserved = this.replaceSnapshot(
-        this.workspacePath,
-        nextWorkspace.data,
-        previousWorkspaceBytes,
-      );
-      if (!reserved.ok) return reserved;
-      const taskContext = { now: input.now ?? now(), revision: newRevision() };
-      let changedTask: Result<TaskRecord>;
-      try {
-        changedTask = input.task(task.data, Object.freeze({ ...taskContext }));
-      } catch (error) {
-        this.markUncertain(nextWorkspace.data);
-        return failure(
-          "external_outcome_unknown",
-          `workspace reserved but task mutation threw: ${String(error)}`,
-          { operation: "coupled_mutation", outcome: "unknown" },
-        );
-      }
-      if (!changedTask.ok) {
-        this.markUncertain(nextWorkspace.data);
-        return failure(
-          "external_outcome_unknown",
-          "workspace reserved but task update is uncertain",
-          { operation: "coupled_mutation", outcome: "unknown" },
-        );
-      }
-      const nextTask = taskRecordSchema.safeParse({
-        ...changedTask.data,
-        id: input.taskId,
-        workspaceId: task.data.workspaceId,
-        createdAt: task.data.createdAt,
-        revision: taskContext.revision,
-        updatedAt: taskContext.now,
-        runtime: stampNew(task.data),
-      });
-      if (!nextTask.success) {
-        this.markUncertain(nextWorkspace.data);
-        return failure(
-          "external_outcome_unknown",
-          "workspace reserved but task update is uncertain",
-          { operation: "coupled_mutation", outcome: "unknown" },
-        );
-      }
-      const written = this.replaceSnapshot(
-        this.taskPath(input.taskId),
-        nextTask.data,
-        previousTaskBytes,
-      );
-      if (!written.ok) {
-        this.markUncertain(nextWorkspace.data);
-        return failure(
-          "external_outcome_unknown",
-          "workspace reserved but task replacement is uncertain",
-          { operation: "coupled_mutation", outcome: "unknown" },
-        );
-      }
-      return success(nextTask.data.revision, nextWorkspace.data.revision, {
-        task: nextTask.data,
-        workspace: nextWorkspace.data,
-      });
-    });
-  }
-
-  recoveryCandidates(): Result<RecoveryCandidate[]> {
-    if (!fs.existsSync(this.recoveryDir)) return success(null, null, []);
-    try {
-      const candidates: RecoveryCandidate[] = [];
-      for (const name of fs.readdirSync(this.recoveryDir)) {
-        const match = RECOVERY_NAME.exec(name);
-        if (match)
-          candidates.push({
-            target: match[1] as "task" | "workspace",
-            path: path.join(this.recoveryDir, name),
-            digest: match[3],
+    if (!validId(input.taskId))
+      return failure("invalid_input", "task ID is invalid", { taskId: input.taskId });
+    const ready = this.ready(true);
+    if (!ready.ok) return ready;
+    const result = this.withLock(this.paths().checkoutLock, () =>
+      this.withLock(this.taskLockPath(input.taskId), () => {
+        const task = this.loadBound(input.taskId);
+        if (!task.ok) return task;
+        const workspace = this.readWorkspace();
+        if (!workspace.ok) return workspace;
+        if (!workspace.data) return failure("not_found", "workspace not found");
+        const expected = input.expectedRevision;
+        if (!expected) return failure("invalid_input", "task revision is required");
+        if (task.data.record.revision !== expected)
+          return this.conflict(expected, task.data.record.revision);
+        if (workspace.data.revision !== input.expectedWorkspaceRevision)
+          return this.workspaceConflict(input.expectedWorkspaceRevision, workspace.data.revision);
+        const workspaceContext = { now: input.now ?? now(), revision: newRevision() };
+        let changedWorkspace: Result<WorkspaceRecord>;
+        try {
+          changedWorkspace = input.workspace(
+            workspace.data,
+            Object.freeze({ ...workspaceContext }),
+          );
+        } catch (error) {
+          return failure("storage_error", `workspace mutation failed: ${String(error)}`);
+        }
+        if (!changedWorkspace.ok) return changedWorkspace;
+        const nextWorkspace = workspaceRecordSchema.safeParse({
+          ...changedWorkspace.data,
+          id: workspace.data.id,
+          root: this.root,
+          revision: workspaceContext.revision,
+          runtime: stampNew(workspace.data),
+        });
+        if (!nextWorkspace.success)
+          return failure("invalid_input", "workspace mutation produced an invalid record");
+        const reserved = this.writeWorkspace(nextWorkspace.data);
+        if (!reserved.ok) return reserved;
+        const uncertain = (message: string) => {
+          this.markUncertain(nextWorkspace.data);
+          return failure("external_outcome_unknown", message, {
+            operation: "coupled_mutation",
+            outcome: "unknown",
           });
-      }
-      return success(null, null, candidates);
-    } catch (error) {
-      return failure("storage_error", `unable to list recovery: ${String(error)}`, {
-        path: this.recoveryDir,
-      });
-    }
-  }
-
-  recoverTask(taskId: Id, input: RecoveryInput): Result<TaskRecord> {
-    return this.recover("task", taskId, input);
-  }
-
-  recoverWorkspace(input: RecoveryInput): Result<WorkspaceRecord> {
-    return this.recover("workspace", null, input);
+        };
+        const taskContext = { now: input.now ?? now(), revision: newRevision() };
+        let changedTask: Result<TaskRecord>;
+        try {
+          changedTask = input.task(
+            structuredClone(task.data.record),
+            Object.freeze({ ...taskContext }),
+          );
+        } catch (error) {
+          return uncertain(`workspace reserved but task mutation threw: ${String(error)}`);
+        }
+        if (!changedTask.ok) return uncertain("workspace reserved but task update is uncertain");
+        const nextTask = this.nextTask(task.data.record, changedTask.data, taskContext);
+        if (!nextTask) return uncertain("workspace reserved but task update is uncertain");
+        const written = this.appendPatch(task.data, nextTask);
+        if (!written.ok) return uncertain("workspace reserved but task append is uncertain");
+        return success(nextTask.revision, nextWorkspace.data.revision, {
+          task: nextTask,
+          workspace: nextWorkspace.data,
+        });
+      }),
+    );
+    this.compactPending();
+    return result;
   }
 
-  private recover(
-    target: "task" | "workspace",
-    taskId: Id | null,
-    input: RecoveryInput,
-  ): Result<any> {
-    if (taskId !== null && !validId(taskId))
-      return failure("invalid_input", "task ID is invalid", { taskId });
+  /** Hold this checkout's lock across a managed effect. */
+  async withExternalActionLock<T>(
+    operation: () => Promise<Result<T>>,
+    reentrant = false,
+  ): Promise<Result<T>> {
+    const activeRoots = externalActionLockRoots.getStore();
     if (
-      !input.reason ||
-      !Array.isArray(input.authorityRefs) ||
-      typeof input.processEvidence !== "function" ||
-      !validDigest(input.expectedBytes) ||
-      !validDigest(input.snapshotDigest)
+      activeRoots &&
+      [...activeRoots].some((root) => root === this.root || sameDirectoryIdentity(root, this.root))
     )
-      return failure("invalid_input", "recovery authority is invalid");
-    if (input.authorityRefs.some((ref) => !refSchema.safeParse(ref).success))
-      return failure("invalid_input", "recovery references are invalid");
+      return operation();
+    const ready = this.ready(true);
+    if (!ready.ok) return ready;
+    const lockPath = this.paths().checkoutLock;
     try {
-      const workspace = this.readWorkspace();
-      if (!workspace.ok && target === "task") return workspace;
-      const workspaceValue = workspace.ok ? workspace.data : null;
-      if (workspaceValue && workspaceValue.revision !== input.expectedWorkspaceRevision)
-        return this.conflict(input.expectedWorkspaceRevision, workspaceValue.revision);
-      const file = target === "workspace" ? this.workspacePath : this.taskPath(taskId!);
-      const currentBytes = this.snapshotBytes(file);
-      if (!currentBytes) return failure("not_found", "snapshot not found");
-      if (digestBytes(currentBytes) !== input.expectedBytes)
-        return failure("revision_conflict", "snapshot bytes do not match expected bytes");
-      let selectedBytes = currentBytes;
-      if (digestBytes(currentBytes) !== input.snapshotDigest) {
-        const candidate = this.findRecovery(target, taskId, input.snapshotDigest, workspaceValue);
-        if (!candidate)
-          return failure("recovery_required", "validated recovery snapshot not found");
-        selectedBytes = candidate;
-      }
-      const selectedRecord =
-        target === "workspace"
-          ? 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>;
-        if (!parsed.ok || parsed.data.root !== this.root)
-          return failure("recovery_required", "workspace recovery binding is invalid");
-      } else {
-        const parsed = selectedRecord as Result<TaskRecord>;
-        if (
-          !parsed.ok ||
-          parsed.data.id !== taskId ||
-          !workspaceValue ||
-          parsed.data.workspaceId !== workspaceValue.id
-        )
-          return failure("recovery_required", "task recovery binding is invalid");
-      }
-      const lock = this.readLockSnapshot();
-      if (!lock.ok) return lock;
-      const writer =
-        target === "workspace"
-          ? (selectedRecord.data as WorkspaceRecord).writer
-          : (workspaceValue?.writer ?? null);
-      const evidence = this.processEvidence(input, lock.data?.data ?? null, writer);
-      if (!evidence.ok) return evidence;
-      if (
-        lock.data &&
-        (evidence.data.pid !== lock.data.data.pid ||
-          evidence.data.processStart !== lock.data.data.processStart)
-      )
-        return failure("recovery_required", "process evidence does not match metadata lock");
-      if (
-        writer &&
-        (evidence.data.state !== "accounted_for" ||
-          evidence.data.ownerDigest !== sha256(canonicalJson(writer)))
-      )
-        return failure("recovery_required", "workspace writer is not accounted for");
-      const recoveryGate = { reclaimed: false };
-      const result = this.withLock<any>(
-        (handle) => {
-          if (lock.data && !recoveryGate.reclaimed)
-            return failure("recovery_required", "metadata lock changed during recovery", {
-              path: this.lockPath,
-            });
-          if (!handle.verifyStillHeld())
-            return failure("recovery_required", "metadata lock was compromised", {
-              path: this.lockPath,
-            });
-          const reacquiredBytes = this.snapshotBytes(file);
-          if (!reacquiredBytes)
-            return failure("recovery_required", "snapshot disappeared during recovery");
-          if (digestBytes(reacquiredBytes) !== input.expectedBytes)
-            return failure("revision_conflict", "snapshot changed during recovery");
-          if (target === "task") {
-            const currentWorkspace = this.readWorkspace();
-            if (!currentWorkspace.ok || !currentWorkspace.data)
-              return failure("recovery_required", "workspace changed during recovery");
-            if (currentWorkspace.data.revision !== input.expectedWorkspaceRevision)
-              return this.conflict(input.expectedWorkspaceRevision, currentWorkspace.data.revision);
-          }
-          if (target === "workspace") {
-            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, "rewrite");
-          if (!parsed.ok) return parsed;
-          const value = {
-            ...parsed.data,
-            revision: newRevision(),
-            updatedAt: now(),
-            status: parsed.data.status === "active" ? "paused" : parsed.data.status,
-          } as TaskRecord;
-          const replaced = this.replaceSnapshot(file, value, reacquiredBytes);
-          return replaced.ok ? success(value.revision, null, value) : replaced;
-        },
-        this.recoveryLockOptions(lock.data, evidence.data, recoveryGate),
-        "recovery_required",
-      );
-      return result;
+      this.initializeStorage();
     } catch (error) {
-      return failure("recovery_required", `recovery protocol failed: ${String(error)}`);
+      return failure("storage_error", `unable to initialize store: ${String(error)}`, {
+        path: this.paths().dir,
+      });
     }
-  }
-
-  private processEvidence(
-    input: RecoveryInput,
-    lock: MetadataLock | null,
-    writer: WorkspaceRecord["writer"],
-  ): Result<ProcessEvidence> {
-    const lockCopy = lock ? this.deepFreeze(structuredClone(lock)) : null;
-    const writerCopy = writer ? this.deepFreeze(structuredClone(writer)) : null;
-    const lockDigest = lockCopy ? sha256(canonicalJson(lockCopy)) : null;
-    const writerDigest = writerCopy ? sha256(canonicalJson(writerCopy)) : null;
+    let handle: FileLockSyncHandle;
     try {
-      const result = input.processEvidence(lockCopy, writerCopy);
-      if (lockCopy && sha256(canonicalJson(lockCopy)) !== lockDigest)
-        return failure("recovery_required", "process evidence mutated lock identity");
-      if (writerCopy && sha256(canonicalJson(writerCopy)) !== writerDigest)
-        return failure("recovery_required", "process evidence mutated writer identity");
-      if (!result.ok) return result;
-      const parsed = processEvidenceSchema.safeParse(result.data);
-      return parsed.success
-        ? success(null, null, parsed.data)
-        : failure("recovery_required", "process evidence is invalid");
+      const options = this.lockOptions(lockPath);
+      handle = this.acquire(lockPath, {
+        ...options,
+        payload: () => ({ ...options.payload(), externalAction: true }),
+      });
     } catch (error) {
-      return failure("recovery_required", `process evidence failed: ${String(error)}`);
-    }
-  }
-
-  private deepFreeze<T>(value: T): T {
-    if (value && typeof value === "object") {
-      for (const child of Object.values(value as Record<string, unknown>)) this.deepFreeze(child);
-      Object.freeze(value);
+      return this.lockFailure(lockPath, error);
     }
-    return value;
-  }
-
-  private readLockSnapshot(): Result<LockSnapshot | null> {
-    try {
-      const stat = fs.lstatSync(this.lockPath);
-      if (!stat.isFile() || stat.isSymbolicLink())
-        return failure("recovery_required", "metadata lock is not a regular file", {
-          path: this.lockPath,
-        });
-      const raw = fs.readFileSync(this.lockPath, "utf8");
-      return success(null, null, { raw, data: parseMetadataLock(raw) });
-    } catch (error: any) {
-      if (error?.code === "ENOENT") return success(null, null, null);
-      return failure("recovery_required", `metadata lock is invalid: ${String(error)}`, {
-        path: this.lockPath,
-      });
-    }
-  }
-
-  /**
-   * 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: 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: 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 }) };
-  }
-
-  /** Hold the workspace metadata lock across a managed effect in this checkout. */
-  async withExternalActionLock<T>(
-    operation: () => Promise<Result<T>>,
-    reentrant = false,
-  ): Promise<Result<T>> {
-    const activeRoots = externalActionLockRoots.getStore();
-    if (
-      activeRoots &&
-      [...activeRoots].some((root) => root === this.root || sameDirectoryIdentity(root, this.root))
-    )
-      return operation();
-    try {
-      this.initializeMutationStorage();
-    } catch (error) {
-      return failure("storage_error", `unable to initialize store: ${String(error)}`, {
-        path: this.workitDir,
-      });
-    }
-    let handle: FileLockSyncHandle;
-    try {
-      handle = this.acquireMetadataLock(this.externalActionLockOptions());
-    } catch (error) {
-      return this.lockFailure(error);
-    }
-    holdRoot(this.root);
-    let result: Result<T>;
+    hold(lockPath);
+    let result: Result<T>;
     try {
       if (!handle.verifyStillHeld())
-        result = failure("recovery_required", "metadata lock was compromised", {
-          path: this.lockPath,
-        });
+        result = failure("recovery_required", "metadata lock was compromised", { path: lockPath });
       else {
         try {
           const run = () => operation();
@@ -1155,26 +936,26 @@ export class TaskStore {
           if (!handle.verifyStillHeld())
             result = failure("external_outcome_unknown", "metadata lock was compromised", {
               outcome: "unknown",
-              path: this.lockPath,
+              path: lockPath,
             });
         } catch {
           result = failure("external_outcome_unknown", "metadata lock could not be verified", {
             outcome: "unknown",
-            path: this.lockPath,
+            path: lockPath,
           });
         }
       }
     } catch {
       result = failure("external_outcome_unknown", "external action lock operation failed", {
         outcome: "unknown",
-        path: this.lockPath,
+        path: lockPath,
       });
     }
-    dropRoot(this.root);
+    drop(lockPath);
     try {
       retryTransient(() => handle.release());
     } catch (error) {
-      const released = this.lockFailure(error);
+      const released = this.lockFailure(lockPath, error);
       const releaseError = released.ok ? "metadata lock release failed" : released.error;
       return result.ok
         ? failure(
@@ -1182,7 +963,7 @@ export class TaskStore {
             "external action metadata lock release is uncertain",
             {
               outcome: "unknown",
-              path: this.lockPath,
+              path: lockPath,
             },
           )
         : failure("recovery_required", `${result.error}; ${releaseError}`, result.details);
@@ -1190,597 +971,900 @@ export class TaskStore {
     return result;
   }
 
-  private recoveryLockOptions(
-    observed: LockSnapshot | null,
-    evidence: ProcessEvidence,
-    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(
-        observed &&
-        sameMetadataLock(payload, observed.data) &&
-        (evidence.state === "stopped" || evidence.state === "accounted_for"),
-      );
-    options.shouldRemoveStaleLock = ({ raw, payload }) => {
-      if (!observed || raw !== observed.raw || !sameMetadataLock(payload, observed.data))
-        return false;
-      gate.reclaimed = true;
-      return true;
+  /**
+   * `workit gc`: compact long task logs into a checkpoint plus their most
+   * recent events (the latest state is never lost), remove unreferenced
+   * candidate blobs and temp files left by crashed writers, and report a 2.x
+   * `.workit/recovery` directory left behind by migration (removed only with
+   * `pruneRecovery`). A dry run is read-only.
+   */
+  collectGarbage(
+    options: { dryRun?: boolean; pruneRecovery?: boolean; compactAbove?: number } = {},
+  ): Result<GarbageReport> {
+    const dryRun = options.dryRun === true;
+    const compactAbove = options.compactAbove ?? COMPACT_ABOVE;
+    const report: GarbageReport = {
+      dryRun,
+      compacted: { tasks: [], eventsFolded: 0, bytesBefore: 0, bytesAfter: 0 },
+      blobs: { removed: 0, removedBytes: 0, kept: 0 },
+      temporary: { removed: 0 },
+      legacyRecovery: null,
+      retried: [],
+      failed: [],
+    };
+    const ready = this.ready(!dryRun);
+    if (!ready.ok) return ready;
+    const dirs = this.paths();
+    const recovery = path.join(this.root, ".workit", "recovery");
+    if (fs.existsSync(recovery)) {
+      let files = 0;
+      let bytes = 0;
+      try {
+        for (const name of fs.readdirSync(recovery)) {
+          const stat = fs.lstatSync(path.join(recovery, name));
+          if (!stat.isFile()) continue;
+          files += 1;
+          bytes += stat.size;
+        }
+      } catch {}
+      const remove = options.pruneRecovery === true && !dryRun;
+      if (remove) fs.rmSync(recovery, { recursive: true, force: true });
+      report.legacyRecovery = { path: recovery, files, bytes, removed: remove };
+    }
+    if (!fs.existsSync(dirs.tasks)) return success(null, null, report);
+    const names = fs.readdirSync(dirs.tasks).filter((name) => validId(name));
+    for (const name of names) {
+      const file = this.eventsPath(name);
+      let size = 0;
+      try {
+        size = fs.statSync(file).size;
+      } catch {
+        continue;
+      }
+      const lines = this.countEvents(file);
+      if (lines > compactAbove) {
+        if (dryRun) {
+          report.compacted.tasks.push(name);
+          report.compacted.eventsFolded += lines - COMPACT_KEEP;
+          report.compacted.bytesBefore += size;
+        } else {
+          const compacted = this.compact(name);
+          if (!compacted.ok)
+            (compacted.code === "busy" ? report.retried : report.failed).push(name);
+          else {
+            report.compacted.tasks.push(name);
+            report.compacted.eventsFolded += compacted.data.folded;
+            report.compacted.bytesBefore += size;
+            report.compacted.bytesAfter += compacted.data.bytes;
+          }
+        }
+      }
+    }
+    const nowMs = Date.now();
+    // Blobs go only when unreferenced and older than the grace period, under
+    // the store's gc lock (one sweep at a time).
+    const sweep = (): Result<null> => {
+      const references = new Set<string>();
+      for (const name of names)
+        try {
+          for (const match of fs
+            .readFileSync(this.eventsPath(name), "utf8")
+            .matchAll(/"\$blob":"([0-9a-f]{64})"/g))
+            references.add(match[1]);
+        } catch {}
+      if (fs.existsSync(dirs.blobs))
+        for (const name of fs.readdirSync(dirs.blobs)) {
+          const digest = name.replace(/\.json$/, "");
+          const file = path.join(dirs.blobs, name);
+          let stat: fs.Stats;
+          try {
+            stat = fs.lstatSync(file);
+          } catch {
+            continue;
+          }
+          if (references.has(digest) || nowMs - stat.mtimeMs <= STALE_TEMPORARY_MS) {
+            report.blobs.kept += 1;
+            continue;
+          }
+          report.blobs.removed += 1;
+          report.blobs.removedBytes += stat.size;
+          if (!dryRun) fs.rmSync(file, { force: true });
+        }
+      return success(null, null, null);
     };
-    return options;
+    const swept = dryRun ? sweep() : this.withLock(path.join(dirs.dir, "gc.lock"), sweep);
+    if (!swept.ok) return swept;
+    const temporaryDirs = [
+      dirs.dir,
+      dirs.tasks,
+      dirs.blobs,
+      dirs.checkout,
+      ...names.map((name) => path.join(dirs.tasks, name)),
+    ];
+    for (const directory of temporaryDirs) {
+      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);
+        try {
+          const stat = fs.lstatSync(file);
+          if (!stat.isFile() || nowMs - stat.mtimeMs <= STALE_TEMPORARY_MS) continue;
+        } catch {
+          continue;
+        }
+        report.temporary.removed += 1;
+        if (!dryRun) fs.rmSync(file, { force: true });
+      }
+    }
+    return success(null, null, report);
   }
 
-  private markUncertain(workspace: WorkspaceRecord) {
-    if (!workspace.writer || workspace.writer.state === "uncertain") return;
-    const value = {
-      ...workspace,
-      writer: { ...workspace.writer, state: "uncertain" as const },
-      revision: newRevision(),
-      runtime: stampNew(workspace),
+  // -------------------------------------------------------------------------
+  // internals: layout
+
+  private paths() {
+    const location = this.location();
+    // Callers go through ready(), which fails first when the store is unresolved.
+    const dir = location.ok ? location.data.dir : path.join(this.root, ".workit");
+    const checkout = path.join(dir, "checkouts", checkoutSlug(this.root));
+    return {
+      dir,
+      shared: location.ok ? location.data.shared : false,
+      marker: path.join(dir, "store.json"),
+      checkout,
+      workspace: path.join(checkout, "workspace.json"),
+      checkoutLock: path.join(checkout, "metadata.lock"),
+      tasks: path.join(dir, "tasks"),
+      index: path.join(dir, "task-index.json"),
+      blobs: path.join(dir, "blobs", "candidates"),
+      legacy: path.join(dir, "legacy", checkoutSlug(this.root), "v2"),
+      v2: path.join(this.root, ".workit"),
     };
-    this.replaceSnapshot(this.workspacePath, value, workspace);
+  }
+  private eventsPath(taskId: Id) {
+    return path.join(this.paths().tasks, taskId, "events.jsonl");
+  }
+  private snapshotPath(taskId: Id) {
+    return path.join(this.paths().tasks, taskId, "snapshot.json");
+  }
+  private taskLockPath(taskId: Id) {
+    return path.join(this.paths().tasks, taskId, "lock");
   }
 
-  private withLock<T>(
-    operation: (handle: FileLockSyncHandle) => Result<T>,
-    options: FileLockSyncAcquireOptions<MetadataLock> = this.metadataLockOptions(),
-    contention: "busy" | "recovery_required" = "busy",
-  ): Result<T> {
+  /** The store resolves, its format is readable, and any 2.x store here is migrated. */
+  /**
+   * The store resolves and its format is readable. A pending migration (a
+   * 2.x store, or a pre-git 3.x store) runs on writes, and on reads only for
+   * a host that can tell the user (the CLI); other reads, e.g. per-turn
+   * hooks, get a `needs_input` naming the command that migrates.
+   */
+  private ready(write = false): Result<null> {
+    const location = this.location();
+    if (!location.ok) return location;
+    if (this.migrationChecked) return success(null, null, null);
+    const dirs = this.paths();
     try {
-      this.initializeMutationStorage();
-    } catch (error) {
-      return failure("storage_error", `unable to initialize store: ${String(error)}`, {
-        path: this.workitDir,
-      });
+      const marker = JSON.parse(fs.readFileSync(dirs.marker, "utf8")) as { version?: unknown };
+      if (typeof marker.version === "number" && marker.version > STORE_FORMAT)
+        return failure(
+          "recovery_required",
+          `the workit store at ${dirs.dir} has format ${marker.version}; upgrade Workit to use it`,
+          { path: dirs.marker },
+        );
+    } catch {}
+    // Reads made by the migration itself see the store as ready.
+    this.migrationChecked = true;
+    const settled = this.settleMigrations(write);
+    if (!settled.ok) this.migrationChecked = false;
+    return settled;
+  }
+
+  private settleMigrations(write: boolean): Result<null> {
+    const moved = this.adoptLocalStore();
+    if (!moved.ok) return moved;
+    const pending = this.pendingMigrations();
+    if (pending.length > 0 && !write && !(this.migrateOnRead ?? migrationReporterInstalled()))
+      return failure(
+        "needs_input",
+        `${MIGRATION_PENDING}: the task store at ${pending[0]} has not been migrated yet; run \`workit task status\` to migrate it`,
+        { path: pending[0], guidance: "workit task status" },
+      );
+    for (const v2 of this.v2Dirs()) {
+      const migrated = this.migrateV2(v2);
+      if (!migrated.ok) return migrated;
     }
-    let handle: FileLockSyncHandle | undefined;
-    let result: Result<T> = failure(
-      "storage_error",
-      "metadata lock operation did not produce a result",
-    );
+    return success(null, null, null);
+  }
+
+  private blobStore(): BlobStore {
+    const dir = this.paths().blobs;
+    return {
+      read: (digest) => {
+        try {
+          return JSON.parse(fs.readFileSync(path.join(dir, `${digest}.json`), "utf8"));
+        } catch (error) {
+          throw new LogDamage(
+            `stored candidate ${digest} is missing or unreadable: ${String(error)}`,
+          );
+        }
+      },
+      write: (digest, value) => {
+        const file = path.join(dir, `${digest}.json`);
+        if (fs.existsSync(file)) {
+          // A reused blob is fresh again: gc spares blobs younger than its
+          // grace period, so one about to be referenced is never collected.
+          const stamp = new Date();
+          try {
+            fs.utimesSync(file, stamp, stamp);
+            return;
+          } catch {}
+        }
+        fs.mkdirSync(dir, { recursive: true });
+        replaceFile(file, JSON.stringify(value), true);
+      },
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // internals: task logs
+
+  /** Reduce a task's log (from its snapshot when that matches); null when absent. */
+  private load(taskId: Id): Result<Loaded | null> {
     try {
-      handle = this.acquireMetadataLock(options);
+      const loaded = this.loadOrThrow(taskId);
+      if (!loaded) return success(null, null, null);
+      const parsed = this.parseTask(loaded.state.record, taskId);
+      if (!parsed.ok) return parsed;
+      return success(null, null, {
+        record: parsed.data,
+        key: loaded.state.key,
+        legacy: loaded.state.legacy,
+        seq: loaded.seq,
+        lastId: loaded.lastId,
+        lastStart: loaded.lastStart,
+        end: loaded.end,
+        size: loaded.size,
+        snapshotSeq: loaded.snapshotSeq,
+      });
     } catch (error) {
-      result = this.lockFailure(error, contention);
+      if (error instanceof LogDamage)
+        return failure(
+          "recovery_required",
+          error.upgrade ? error.message : `task ${taskId} log is damaged: ${error.message}`,
+          { taskId, path: this.eventsPath(taskId) },
+        );
+      return failure("recovery_required", `task ${taskId} cannot be read: ${String(error)}`, {
+        taskId,
+      });
     }
-    if (handle) holdRoot(this.root);
-    if (handle) {
+  }
+
+  private loadOrThrow(taskId: Id) {
+    const blobs = this.blobStore();
+    const file = this.eventsPath(taskId);
+    const snapshot = this.readSnapshot(taskId);
+    if (snapshot) {
       try {
-        if (!handle.verifyStillHeld())
-          result = failure("recovery_required", "metadata lock was compromised", {
-            path: this.lockPath,
-          });
-        else {
-          try {
-            result = operation(handle);
-          } catch (error) {
-            result = failure("storage_error", `mutation failed: ${String(error)}`);
-          }
+        const tail = readLog(file, snapshot.lastStart, snapshot.seq);
+        const first = tail?.events[0];
+        // The snapshot names the event it was taken after: same seq, same id.
+        if (tail && first && first.id === snapshot.lastId) {
+          let state: ReducedTask | null = {
+            record: snapshot.record as Record<string, unknown>,
+            key: snapshot.key,
+            legacy: snapshot.legacy,
+          };
+          for (const event of tail.events.slice(1)) state = reduce(state, event, blobs);
+          return this.loadedFrom(state!, tail, snapshot.seq);
         }
       } catch (error) {
-        result = this.lockFailure(error);
+        if (error instanceof LogDamage && error.upgrade) throw error;
+        // Any other mismatch: fall back to a full replay.
       }
     }
-    if (handle) {
-      dropRoot(this.root);
-      try {
-        retryTransient(() => handle.release());
-      } catch (error) {
-        const releaseFailure = this.lockFailure(error);
-        const releaseError = releaseFailure.ok
-          ? "metadata lock release failed"
-          : releaseFailure.error;
-        result = result.ok
-          ? releaseFailure
-          : failure("recovery_required", `${result.error}; ${releaseError}`, result.details);
-      }
+    const log = readLog(file, 0, null);
+    if (!log || log.events.length === 0) {
+      if (log && log.size > 0) throw new LogDamage("the log holds no complete event");
+      return null;
     }
-    return result;
+    if (!OPENING_TYPES.has(log.events[0].type))
+      throw new LogDamage(`the log starts with ${log.events[0].type}, not an opening event`);
+    let state: ReducedTask | null = null;
+    for (const event of log.events) state = reduce(state, event, blobs);
+    return this.loadedFrom(state!, log, 0);
   }
 
-  /** Whether the lock's directory accepts a new file right now. */
-  private lockDirWritable(): boolean {
-    const probe = `${this.lockPath}.${process.pid}.${randomUUID()}.probe`;
+  private loadedFrom(state: ReducedTask, log: LogRead, snapshotSeq: number) {
+    const last = log.events.at(-1)!;
+    return {
+      state,
+      seq: last.seq,
+      lastId: last.id,
+      lastStart: log.lastStart,
+      end: log.end,
+      size: log.size,
+      snapshotSeq,
+    };
+  }
+
+  private readSnapshot(taskId: Id): Snapshot | null {
     try {
-      fs.closeSync(fs.openSync(probe, "wx", 0o600));
+      const value = JSON.parse(fs.readFileSync(this.snapshotPath(taskId), "utf8")) as unknown;
+      if (
+        !isObject(value) ||
+        value.v !== 1 ||
+        value.task !== taskId ||
+        typeof value.seq !== "number" ||
+        typeof value.lastId !== "string" ||
+        typeof value.lastStart !== "number" ||
+        typeof value.end !== "number" ||
+        !isObject(value.record)
+      )
+        return null;
+      return value as Snapshot;
     } catch {
-      return false;
+      return null;
     }
+  }
+
+  private writeSnapshot(taskId: Id, loaded: Omit<Loaded, "size" | "snapshotSeq">) {
+    const snapshot: Snapshot = {
+      v: 1,
+      task: taskId,
+      seq: loaded.seq,
+      lastId: loaded.lastId,
+      lastStart: loaded.lastStart,
+      end: loaded.end,
+      key: loaded.key,
+      legacy: loaded.legacy,
+      record: loaded.record,
+    };
     try {
-      fs.rmSync(probe, { force: true });
+      // A cache: a lost or torn snapshot only costs a replay.
+      replaceFile(this.snapshotPath(taskId), JSON.stringify(snapshot), false);
     } 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";
-    }
+  /** The task when it exists and belongs to this checkout. */
+  private loadBound(taskId: Id): Result<Loaded> {
+    const loaded = this.load(taskId);
+    if (!loaded.ok) return loaded;
+    if (!loaded.data) return failure("not_found", "task not found", { taskId });
+    const workspace = this.readWorkspace();
+    if (!workspace.ok) return workspace;
+    const bound = this.bindingError(loaded.data.record, workspace.data);
+    return bound ?? success(null, null, loaded.data);
   }
 
-  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 : "";
-    // 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" ||
-      code === "file_lock_timeout" ||
-      code === "file_lock_stale" ||
-      code === "metadata_lock_invalid" ||
-      code === "not-file" ||
-      /metadata lock|file lock|reclaim/i.test(String(value?.message ?? error));
+  private bindingError(task: TaskRecord, workspace: WorkspaceRecord | null): Result<never> | null {
+    if (workspace && task.workspaceId === workspace.id) return null;
     return failure(
-      recovery ? "recovery_required" : "storage_error",
-      `metadata lock operation failed: ${String(error)}`,
-      { path: this.lockPath },
+      "not_found",
+      `task ${task.id} belongs to another checkout of this repository; run there, or move it here with \`workit task adopt ${task.id}\``,
+      { taskId: task.id },
     );
   }
 
-  private initializeMutationStorage() {
-    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 nextTask(
+    current: TaskRecord,
+    changed: TaskRecord,
+    context: MutationContext,
+  ): TaskRecord | null {
+    const valid = taskRecordSchema.safeParse({
+      ...changed,
+      id: current.id,
+      workspaceId: current.workspaceId,
+      createdAt: current.createdAt,
+      revision: context.revision,
+      updatedAt: context.now,
+      runtime: stampNew(current),
+    });
+    return valid.success ? valid.data : null;
+  }
+
+  private event(taskId: Id, seq: number, type: string, data: Record<string, unknown>): StoreEvent {
+    return {
+      v: EVENT_VERSION,
+      seq,
+      at: new Date().toISOString(),
+      id: newId(),
+      task: taskId,
+      actor: this.actor,
+      type,
+      data,
+    };
   }
 
-  private replaceSnapshot(file: string, value: unknown, previous: unknown): Result<any> {
-    let temporary: string | undefined;
+  /** Append the patch from `loaded` to `next` (under the task lock). */
+  private appendPatch(
+    loaded: Loaded,
+    next: TaskRecord,
+    extra: { key?: TaskKey | null; type?: string; legacy?: LegacyOrigin } = {},
+  ): Result<null> {
+    const taskId = next.id;
     try {
-      if (Buffer.isBuffer(previous)) this.saveRecovery(file, previous);
-      else if (previous !== null && typeof previous === "object")
-        this.saveRecovery(file, jsonBytes(previous));
-      else if (typeof previous === "string") this.saveRecovery(file, previous);
-      temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
-      const fd = fs.openSync(temporary, "wx", 0o600);
-      try {
-        fs.writeSync(fd, jsonBytes(value));
-        fs.fsyncSync(fd);
-      } finally {
-        fs.closeSync(fd);
-      }
-      retryTransient(() => fs.renameSync(temporary!, file));
-      temporary = undefined;
-      this.fsyncDirectory(path.dirname(file));
-      if (path.dirname(file) === this.tasksDir) this.indexTaskWrite(file, value as TaskRecord);
-      return success(null, null, value);
+      const blobs = this.blobStore();
+      const before = loaded.record as unknown as Record<string, unknown>;
+      const after = next as unknown as Record<string, unknown>;
+      const ops = encodeOps(diff(before, after), blobs);
+      const { type, ...data } = extra;
+      if (data.key)
+        data.key = { ...data.key, boundAt: data.key.boundAt ?? new Date().toISOString() };
+      const event = this.event(
+        taskId,
+        loaded.seq + 1,
+        type ?? ("key" in extra ? "task.bound" : eventType(before, after)),
+        { ops, ...data },
+      );
+      const start = appendEvent(this.eventsPath(taskId), event, loaded.end);
+      const end = start + Buffer.byteLength(`${JSON.stringify(event)}\n`);
+      const key = "key" in data ? (data.key ?? null) : loaded.key;
+      const state = {
+        record: next,
+        key,
+        legacy: extra.legacy ?? loaded.legacy,
+        seq: event.seq,
+        lastId: event.id,
+        lastStart: start,
+        end,
+      };
+      if (
+        event.seq - loaded.snapshotSeq >= SNAPSHOT_EVERY ||
+        next.status !== loaded.record.status ||
+        loaded.snapshotSeq === 0
+      )
+        this.writeSnapshot(taskId, state);
+      // Bounded without a gc run: a log past the watermark is folded once
+      // this write releases its lock (see compactDue).
+      if (end > AUTO_COMPACT_BYTES) this.compactDue.add(taskId);
+      this.indexTask(next, key, (extra.legacy ?? loaded.legacy) !== null);
+      return success(null, null, null);
     } catch (error) {
-      return failure("storage_error", `snapshot replacement failed: ${String(error)}`, {
-        path: file,
+      return failure("storage_error", `task append failed: ${String(error)}`, {
+        path: this.eventsPath(taskId),
       });
-    } finally {
-      if (temporary)
-        try {
-          fs.unlinkSync(temporary);
-        } catch {}
     }
   }
 
-  private readIndex(workspaceId: Id): Record<string, TaskIndexEntry> {
+  /** Write a new task's opening event. */
+  private openTask(
+    record: TaskRecord,
+    type: string,
+    key: TaskKey | null,
+    legacy: LegacyOrigin | null = null,
+  ) {
+    const dir = path.join(this.paths().tasks, record.id);
+    fs.mkdirSync(dir, { recursive: true });
+    const blobs = this.blobStore();
+    const bound = key ? { ...key, boundAt: key.boundAt ?? new Date().toISOString() } : null;
+    const event = this.event(record.id, 1, type, {
+      record: encodeRecord(record, blobs),
+      key: bound,
+      ...(legacy ? { legacy } : {}),
+    });
+    const file = this.eventsPath(record.id);
+    const existing = readLog(file, 0, null);
+    if (existing && existing.events.length > 0)
+      throw new Error(`task ${record.id} already has a log`);
+    appendEvent(file, event, 0);
+    this.indexTask(record, bound, legacy !== null);
+  }
+
+  /** Fold the logs that writes marked past AUTO_COMPACT_BYTES (best effort). */
+  private compactPending() {
+    for (const taskId of this.compactDue) {
+      this.compactDue.delete(taskId);
+      this.compact(taskId);
+    }
+  }
+
+  /**
+   * Compact a task log to a checkpoint + its last COMPACT_KEEP events. The
+   * checkpoint is built without the lock; the task lock is held only to
+   * check that the log still holds the events it was built from, carry over
+   * events appended meanwhile, and swap the file.
+   */
+  private compact(taskId: Id): Result<{ folded: number; bytes: number }> {
     try {
-      const value = JSON.parse(fs.readFileSync(this.indexPath, "utf8")) as unknown;
-      if (
-        !isObject(value) ||
-        value.version !== INDEX_VERSION ||
-        value.workspaceId !== workspaceId ||
-        !isObject(value.tasks)
-      )
-        return {};
-      const tasks: Record<string, TaskIndexEntry> = {};
-      for (const [id, entry] of Object.entries(value.tasks))
-        if (
-          isObject(entry) &&
-          entry.id === id &&
-          typeof entry.file === "string" &&
-          typeof entry.status === "string" &&
-          typeof entry.updatedAt === "string" &&
-          Array.isArray(entry.sessions) &&
-          isObject(entry.progress) &&
-          isObject(entry.source)
-        )
-          tasks[id] = entry as TaskIndexEntry;
-      return tasks;
-    } catch {
-      return {};
+      const file = this.eventsPath(taskId);
+      const log = readLog(file, 0, null);
+      if (!log || log.events.length <= COMPACT_KEEP + 1)
+        return success(null, null, { folded: 0, bytes: log?.size ?? 0 });
+      const blobs = this.blobStore();
+      const cut = log.events.length - COMPACT_KEEP;
+      let state: ReducedTask | null = null;
+      for (const event of log.events.slice(0, cut)) state = reduce(state, event, blobs);
+      const folded = log.events[cut - 1];
+      const checkpoint: StoreEvent = {
+        ...this.event(taskId, folded.seq, "task.checkpoint", {
+          record: encodeRecord(state!.record, blobs),
+          key: state!.key,
+          ...(state!.legacy ? { legacy: state!.legacy } : {}),
+          folded: { from: log.events[0].seq, to: folded.seq },
+        }),
+      };
+      const prefix = `${[checkpoint, ...log.events.slice(cut)].map((event) => JSON.stringify(event)).join("\n")}\n`;
+      const last = log.events.at(-1)!;
+      return this.withLock(this.taskLockPath(taskId), () => {
+        // The log must still hold the events read above (another compaction
+        // or a rewrite means start over next time).
+        let latest: LogRead | null = null;
+        try {
+          latest = readLog(file, log.lastStart, last.seq);
+        } catch {}
+        if (!latest || latest.events[0]?.id !== last.id)
+          return failure("busy", "the task log changed during compaction; retry", { taskId });
+        const appended = fs.readFileSync(file).subarray(log.end, latest.end);
+        const bytes = Buffer.concat([Buffer.from(prefix, "utf8"), appended]);
+        replaceFile(file, bytes.toString("utf8"), true);
+        // Re-anchor the snapshot on the rewritten log.
+        try {
+          fs.rmSync(this.snapshotPath(taskId), { force: true });
+        } catch {}
+        const reloaded = this.load(taskId);
+        if (reloaded.ok && reloaded.data) this.writeSnapshot(taskId, reloaded.data);
+        return success(null, null, { folded: cut, bytes: bytes.length });
+      });
+    } catch (error) {
+      return failure("storage_error", `compaction failed: ${String(error)}`, { taskId });
     }
   }
 
-  /** The index is a disposable cache: write it atomically, never fail the caller. */
-  private writeIndex(workspaceId: Id, entries: TaskIndexEntry[]) {
-    const temporary = `${this.indexPath}.${process.pid}.${randomUUID()}.tmp`;
+  private countEvents(file: string): number {
     try {
-      fs.writeFileSync(
-        temporary,
-        JSON.stringify({
-          version: INDEX_VERSION,
-          workspaceId,
-          tasks: Object.fromEntries(entries.map((entry) => [entry.id, entry])),
-        }),
-        { mode: 0o600, flag: "wx" },
-      );
-      retryTransient(() => fs.renameSync(temporary, this.indexPath));
+      const bytes = fs.readFileSync(file);
+      let count = 0;
+      for (let index = bytes.indexOf(0x0a); index >= 0; index = bytes.indexOf(0x0a, index + 1))
+        count += 1;
+      return count;
     } catch {
-      try {
-        fs.unlinkSync(temporary);
-      } catch {}
+      return 0;
     }
   }
 
-  private indexTaskWrite(file: string, task: TaskRecord) {
-    try {
-      const signature = fileSignature(file);
-      if (signature === null) return;
-      const tasks = this.readIndex(task.workspaceId);
-      tasks[task.id] = indexEntry(task, signature);
-      this.writeIndex(task.workspaceId, Object.values(tasks));
-    } catch {
-      // A stale index entry is repaired by the next listTaskIndex().
-    }
+  /**
+   * Open tasks bound to `key` anywhere in the store, oldest first (with
+   * duplicates, e.g. from a 2.x-era race, the oldest is the one used). A
+   * task follows its branch through `git branch -m`: it counts for the new
+   * name, and a branch created later under the old name starts fresh.
+   */
+  private openTasksForKey(key: string): Result<TaskIndexEntry[]> {
+    const all = this.listStoreIndex();
+    if (!all.ok) return all;
+    const location = this.location();
+    const renames = location.ok ? branchRenames(location.data) : [];
+    return success(
+      null,
+      null,
+      all.data
+        .filter((entry) => entry.key !== null && entry.status !== "closed")
+        .filter(
+          (entry) =>
+            (renames.length
+              ? followRenames(entry.key!, entry.boundAt ?? entry.createdAt, renames)
+              : entry.key) === key,
+        )
+        .toSorted(oldestFirst),
+    );
   }
 
-  private saveRecovery(file: string, bytes: string | Buffer) {
-    const target = path.basename(file) === "workspace.json" ? "workspace" : "task";
-    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(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 {
-      temporary = `${destination}.${process.pid}.${randomUUID()}.tmp`;
-      const fd = fs.openSync(temporary, "wx", 0o600);
-      try {
-        fs.writeSync(fd, bytes as any);
-        fs.fsyncSync(fd);
-      } finally {
-        fs.closeSync(fd);
-      }
-      retryTransient(() => fs.renameSync(temporary!, destination));
-      temporary = undefined;
-      this.fsyncDirectory(this.recoveryDir);
-      this.pruneRecovery(`${target}.${id}.`, destination);
-    } finally {
-      if (temporary)
-        try {
-          fs.unlinkSync(temporary);
-        } catch {}
-    }
+  private openTaskForKey(key: string): Result<TaskIndexEntry | null> {
+    const bound = this.openTasksForKey(key);
+    return bound.ok ? success(null, null, bound.data[0] ?? null) : bound;
   }
 
-  /**
-   * 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 {}
+  /** Serialize implicit-task binding for one key across the whole store. */
+  private withKeyLock<T>(key: string, operation: () => Result<T>): Result<T> {
+    const digest = createHash("sha256").update(key).digest("hex").slice(0, 32);
+    return this.withLock(path.join(this.paths().dir, "keys", `${digest}.lock`), operation);
   }
 
-  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 {}
+  /** Bind `taskId` to `key` and this checkout (under the checkout lock). */
+  private bindLocked(taskId: Id, key: TaskKey, timestamp?: Utc): Result<TaskRecord> {
+    const current = this.readWorkspace();
+    if (!current.ok) return current;
+    let workspace = current.data;
+    if (!workspace) {
+      workspace = this.nextWorkspace(null);
+      const written = this.writeWorkspace(workspace);
+      if (!written.ok) return written;
     }
-    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);
+    const target = workspace;
+    return this.withLock(this.taskLockPath(taskId), () => {
+      const loaded = this.load(taskId);
+      if (!loaded.ok) return loaded;
+      if (!loaded.data) return failure("not_found", "task not found", { taskId });
+      if (loaded.data.record.status === "closed")
+        return failure("invalid_transition", "a closed task cannot be adopted", { taskId });
+      if (loaded.data.record.workspaceId === target.id && loaded.data.key?.key === key.key)
+        return success(loaded.data.record.revision, null, loaded.data.record);
+      const next = taskRecordSchema.safeParse({
+        ...loaded.data.record,
+        workspaceId: target.id,
+        revision: newRevision(),
+        updatedAt: timestamp ?? now(),
+        runtime: stampNew(loaded.data.record),
+      });
+      if (!next.success) return failure("invalid_input", "rebound task is invalid");
+      const written = this.appendPatch(loaded.data, next.data, { key });
+      return written.ok ? success(next.data.revision, null, next.data) : written;
+    });
   }
 
-  /**
-   * `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 });
+  /** Release a task's implicit key (under the checkout lock). */
+  private unbindLocked(taskId: Id): Result<null> {
+    return this.withLock(this.taskLockPath(taskId), () => {
+      const loaded = this.load(taskId);
+      if (!loaded.ok) return loaded;
+      if (!loaded.data || loaded.data.key === null) return success(null, null, null);
+      return this.appendPatch(loaded.data, loaded.data.record, { key: null });
+    });
+  }
+
+  /** Create a task (under the checkout lock), bound to `key`, or with
+   * `bindCurrent` to the checkout's current key. */
+  private createLocked(
+    value: CreateInput,
+    bindCurrent: boolean,
+    key: TaskKey | null,
+    checkRevision = true,
+  ): Result<TaskRecord> {
+    const current = this.readWorkspace();
+    if (!current.ok) return current;
+    if (
+      checkRevision &&
+      (current.data
+        ? value.expectedWorkspaceRevision !== current.data.revision
+        : value.expectedWorkspaceRevision !== null)
+    )
+      return failure(
+        "revision_conflict",
+        "workspace revision does not match; omit expectedWorkspaceRevision to use the current record",
+        {
+          expectedWorkspaceRevision: value.expectedWorkspaceRevision,
+          actualWorkspaceRevision: current.data?.revision ?? null,
+        },
+      );
+    if (!value.provenance) return failure("invalid_input", "provenance is required");
+    if (
+      !intentSchema.safeParse(value.intent).success ||
+      !provenanceSchema.safeParse(value.provenance).success
+    )
+      return failure("invalid_input", "task intent or provenance is invalid");
+    // An explicitly started task takes the branch over: the task that held
+    // its key stays open, unbound (listed by `workit task status --all`).
+    if (bindCurrent) {
+      const currentKey = this.currentKey();
+      if (currentKey.ok)
+        return this.withKeyLock(currentKey.data.key, () => {
+          const holder = this.openTaskForKey(currentKey.data.key);
+          if (!holder.ok) return holder;
+          if (holder.data) {
+            const released = this.unbindLocked(holder.data.id);
+            if (!released.ok) return released;
           }
-        }
-        return success(null, null, null);
-      } catch (error) {
-        return failure("storage_error", `garbage collection failed: ${String(error)}`, {
-          path: this.recoveryDir,
+          return this.newTask(value, current.data, currentKey.data);
         });
-      }
-    };
-    // 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);
+    return this.newTask(value, current.data, key);
   }
 
-  private findRecovery(
-    target: "task" | "workspace",
-    taskId: Id | null,
-    digest: string,
-    workspace: WorkspaceRecord | null,
-  ): Buffer | null {
-    if (!fs.existsSync(this.recoveryDir)) return null;
-    const workspaceId = workspace?.id ?? this.trustedWorkspaceId();
-    if (target === "workspace" && !workspaceId) return null;
-    const candidates = this.recoveryCandidates();
-    if (!candidates.ok) return null;
-    for (const candidate of candidates.data) {
-      if (candidate.target !== target || candidate.digest !== digest) continue;
-      try {
-        if (!fs.lstatSync(candidate.path).isFile()) continue;
-        const bytes = fs.readFileSync(candidate.path);
-        if (digestBytes(bytes) !== digest) continue;
-        if (target === "workspace") {
-          const parsed = this.parseBytes<WorkspaceRecord>(bytes, workspaceRecordSchema);
-          if (parsed.ok && parsed.data.id === workspaceId && parsed.data.root === this.root)
-            return bytes;
-        } else {
-          const parsed = this.parseBytes<TaskRecord>(bytes, taskRecordSchema);
-          if (parsed.ok && parsed.data.id === taskId && parsed.data.workspaceId === workspace?.id)
-            return bytes;
-        }
-      } catch {}
-    }
-    return null;
+  /** Write a new task, bound to `binding` (under the checkout lock). */
+  private newTask(
+    value: CreateInput,
+    previous: WorkspaceRecord | null,
+    binding: TaskKey | null,
+  ): Result<TaskRecord> {
+    const current = { data: previous };
+    const workspace = this.nextWorkspace(current.data);
+    const timestamp = value.now ?? now();
+    const task: TaskRecord = {
+      schemaVersion: SCHEMA_VERSION,
+      id: newId(),
+      workspaceId: workspace.id,
+      revision: newRevision(),
+      createdAt: timestamp,
+      updatedAt: timestamp,
+      origin: null,
+      intent: {
+        id: newId(),
+        recordedAt: timestamp,
+        provenance: value.provenance,
+        data: value.intent,
+      },
+      constraints: [],
+      status: "active",
+      closure: null,
+      progress: { summary: "", nextAction: null, blockers: [] },
+      runtime: { createdWith: runtimeVersion(), updatedWith: runtimeVersion() },
+      assessments: [],
+      policy: null,
+      policyChanges: [],
+      candidates: [],
+      evidence: [],
+      decisions: [],
+      findings: [],
+      workers: [],
+    };
+    return this.writeNewTask(current.data, workspace, task, "task.opened", binding, {
+      operation: "create",
+    });
+  }
+
+  private nextWorkspace(current: WorkspaceRecord | null, id?: Id): WorkspaceRecord {
+    return current
+      ? { ...current, revision: newRevision(), root: this.root, runtime: stampNew(current) }
+      : {
+          schemaVersion: SCHEMA_VERSION,
+          id: id ?? newId(),
+          revision: newRevision(),
+          root: this.root,
+          runtime: { createdWith: runtimeVersion(), updatedWith: runtimeVersion() },
+          writer: null,
+        };
   }
 
-  private fsyncDirectory(directory: string) {
+  /** Write the workspace, then the task's opening event; undo the workspace on failure. */
+  private writeNewTask(
+    previous: WorkspaceRecord | null,
+    workspace: WorkspaceRecord,
+    task: TaskRecord,
+    type: string,
+    key: TaskKey | null,
+    details: { operation: string },
+  ): Result<TaskRecord> {
+    const written = this.writeWorkspace(workspace);
+    if (!written.ok) return written;
     try {
-      const fd = fs.openSync(directory, "r");
-      try {
-        fs.fsyncSync(fd);
-      } finally {
-        fs.closeSync(fd);
-      }
+      this.openTask(task, type, key);
     } catch (error) {
-      // Windows rejects fsync on a directory handle; the rename is the durable step there.
-      if (process.platform !== "win32") throw error;
+      if (previous) {
+        const restored = this.writeWorkspace(previous);
+        if (!restored.ok)
+          return failure(
+            "external_outcome_unknown",
+            `task ${details.operation} failed and workspace restoration is uncertain`,
+            { ...details, outcome: "unknown" },
+          );
+      }
+      return failure(
+        "external_outcome_unknown",
+        `workspace written but the task log is uncertain: ${String(error)}`,
+        { ...details, outcome: "unknown" },
+      );
     }
+    return success(task.revision, workspace.revision, task);
   }
 
-  private trustedWorkspaceId(): Id | null {
-    if (!fs.existsSync(this.tasksDir)) return null;
-    const ids = new Set<Id>();
+  private writeWorkspace(record: WorkspaceRecord): Result<null> {
+    const file = this.paths().workspace;
     try {
-      for (const name of fs.readdirSync(this.tasksDir)) {
-        if (!name.endsWith(".json") || !validId(name.slice(0, -5))) return null;
-        const parsed = this.parseBytes<TaskRecord>(
-          fs.readFileSync(path.join(this.tasksDir, name)),
-          taskRecordSchema,
-        );
-        if (!parsed.ok || parsed.data.id !== name.slice(0, -5)) return null;
-        ids.add(parsed.data.workspaceId);
-      }
-    } catch {
-      return null;
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      replaceFile(file, `${canonicalJson(record)}\n`, true);
+      return success(null, null, null);
+    } catch (error) {
+      return failure("storage_error", `workspace write failed: ${String(error)}`, { path: file });
     }
-    return ids.size === 1 ? [...ids][0] : null;
   }
 
-  private snapshotBytes(file: string): Buffer | null {
+  private markUncertain(workspace: WorkspaceRecord) {
+    if (!workspace.writer || workspace.writer.state === "uncertain") return;
+    this.writeWorkspace({
+      ...workspace,
+      writer: { ...workspace.writer, state: "uncertain" as const },
+      revision: newRevision(),
+      runtime: stampNew(workspace),
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // internals: index cache
+
+  private readIndex(): Record<string, TaskIndexEntry> {
     try {
-      return retryTransient(() => fs.readFileSync(file));
+      const value = JSON.parse(fs.readFileSync(this.paths().index, "utf8")) as unknown;
+      if (!isObject(value) || value.version !== INDEX_VERSION || !isObject(value.tasks)) return {};
+      const tasks: Record<string, TaskIndexEntry> = {};
+      for (const [id, entry] of Object.entries(value.tasks))
+        if (
+          isObject(entry) &&
+          entry.id === id &&
+          typeof entry.file === "string" &&
+          typeof entry.status === "string" &&
+          typeof entry.updatedAt === "string" &&
+          typeof entry.workspaceId === "string" &&
+          Array.isArray(entry.sessions) &&
+          isObject(entry.progress) &&
+          isObject(entry.source)
+        )
+          tasks[id] = entry as TaskIndexEntry;
+      return tasks;
     } catch {
-      return null;
+      return {};
     }
   }
 
-  private readRecord<T>(file: string, schema: z.ZodType) {
+  /** The index is a disposable cache: write it atomically, never fail the caller. */
+  private writeIndex(entries: TaskIndexEntry[]) {
     try {
-      const bytes = retryTransient(() => fs.readFileSync(file, "utf8"));
-      return { exists: true, result: this.parseBytes<T>(bytes, schema) };
-    } catch (error: any) {
-      if (error?.code === "ENOENT")
-        return { exists: false, result: success(null, null, null as T) };
-      return {
-        exists: true,
-        result: failure("recovery_required", `snapshot cannot be read: ${String(error)}`, {
-          path: file,
+      fs.mkdirSync(this.paths().tasks, { recursive: true });
+      replaceFile(
+        this.paths().index,
+        JSON.stringify({
+          version: INDEX_VERSION,
+          tasks: Object.fromEntries(entries.map((entry) => [entry.id, entry])),
         }),
-      };
+        false,
+      );
+    } catch {}
+  }
+
+  private indexTask(task: TaskRecord, key: TaskKey | null, legacy: boolean) {
+    try {
+      const signature = fileSignature(this.eventsPath(task.id));
+      if (signature === null) return;
+      const tasks = this.readIndex();
+      tasks[task.id] = indexEntry(task, key, legacy, signature);
+      this.writeIndex(Object.values(tasks));
+    } catch {
+      // A stale index entry is repaired by the next listing.
     }
   }
 
-  /** `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: z.ZodType,
-    mode: "read" | "rewrite" = "read",
+  // -------------------------------------------------------------------------
+  // internals: record parsing
+
+  private parseTask(record: Record<string, unknown>, taskId: Id): Result<TaskRecord> {
+    const parsed = this.parseValue<TaskRecord>(record, taskRecordSchema, "task");
+    if (!parsed.ok) return { ...parsed, details: { ...parsed.details, taskId } };
+    if (parsed.data.id !== taskId)
+      return failure("recovery_required", "task log and record ID differ", { taskId });
+    return parsed;
+  }
+
+  private parseRecord<T>(
+    bytes: string,
+    schema: typeof taskRecordSchema | typeof workspaceRecordSchema,
+    label: string,
   ): Result<T> {
     let value: unknown;
     try {
-      value = JSON.parse(typeof bytes === "string" ? bytes : bytes.toString("utf8"));
+      value = JSON.parse(bytes);
     } catch {
-      return failure("recovery_required", "snapshot JSON is corrupt");
+      return failure("recovery_required", `${label} record JSON is corrupt`);
     }
+    return this.parseValue<T>(value, schema, label);
+  }
+
+  private parseValue<T>(
+    value: unknown,
+    schema: typeof taskRecordSchema | typeof workspaceRecordSchema,
+    label: string,
+  ): Result<T> {
     if (isObject(value) && "schemaVersion" in value && value.schemaVersion !== SCHEMA_VERSION)
-      return failure("unsupported_version", "unsupported snapshot schema version");
+      return failure("unsupported_version", `unsupported ${label} schema version`);
     const parsed = parseStoredRecord(schema, value);
-    if (parsed.success && (mode === "read" || parsed.stripped.length === 0))
-      return success(null, null, parsed.data as T);
+    if (parsed.success) 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}`,
-      );
+      isObject(value) && isObject(value.runtime) ? value.runtime.updatedWith : null;
     if (parsed.critical.length > 0)
       return failure(
         "recovery_required",
-        `snapshot requires fields this Workit cannot read (${parsed.critical.join(", ")}); ${upgrade}`,
+        `${label} record requires fields this Workit cannot read (${parsed.critical.join(", ")}); upgrade Workit before mutating this checkout`,
       );
     if (typeof writerVersion === "string" && isNewerVersion(writerVersion, runtimeVersion()))
       return failure(
         "recovery_required",
-        `snapshot was written by workit ${writerVersion}; upgrade Workit before mutating this checkout`,
+        `${label} record was written by workit ${writerVersion}; upgrade Workit before mutating this checkout`,
       );
-    return failure("recovery_required", "snapshot does not satisfy its schema");
+    return failure("recovery_required", `${label} record does not satisfy its schema`);
   }
 
   private conflict(expected: Revision, actual: Revision): Result<never> {
     return failure(
       "revision_conflict",
       "snapshot revision does not match; omit expectedRevision to use the current record",
-      {
-        expectedRevision: expected,
-        actualRevision: actual,
-      },
+      { expectedRevision: expected, actualRevision: actual },
     );
   }
 
@@ -1792,28 +1876,542 @@ export class TaskStore {
     );
   }
 
-  private taskPath(taskId: Id) {
-    return path.join(this.tasksDir, `${taskId}.json`);
+  // -------------------------------------------------------------------------
+  // internals: 2.x migration
+
+  /** 2.x stores this checkout may have: `<top>/.workit`, and `<dir>/.workit`
+   * when the store was opened from a subdirectory. */
+  private v2Dirs(): string[] {
+    return [...new Set([this.root, this.origin])].map((dir) => path.join(dir, ".workit"));
   }
-  private get workitDir() {
-    return path.join(this.root, ".workit");
+
+  /** 2.x stores waiting to migrate into this checkout. (A pre-git 3.x
+   * store is this runtime's own data and moves on any access.) */
+  private pendingMigrations(): string[] {
+    return this.v2Dirs().filter((dir) => {
+      const raw = this.readV2Workspace(path.join(dir, "workspace.json"));
+      return raw !== null && raw !== TOMBSTONE;
+    });
   }
-  private get tasksDir() {
-    return path.join(this.workitDir, "tasks");
+
+  /**
+   * Migrate the 2.x store in `v2` (tasks/*.json + workspace.json) into this
+   * store, under the checkout lock and the 2.x store's own metadata lock (S1
+   * identity and reclaim rules), so a live 2.x writer is never migrated
+   * under: its lock makes this `busy` and nothing changes.
+   *   1. back up the 2.x files to legacy/<checkout>/v2/ (refreshed each run);
+   *   2. each task file is migrated by content: a new task becomes
+   *      tasks/<id>/events.jsonl with one `migrated.from_v2` event holding the
+   *      whole record and the file's digest; a task already migrated from
+   *      other bytes (a 2.x write after an interrupted run) gets the
+   *      difference appended as another `migrated.from_v2` event;
+   *   3. the tasks join this checkout's workspace (the existing 3.x record,
+   *      else the 2.x one, so nothing migrated is hidden);
+   *   4. each task file is replaced by a marker only while its digest still
+   *      matches what was migrated (compare-and-swap under the 2.x lock);
+   *   5. `.workit/workspace.json` becomes the marker last, so an interrupted
+   *      run is finished by the next one.
+   * `.workit/recovery` is left in place (`workit gc` reports it).
+   */
+  private migrateV2(v2: string): Result<null> {
+    const dirs = this.paths();
+    const v2Workspace = path.join(v2, "workspace.json");
+    const v2Tasks = path.join(v2, "tasks");
+    const legacy = path.join(dirs.dir, "legacy", checkoutSlug(path.dirname(v2)), "v2");
+    const raw = this.readV2Workspace(v2Workspace);
+    if (raw === null || raw === TOMBSTONE) return success(null, null, null);
+    return this.withLock(dirs.checkoutLock, () =>
+      this.withLock(path.join(v2, "metadata.lock"), () => {
+        const workspace = this.readV2Workspace(v2Workspace);
+        if (workspace === null || workspace === TOMBSTONE) return success(null, null, null);
+        const parsedWorkspace = this.parseRecord<WorkspaceRecord>(
+          workspace.bytes,
+          workspaceRecordSchema,
+          "2.x workspace",
+        );
+        if (!parsedWorkspace.ok)
+          return failure(
+            "recovery_required",
+            `cannot migrate the 2.x store at ${v2}: ${parsedWorkspace.error}; move it aside to start fresh`,
+            { path: v2Workspace },
+          );
+        let files: string[] = [];
+        try {
+          files = fs
+            .readdirSync(v2Tasks)
+            .filter((name) => name.endsWith(".json") && validId(name.slice(0, -5)))
+            .filter((name) => !this.isStub(path.join(v2Tasks, name)));
+        } catch {}
+        const current = this.readWorkspace();
+        if (!current.ok) return current;
+        let workspaceMoved = false;
+        let target = current.data;
+        if (!target) {
+          target = { ...parsedWorkspace.data, root: this.root };
+          const written = this.writeWorkspace(target);
+          if (!written.ok) return written;
+          workspaceMoved = true;
+        }
+        let migrated = 0;
+        let skipped = 0;
+        const done = new Map<string, string>();
+        try {
+          fs.mkdirSync(path.join(legacy, "tasks"), { recursive: true });
+          for (const name of ["workspace.json", "index.json"])
+            if (fs.existsSync(path.join(v2, name)))
+              fs.copyFileSync(path.join(v2, name), path.join(legacy, name));
+          for (const name of files) {
+            const id = name.slice(0, -5);
+            const file = path.join(v2Tasks, name);
+            const bytes = fs.readFileSync(file, "utf8");
+            const digest = sha256(bytes);
+            fs.writeFileSync(path.join(legacy, "tasks", name), bytes);
+            const parsed = this.parseRecord<TaskRecord>(bytes, taskRecordSchema, "2.x task");
+            if (!parsed.ok || parsed.data.id !== id)
+              return failure(
+                "recovery_required",
+                `cannot migrate 2.x task ${id}: ${parsed.ok ? "file name and record ID differ" : parsed.error}; move ${file} aside to continue`,
+                { path: file },
+              );
+            const record = { ...parsed.data, workspaceId: target.id };
+            const origin = { path: path.join(legacy, "tasks", name), digest };
+            if (!fs.existsSync(this.eventsPath(id))) {
+              this.openTask(record, "migrated.from_v2", null, origin);
+              migrated += 1;
+            } else {
+              const resynced = this.withLock(this.taskLockPath(id), () => {
+                const loaded = this.load(id);
+                if (!loaded.ok) return loaded;
+                if (!loaded.data) return failure("not_found", "task not found", { taskId: id });
+                if (loaded.data.legacy?.digest === digest) return success(null, null, false);
+                const appended = this.appendPatch(loaded.data, record, {
+                  type: "migrated.from_v2",
+                  legacy: origin,
+                });
+                return appended.ok ? success(null, null, true) : appended;
+              });
+              if (!resynced.ok) return resynced;
+              if (resynced.data) migrated += 1;
+              else skipped += 1;
+            }
+            done.set(name, digest);
+          }
+        } catch (error) {
+          return failure(
+            "storage_error",
+            `cannot migrate the 2.x store at ${v2}: ${String(error)}`,
+            {
+              path: v2,
+            },
+          );
+        }
+        try {
+          // Compare-and-swap: replace a 2.x task file by a marker (so a 2.x
+          // reader asked for it by id fails closed) only if it still holds
+          // the bytes just migrated; otherwise leave the store unfinished so
+          // the next run migrates the change.
+          let complete = true;
+          for (const [name, digest] of done) {
+            const file = path.join(v2Tasks, name);
+            if (sha256(fs.readFileSync(file, "utf8")) !== digest) {
+              complete = false;
+              continue;
+            }
+            replaceFile(file, this.stubFor(name.slice(0, -5)), false);
+          }
+          if (!complete)
+            return failure("busy", `the 2.x store at ${v2} changed during migration; retry`, {
+              path: v2,
+            });
+          fs.rmSync(path.join(v2, "index.json"), { force: true });
+          this.writeTombstone(v2, target.id);
+        } catch (error) {
+          return failure("storage_error", `cannot finish the 2.x migration: ${String(error)}`, {
+            path: v2,
+          });
+        }
+        reportMigration({
+          from: v2,
+          to: dirs.dir,
+          backup: legacy,
+          tasks: migrated,
+          skipped,
+          workspace: workspaceMoved,
+        });
+        return success(null, null, null);
+      }),
+    );
+  }
+
+  /**
+   * A 3.x store kept in `<root>/.workit` while the directory was not a git
+   * repository moves into the git store once it is one: task logs, checkout
+   * records, blobs and (when the git store has none) the ledger. Entries the
+   * git store already has are left in place. The local marker is renamed so
+   * this runs once.
+   */
+  private adoptLocalStore(): Result<null> {
+    const dirs = this.paths();
+    const marker = path.join(dirs.v2, "store.json");
+    if (!dirs.shared || !fs.existsSync(marker)) return success(null, null, null);
+    return this.withLock(dirs.checkoutLock, () => {
+      if (!fs.existsSync(marker)) return success(null, null, null);
+      let tasks = 0;
+      try {
+        // Move what the git store lacks; merge directories both have.
+        const merge = (from: string, to: string) => {
+          if (!fs.existsSync(to)) {
+            fs.mkdirSync(path.dirname(to), { recursive: true });
+            try {
+              fs.renameSync(from, to);
+            } catch {
+              fs.cpSync(from, to, { recursive: true, errorOnExist: true, force: false });
+              fs.rmSync(from, { recursive: true, force: true });
+            }
+            return;
+          }
+          if (fs.lstatSync(from).isDirectory() && fs.lstatSync(to).isDirectory())
+            for (const name of fs.readdirSync(from))
+              merge(path.join(from, name), path.join(to, name));
+        };
+        for (const sub of ["tasks", "checkouts", "blobs", "legacy"]) {
+          const from = path.join(dirs.v2, sub);
+          if (!fs.existsSync(from)) continue;
+          if (sub === "tasks")
+            for (const name of fs.readdirSync(from))
+              if (validId(name) && !fs.existsSync(path.join(dirs.dir, sub, name))) tasks += 1;
+          merge(from, path.join(dirs.dir, sub));
+        }
+        const ledger = path.join(dirs.v2, "ledger");
+        if (fs.existsSync(ledger) && !fs.existsSync(path.join(dirs.dir, "ledger")))
+          merge(ledger, path.join(dirs.dir, "ledger"));
+        fs.rmSync(path.join(dirs.v2, "task-index.json"), { force: true });
+        fs.renameSync(marker, path.join(dirs.v2, "store.moved.json"));
+      } catch (error) {
+        return failure(
+          "storage_error",
+          `cannot move ${dirs.v2} into ${dirs.dir}: ${String(error)}`,
+          {
+            path: dirs.v2,
+          },
+        );
+      }
+      reportMigration({
+        from: dirs.v2,
+        to: dirs.dir,
+        backup: dirs.v2,
+        tasks,
+        skipped: 0,
+        workspace: false,
+      });
+      return success(null, null, null);
+    });
+  }
+
+  /** The 2.x workspace bytes, TOMBSTONE for a 3.x marker, or null when absent. */
+  private readV2Workspace(file: string): { bytes: string } | typeof TOMBSTONE | null {
+    let bytes: string;
+    try {
+      bytes = fs.readFileSync(file, "utf8");
+    } catch {
+      return null;
+    }
+    try {
+      const value = JSON.parse(bytes) as unknown;
+      if (isObject(value) && isObject(value.store) && value.store.format === "workit-store")
+        return TOMBSTONE;
+    } catch {}
+    return { bytes };
+  }
+
+  /**
+   * `<root>/.workit/workspace.json` as a marker 2.x readers fail closed on:
+   * its `store` field is declared critical, and runtimes that predate the
+   * critical rule reject it as written by a newer Workit.
+   */
+  private writeTombstone(v2: string, workspaceId: Id | null) {
+    const dirs = this.paths();
+    const version = isNewerVersion(runtimeVersion(), STORE_MIN_RUNTIME)
+      ? runtimeVersion()
+      : STORE_MIN_RUNTIME;
+    const marker = {
+      schemaVersion: SCHEMA_VERSION,
+      id: workspaceId ?? newId(),
+      revision: newRevision(),
+      root: path.dirname(v2),
+      runtime: { createdWith: version, updatedWith: version },
+      writer: null,
+      store: {
+        format: "workit-store",
+        version: STORE_FORMAT,
+        path: dirs.dir,
+        note: `workit ${STORE_MIN_RUNTIME}+ keeps task state in ${dirs.dir}; upgrade Workit`,
+      },
+      critical: ["store"],
+    };
+    fs.mkdirSync(v2, { recursive: true });
+    // Keep the marker directory out of version control.
+    const ignore = path.join(v2, ".gitignore");
+    if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, "*\n");
+    replaceFile(path.join(v2, "workspace.json"), `${JSON.stringify(marker, null, 2)}\n`, true);
+  }
+
+  /** The marker that replaces a migrated 2.x task file. */
+  private stubFor(taskId: Id): string {
+    const version = isNewerVersion(runtimeVersion(), STORE_MIN_RUNTIME)
+      ? runtimeVersion()
+      : STORE_MIN_RUNTIME;
+    return `${JSON.stringify({
+      schemaVersion: SCHEMA_VERSION,
+      id: taskId,
+      runtime: { createdWith: version, updatedWith: version },
+      store: { format: "workit-store", version: STORE_FORMAT, path: this.paths().dir },
+      critical: ["store"],
+    })}\n`;
+  }
+
+  private isStub(file: string): boolean {
+    try {
+      const value = JSON.parse(fs.readFileSync(file, "utf8")) as unknown;
+      return isObject(value) && isObject(value.store) && value.store.format === "workit-store";
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Every checkout this runtime writes for carries the marker at
+   * `<top>/.workit/workspace.json`, so a 2.x runtime never starts a second,
+   * divergent store there (it fails closed with the upgrade message).
+   */
+  private writeTombstoneIfMissing() {
+    try {
+      const v2 = path.join(this.root, ".workit");
+      if (fs.existsSync(path.join(v2, "workspace.json"))) return;
+      let id: Id | null = null;
+      try {
+        id =
+          (JSON.parse(fs.readFileSync(this.paths().workspace, "utf8")) as { id?: Id }).id ?? null;
+      } catch {}
+      this.writeTombstone(v2, id);
+    } catch {}
+  }
+
+  // -------------------------------------------------------------------------
+  // internals: locks
+
+  private initializeStorage() {
+    const dirs = this.paths();
+    retryTransient(() => fs.mkdirSync(dirs.checkout, { recursive: true }));
+    retryTransient(() => fs.mkdirSync(dirs.tasks, { recursive: true }));
+    if (!fs.existsSync(dirs.marker))
+      replaceFile(
+        dirs.marker,
+        `${JSON.stringify({ format: "workit-store", version: STORE_FORMAT, createdWith: runtimeVersion() })}\n`,
+        false,
+      );
+    if (!dirs.shared) {
+      // Outside git the store sits in the checkout: keep it out of any VCS.
+      const ignore = path.join(dirs.dir, ".gitignore");
+      let current: string | null = null;
+      try {
+        current = fs.readFileSync(ignore, "utf8");
+      } catch {}
+      if (current !== "*\n") retryTransient(() => fs.writeFileSync(ignore, "*\n"));
+    }
+    this.writeTombstoneIfMissing();
+  }
+
+  /**
+   * Lock options: 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 lockOptions(lockPath: string): FileLockSyncAcquireOptions<MetadataLock> & {
+    payload: () => MetadataLock;
+  } {
+    const inProcess = heldInProcess.has(lockPath);
+    return {
+      lockPath,
+      staleMs: Number.MAX_SAFE_INTEGER,
+      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(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: processStartOf(process.pid),
+        host: localLockHost(),
+        nonce: randomUUID(),
+      }),
+    };
   }
-  private get recoveryDir() {
-    return path.join(this.workitDir, "recovery");
+
+  private acquire(
+    lockPath: string,
+    options: FileLockSyncAcquireOptions<MetadataLock>,
+  ): FileLockSyncHandle {
+    clearAbandonedReclaimGuard(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(lockPath, {
+          ...options,
+          timeoutMs: Math.max(0, deadline - Date.now()),
+        });
+      } catch (error) {
+        const code = (error as { code?: unknown })?.code;
+        if (
+          (code !== "file_lock_stale" && !isTransientWindowsError(error)) ||
+          Date.now() >= deadline
+        )
+          throw error;
+        // A Windows denial with no visible holder and a directory that
+        // refuses new files is a permission problem: fail fast.
+        if (
+          code !== "file_lock_stale" &&
+          !this.lockHolderPresent(lockPath) &&
+          !this.lockDirWritable(lockPath)
+        )
+          throw error;
+        if (code !== "file_lock_stale")
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+      }
+    }
   }
-  private get workspacePath() {
-    return path.join(this.workitDir, "workspace.json");
+
+  private withLock<T>(lockPath: string, operation: () => Result<T>): Result<T> {
+    try {
+      this.initializeStorage();
+      fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    } catch (error) {
+      return failure("storage_error", `unable to initialize store: ${String(error)}`, {
+        path: this.paths().dir,
+      });
+    }
+    let handle: FileLockSyncHandle;
+    try {
+      handle = this.acquire(lockPath, this.lockOptions(lockPath));
+    } catch (error) {
+      return this.lockFailure(lockPath, error);
+    }
+    hold(lockPath);
+    let result: Result<T>;
+    try {
+      if (!handle.verifyStillHeld())
+        result = failure("recovery_required", "metadata lock was compromised", { path: lockPath });
+      else {
+        try {
+          result = operation();
+        } catch (error) {
+          result = failure("storage_error", `mutation failed: ${String(error)}`);
+        }
+      }
+    } catch (error) {
+      result = this.lockFailure(lockPath, error);
+    }
+    drop(lockPath);
+    try {
+      retryTransient(() => handle.release());
+    } catch (error) {
+      const released = this.lockFailure(lockPath, error);
+      const releaseError = released.ok ? "metadata lock release failed" : released.error;
+      result = result.ok
+        ? released
+        : failure("recovery_required", `${result.error}; ${releaseError}`, result.details);
+    }
+    return result;
   }
-  private get indexPath() {
-    return path.join(this.workitDir, "index.json");
+
+  /** Whether the lock's directory accepts a new file right now. */
+  private lockDirWritable(lockPath: string): boolean {
+    const probe = `${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;
   }
-  private get lockPath() {
-    return path.join(this.workitDir, "metadata.lock");
+
+  /** A lock file (or an entry Windows is still tearing down) exists. */
+  private lockHolderPresent(lockPath: string): boolean {
+    try {
+      fs.lstatSync(lockPath);
+      return true;
+    } catch (error) {
+      return (error as { code?: unknown } | null)?.code !== "ENOENT";
+    }
   }
-  private get gitignorePath() {
-    return path.join(this.workitDir, ".gitignore");
+
+  private lockFailure(lockPath: string, error: unknown): Result<never> {
+    const value = error as { code?: unknown; message?: unknown };
+    const code = typeof value?.code === "string" ? value.code : "";
+    // A sharing-class denial is contention only when someone holds the lock.
+    if (
+      isTransientWindowsError(error) &&
+      !this.lockHolderPresent(lockPath) &&
+      !this.lockDirWritable(lockPath)
+    )
+      return failure(
+        "storage_error",
+        `cannot create the workit lock (${code}); no other Workit call holds it`,
+        {
+          path: lockPath,
+          guidance: `Check permissions and the read-only attribute on ${path.dirname(lockPath)}.`,
+        },
+      );
+    if (
+      code === "EEXIST" ||
+      code === "file_lock_timeout" ||
+      code === "file_lock_stale" ||
+      isTransientWindowsError(error)
+    ) {
+      let lock: MetadataLock | null = null;
+      try {
+        lock = parseMetadataLockOrNull(fs.readFileSync(lockPath, "utf8"));
+      } catch {}
+      if (lock?.externalAction)
+        return failure("writer_conflict", "workspace is reserved by a managed external action", {
+          outcome: "not_started",
+          path: lockPath,
+        });
+      return failure(
+        "busy",
+        `workit lock is held by another Workit call${lock ? ` (pid ${lock.pid} on ${lock.host})` : ""}; retry shortly`,
+        {
+          outcome: "not_started",
+          path: 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 === "metadata_lock_invalid" ||
+      code === "not-file" ||
+      /metadata lock|file lock|reclaim/i.test(String(value?.message ?? error));
+    return failure(
+      recovery ? "recovery_required" : "storage_error",
+      `lock operation failed: ${String(error)}`,
+      { path: lockPath },
+    );
   }
 }