@narumitw/pi-sync 0.51.1 → 0.52.1

package/src/sync/partial-progress.ts

@@ -0,0 +1,54 @@
+import type { RemoteHead } from "../backends/sync-backend.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import type { Snapshot, SnapshotFile } from "../snapshot/snapshot-types.js";
+import type { SyncState } from "../state/state-types.js";
+import type { FileMergeDecision } from "./file-merge-planner.js";
+import { fileHashMap } from "./sync-state.js";
+/** Withholding preserves the complete local version, including explicit absence. */
+export function acceptedMergeFiles(
+  decisions: readonly FileMergeDecision[],
+  localFiles: readonly SnapshotFile[],
+  withheld: ReadonlySet<string>,
+) {
+  const localByPath = new Map(localFiles.map((file) => [file.path, file]));
+  return decisions.flatMap((decision) => {
+    const file = withheld.has(decision.path)
+      ? localByPath.get(decision.path)
+      : decision.kind === "accepted"
+        ? decision.file
+        : undefined;
+    return file ? [file] : [];
+  });
+}
+
+export interface PartialProgress {
+  previous: SyncState;
+  groups: { paths: string[]; artifact: string }[];
+}
+export function progressState(
+  config: AnySyncConfig,
+  head: RemoteHead,
+  snapshot: Snapshot,
+  progress: PartialProgress,
+): SyncState {
+  const withheld = new Set(progress.groups.flatMap((group) => group.paths));
+  const current = fileHashMap(snapshot);
+  const hashes = Object.assign(Object.create(null) as Record<string, string>, progress.previous.lastFileHashes);
+  for (const key of new Set([...Object.keys(hashes), ...Object.keys(current)])) {
+    if (withheld.has(key)) continue;
+    const value = current[key];
+    if (value === undefined) delete hashes[key];
+    else hashes[key] = value;
+  }
+  return {
+    ...progress.previous,
+    version: 3,
+    profile: config.snapshotIdentity,
+    lastFileHashes: hashes,
+    include: [...config.include],
+    localFields: config.localFields,
+    lastObservedSnapshot: head.snapshotId,
+    lastObservedRevision: head.revision,
+    unresolved: progress.groups,
+  };
+}

package/src/sync/remote-snapshot.ts

@@ -4,6 +4,7 @@ import type { AnySyncConfig } from "../settings/settings-types.js";
 import { filterSnapshotForConfigPolicy } from "../snapshot/snapshot.js";
 import type { Snapshot } from "../snapshot/snapshot-types.js";
 import { safeTerminalText } from "../ui/terminal-text.js";
+import { sameLocalFields, validatePortableSnapshot } from "./local-fields.js";
 import {
   inspectRemoteSelection,
   type RemoteSelectionState,
@@ -17,6 +18,7 @@ export async function readSnapshotForHead(backend: SyncBackend, head: RemoteHead
   if (signal?.aborted) {
     throw signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
   }
+  validatePortableSnapshot(snapshot);
   if (snapshot.id !== head.snapshotId) {
     throw new Error(`Remote head ${head.snapshotId} resolved to unexpected snapshot ${snapshot.id}.`);
   }
@@ -30,6 +32,10 @@ export async function readSnapshotForHead(backend: SyncBackend, head: RemoteHead
 }
 
 export function requireCompatibleRemoteSelection(config: AnySyncConfig, snapshot: Snapshot) {
+  if (!sameLocalFields(config.localFields, snapshot.localFields))
+    throw new Error(
+      "Remote local-field policy differs; confirm a reviewed directional migration. Old history is not erased.",
+    );
   const state = inspectRemoteSelection(config.include, snapshot);
   if (state.kind === "different") {
     throw remoteSelectionMismatch(config, state.include, syncConfigReviewFingerprint(config));

package/src/sync/session-merge.ts

@@ -0,0 +1,194 @@
+import { CURRENT_SESSION_VERSION } from "@earendil-works/pi-coding-agent";
+import { parseJsonObjectDocument } from "./json-document.js";
+import { text } from "./text-merge.js";
+
+// Public header IDs use Pi assertValidSessionId; generated entry IDs have a separate grammar.
+const sessionId = (value: unknown): value is string =>
+  typeof value === "string" && /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/u.test(value);
+const id = (value: unknown): value is string => typeof value === "string" && /^[a-zA-Z0-9_-]{1,128}$/u.test(value);
+const content = (value: unknown, types = ["text", "image", "thinking", "toolCall"]): boolean =>
+  typeof value === "string" ||
+  (Array.isArray(value) &&
+    value.every(
+      (block) =>
+        object(block) &&
+        types.includes(String(block.type)) &&
+        ((block.type === "text" && typeof block.text === "string") ||
+          (block.type === "image" && typeof block.data === "string" && typeof block.mimeType === "string") ||
+          (block.type === "thinking" && typeof block.thinking === "string") ||
+          (block.type === "toolCall" &&
+            typeof block.id === "string" &&
+            typeof block.name === "string" &&
+            object(block.arguments))),
+    ));
+const message = (value: unknown) => {
+  if (!object(value) || typeof value.timestamp !== "number" || !Number.isFinite(value.timestamp)) return false;
+  switch (value.role) {
+    case "system":
+      return (
+        content(value.content, ["text"]) &&
+        (value.sections === undefined ||
+          (object(value.sections) &&
+            Object.values(value.sections).every((section) => section === null || typeof section === "string"))) &&
+        (value.toolsAdded === undefined ||
+          (Array.isArray(value.toolsAdded) &&
+            value.toolsAdded.every(
+              (tool) =>
+                object(tool) &&
+                typeof tool.name === "string" &&
+                typeof tool.description === "string" &&
+                object(tool.parameters),
+            ))) &&
+        (value.toolsRemoved === undefined ||
+          (Array.isArray(value.toolsRemoved) &&
+            value.toolsRemoved.every((tool) => object(tool) && typeof tool.name === "string")))
+      );
+    case "user":
+      return content(value.content, ["text", "image"]);
+    case "assistant":
+      return (
+        Array.isArray(value.content) &&
+        content(value.content, ["text", "thinking", "toolCall"]) &&
+        typeof value.api === "string" &&
+        typeof value.provider === "string" &&
+        typeof value.model === "string" &&
+        object(value.usage) &&
+        ["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"].includes(String(value.stopReason))
+      );
+    case "toolResult":
+      return (
+        typeof value.toolCallId === "string" &&
+        typeof value.toolName === "string" &&
+        Array.isArray(value.content) &&
+        content(value.content, ["text", "image"]) &&
+        typeof value.isError === "boolean"
+      );
+    case "custom":
+      return (
+        typeof value.customType === "string" &&
+        content(value.content, ["text", "image"]) &&
+        typeof value.display === "boolean"
+      );
+    case "bashExecution":
+      return (
+        typeof value.command === "string" &&
+        typeof value.output === "string" &&
+        typeof value.cancelled === "boolean" &&
+        typeof value.truncated === "boolean"
+      );
+    case "branchSummary":
+      return typeof value.summary === "string" && (value.fromId === null || typeof value.fromId === "string");
+    case "compactionSummary":
+      return (
+        typeof value.summary === "string" &&
+        typeof value.tokensBefore === "number" &&
+        Number.isFinite(value.tokensBefore) &&
+        value.tokensBefore >= 0
+      );
+    default:
+      return false;
+  }
+};
+const object = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === "object" && !Array.isArray(value);
+/** Stricter than Pi's repair-tolerant reader: never skip malformed lines or migrate a log. */
+export function validateSession(bytes: Buffer) {
+  if (CURRENT_SESSION_VERSION !== 3) throw new Error("Unaudited Pi session format; require review.");
+  const raw = text(bytes);
+  if (!raw.endsWith("\n")) throw new Error("Incomplete session tail.");
+  const rows: unknown[] = raw
+    .slice(0, -1)
+    .split("\n")
+    .map((line) => {
+      if (line.startsWith("\uFEFF")) throw new Error("Unexpected session-record BOM; require review.");
+      return parseJsonObjectDocument(Buffer.from(line)).root.value;
+    });
+  if (rows.length > 16_384) throw new Error("Session entry bound exceeded.");
+  const header = rows[0];
+  if (
+    !object(header) ||
+    header.type !== "session" ||
+    header.version !== CURRENT_SESSION_VERSION ||
+    !sessionId(header.id) ||
+    typeof header.cwd !== "string" ||
+    typeof header.timestamp !== "string" ||
+    !Number.isFinite(Date.parse(header.timestamp)) ||
+    (header.parentSession !== undefined && typeof header.parentSession !== "string")
+  )
+    throw new Error("Unsupported session header.");
+  const ids = new Set<string>();
+  const known = (value: unknown) => id(value) && ids.has(value);
+  for (const row of rows.slice(1)) {
+    if (
+      !object(row) ||
+      !id(row.id) ||
+      ids.has(row.id) ||
+      typeof row.timestamp !== "string" ||
+      !Number.isFinite(Date.parse(row.timestamp)) ||
+      (row.parentId !== null && !known(row.parentId))
+    )
+      throw new Error("Invalid session graph.");
+    const strings = (...keys: string[]) => keys.every((key) => typeof row[key] === "string");
+    let valid = false;
+    switch (row.type) {
+      case "message":
+        valid = message(row.message);
+        break;
+      case "thinking_level_change":
+        valid = strings("thinkingLevel");
+        break;
+      case "model_change":
+        valid = strings("provider", "modelId");
+        break;
+      case "usage":
+        valid = strings("kind", "provider", "model") && object(row.usage);
+        break;
+      case "compaction":
+        valid =
+          strings("summary") &&
+          (known(row.firstKeptEntryId) || row.firstKeptEntryId === row.id) &&
+          (row.systemMessage === undefined ||
+            (object(row.systemMessage) && row.systemMessage.role === "system" && message(row.systemMessage))) &&
+          typeof row.tokensBefore === "number" &&
+          Number.isFinite(row.tokensBefore) &&
+          row.tokensBefore >= 0;
+        break;
+      case "branch_summary":
+        valid = strings("summary") && (known(row.fromId) || row.fromId === "root");
+        break;
+      case "custom":
+        valid = strings("customType");
+        break;
+      case "custom_message":
+        valid = strings("customType") && typeof row.display === "boolean" && content(row.content, ["text", "image"]);
+        break;
+      case "context_edit":
+        valid =
+          known(row.targetId) &&
+          (row.replacement === null || (object(row.replacement) && content(row.replacement.content)));
+        break;
+      case "label":
+        valid = known(row.targetId) && (row.label === undefined || typeof row.label === "string");
+        break;
+      case "session_info":
+        valid = row.name === undefined || typeof row.name === "string";
+        break;
+    }
+    if (!valid) throw new Error("Unsupported session entry.");
+    ids.add(row.id);
+  }
+  return header.id;
+}
+export function mergeSession(base: Buffer, local: Buffer, remote: Buffer): Buffer | undefined {
+  try {
+    const identity = validateSession(base);
+    if (validateSession(local) !== identity || validateSession(remote) !== identity) return;
+    const prefix = (left: Buffer, right: Buffer) =>
+      right.length >= left.length && right.subarray(0, left.length).equals(left);
+    if (!prefix(base, local) || !prefix(base, remote)) return;
+    if (prefix(local, remote)) return remote;
+    if (prefix(remote, local)) return local;
+  } catch {
+    return;
+  }
+}

package/src/sync/settings-conflicts.ts

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import type { Snapshot } from "../snapshot/snapshot-types.js";
+import { readMergeAncestor } from "../state/merge-baseline-store.js";
+import type { SyncState } from "../state/state-types.js";
+import type { FileMergePlan } from "./file-merge-planner.js";
+import { mergeSettingsJson } from "./settings-merge.js";
+
+export async function resolveSettingsConflicts(
+  config: AnySyncConfig,
+  state: SyncState,
+  local: Snapshot,
+  remote: Snapshot,
+  plan: FileMergePlan,
+): Promise<{ plan: FileMergePlan; fields: string[] }> {
+  if (plan.kind !== "planned") return { plan, fields: [] };
+  const fields: string[] = [];
+  const decisions = [...plan.decisions];
+  for (let index = 0; index < decisions.length; index++) {
+    const decision = decisions[index];
+    if (decision?.kind !== "conflict" || decision.reason !== "both-changed" || decision.path !== "settings.json")
+      continue;
+    const left = local.files.find((file) => file.path === decision.path);
+    const right = remote.files.find((file) => file.path === decision.path);
+    if (!left || !right) continue; // File deletion/addition is not a JSON field merge.
+    const ancestor = await readMergeAncestor(config, state, decision.path);
+    if (!ancestor) continue;
+    const merged = mergeSettingsJson(
+      ancestor,
+      Buffer.from(left.contentBase64, "base64"),
+      Buffer.from(right.contentBase64, "base64"),
+    );
+    if (merged.kind === "review") {
+      fields.push(...merged.fields);
+      continue;
+    }
+    decisions[index] = {
+      kind: "accepted",
+      path: decision.path,
+      source: "merged",
+      file: {
+        path: decision.path,
+        contentBase64: merged.content.toString("base64"),
+        sha256: createHash("sha256").update(merged.content).digest("hex"),
+      },
+    };
+  }
+  return {
+    plan: { kind: "planned", decisions, conflicts: decisions.filter((decision) => decision.kind === "conflict") },
+    fields,
+  };
+}

package/src/sync/settings-merge.ts

@@ -0,0 +1,57 @@
+import {
+  type JsonDocument,
+  type JsonNode,
+  jsonEqual,
+  parseSettingsDocument,
+  renderSettingsMembers,
+} from "./json-document.js";
+
+export type SettingsMergeResult =
+  | { kind: "merged"; content: Buffer }
+  | { kind: "review"; reason: "unsupported-format" | "field-conflict"; fields: string[] };
+
+const COUPLED_FIELDS = [
+  ["defaultProvider", "defaultModel"],
+  ["queueMode", "steeringMode"],
+  ["websockets", "transport"],
+  ["skills", "enableSkillCommands"],
+  ["enableAnalytics", "trackingId"],
+] as const;
+
+/** Only global settings.json; objects/arrays are atomic units until their invariants are proven. */
+export function mergeSettingsJson(ancestor: Buffer, local: Buffer, remote: Buffer): SettingsMergeResult {
+  let documents: JsonDocument[];
+  try {
+    documents = [ancestor, local, remote].map(parseSettingsDocument);
+  } catch {
+    return { kind: "review", reason: "unsupported-format", fields: [] };
+  }
+  const [base, left, right] = documents as [JsonDocument, JsonDocument, JsonDocument];
+  const selected = new Map<string, { document: JsonDocument; node: JsonNode }>();
+  const fields = new Set(documents.flatMap((document) => [...document.root.members.keys()]));
+  const units: string[][] = COUPLED_FIELDS.map((group) => [...group]);
+  const coupled = new Set(units.flat());
+  units.push(...[...fields].filter((field) => !coupled.has(field)).map((field) => [field]));
+  const conflicts: string[] = [];
+  for (const unit of units) {
+    const equal = (first: JsonDocument, second: JsonDocument) =>
+      unit.every((field) =>
+        jsonEqual(first.root.members.get(field)?.node.value, second.root.members.get(field)?.node.value),
+      );
+    const source = equal(left, right) ? left : equal(left, base) ? right : equal(right, base) ? left : undefined;
+    if (!source) {
+      conflicts.push(...unit.filter((field) => fields.has(field)));
+      continue;
+    }
+    for (const field of unit) {
+      const member = source.root.members.get(field);
+      if (member) selected.set(field, { document: source, node: member.node });
+    }
+  }
+  if (conflicts.length) return { kind: "review", reason: "field-conflict", fields: conflicts };
+  try {
+    return { kind: "merged", content: renderSettingsMembers(left, selected) };
+  } catch {
+    return { kind: "review", reason: "unsupported-format", fields: [] };
+  }
+}

package/src/sync/startup-check.ts

@@ -20,16 +20,40 @@ export function createStartupCheck(loaders: SyncLoaders, attention: SyncAttentio
         controller: AbortController;
         promise: Promise<void>;
         owner: ExtensionContext["sessionManager"];
+        transfer: boolean;
       }
     | undefined;
 
-  return {
+  let pending: { ctx: ExtensionContext; signal: AbortSignal; config: AnySyncConfig } | undefined;
+
+  const controllerApi = {
+    async interrupt(ctx: ExtensionContext) {
+      const task = active;
+      if (!task?.transfer || task.owner !== ctx.sessionManager) return;
+      task.controller.abort(new DOMException("Agent became busy", "AbortError"));
+      await task.promise;
+    },
+    settled(ctx: ExtensionContext) {
+      const queued = pending;
+      if (!queued || queued.ctx.sessionManager !== ctx.sessionManager || queued.signal.aborted || !ctx.isIdle()) return;
+      pending = undefined;
+      controllerApi.start(ctx, queued.signal, queued.config);
+    },
     start(ctx: ExtensionContext, sessionSignal: AbortSignal, initialConfig?: AnySyncConfig) {
       if (!ctx.hasUI || sessionSignal.aborted) return;
+      if (initialConfig?.automaticTransfer && !ctx.isIdle()) {
+        pending = { ctx, signal: sessionSignal, config: initialConfig };
+        return;
+      }
       if (active) throw new Error("Previous startup check has not been drained.");
       const controller = new AbortController();
       const signal = combineSignals(sessionSignal, controller.signal);
-      const task = { controller, owner: ctx.sessionManager, promise: Promise.resolve() };
+      const task = {
+        controller,
+        owner: ctx.sessionManager,
+        promise: Promise.resolve(),
+        transfer: Boolean(initialConfig?.automaticTransfer),
+      };
       active = task;
       const isCurrent = () => !sessionSignal.aborted && active === task && task.owner === ctx.sessionManager;
       const timer = setTimeout(
@@ -44,8 +68,9 @@ export function createStartupCheck(loaders: SyncLoaders, attention: SyncAttentio
           try {
             throwIfAborted(signal);
             config = initialConfig ?? (await loadConfigForCheck());
+            task.transfer = Boolean(config.automaticTransfer);
             throwIfAborted(signal);
-            if (!config.automatic) return;
+            if (!config.automatic && !config.automaticTransfer) return;
             const captured = config;
             const identity = syncCheckConfigFingerprint(captured);
             checking = true;
@@ -76,6 +101,47 @@ export function createStartupCheck(loaders: SyncLoaders, attention: SyncAttentio
               configIdentity: identity,
               checkedAt: new Date().toISOString(),
               inspection,
+              automaticTransfer: captured.automaticTransfer,
+            });
+            if (
+              captured.automaticTransfer &&
+              !inspection.firstSync &&
+              inspection.head &&
+              inspection.selectionState?.kind === "same"
+            ) {
+              const operations = await loaders.operations();
+              throwIfAborted(signal);
+              if (!isCurrent()) return;
+              if (!ctx.isIdle()) {
+                pending = { ctx, signal: sessionSignal, config: captured };
+                return;
+              }
+              await withStateDirectoryAccess(() =>
+                withLock("startup-transfer", () =>
+                  operations.syncBoth(ctx, {
+                    args: [],
+                    yes: true,
+                    force: false,
+                    stale: false,
+                    silent: true,
+                    reload: false,
+                    auto: true,
+                    signal,
+                    onCommit: () => attention.clearObservation(),
+                  }),
+                ),
+              );
+              throwIfAborted(signal);
+              if (!isCurrent()) return;
+              attention.clearObservation();
+              return;
+            }
+            attention.observe({
+              setupName: captured.setupName,
+              configIdentity: identity,
+              checkedAt: new Date().toISOString(),
+              inspection,
+              automaticTransfer: captured.automaticTransfer,
             });
             if (ctx.mode === "rpc") attention.notifyObservation(ctx);
           } catch (error) {
@@ -88,12 +154,29 @@ export function createStartupCheck(loaders: SyncLoaders, attention: SyncAttentio
               if (!latest || syncCheckConfigFingerprint(latest) !== syncCheckConfigFingerprint(config)) return;
             }
             ctx.ui.notify(
-              `pi-sync startup check skipped: ${safeTerminalText(errorMessage(error))}. Run /sync status to retry. No startup transfer was performed.`,
+              config?.automaticTransfer
+                ? `pi-sync automatic transfer stopped: ${safeTerminalText(errorMessage(error))}. Run /sync to review or reconcile retained recovery evidence. No resources were reloaded.`
+                : `pi-sync startup check skipped: ${safeTerminalText(errorMessage(error))}. Run /sync status to retry. No startup transfer was performed.`,
               "warning",
             );
           } finally {
             clearTimeout(timer);
-            if (isCurrent() && checking) await attention.publish(ctx, sessionSignal);
+            if (isCurrent() && checking) {
+              if (!signal.aborted || controller.signal.reason?.name === "TimeoutError") {
+                const latest = await loadConfigForCheck().catch(() => undefined);
+                if (isCurrent()) {
+                  if (signal.aborted && controller.signal.reason?.name !== "TimeoutError")
+                    setSyncStatus(ctx, undefined);
+                  else if (
+                    config &&
+                    latest &&
+                    syncCheckConfigFingerprint(latest) === syncCheckConfigFingerprint(config)
+                  )
+                    await attention.publish(ctx, sessionSignal);
+                  else attention.reset(ctx);
+                }
+              } else setSyncStatus(ctx, undefined);
+            }
             if (active === task) active = undefined;
           }
         })
@@ -104,6 +187,7 @@ export function createStartupCheck(loaders: SyncLoaders, attention: SyncAttentio
         });
     },
     async stop() {
+      pending = undefined;
       const task = active;
       if (!task) return;
       task.controller.abort(new DOMException("Startup check cancelled", "AbortError"));
@@ -111,4 +195,5 @@ export function createStartupCheck(loaders: SyncLoaders, attention: SyncAttentio
       await task.promise;
     },
   };
+  return controllerApi;
 }

package/src/sync/sync-inspection.ts

@@ -43,5 +43,6 @@ export interface StartupObservation {
   setupName: string;
   configIdentity: string;
   checkedAt: string;
+  automaticTransfer?: boolean;
   inspection: SyncInspection;
 }

package/src/sync/sync-local.ts

@@ -0,0 +1,61 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { agentDir, sessionDirFromContext } from "../snapshot/session-paths.js";
+import { createSnapshot, sessionSnapshotPathFromAbsolute } from "../snapshot/snapshot.js";
+import { encodeSnapshot } from "../snapshot/snapshot-codec.js";
+import type { SnapshotOptions } from "../snapshot/snapshot-types.js";
+import { syncDirectory } from "../state/json-file.js";
+import { stateDir } from "../state/state-directory.js";
+import { throwIfAborted } from "./signals.js";
+
+export function protectedSessionPaths(
+  ctx: ExtensionCommandContext | ExtensionContext,
+  sessionRoot = sessionDirFromContext(ctx),
+) {
+  const getSessionFile = ctx.sessionManager.getSessionFile;
+  if (typeof getSessionFile !== "function") return new Set<string>();
+  const sessionFile = getSessionFile.call(ctx.sessionManager) as string | undefined;
+  const snapshotPath = sessionFile ? sessionSnapshotPathFromAbsolute(sessionFile, sessionRoot) : undefined;
+  return snapshotPath ? new Set([snapshotPath]) : new Set<string>();
+}
+
+export function captureMutationOwner(ctx: ExtensionContext | ExtensionCommandContext, signal?: AbortSignal) {
+  const manager = ctx.sessionManager;
+  const file = manager.getSessionFile?.();
+  const id = manager.getSessionId?.();
+  const cwd = manager.getCwd?.();
+  const root = agentDir();
+  return () => {
+    throwIfAborted(signal);
+    if (
+      ctx.sessionManager !== manager ||
+      manager.getSessionFile?.() !== file ||
+      manager.getSessionId?.() !== id ||
+      manager.getCwd?.() !== cwd ||
+      agentDir() !== root
+    )
+      throw new Error("Session changed during file mutation; evidence retained for review.");
+  };
+}
+
+export async function backupLocal(profile: string, options: SnapshotOptions = {}, signal?: AbortSignal) {
+  throwIfAborted(signal);
+  const snapshot = await createSnapshot(profile, { ...options, signal });
+  throwIfAborted(signal);
+  const backupDirectory = path.join(stateDir(), "backups");
+  await fs.mkdir(backupDirectory, { recursive: true, mode: 0o700 });
+  throwIfAborted(signal);
+  const backupPath = path.join(backupDirectory, `${snapshot.id}.json.gz`);
+  const encoded = await encodeSnapshot(snapshot);
+  throwIfAborted(signal);
+  const handle = await fs.open(backupPath, "wx", 0o600);
+  try {
+    await handle.writeFile(encoded);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await syncDirectory(backupDirectory);
+  return backupPath;
+}