@zhivex-ai/harness 1.4.0-rc.6 → 1.4.0

package/dist/{index-49ys3s4q.js → index-5jhgatga.js}

@@ -1,17 +1,19 @@
 import {
-  createHarnessClientAdapter,
+  createHarnessClientAdapter
+} from "./index-937cb7y8.js";
+import {
   harnessPolicyDecisionEventSchema
-} from "./index-4j1h4j8c.js";
+} from "./index-pp474137.js";
 import {
   openCliSessionStore
-} from "./index-vtqfjnab.js";
+} from "./index-s2k2edts.js";
 import {
   SqliteDatabase
-} from "./index-r0tdj04h.js";
+} from "./index-m34q25jj.js";
 import {
   harnessClientRequestSchema,
   streamEventDocument
-} from "./index-qfpz5y2v.js";
+} from "./index-nmjdwd4p.js";
 import {
   __require
 } from "./index-1bx83sw4.js";
@@ -63,6 +65,14 @@ var openHarnessActivityStore = async (config, options = {}) => {
   db.exec(`CREATE TABLE IF NOT EXISTS client_activity_events(sequence INTEGER PRIMARY KEY AUTOINCREMENT, scope TEXT NOT NULL, session TEXT NOT NULL, run TEXT NOT NULL, at INTEGER NOT NULL, activity TEXT NOT NULL);
     CREATE INDEX IF NOT EXISTS client_activity_scope ON client_activity_events(scope, session, sequence);
     CREATE TABLE IF NOT EXISTS client_activity_snapshots(scope TEXT NOT NULL, session TEXT NOT NULL, sequence INTEGER NOT NULL, expired_through INTEGER NOT NULL DEFAULT 0, snapshot TEXT NOT NULL, PRIMARY KEY(scope,session));`);
+  const readSnapshot = db.query("SELECT snapshot,expired_through FROM client_activity_snapshots WHERE scope=? AND session=?");
+  const expiredEvents = db.query(`SELECT session,MAX(sequence) AS seq FROM client_activity_events WHERE scope=? AND (at < ? OR sequence NOT IN (SELECT sequence FROM client_activity_events WHERE scope=? ORDER BY sequence DESC LIMIT ?)) GROUP BY session`);
+  const markExpired = db.query("UPDATE client_activity_snapshots SET expired_through=MAX(expired_through,?) WHERE scope=? AND session=?");
+  const deleteExpired = db.query("DELETE FROM client_activity_events WHERE scope=? AND session=? AND sequence<=?");
+  const insertEvent = db.query("INSERT INTO client_activity_events(scope,session,run,at,activity) VALUES(?,?,?,?,?)");
+  const lastSequence = db.query("SELECT last_insert_rowid() AS seq");
+  const saveSnapshot = db.query("INSERT INTO client_activity_snapshots(scope,session,sequence,snapshot) VALUES(?,?,?,?) ON CONFLICT(scope,session) DO UPDATE SET sequence=excluded.sequence,snapshot=excluded.snapshot");
+  const readEvents = db.query("SELECT sequence,session,run,at,activity FROM client_activity_events WHERE scope=? AND session=? AND sequence>? ORDER BY sequence LIMIT 201");
   const redaction = createRedactionPolicy({ includeEmails: true });
   const redact = (text) => {
     let result = text;
@@ -111,14 +121,14 @@ var openHarnessActivityStore = async (config, options = {}) => {
     return result;
   };
   const snapshot = (sessionId) => {
-    const row = db.query("SELECT snapshot,expired_through FROM client_activity_snapshots WHERE scope=? AND session=?").get(scope, sessionId);
+    const row = readSnapshot.get(scope, sessionId);
     return { state: row ? JSON.parse(row.snapshot) : { schemaVersion: 1, sessionId, sequence: 0, runs: {} }, expiredThrough: row?.expired_through ?? 0 };
   };
   const prune = () => {
-    const expired = db.query(`SELECT session,MAX(sequence) AS seq FROM client_activity_events WHERE scope=? AND (at < ? OR sequence NOT IN (SELECT sequence FROM client_activity_events WHERE scope=? ORDER BY sequence DESC LIMIT ?)) GROUP BY session`).all(scope, now() - retentionMs, scope, maxEvents);
+    const expired = expiredEvents.all(scope, now() - retentionMs, scope, maxEvents);
     for (const row of expired) {
-      db.query("UPDATE client_activity_snapshots SET expired_through=MAX(expired_through,?) WHERE scope=? AND session=?").run(row.seq, scope, row.session);
-      db.query("DELETE FROM client_activity_events WHERE scope=? AND session=? AND sequence<=?").run(scope, row.session, row.seq);
+      markExpired.run(row.seq, scope, row.session);
+      deleteExpired.run(scope, row.session, row.seq);
     }
   };
   const write = (sessionId, runId, activity) => {
@@ -160,10 +170,10 @@ var openHarnessActivityStore = async (config, options = {}) => {
       if (activity.type === "tool-approval-request" || activity.type === "agent-approval-request")
         state.status = "waiting_approval";
       current.runs[runId] = state;
-      db.query("INSERT INTO client_activity_events(scope,session,run,at,activity) VALUES(?,?,?,?,?)").run(scope, sessionId, runId, at, encoded);
-      current.sequence = db.query("SELECT last_insert_rowid() AS seq").get().seq;
+      insertEvent.run(scope, sessionId, runId, at, encoded);
+      current.sequence = lastSequence.get().seq;
       const bounded = serializeBoundedSnapshot(current, runId);
-      db.query("INSERT INTO client_activity_snapshots(scope,session,sequence,snapshot) VALUES(?,?,?,?) ON CONFLICT(scope,session) DO UPDATE SET sequence=excluded.sequence,snapshot=excluded.snapshot").run(scope, sessionId, current.sequence, bounded);
+      saveSnapshot.run(scope, sessionId, current.sequence, bounded);
       prune();
       db.exec("COMMIT");
     } catch (e) {
@@ -250,7 +260,7 @@ var openHarnessActivityStore = async (config, options = {}) => {
         throw new Error("ACTIVITY_CURSOR_AHEAD");
       if (expired)
         return { schemaVersion: 1, cursorExpired: true, hasMore: false, policyEvidenceIncomplete: true, nextCursor: current.state.sequence, events: [], snapshot: current.state };
-      const rows = db.query("SELECT sequence,session,run,at,activity FROM client_activity_events WHERE scope=? AND session=? AND sequence>? ORDER BY sequence LIMIT 201").all(scope, sessionId, after);
+      const rows = readEvents.all(scope, sessionId, after);
       const events = rows.slice(0, 200).map((row) => ({ schemaVersion: 1, eventId: createHash("sha256").update(`${scope}:${row.sequence}`).digest("hex"), sequence: row.sequence, sessionId: row.session, runId: row.run, at: row.at, activity: JSON.parse(row.activity) }));
       return { schemaVersion: 1, cursorExpired: false, hasMore: rows.length > 200, policyEvidenceIncomplete: current.expiredThrough > 0, nextCursor: events.at(-1)?.sequence ?? after, events };
     },
@@ -416,9 +426,18 @@ var startHarnessLocalService = async (harness, options) => {
     adapter = await createHarnessClientAdapter(harness, {
       ...options.approvalNow ? { now: options.approvalNow } : {},
       onPolicyDecision: (sessionId, runId, event) => activity.policyDecision(sessionId, runId, event),
-      onPrompt: (sessionId, runId, prompt) => activity.prompt(sessionId, runId, prompt),
-      onEvent: (sessionId, runId, event) => activity.append(sessionId, runId, event),
-      onCheckpoint: (sessionId, runId, status) => activity.checkpoint(sessionId, runId, status)
+      onPrompt: async (sessionId, runId, prompt) => {
+        await activity.prompt(sessionId, runId, prompt);
+        await options.onPrompt?.(sessionId, runId, prompt);
+      },
+      onEvent: async (sessionId, runId, event) => {
+        await activity.append(sessionId, runId, event);
+        await options.onEvent?.(sessionId, runId, event);
+      },
+      onCheckpoint: async (sessionId, runId, status) => {
+        await activity.checkpoint(sessionId, runId, status);
+        await options.onCheckpoint?.(sessionId, runId, status);
+      }
     });
     await new Promise((resolve, reject) => {
       server.once("error", reject);

package/dist/{index-wq2tax80.js → index-61gthdz6.js}

@@ -1,7 +1,7 @@
 import {
   DEFAULT_PROVIDER_REGISTRY,
   HARNESS_SUBAGENT_PROFILES
-} from "./index-gq9xagx2.js";
+} from "./index-8zjmnyw5.js";
 
 // src/providers/routing.ts
 var routeError = (value) => new Error(`Invalid route: ${value}. Use <profile>=<provider>[:<model>].`);

package/dist/index-6dft2vev.js

@@ -0,0 +1,343 @@
+import {
+  TERMINAL_SESSION_RUN_STATUSES
+} from "./index-s2k2edts.js";
+import {
+  SqliteDatabase,
+  createEditProposal,
+  fileDigestSchema,
+  readRegularFileNoFollow,
+  statRegularFileNoFollow,
+  withWorkspaceMutation,
+  workspaceFilePathSchema
+} from "./index-m34q25jj.js";
+
+// src/persistence/workspace-checkpoints.ts
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { z } from "zod";
+var fileSchema = z.strictObject({
+  path: workspaceFilePathSchema,
+  digest: fileDigestSchema,
+  content: z.string().max(65536),
+  mode: z.number().int().min(0).max(511)
+}).refine((file) => Buffer.byteLength(file.content) <= 65536 && !file.content.includes("\x00") && file.digest === `sha256:${createHash("sha256").update(file.content).digest("hex")}`, "Invalid checkpoint content identity.");
+var workspaceCheckpointSchema = z.strictObject({
+  id: z.string().uuid(),
+  sessionId: z.string(),
+  turnId: z.string(),
+  files: z.array(fileSchema).min(1).max(20)
+});
+var workspaceRestoreOperationSchema = z.strictObject({
+  id: z.string().uuid(),
+  checkpoint: workspaceCheckpointSchema,
+  proposalId: fileDigestSchema,
+  expected: z.record(z.string(), fileDigestSchema),
+  stage: z.enum(["prepared", "forking", "forked", "applying", "applied", "completed"]),
+  forkSessionId: z.string().optional()
+});
+var digest = (content) => `sha256:${createHash("sha256").update(content).digest("hex")}`;
+var retentionSelection = z.object({ checkpointIds: z.array(z.string().uuid()).max(100), completedRestoreIds: z.array(z.string().uuid()).max(100) }).strict().refine((value) => value.checkpointIds.length + value.completedRestoreIds.length > 0 && new Set([...value.checkpointIds, ...value.completedRestoreIds]).size === value.checkpointIds.length + value.completedRestoreIds.length, "Select unique checkpoint and completed restore IDs.");
+var openWorkspaceCheckpointStore = async (workspace, sessions) => {
+  const key = createHash("sha256").update("workspace\x00").update(workspace.root).digest("hex");
+  if (key !== sessions.workspaceKey)
+    throw new Error("Checkpoint session store belongs to a different workspace.");
+  const before = await statRegularFileNoFollow(sessions.databasePath, { label: "Checkpoint database", requireSingleLink: true });
+  if (before.uid !== process.getuid?.() || before.mode & 63)
+    throw new Error("Checkpoint database must be private.");
+  const db = new SqliteDatabase(sessions.databasePath, { create: false });
+  const after = await statRegularFileNoFollow(sessions.databasePath, { label: "Checkpoint database", requireSingleLink: true });
+  if (before.dev !== after.dev || before.ino !== after.ino) {
+    db.close();
+    throw new Error("Checkpoint database changed.");
+  }
+  db.exec("CREATE TABLE IF NOT EXISTS zhivex_workspace_checkpoints (id TEXT PRIMARY KEY, workspace_key TEXT NOT NULL, scope_key TEXT NOT NULL, kind TEXT NOT NULL, body TEXT NOT NULL)");
+  const save = (kind, value) => {
+    const existing = db.query("SELECT id FROM zhivex_workspace_checkpoints WHERE id=?").get(value.id);
+    const count = db.query("SELECT COUNT(*) AS count FROM zhivex_workspace_checkpoints WHERE workspace_key=? AND scope_key=?").get(sessions.workspaceKey, sessions.scopeKey)?.count ?? 0;
+    if (!existing && count >= 100)
+      throw new Error("Checkpoint scope storage limit reached (100 records).");
+    const body = JSON.stringify(value);
+    if (Buffer.byteLength(body) > 2 * 1024 * 1024)
+      throw new Error("Checkpoint exceeds storage limit.");
+    db.query("INSERT INTO zhivex_workspace_checkpoints(id, workspace_key, scope_key, kind, body) VALUES (?, ?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET body=excluded.body WHERE workspace_key=excluded.workspace_key AND scope_key=excluded.scope_key AND kind=excluded.kind").run(value.id, sessions.workspaceKey, sessions.scopeKey, kind, body);
+  };
+  const load = (kind, id) => {
+    const row = db.query("SELECT body FROM zhivex_workspace_checkpoints WHERE id=? AND workspace_key=? AND scope_key=? AND kind=?").get(id, sessions.workspaceKey, sessions.scopeKey, kind);
+    if (!row)
+      throw new Error("Unknown checkpoint or restore operation in this scope.");
+    return JSON.parse(row.body);
+  };
+  const read = async (target) => {
+    const authorized = await workspace.readFile(target, 1, 1);
+    const { contents, stat } = await readRegularFileNoFollow(path.join(workspace.root, target), {
+      label: "Checkpoint target",
+      maxBytes: 65536,
+      requireSingleLink: true
+    });
+    const content = new TextDecoder("utf-8", { fatal: true }).decode(contents);
+    if (contents.includes(0) || digest(contents) !== authorized.digest)
+      throw new Error("Checkpoint file changed while reading.");
+    return fileSchema.parse({ path: target, digest: digest(contents), content, mode: stat.mode & 511 });
+  };
+  const validateTurn = async (checkpoint) => {
+    const session = await sessions.get(checkpoint.sessionId);
+    const run = session?.runs.find((entry) => entry.turnId === checkpoint.turnId);
+    if (!session || !run || !TERMINAL_SESSION_RUN_STATUSES.includes(run.status)) {
+      throw new Error("Checkpoint requires an existing terminal conversation turn.");
+    }
+    return session;
+  };
+  const proposal = (operation) => {
+    if (new Set(operation.checkpoint.files.map((file) => file.path)).size !== operation.checkpoint.files.length || operation.checkpoint.files.some((file) => digest(file.content) !== file.digest))
+      throw new Error("Checkpoint content identity is corrupt.");
+    const changes = operation.checkpoint.files.map((file) => ({ path: file.path, expectedDigest: operation.expected[file.path], content: file.content }));
+    const result = createEditProposal({ changes });
+    if (result.proposalId !== operation.proposalId)
+      throw new Error("Restore proposal identity is corrupt.");
+    return { proposalId: result.proposalId, changes };
+  };
+  const getOperation = (id) => workspaceRestoreOperationSchema.parse(load("restore", id));
+  const list = (kind) => db.query("SELECT body FROM zhivex_workspace_checkpoints WHERE workspace_key=? AND scope_key=? AND kind=? ORDER BY id").all(sessions.workspaceKey, sessions.scopeKey, kind).map((row) => JSON.parse(row.body));
+  const summary = (checkpoint) => ({
+    id: checkpoint.id,
+    sessionId: checkpoint.sessionId,
+    turnId: checkpoint.turnId,
+    files: checkpoint.files.map((file) => ({
+      path: file.path,
+      digest: file.digest,
+      bytes: Buffer.byteLength(file.content),
+      mode: file.mode
+    }))
+  });
+  const inventory = () => db.query("SELECT id,kind,body FROM zhivex_workspace_checkpoints WHERE workspace_key=? AND scope_key=? ORDER BY id").all(sessions.workspaceKey, sessions.scopeKey).map((row) => {
+    const value = row.kind === "checkpoint" ? workspaceCheckpointSchema.parse(JSON.parse(row.body)) : row.kind === "restore" ? workspaceRestoreOperationSchema.parse(JSON.parse(row.body)) : undefined;
+    if (!value || value.id !== row.id)
+      throw new Error("Invalid checkpoint inventory.");
+    return { ...row, value };
+  });
+  const retentionPlan = (input) => {
+    const selection = retentionSelection.parse(input);
+    const rows = inventory();
+    const selected = new Set([...selection.checkpointIds, ...selection.completedRestoreIds]);
+    for (const id of selection.checkpointIds) {
+      if (!rows.some((row) => row.id === id && row.kind === "checkpoint"))
+        throw new Error("Unknown checkpoint selection in this scope.");
+    }
+    for (const id of selection.completedRestoreIds) {
+      const row = rows.find((row2) => row2.id === id && row2.kind === "restore");
+      if (!row || !("stage" in row.value) || row.value.stage !== "completed")
+        throw new Error("Retention cannot remove pending or unknown restore evidence.");
+    }
+    for (const row of rows) {
+      if ("checkpoint" in row.value && selection.checkpointIds.includes(row.value.checkpoint.id) && !selected.has(row.id)) {
+        throw new Error("Checkpoint is still referenced by a retained restore operation.");
+      }
+    }
+    const records = rows.filter((row) => selected.has(row.id)).map((row) => ({
+      id: row.id,
+      kind: row.kind,
+      sessionId: "checkpoint" in row.value ? row.value.checkpoint.sessionId : row.value.sessionId,
+      bytes: Buffer.byteLength(row.body)
+    }));
+    const planId = digest(JSON.stringify({
+      workspace: sessions.workspaceKey,
+      scope: sessions.scopeKey,
+      selection: [...selected].sort(),
+      inventory: rows.map((row) => [row.id, row.kind, digest(row.body)])
+    }));
+    return {
+      planId,
+      selection: { checkpointIds: [...selection.checkpointIds].sort(), completedRestoreIds: [...selection.completedRestoreIds].sort() },
+      records,
+      recordsBefore: rows.length,
+      recordsAfter: rows.length - records.length,
+      bytesRemoved: records.reduce((sum, row) => sum + row.bytes, 0),
+      workspaceFilesChanged: false,
+      conversationsChanged: false
+    };
+  };
+  return {
+    close: () => db.close(),
+    getCheckpoint: (id) => workspaceCheckpointSchema.parse(load("checkpoint", id)),
+    getOperation,
+    storageStatus: () => {
+      const rows = inventory();
+      const operations = rows.filter((row) => ("stage" in row.value));
+      const referenced = new Set(operations.map((row) => row.value.checkpoint.id));
+      return {
+        policy: "explicit-reviewed-removal",
+        automaticEviction: false,
+        maxRecords: 100,
+        maxRecordBytes: 2 * 1024 * 1024,
+        maxFilesPerCheckpoint: 20,
+        maxFileBytes: 65536,
+        records: rows.length,
+        availableRecords: Math.max(0, 100 - rows.length),
+        serializedBytes: rows.reduce((sum, row) => sum + Buffer.byteLength(row.body), 0),
+        pendingRestores: operations.filter((row) => row.value.stage !== "completed").length,
+        checkpoints: rows.filter((row) => row.kind === "checkpoint").map((row) => ({ id: row.id, referenced: referenced.has(row.id) }))
+      };
+    },
+    prepareRetention: retentionPlan,
+    applyRetention: async (selection, reviewedPlanId) => withWorkspaceMutation(workspace.root, async () => {
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        const plan = retentionPlan(selection);
+        if (plan.planId !== reviewedPlanId)
+          throw new Error("Retention inventory changed or was not reviewed.");
+        for (const row of plan.records)
+          db.query("DELETE FROM zhivex_workspace_checkpoints WHERE id=? AND workspace_key=? AND scope_key=? AND kind=?").run(row.id, sessions.workspaceKey, sessions.scopeKey, row.kind);
+        db.exec("COMMIT");
+        return plan;
+      } catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+      }
+    }),
+    listCheckpoints: (sessionId) => list("checkpoint").map((value) => workspaceCheckpointSchema.parse(value)).filter((checkpoint) => checkpoint.sessionId === sessionId).map(summary),
+    listRestores: (sessionId) => list("restore").map((value) => workspaceRestoreOperationSchema.parse(value)).filter((operation) => operation.checkpoint.sessionId === sessionId).map((operation) => ({
+      id: operation.id,
+      checkpointId: operation.checkpoint.id,
+      proposalId: operation.proposalId,
+      stage: operation.stage,
+      ...operation.forkSessionId ? { forkSessionId: operation.forkSessionId } : {}
+    })),
+    inspectCheckpoint: async (id) => {
+      const checkpoint = workspaceCheckpointSchema.parse(load("checkpoint", id));
+      const files = await Promise.all(checkpoint.files.map(async (file) => {
+        try {
+          const current = await read(file.path);
+          if (current.mode !== file.mode)
+            return { path: file.path, status: "mode-conflict" };
+          return {
+            path: file.path,
+            status: "available",
+            before: current.content,
+            after: file.content,
+            expectedDigest: current.digest,
+            afterDigest: file.digest,
+            mode: file.mode
+          };
+        } catch {
+          return { path: file.path, status: "unavailable" };
+        }
+      }));
+      return {
+        checkpoint: summary(checkpoint),
+        files,
+        coverage: {
+          existingTextOnly: true,
+          maxFiles: 20,
+          maxFileBytes: 65536,
+          creation: false,
+          deletion: false,
+          binary: false,
+          modeRollback: false,
+          fullWorkspaceSnapshot: false
+        }
+      };
+    },
+    previewRestore: async (id) => {
+      const operation = getOperation(id);
+      for (const file of operation.checkpoint.files) {
+        if ((await read(file.path)).mode !== file.mode)
+          throw new Error(`Restore mode conflict: ${file.path}.`);
+      }
+      return workspace.previewPatch(proposal(operation));
+    },
+    capture: async (input) => withWorkspaceMutation(workspace.root, async () => {
+      await validateTurn(input);
+      if (input.paths.length === 0 || input.paths.length > 20 || new Set(input.paths).size !== input.paths.length)
+        throw new Error("Capture requires 1 to 20 unique existing text files.");
+      const files = [];
+      for (const target of input.paths)
+        files.push(await read(target));
+      const checkpoint = workspaceCheckpointSchema.parse({ id: randomUUID(), sessionId: input.sessionId, turnId: input.turnId, files });
+      save("checkpoint", checkpoint);
+      return checkpoint;
+    }),
+    prepareRestore: async (checkpointId, expectedCurrent) => withWorkspaceMutation(workspace.root, async () => {
+      const checkpoint = workspaceCheckpointSchema.parse(load("checkpoint", checkpointId));
+      await validateTurn(checkpoint);
+      if (Object.keys(expectedCurrent).length !== checkpoint.files.length)
+        throw new Error("Provide exact post-agent digests for every captured file.");
+      for (const file of checkpoint.files) {
+        const current = await read(file.path);
+        if (current.digest !== expectedCurrent[file.path] || current.mode !== file.mode)
+          throw new Error(`Restore conflicts with current content or mode: ${file.path}.`);
+      }
+      const changes = checkpoint.files.map((file) => ({ path: file.path, expectedDigest: expectedCurrent[file.path], content: file.content }));
+      const preview = createEditProposal({ changes });
+      const operation = workspaceRestoreOperationSchema.parse({
+        id: randomUUID(),
+        checkpoint,
+        proposalId: preview.proposalId,
+        expected: expectedCurrent,
+        stage: "prepared"
+      });
+      save("restore", operation);
+      return { operation, proposal: { ...preview, changes } };
+    }),
+    applyRestore: async (id, reviewedProposalId) => withWorkspaceMutation(workspace.root, async () => {
+      const operation = getOperation(id);
+      if (operation.proposalId !== reviewedProposalId)
+        throw new Error("Restore requires the reviewed proposal identity.");
+      const patch = proposal(operation);
+      if (operation.stage === "completed")
+        return operation;
+      if (operation.stage === "forking")
+        throw new Error(`Fork outcome uncertain. Inspect child sessions titled restore:${operation.id} and call recoverFork with the exact child ID; no files changed.`);
+      const current = [];
+      for (const file of operation.checkpoint.files) {
+        const found = await read(file.path);
+        if (found.mode !== file.mode)
+          throw new Error(`Restore mode conflict: ${file.path}.`);
+        current.push(found);
+      }
+      const beforeApply = current.every((file) => file.digest === operation.expected[file.path]);
+      const afterApply = current.every((file) => file.digest === operation.checkpoint.files.find((entry) => entry.path === file.path)?.digest);
+      if (["applying", "applied"].includes(operation.stage) && afterApply) {
+        operation.stage = "completed";
+        save("restore", operation);
+        return operation;
+      }
+      if (!beforeApply || operation.stage === "applied")
+        throw new Error("Restore conflicts with subsequent edits or a partially applied filesystem operation; manual recovery required.");
+      if (operation.stage === "prepared") {
+        const source = await validateTurn(operation.checkpoint);
+        operation.stage = "forking";
+        save("restore", operation);
+        const fork = await sessions.fork(source.sessionId, {
+          atTurnId: operation.checkpoint.turnId,
+          expectedRevision: source.revision,
+          title: `restore:${operation.id}`
+        });
+        operation.forkSessionId = fork.sessionId;
+        operation.stage = "forked";
+        save("restore", operation);
+      }
+      if (!operation.forkSessionId)
+        throw new Error("Restore has no recorded conversation fork.");
+      operation.stage = "applying";
+      save("restore", operation);
+      await workspace.applyPatchWithModes(patch, new Map(operation.checkpoint.files.map((file) => [file.path, { beforeMode: file.mode, afterMode: file.mode }])));
+      operation.stage = "applied";
+      save("restore", operation);
+      operation.stage = "completed";
+      save("restore", operation);
+      return operation;
+    }),
+    recoverFork: async (id, forkSessionId) => withWorkspaceMutation(workspace.root, async () => {
+      const operation = getOperation(id);
+      const fork = await sessions.get(forkSessionId);
+      if (operation.stage !== "forking" || !fork || fork.parentSessionId !== operation.checkpoint.sessionId || fork.forkedFromTurnId !== operation.checkpoint.turnId || fork.title !== `restore:${operation.id}`)
+        throw new Error("Fork does not match this interrupted restore.");
+      operation.forkSessionId = forkSessionId;
+      operation.stage = "forked";
+      save("restore", operation);
+      return operation;
+    })
+  };
+};
+
+export { workspaceCheckpointSchema, workspaceRestoreOperationSchema, openWorkspaceCheckpointStore };