@narumitw/pi-sync 0.51.0 → 0.52.0

package/dist/chunks/chunk-ANWNQIR7.ts

@@ -0,0 +1,1013 @@
+// @generated by scripts/build-runtime.mjs; do not edit.
+// @ts-nocheck -- generated JavaScript uses a .ts extension for Pi's Jiti loader.
+import {
+  withLock
+} from "./chunk-IJ6VV6FN.ts";
+import {
+  mergePathIdentity
+} from "./chunk-76NB4R7U.ts";
+import {
+  stateDir
+} from "./chunk-BVVP33U5.ts";
+import {
+  agentDir,
+  configuredSessionDir,
+  expandSessionDir,
+  sessionStorageRoot
+} from "./chunk-QOFMXPM5.ts";
+import {
+  assertWithinRoot,
+  isDeniedPath,
+  isPathInside,
+  syncDirectory,
+  writeJson
+} from "./chunk-HUZ5CR4W.ts";
+
+// src/state/mutation-directory-sync.ts
+import path from "node:path";
+async function syncMutationParents(targets, roots, options = {}) {
+  const directories = /* @__PURE__ */ new Set();
+  for (const target of targets) {
+    const root = roots.map((root2) => path.resolve(root2)).find((root2) => isPathInside(root2, target));
+    if (!root) throw new Error("Unowned mutation directory.");
+    for (let parent = path.dirname(target); ; parent = path.dirname(parent)) {
+      directories.add(parent);
+      if (mergePathIdentity(parent) === mergePathIdentity(root)) break;
+      if (path.dirname(parent) === parent) throw new Error("Mutation directory escaped its owned root.");
+    }
+  }
+  for (const directory of [...directories].sort((a, b) => b.length - a.length)) {
+    options.signal?.throwIfAborted();
+    options.validateMutation?.();
+    try {
+      await syncDirectory(directory);
+    } catch (error) {
+      const code = error.code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+    }
+    options.signal?.throwIfAborted();
+    options.validateMutation?.();
+  }
+}
+
+// src/snapshot/snapshot-transaction.ts
+import { createHash as createHash2, randomUUID } from "node:crypto";
+import fs3 from "node:fs/promises";
+import path5 from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+
+// src/snapshot/snapshot-case-replacement.ts
+import fs from "node:fs/promises";
+import path2 from "node:path";
+function isCaseReplacement(root, before, after) {
+  return before !== after && path2.dirname(before) === root && path2.dirname(after) === root && path2.basename(before).toLowerCase() === path2.basename(after).toLowerCase();
+}
+async function caseReplacementSpelling(before, after) {
+  const observations = await Promise.all(
+    [before, after].map(async (target) => {
+      try {
+        const stat = await fs.lstat(target);
+        if (!stat.isFile() || stat.nlink !== 1) throw new Error("Unsafe case replacement target.");
+        return await fs.realpath(target);
+      } catch (error) {
+        if (error.code === "ENOENT") return void 0;
+        throw error;
+      }
+    })
+  );
+  if (observations.every((value) => value === void 0)) return void 0;
+  if (!observations[0] || observations[0] !== observations[1])
+    throw new Error("Case replacement no longer identifies one physical file; preserve evidence for review.");
+  const names = (await fs.readdir(path2.dirname(before))).filter(
+    (name) => name.toLowerCase() === path2.basename(before).toLowerCase()
+  );
+  if (names.length !== 1 || names[0] !== path2.basename(before) && names[0] !== path2.basename(after))
+    throw new Error("Case replacement spelling changed; preserve evidence for review.");
+  return path2.join(path2.dirname(before), names[0]);
+}
+async function coalesceCaseReplacements(root, plan) {
+  const replacements = /* @__PURE__ */ new Map();
+  const deletesByCase = /* @__PURE__ */ new Map();
+  const writeTargets = new Set(plan.writes.map((item) => item.target));
+  for (const target of new Set(plan.deletes)) {
+    if (path2.dirname(target) !== root || writeTargets.has(target)) continue;
+    const key = path2.basename(target).toLowerCase();
+    const group = deletesByCase.get(key) ?? [];
+    group.push(target);
+    deletesByCase.set(key, group);
+  }
+  for (const item of plan.writes) {
+    if (path2.dirname(item.target) !== root) continue;
+    const candidates = deletesByCase.get(path2.basename(item.target).toLowerCase()) ?? [];
+    if (candidates.length !== 1) continue;
+    const before = candidates[0];
+    if (!before || !isCaseReplacement(root, before, item.target)) continue;
+    let beforePath;
+    let afterPath;
+    try {
+      [beforePath, afterPath] = await Promise.all([fs.realpath(before), fs.realpath(item.target)]);
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw error;
+    }
+    if (beforePath !== afterPath) continue;
+    if (replacements.has(before)) throw new Error("Multiple writes alias a case replacement target.");
+    if (await caseReplacementSpelling(before, item.target) !== before)
+      throw new Error("Case replacement preimage spelling changed; review is required.");
+    replacements.set(before, item.target);
+  }
+  const beforeByAfter = new Map([...replacements].map(([before, after]) => [after, before]));
+  return {
+    replacements,
+    plan: {
+      deletes: plan.deletes,
+      writes: plan.writes.map((item) => ({ ...item, target: beforeByAfter.get(item.target) ?? item.target }))
+    }
+  };
+}
+
+// src/snapshot/snapshot-root-transition.ts
+import fs2 from "node:fs/promises";
+import path4 from "node:path";
+
+// src/snapshot/snapshot-transaction-plan.ts
+import { createHash } from "node:crypto";
+import path3 from "node:path";
+function fileImage(content) {
+  return `file:${createHash("sha256").update(content).digest("hex")}`;
+}
+function indexTransactionPlan(plan, targets) {
+  const targetIndex = indexTargets(targets);
+  const writeImages = /* @__PURE__ */ new Map();
+  const postFiles = new Map(targets.map((target) => [target, []]));
+  for (const write of plan.writes) {
+    const image2 = fileImage(write.content);
+    if (!writeImages.has(write.target)) writeImages.set(write.target, image2);
+    for (const ancestor of ancestorTargets(write.target, targetIndex, false)) {
+      if (ancestor !== write.target && isStrictDescendant(ancestor, write.target)) {
+        postFiles.get(ancestor)?.push({ relative: path3.relative(ancestor, write.target), image: image2 });
+      }
+    }
+  }
+  const deleteIndex = indexTargets(plan.deletes);
+  const deletes = plan.deletes.filter((target) => {
+    for (const ancestor of ancestorTargets(target, deleteIndex, false)) {
+      if (ancestor !== target && isStrictDescendant(ancestor, target)) return false;
+    }
+    return true;
+  });
+  const deletedWrites = /* @__PURE__ */ new Set();
+  const outerDeleteIndex = indexTargets(deletes);
+  for (const write of plan.writes) {
+    for (const ancestor of ancestorTargets(write.target, outerDeleteIndex)) {
+      if (ancestor === write.target || isPathInside(ancestor, write.target)) {
+        deletedWrites.add(write.target);
+        break;
+      }
+    }
+  }
+  return { writeImages, postFiles, deletes, deletedWrites };
+}
+function isStrictDescendant(parent, target) {
+  return path3.relative(path3.resolve(parent), path3.resolve(target)) !== "" && isPathInside(parent, target);
+}
+function pathKey(target) {
+  const resolved = path3.resolve(target);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function indexTargets(targets) {
+  const index = /* @__PURE__ */ new Map();
+  for (const target of new Set(targets)) {
+    const key = pathKey(target);
+    const rows = index.get(key) ?? [];
+    rows.push(target);
+    index.set(key, rows);
+  }
+  return index;
+}
+function* ancestorTargets(target, index, includeSelf = true) {
+  const resolved = path3.resolve(target);
+  for (let ancestor = includeSelf ? resolved : path3.dirname(resolved); ; ancestor = path3.dirname(ancestor)) {
+    yield* index.get(pathKey(ancestor)) ?? [];
+    if (path3.dirname(ancestor) === ancestor) return;
+  }
+}
+
+// src/snapshot/snapshot-root-transition.ts
+function validateOwner(guards) {
+  guards.validateMutation?.();
+  guards.signal?.throwIfAborted();
+}
+function rootFromSettings(root, bytes) {
+  let settings;
+  try {
+    settings = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw new Error("Invalid settings root-transition evidence.");
+  }
+  if (!settings || typeof settings !== "object" || Array.isArray(settings))
+    throw new Error("Invalid settings root-transition evidence.");
+  const value = settings.sessionDir;
+  if (value !== void 0 && typeof value !== "string") throw new Error("Invalid settings root-transition evidence.");
+  return path4.resolve(sessionStorageRoot(root, value ? expandSessionDir(value) : void 0));
+}
+async function beforeRoot(directory, root, entry, guards) {
+  validateOwner(guards);
+  if (entry.kind === "missing" && entry.beforeImage === "missing") return path4.join(root, "sessions");
+  if (entry.kind !== "file") throw new Error("Root transition requires regular settings preimage evidence.");
+  const backup = path4.join(directory, "before", entry.backupName);
+  const stat = await fs2.lstat(backup);
+  validateOwner(guards);
+  if (!stat.isFile()) throw new Error("Invalid settings root-transition backup.");
+  const bytes = await fs2.readFile(backup);
+  validateOwner(guards);
+  if (fileImage(bytes) !== entry.beforeImage) throw new Error("Changed settings root-transition backup.");
+  return rootFromSettings(root, bytes);
+}
+async function prepareSessionRootTransition(directory, root, sessionRoot, entries, plan, guards = {}) {
+  const settingsTarget = path4.join(root, "settings.json");
+  const entry = entries.find((item) => item.target === settingsTarget || item.afterTarget === settingsTarget);
+  const write = plan.writes.find((item) => item.target === settingsTarget || item.target === entry?.target);
+  if (!entry || !entries.some((item) => item !== entry && isPathInside(sessionRoot, item.target))) return void 0;
+  const deleted = !write && plan.deletes.includes(entry.target) && entry.afterImage === "missing";
+  if (!write && !deleted) return void 0;
+  const afterRoot = write ? rootFromSettings(root, write.content) : path4.join(root, "sessions");
+  if (afterRoot !== sessionRoot) return void 0;
+  const previous = await beforeRoot(directory, root, entry, guards);
+  if (previous === sessionRoot) return void 0;
+  if (write && fileImage(write.content) !== entry.afterImage) throw new Error("Changed settings transition postimage.");
+  if (!write) return { beforeRoot: previous, settingsAfterBase64: null };
+  validateOwner(guards);
+  const handle = await fs2.open(path4.join(directory, "settings-after"), "wx", 384);
+  try {
+    validateOwner(guards);
+    await handle.writeFile(write.content);
+    validateOwner(guards);
+    await handle.sync();
+    validateOwner(guards);
+  } finally {
+    await handle.close();
+  }
+  await syncDirectory(directory);
+  validateOwner(guards);
+  return { beforeRoot: previous, settingsAfterFile: true };
+}
+function validateSessionRootTransition(value) {
+  if (!value || typeof value.beforeRoot !== "string" || !path4.isAbsolute(value.beforeRoot) || path4.resolve(value.beforeRoot) !== value.beforeRoot || value.settingsAfterFile !== void 0 && value.settingsAfterFile !== true || (value.settingsAfterFile === true ? value.settingsAfterBase64 !== void 0 : value.settingsAfterBase64 !== null && (typeof value.settingsAfterBase64 !== "string" || value.settingsAfterBase64.length > 32 * 1024 * 1024 || Buffer.from(value.settingsAfterBase64, "base64").toString("base64") !== value.settingsAfterBase64)))
+    throw new Error("Invalid session root-transition evidence.");
+}
+async function resolveTransitionSessionRoot(directory, root, sessionRoot, transition, entries, currentRoot, guards = {}) {
+  const settingsTarget = path4.join(root, "settings.json");
+  const entry = entries.find((item) => item.target === settingsTarget || item.afterTarget === settingsTarget);
+  if (!entry) throw new Error("Missing settings root-transition evidence.");
+  let after;
+  if (transition.settingsAfterFile) {
+    const file = path4.join(directory, "settings-after");
+    const stat = await fs2.lstat(file);
+    validateOwner(guards);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || process.platform !== "win32" && (stat.mode & 63) !== 0)
+      throw new Error("Unsafe settings root-transition postimage.");
+    after = await fs2.readFile(file);
+    validateOwner(guards);
+  } else if (transition.settingsAfterBase64 !== null)
+    after = Buffer.from(transition.settingsAfterBase64, "base64");
+  if ((after ? fileImage(after) : "missing") !== entry.afterImage || (after ? rootFromSettings(root, after) : path4.join(root, "sessions")) !== sessionRoot || await beforeRoot(directory, root, entry, guards) !== transition.beforeRoot)
+    throw new Error("Inconsistent settings root-transition evidence.");
+  if (currentRoot !== transition.beforeRoot && currentRoot !== sessionRoot)
+    throw new Error("Transaction session root is not owned by this context; preserve evidence for review.");
+  return sessionRoot;
+}
+
+// src/snapshot/snapshot-transaction.ts
+var JOURNAL_VERSION = 4;
+async function applySnapshotTransaction(plan, options = {}) {
+  options.validateMutation?.();
+  await recoverPendingSnapshotTransactions(options);
+  const coalesced = await coalesceCaseReplacements(path5.resolve(agentDir()), plan);
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+  const targets = [.../* @__PURE__ */ new Set([...coalesced.plan.deletes, ...coalesced.plan.writes.map((item) => item.target)])].sort();
+  if (targets.length > 16384)
+    throw new Error("Snapshot transaction exceeds its target bound; review a smaller transfer.");
+  return withTargetQueues(targets, async () => {
+    options.signal?.throwIfAborted();
+    if (targets.some(
+      (target) => options.protectedTargets?.some(
+        (protectedTarget) => mergePathIdentity(target) === mergePathIdentity(protectedTarget) || isPathInside(mergePathIdentity(target), mergePathIdentity(protectedTarget))
+      )
+    ))
+      throw new Error("Snapshot transaction targets the current session; review is required.");
+    for (const [before, after] of coalesced.replacements) {
+      if (await caseReplacementSpelling(before, after) !== before)
+        throw new Error("Case replacement changed before preparation; review is required.");
+      options.validateMutation?.();
+      options.signal?.throwIfAborted();
+    }
+    const originalTargets = new Map([...coalesced.replacements].map(([before, after]) => [after, before]));
+    const expectedPreimages = new Map(
+      [...options.expectedPreimages ?? []].map(([target, expected]) => [
+        originalTargets.get(target) ?? target,
+        expected
+      ])
+    );
+    for (const [target, expected] of options.expectedPreimages ?? []) {
+      if (originalTargets.has(target)) continue;
+      const variants = coalesced.plan.deletes.filter(
+        (candidate) => candidate !== target && path5.dirname(candidate) === path5.dirname(target) && mergePathIdentity(candidate) === mergePathIdentity(target)
+      );
+      if (variants.length > 1) throw new Error("Ambiguous reviewed file preimage spellings; review required.");
+      const original = variants[0];
+      if (!original) continue;
+      const destination = await image(target);
+      options.validateMutation?.();
+      options.signal?.throwIfAborted();
+      if (destination !== "missing" && destination !== expected)
+        throw new Error("Reviewed destination preimage changed before apply.");
+      expectedPreimages.set(original, expected);
+      expectedPreimages.set(target, destination);
+    }
+    for (const [target, expected] of expectedPreimages) {
+      const current = await image(target);
+      options.validateMutation?.();
+      options.signal?.throwIfAborted();
+      if (current !== expected)
+        throw new Error("Reviewed file preimage changed before apply; snapshot installation refused.");
+    }
+    const transaction = await prepareTransaction(
+      coalesced.plan,
+      targets,
+      { ...options, expectedPreimages },
+      coalesced.replacements
+    );
+    const entriesByTarget = new Map(
+      transaction.journal.entries.flatMap((entry) => [
+        [entry.target, entry],
+        ...entry.afterTarget ? [[entry.afterTarget, entry]] : []
+      ])
+    );
+    try {
+      for (const target of transaction.deletes.sort((a, b) => a.length - b.length)) {
+        options.signal?.throwIfAborted();
+        const entry = entriesByTarget.get(target);
+        if (!entry) throw new Error("Unowned transaction target.");
+        await removeOwnedTarget(transaction.directory, entry, transaction.journal, options);
+        await syncDirectory(path5.dirname(target));
+      }
+      await withCaseDestinationQueues([...coalesced.replacements], options, async () => {
+        await retireRemovalIntent(
+          transaction.directory,
+          transaction.journal,
+          transaction.journal.entries.filter(
+            (entry) => entry.removalPending && (entry.afterImage !== "missing" || (entry.postFiles?.length ?? 0) > 0)
+          ),
+          options
+        );
+        const uninstalledWrites = new Set(transaction.deletedWrites);
+        for (const item of plan.writes) {
+          options.signal?.throwIfAborted();
+          const entry = entriesByTarget.get(item.target);
+          if (!entry) throw new Error("Unowned transaction target.");
+          const deletedByThisCall = uninstalledWrites.delete(entry.target);
+          await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
+          options.validateMutation?.();
+          options.signal?.throwIfAborted();
+          await fs3.mkdir(path5.dirname(item.target), { recursive: true });
+          options.validateMutation?.();
+          options.signal?.throwIfAborted();
+          const temp = path5.join(path5.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);
+          try {
+            let mode = 384;
+            try {
+              const stat = await fs3.lstat(item.target);
+              if (stat.isFile()) mode = stat.mode & 511;
+            } catch (error) {
+              if (error.code !== "ENOENT") throw error;
+            }
+            const handle = await fs3.open(temp, "wx", mode);
+            try {
+              await handle.writeFile(item.content);
+              await handle.sync();
+            } finally {
+              await handle.close();
+            }
+            await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
+            options.signal?.throwIfAborted();
+            options.validateMutation?.();
+            await fs3.rename(temp, item.target);
+            await syncDirectory(path5.dirname(item.target));
+          } finally {
+            await fs3.rm(temp, { force: true });
+          }
+        }
+        options.validateMutation?.();
+        options.signal?.throwIfAborted();
+        await syncMutationParents(
+          targets,
+          [transaction.journal.root, ...transaction.journal.sessionRoot ? [transaction.journal.sessionRoot] : []],
+          options
+        );
+        options.validateMutation?.();
+        options.signal?.throwIfAborted();
+      });
+    } catch (error) {
+      if (options.signal?.aborted)
+        throw new Error("Snapshot apply cancelled; guarded transaction evidence retained for review.");
+      if (coalesced.replacements.size)
+        throw new Error("Case replacement apply failed; guarded transaction evidence retained for review.", {
+          cause: error
+        });
+      try {
+        await restoreTransaction(transaction.directory, transaction.journal, options);
+      } catch (recoveryError) {
+        throw new AggregateError(
+          [error, recoveryError],
+          "Snapshot apply failed and guarded recovery requires review. Transaction and backup retained; newer bytes were not restored over."
+        );
+      }
+      throw error;
+    }
+    await completeTransaction(transaction.directory, transaction.journal);
+  });
+}
+async function recoverSnapshotTransactionsOnStartup(options = {}) {
+  if (!(await pendingTransactionEntries()).some((entry) => entry.isDirectory())) return;
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+  await withLock(
+    "recovery",
+    () => recoverPendingSnapshotTransactions({ ...options, resolveConfiguredSessionDir: true }),
+    {
+      reclaimStale: true
+    }
+  );
+}
+async function recoverPendingSnapshotTransactions(options = {}) {
+  for (const entry of (await pendingTransactionEntries()).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory()) continue;
+    const directory = path5.join(transactionRoot(), entry.name);
+    let journal;
+    try {
+      const file = path5.join(directory, "journal.json");
+      const stat = await fs3.lstat(file);
+      if (!stat.isFile() || stat.size > 32 * 1024 * 1024) throw new Error("Invalid journal file.");
+      journal = JSON.parse(await fs3.readFile(file, "utf8"));
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw new Error("Cannot recover malformed pi-sync transaction; preserve private evidence for review.");
+    }
+    let sessionDir = options.sessionDir;
+    if (sessionDir === void 0 && options.resolveConfiguredSessionDir && !journal.completed && transactionHasSessionTargets(journal)) {
+      sessionDir = await configuredSessionDir();
+    }
+    options.validateMutation?.();
+    options.signal?.throwIfAborted();
+    if (journal.sessionRootTransition && !journal.completed) {
+      validateJournal(directory, journal, journal.sessionRoot);
+      sessionDir = await resolveTransitionSessionRoot(
+        directory,
+        journal.root,
+        journal.sessionRoot,
+        journal.sessionRootTransition,
+        journal.entries,
+        path5.resolve(sessionStorageRoot(journal.root, sessionDir)),
+        options
+      );
+      options.validateMutation?.();
+      options.signal?.throwIfAborted();
+    }
+    validateJournal(directory, journal, sessionDir);
+    if (journal.completed) {
+      await removeTransaction(directory);
+      continue;
+    }
+    await withTargetQueues(
+      journal.entries.map((entry2) => entry2.target).sort(),
+      () => restoreTransaction(directory, journal, { ...options, sessionDir })
+    );
+  }
+}
+async function pendingTransactionEntries() {
+  try {
+    return await fs3.readdir(transactionRoot(), { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+async function prepareTransaction(plan, targets, options, replacements = /* @__PURE__ */ new Map()) {
+  const { sessionDir } = options;
+  const root = path5.resolve(agentDir());
+  const sessionRoot = sessionDir ? path5.resolve(sessionStorageRoot(root, sessionDir)) : void 0;
+  const indexed = indexTransactionPlan(plan, targets);
+  const directory = path5.join(transactionRoot(), randomUUID());
+  const backupDirectory = path5.join(directory, "before");
+  await fs3.mkdir(backupDirectory, { recursive: true, mode: 448 });
+  const entries = [];
+  for (const [index, target] of targets.entries()) {
+    options.signal?.throwIfAborted();
+    options.validateMutation?.();
+    assertAllowedTarget(root, sessionRoot, target);
+    await assertSafeParents(root, sessionRoot, target);
+    const entry = { target, backupName: `${index}`, kind: "missing" };
+    if (replacements.has(target)) entry.afterTarget = replacements.get(target);
+    const backup = path5.join(backupDirectory, entry.backupName);
+    try {
+      const stat = await fs3.lstat(target);
+      if (stat.isSymbolicLink()) {
+        entry.kind = "symlink";
+        entry.linkTarget = await fs3.readlink(target);
+      } else if (stat.isDirectory()) {
+        entry.kind = "directory";
+        await fs3.cp(target, backup, {
+          recursive: true,
+          dereference: false,
+          verbatimSymlinks: true,
+          preserveTimestamps: true,
+          filter: () => {
+            options.signal?.throwIfAborted();
+            options.validateMutation?.();
+            return true;
+          }
+        });
+      } else if (stat.isFile()) {
+        entry.kind = "file";
+        await fs3.copyFile(target, backup);
+        await fs3.chmod(backup, stat.mode);
+      } else throw new Error("Unsupported existing snapshot target.");
+    } catch (error) {
+      const code = error.code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+    }
+    entry.beforeImage = entry.kind === "symlink" ? `symlink:${entry.linkTarget}` : entry.kind === "missing" ? "missing" : await image(backup, true);
+    options.validateMutation?.();
+    options.signal?.throwIfAborted();
+    const expected = options.expectedPreimages?.get(target);
+    if (expected !== void 0 && entry.beforeImage !== expected)
+      throw new Error("Reviewed file preimage changed during backup; private preparation evidence retained.");
+    if (entry.afterTarget) {
+      if (entry.kind !== "file" || await caseReplacementSpelling(target, entry.afterTarget) !== target)
+        throw new Error("Case replacement preimage changed during backup; evidence retained for review.");
+      options.validateMutation?.();
+      options.signal?.throwIfAborted();
+    }
+    entry.afterImage = indexed.writeImages.get(target) ?? "missing";
+    entry.postFiles = indexed.postFiles.get(target) ?? [];
+    entries.push(entry);
+  }
+  await syncDirectory(backupDirectory);
+  const effectiveRoot = sessionRoot ?? path5.join(root, "sessions");
+  const sessionRootTransition = await prepareSessionRootTransition(
+    directory,
+    root,
+    effectiveRoot,
+    entries,
+    plan,
+    options
+  );
+  const journal = {
+    version: sessionRootTransition ? 7 : replacements.size ? 5 : JOURNAL_VERSION,
+    root,
+    sessionRoot: sessionRootTransition ? effectiveRoot : sessionRoot,
+    sessionRootTransition,
+    entries
+  };
+  options.signal?.throwIfAborted();
+  options.validateMutation?.();
+  await writeJson(path5.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
+  await syncDirectory(transactionRoot());
+  await syncDirectory(stateDir());
+  await syncDirectory(path5.dirname(stateDir()));
+  return { directory, journal, deletes: indexed.deletes, deletedWrites: indexed.deletedWrites };
+}
+async function restoreTransaction(directory, journal, options) {
+  validateJournal(directory, journal, options.sessionDir);
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+  for (const entry of journal.entries) {
+    if (options.protectedTargets?.some(
+      (target) => mergePathIdentity(target) === mergePathIdentity(entry.target) || isPathInside(mergePathIdentity(entry.target), mergePathIdentity(target))
+    ))
+      throw new Error(
+        "Pending transaction touches the current session; resume a different session before guarded recovery."
+      );
+    await verifyTarget(directory, entry, journal);
+  }
+  for (const entry of journal.entries) {
+    if (!entry.recoveryStaged) continue;
+    options.validateMutation?.();
+    options.signal?.throwIfAborted();
+    await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
+    options.validateMutation?.();
+    options.signal?.throwIfAborted();
+    await fs3.rm(recoveryStagePath(directory, entry), { recursive: true, force: true });
+    options.validateMutation?.();
+    options.signal?.throwIfAborted();
+  }
+  for (const entry of [...journal.entries].sort((a, b) => a.target.length - b.target.length)) {
+    const current = await verifyTarget(directory, entry, journal);
+    const before = await beforeImage(directory, entry);
+    const spellingMatches = async () => !entry.afterTarget || await caseReplacementSpelling(entry.target, entry.afterTarget) === entry.target;
+    if (current === before && await spellingMatches()) continue;
+    options.signal?.throwIfAborted();
+    options.validateMutation?.();
+    if (entry.kind === "file") {
+      const temporary2 = await prepareRecoveryStage(directory, journal, entry, options);
+      try {
+        await fs3.mkdir(path5.dirname(entry.target), { recursive: true });
+        await fs3.copyFile(path5.join(directory, "before", entry.backupName), temporary2);
+        const handle = await fs3.open(temporary2, "r");
+        try {
+          await handle.sync();
+        } finally {
+          await handle.close();
+        }
+        const verified = await verifyTarget(directory, entry, journal);
+        options.validateMutation?.();
+        options.signal?.throwIfAborted();
+        if (verified === before && await spellingMatches()) continue;
+        const needsCaseQueue = entry.afterTarget !== void 0 && await caseReplacementSpelling(entry.target, entry.afterTarget) === entry.afterTarget;
+        if (needsCaseQueue) {
+          await removeOwnedTarget(directory, entry, journal, options);
+        } else if (verified.startsWith("directory:") && !await removeOwnedTarget(directory, entry, journal, options, before))
+          continue;
+        await withCaseDestinationQueues(
+          needsCaseQueue && entry.afterTarget ? [[entry.afterTarget, entry.target]] : [],
+          options,
+          async () => {
+            const atRename = await verifyTarget(directory, entry, journal);
+            options.validateMutation?.();
+            options.signal?.throwIfAborted();
+            if (atRename === before && await spellingMatches()) return;
+            await retireRestorationIntent(directory, journal, entry, options);
+            const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
+            options.validateMutation?.();
+            options.signal?.throwIfAborted();
+            if (atInstall === before && await spellingMatches()) return;
+            await fs3.rename(temporary2, entry.target);
+            await syncDirectory(path5.dirname(entry.target));
+          }
+        );
+      } finally {
+        await fs3.rm(temporary2, { force: true });
+      }
+      continue;
+    }
+    if (entry.kind === "missing") {
+      await removeOwnedTarget(directory, entry, journal, options, before);
+      continue;
+    }
+    const temporary = await prepareRecoveryStage(directory, journal, entry, options);
+    try {
+      await fs3.mkdir(path5.dirname(entry.target), { recursive: true });
+      await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
+      if (entry.kind === "directory") {
+        await fs3.cp(path5.join(directory, "before", entry.backupName), temporary, {
+          recursive: true,
+          dereference: false,
+          verbatimSymlinks: true,
+          preserveTimestamps: true,
+          filter: () => {
+            options.validateMutation?.();
+            options.signal?.throwIfAborted();
+            return true;
+          }
+        });
+      } else if (entry.linkTarget !== void 0) await fs3.symlink(entry.linkTarget, temporary);
+      if (await image(temporary, true) !== before)
+        throw new Error("Staged recovery image differs from the backup; evidence retained.");
+      options.validateMutation?.();
+      options.signal?.throwIfAborted();
+      if (!await removeOwnedTarget(directory, entry, journal, options, before)) continue;
+      const atRename = await verifyTarget(directory, entry, journal);
+      options.validateMutation?.();
+      options.signal?.throwIfAborted();
+      if (atRename === before) continue;
+      await retireRestorationIntent(directory, journal, entry, options);
+      const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
+      options.validateMutation?.();
+      options.signal?.throwIfAborted();
+      if (atInstall === before) continue;
+      await fs3.rename(temporary, entry.target);
+      await syncDirectory(path5.dirname(entry.target));
+    } finally {
+      await fs3.rm(temporary, { recursive: true, force: true });
+    }
+  }
+  await syncMutationParents(
+    journal.entries.map((entry) => entry.target),
+    [journal.root, ...journal.sessionRoot ? [journal.sessionRoot] : []],
+    options
+  );
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+  await completeTransaction(directory, journal);
+}
+async function verifyTarget(directory, entry, journal, deletedByThisCall = false) {
+  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
+  const before = await beforeImage(directory, entry);
+  if (journal.version >= 2 && before !== entry.beforeImage)
+    throw new Error("Transaction backup changed; preserve evidence for review.");
+  if (entry.afterTarget) await caseReplacementSpelling(entry.target, entry.afterTarget);
+  const current = await image(entry.target);
+  if (current === before) return current;
+  if (current === "missing") {
+    if (deletedByThisCall || journal.version >= 4 && entry.removalPending && !entry.replacementStarted)
+      return current;
+  } else if (journal.version >= 2 && (current === entry.afterImage || await ownedPostTree(
+    entry.target,
+    entry.postFiles ?? [],
+    journal.version < 4 || entry.replacementStarted === true || !entry.removalPending
+  )))
+    return current;
+  throw new Error(
+    "Transaction target has unrecognized or newer bytes; automatic rollback refused. Preserve the transaction and review its backup with Pi closed."
+  );
+}
+async function removeOwnedTarget(directory, entry, journal, options, restoringBefore) {
+  const current = await verifyTarget(directory, entry, journal);
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+  if (restoringBefore !== void 0 && current === restoringBefore) return false;
+  upgradeRemovalEvidence(journal);
+  for (const affected of journal.entries) {
+    if (affected.target === entry.target || isStrictlyInside(entry.target, affected.target)) {
+      affected.removalPending = true;
+      affected.replacementStarted = false;
+    }
+  }
+  await writeJson(path5.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
+  const verified = await verifyTarget(directory, entry, journal);
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+  if (restoringBefore !== void 0 && verified === restoringBefore) return false;
+  await fs3.rm(entry.target, { recursive: true, force: true });
+  await syncDirectory(path5.dirname(entry.target));
+  return true;
+}
+function upgradeRemovalEvidence(journal) {
+  if (journal.version < JOURNAL_VERSION) {
+    for (const entry of journal.entries) entry.removalPending = false;
+    journal.version = JOURNAL_VERSION;
+  }
+}
+async function retireRemovalIntent(directory, journal, entries, options) {
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+  if (!entries.length) return;
+  upgradeRemovalEvidence(journal);
+  for (const entry of entries) {
+    entry.removalPending = false;
+    entry.replacementStarted = true;
+  }
+  await writeJson(path5.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+}
+async function retireRestorationIntent(directory, journal, entry, options) {
+  for (const child of journal.entries) {
+    if (isStrictlyInside(entry.target, child.target)) {
+      child.removalPending = false;
+      child.replacementStarted = false;
+    }
+  }
+  await retireRemovalIntent(directory, journal, [entry], options);
+}
+function recoveryStagePath(directory, entry) {
+  const token = createHash2("sha256").update(directory).update("\\0").update(entry.backupName).digest("hex");
+  return path5.join(
+    path5.dirname(entry.target),
+    `.pi-sync.json.${token}.${entry.kind === "file" ? "restore" : "restore-tree"}`
+  );
+}
+async function prepareRecoveryStage(directory, journal, entry, options) {
+  const temporary = recoveryStagePath(directory, entry);
+  if (!entry.recoveryStaged) {
+    try {
+      await fs3.lstat(temporary);
+      throw new Error("Unowned recovery staging path; preserve evidence for review.");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    options.validateMutation?.();
+    options.signal?.throwIfAborted();
+    entry.recoveryStaged = true;
+    await writeJson(path5.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
+    options.validateMutation?.();
+    options.signal?.throwIfAborted();
+  }
+  return temporary;
+}
+async function beforeImage(directory, entry) {
+  if (entry.kind === "missing") return "missing";
+  if (entry.kind === "symlink") return `symlink:${entry.linkTarget}`;
+  const value = await image(path5.join(directory, "before", entry.backupName));
+  if (value === "missing") throw new Error("Transaction backup is missing; preserve evidence for review.");
+  return value;
+}
+async function image(target, durable = false) {
+  let stat;
+  try {
+    stat = await fs3.lstat(target);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") return "missing";
+    throw error;
+  }
+  if (stat.isSymbolicLink()) return `symlink:${await fs3.readlink(target)}`;
+  if (stat.isFile()) {
+    const content = await fs3.readFile(target);
+    if (durable) {
+      const handle = await fs3.open(target, "r");
+      try {
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+    }
+    return fileImage(content);
+  }
+  if (!stat.isDirectory()) throw new Error("Unsupported transaction image.");
+  const entries = [];
+  for (const name of (await fs3.readdir(target)).sort())
+    entries.push([name, await image(path5.join(target, name), durable)]);
+  if (durable) await syncDirectory(target);
+  return `directory:${createHash2("sha256").update(JSON.stringify(entries)).digest("hex")}`;
+}
+async function ownedPostTree(target, files, requireComplete) {
+  if (!files.length) return false;
+  const expected = new Map(files.map((file) => [mergePathIdentity(file.relative), file.image]));
+  const prefixes = /* @__PURE__ */ new Set();
+  for (const relative of expected.keys()) {
+    for (let parent = path5.dirname(relative); parent !== "." && parent !== path5.dirname(parent); parent = path5.dirname(parent))
+      prefixes.add(parent);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  async function visit(directory) {
+    let stat;
+    try {
+      stat = await fs3.lstat(directory);
+    } catch {
+      return false;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return false;
+    for (const name of await fs3.readdir(directory)) {
+      const child = path5.join(directory, name);
+      const relative = mergePathIdentity(path5.relative(target, child));
+      const stat2 = await fs3.lstat(child);
+      if (stat2.isDirectory() && !stat2.isSymbolicLink()) {
+        if (!prefixes.has(relative) || !await visit(child)) return false;
+      } else {
+        if (expected.get(relative) !== await image(child)) return false;
+        seen.add(relative);
+      }
+    }
+    return true;
+  }
+  return await visit(target) && (!requireComplete || [...expected.keys()].every((key) => seen.has(key)));
+}
+function validateJournal(directory, journal, sessionDir) {
+  if (![1, 2, 3, 4, 5, 6, 7].includes(journal.version) || !Array.isArray(journal.entries) || journal.entries.length > 16384)
+    throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
+  if (journal.completed !== void 0 && (![6, 7].includes(journal.version) || journal.completed !== true))
+    throw new Error("Invalid transaction completion evidence.");
+  const root = path5.resolve(agentDir());
+  if (typeof journal.root !== "string" || path5.resolve(journal.root) !== root)
+    throw new Error("Transaction root no longer matches the Pi agent directory.");
+  if (journal.sessionRootTransition !== void 0) {
+    if (journal.version !== 7 || typeof journal.sessionRoot !== "string")
+      throw new Error("Invalid session root-transition version.");
+    validateSessionRootTransition(journal.sessionRootTransition);
+  } else if (journal.version === 7) throw new Error("Missing session root-transition evidence.");
+  const trustedSessionRoot = sessionDir ? path5.resolve(sessionStorageRoot(root, sessionDir)) : path5.join(root, "sessions");
+  if (journal.sessionRoot !== void 0 && (typeof journal.sessionRoot !== "string" || !path5.isAbsolute(journal.sessionRoot) || path5.resolve(journal.sessionRoot) !== journal.sessionRoot || !journal.completed && transactionHasSessionTargets(journal) && journal.sessionRoot !== trustedSessionRoot))
+    throw new Error("Transaction session root is not owned by this context; preserve evidence for review.");
+  for (const entry of journal.entries) {
+    if (!entry || typeof entry.target !== "string" || !path5.isAbsolute(entry.target) || path5.resolve(entry.target) !== entry.target || typeof entry.backupName !== "string" || !/^\d+$/u.test(entry.backupName) || !["missing", "file", "directory", "symlink"].includes(entry.kind))
+      throw new Error("Invalid pi-sync transaction entry.");
+    assertWithinRoot(directory, path5.join(directory, "before", entry.backupName));
+    assertAllowedTarget(root, journal.sessionRoot, entry.target);
+    if (entry.afterTarget !== void 0 && (![5, 6, 7].includes(journal.version) || typeof entry.afterTarget !== "string" || !isCaseReplacement(root, entry.target, entry.afterTarget) || path5.resolve(entry.afterTarget) !== entry.afterTarget || entry.kind !== "file"))
+      throw new Error("Invalid transaction case replacement evidence.");
+    if (entry.afterTarget) assertAllowedTarget(root, journal.sessionRoot, entry.afterTarget);
+    if (journal.version >= 2 && ((entry.beforeImage === void 0 ? !journal.completed : typeof entry.beforeImage !== "string") || (entry.afterImage === void 0 ? !journal.completed : typeof entry.afterImage !== "string") || (entry.postFiles === void 0 ? !journal.completed : !Array.isArray(entry.postFiles))))
+      throw new Error("Invalid transaction postimage evidence.");
+    if (entry.recoveryStaged !== void 0 && typeof entry.recoveryStaged !== "boolean")
+      throw new Error("Invalid recovery staging evidence.");
+    if (entry.removalPending !== void 0 && (journal.version < 3 || typeof entry.removalPending !== "boolean"))
+      throw new Error("Invalid transaction removal evidence.");
+    if (entry.replacementStarted !== void 0 && (journal.version < 4 || typeof entry.replacementStarted !== "boolean"))
+      throw new Error("Invalid transaction replacement evidence.");
+    if (entry.removalPending && entry.replacementStarted)
+      throw new Error("Conflicting transaction replacement evidence.");
+    for (const file of entry.postFiles ?? []) {
+      if (typeof file.relative !== "string" || typeof file.image !== "string" || !isStrictlyInside(entry.target, path5.resolve(entry.target, file.relative)))
+        throw new Error("Invalid transaction subtree evidence.");
+    }
+  }
+}
+function transactionHasSessionTargets(journal) {
+  const root = path5.resolve(agentDir());
+  return Array.isArray(journal.entries) && journal.entries.some(
+    (entry) => typeof entry?.target === "string" && (!isPathInside(root, entry.target) || isPathInside(path5.join(root, "sessions"), entry.target) || typeof journal.sessionRoot === "string" && isPathInside(journal.sessionRoot, entry.target))
+  );
+}
+function isStrictlyInside(root, target) {
+  return path5.relative(path5.resolve(root), path5.resolve(target)) !== "" && isPathInside(root, target);
+}
+function assertAllowedTarget(root, sessionRoot, target) {
+  const resolved = path5.resolve(target);
+  if (isStrictlyInside(root, resolved)) {
+    if (isDeniedPath(path5.relative(root, resolved))) throw new Error("Transaction targets denied private storage.");
+    assertWithinRoot(root, resolved);
+    return;
+  }
+  if (sessionRoot && isStrictlyInside(sessionRoot, resolved)) {
+    if (isDeniedPath(`sessions/${path5.relative(sessionRoot, resolved)}`))
+      throw new Error("Transaction targets denied session storage.");
+    assertWithinRoot(sessionRoot, resolved);
+    return;
+  }
+  throw new Error("Transaction target is outside configured roots.");
+}
+async function assertSafeParents(root, sessionRoot, target) {
+  assertAllowedTarget(root, sessionRoot, target);
+  const boundary = isPathInside(root, target) ? root : sessionRoot;
+  for (let parent = path5.dirname(target); boundary && mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path5.dirname(parent)) {
+    if (path5.dirname(parent) === parent) throw new Error("Transaction parent did not reach its owned boundary.");
+    try {
+      const stat = await fs3.lstat(parent);
+      if (!stat.isDirectory() && !stat.isFile() || stat.isSymbolicLink())
+        throw new Error("Unsafe transaction parent.");
+    } catch (error) {
+      const code = error.code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+    }
+  }
+}
+async function withTargetQueues(targets, action) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const target of targets) {
+    let key = path5.resolve(target);
+    try {
+      key = await fs3.realpath(target);
+    } catch (error) {
+      const code = error.code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+    }
+    if (keys.has(key)) throw new Error("Transaction targets alias the same file.");
+    keys.add(key);
+  }
+  async function acquire(index) {
+    const target = targets[index];
+    return target ? withFileMutationQueue(target, () => acquire(index + 1)) : action();
+  }
+  return acquire(0);
+}
+async function withCaseDestinationQueues(spellings, options, action) {
+  if (!spellings.length) return action();
+  const requireAbsent = async () => {
+    for (const [before, after] of spellings) {
+      options.validateMutation?.();
+      options.signal?.throwIfAborted();
+      const spelling = await caseReplacementSpelling(before, after);
+      options.validateMutation?.();
+      options.signal?.throwIfAborted();
+      if (spelling !== void 0)
+        throw new Error("Case replacement changed before destination queue reservation; evidence retained.");
+    }
+  };
+  await requireAbsent();
+  return withTargetQueues(
+    spellings.map(([, after]) => after),
+    async () => {
+      await requireAbsent();
+      return action();
+    }
+  );
+}
+async function completeTransaction(directory, journal) {
+  await writeJson(
+    path5.join(directory, "journal.json"),
+    { ...journal, version: journal.sessionRootTransition ? 7 : 6, completed: true },
+    {
+      maxBytes: 32 * 1024 * 1024
+    }
+  );
+  await removeTransaction(directory);
+}
+async function removeTransaction(directory) {
+  await fs3.rm(directory, { recursive: true, force: true });
+  await syncDirectory(transactionRoot()).catch(() => {
+  });
+}
+function transactionRoot() {
+  return path5.join(stateDir(), "transactions");
+}
+
+export {
+  syncMutationParents,
+  applySnapshotTransaction,
+  recoverSnapshotTransactionsOnStartup,
+  recoverPendingSnapshotTransactions
+};
+//# sourceMappingURL=chunk-ANWNQIR7.ts.map