@narumitw/pi-sync 0.57.10 → 0.57.11

package/dist/chunks/{chunk-AAPAHANE.ts → chunk-7A35ZAVO.ts}

@@ -6,10 +6,14 @@ import {
 } from "./chunk-5SFMBY5P.ts";
 import {
   withLock
-} from "./chunk-MDUORMCK.ts";
+} from "./chunk-6O3EDBRL.ts";
 import {
   mergePathIdentity
-} from "./chunk-TO2GMX3K.ts";
+} from "./chunk-XJHQPB3E.ts";
+import {
+  syncDirectory,
+  writeJson
+} from "./chunk-AR2DGDUI.ts";
 import {
   stateDir
 } from "./chunk-SWRVXVFD.ts";
@@ -18,22 +22,17 @@ import {
   configuredSessionDir,
   expandSessionDir,
   sessionStorageRoot
-} from "./chunk-DO55XUNU.ts";
-import {
-  syncDirectory,
-  writeJson
-} from "./chunk-AR2DGDUI.ts";
+} from "./chunk-CBLTWXAU.ts";
 import {
   assertWithinRoot,
   isDeniedPath,
   isPathInside
-} from "./chunk-YZ5BQNRZ.ts";
+} from "./chunk-FHE2DCA2.ts";
 
 // 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";
+import fs4 from "node:fs/promises";
+import path6 from "node:path";
 
 // src/state/mutation-directory-sync.ts
 import path from "node:path";
@@ -132,13 +131,124 @@ async function coalesceCaseReplacements(root, plan) {
   };
 }
 
-// src/snapshot/snapshot-root-transition.ts
+// src/snapshot/snapshot-mutation-queues.ts
 import fs2 from "node:fs/promises";
-import path4 from "node:path";
+import path3 from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+function assertCurrent(options) {
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+}
+function isMissing(error) {
+  const code = error.code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+async function targetMissing(target, options) {
+  assertCurrent(options);
+  try {
+    await fs2.lstat(target);
+    assertCurrent(options);
+    return false;
+  } catch (error) {
+    assertCurrent(options);
+    if (!isMissing(error)) throw error;
+    return true;
+  }
+}
+async function queueKey(target, options) {
+  assertCurrent(options);
+  try {
+    const key = await fs2.realpath(target);
+    assertCurrent(options);
+    return key;
+  } catch (error) {
+    assertCurrent(options);
+    if (!isMissing(error)) throw error;
+    return path3.resolve(target);
+  }
+}
+async function assertCanonicalParent(target, options) {
+  const parent = path3.dirname(path3.resolve(target));
+  const suffix = [];
+  for (let current = parent; ; current = path3.dirname(current)) {
+    assertCurrent(options);
+    let canonical;
+    try {
+      canonical = await fs2.realpath(current);
+    } catch (error) {
+      assertCurrent(options);
+      if (!isMissing(error) || path3.dirname(current) === current) throw error;
+      suffix.unshift(path3.basename(current));
+      continue;
+    }
+    assertCurrent(options);
+    if (path3.join(canonical, ...suffix) !== parent)
+      throw new Error(
+        "Snapshot mutation through an aliased parent is unsafe; use the canonical agent/session path. Transaction evidence retained for review."
+      );
+    return;
+  }
+}
+async function assertCanonicalMutationTargets(targets, options) {
+  for (const target of targets) await assertCanonicalParent(target, options);
+}
+async function withTargetQueues(targets, options, action) {
+  await assertCanonicalMutationTargets(targets, options);
+  const keys = /* @__PURE__ */ new Set();
+  const missing = /* @__PURE__ */ new Set();
+  for (const target of targets) {
+    if (await targetMissing(target, options)) missing.add(target);
+    const key = await queueKey(target, options);
+    if (keys.has(key)) throw new Error("Transaction targets alias the same file.");
+    keys.add(key);
+  }
+  const ordered = [...keys].sort();
+  async function acquire(index) {
+    assertCurrent(options);
+    const key = ordered[index];
+    if (key) return withFileMutationQueue(key, () => acquire(index + 1));
+    for (const target of targets) {
+      await assertCanonicalParent(target, options);
+      if (missing.has(target) && !await targetMissing(target, options))
+        throw new Error("Missing transaction target appeared during queue acquisition; review is required.");
+      if (!keys.has(await queueKey(target, options)))
+        throw new Error("Transaction queue identity changed; review is required.");
+    }
+    assertCurrent(options);
+    return action(keys);
+  }
+  return acquire(0);
+}
+async function withMissingTargetQueues(targets, heldKeys, options, action) {
+  const unique = [...new Set(targets)];
+  const requireAbsent = async () => {
+    for (const target of unique) {
+      await assertCanonicalParent(target, options);
+      if (!await targetMissing(target, options))
+        throw new Error("Snapshot target changed before destination queue reservation; evidence retained.");
+    }
+  };
+  const keys = unique.map((target) => path3.resolve(target)).filter((key) => !heldKeys.has(key)).sort();
+  await requireAbsent();
+  const combined = /* @__PURE__ */ new Set([...heldKeys, ...keys]);
+  async function acquire(index) {
+    assertCurrent(options);
+    const key = keys[index];
+    if (key) return withFileMutationQueue(key, () => acquire(index + 1));
+    await requireAbsent();
+    assertCurrent(options);
+    return action(combined);
+  }
+  return acquire(0);
+}
+
+// src/snapshot/snapshot-root-transition.ts
+import fs3 from "node:fs/promises";
+import path5 from "node:path";
 
 // src/snapshot/snapshot-transaction-plan.ts
 import { createHash } from "node:crypto";
-import path3 from "node:path";
+import path4 from "node:path";
 function fileImage(content) {
   return `file:${createHash("sha256").update(content).digest("hex")}`;
 }
@@ -151,7 +261,7 @@ function indexTransactionPlan(plan, targets) {
     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 });
+        postFiles.get(ancestor)?.push({ relative: path4.relative(ancestor, write.target), image: image2 });
       }
     }
   }
@@ -175,10 +285,10 @@ function indexTransactionPlan(plan, targets) {
   return { writeImages, postFiles, deletes, deletedWrites };
 }
 function isStrictDescendant(parent, target) {
-  return path3.relative(path3.resolve(parent), path3.resolve(target)) !== "" && isPathInside(parent, target);
+  return path4.relative(path4.resolve(parent), path4.resolve(target)) !== "" && isPathInside(parent, target);
 }
 function pathKey(target) {
-  const resolved = path3.resolve(target);
+  const resolved = path4.resolve(target);
   return process.platform === "win32" ? resolved.toLowerCase() : resolved;
 }
 function indexTargets(targets) {
@@ -192,10 +302,10 @@ function indexTargets(targets) {
   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)) {
+  const resolved = path4.resolve(target);
+  for (let ancestor = includeSelf ? resolved : path4.dirname(resolved); ; ancestor = path4.dirname(ancestor)) {
     yield* index.get(pathKey(ancestor)) ?? [];
-    if (path3.dirname(ancestor) === ancestor) return;
+    if (path4.dirname(ancestor) === ancestor) return;
   }
 }
 
@@ -215,36 +325,36 @@ function rootFromSettings(root, bytes) {
     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));
+  return path5.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 === "missing" && entry.beforeImage === "missing") return path5.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);
+  const backup = path5.join(directory, "before", entry.backupName);
+  const stat = await fs3.lstat(backup);
   validateOwner(guards);
   if (!stat.isFile()) throw new Error("Invalid settings root-transition backup.");
-  const bytes = await fs2.readFile(backup);
+  const bytes = await fs3.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 settingsTarget = path5.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");
+  const afterRoot = write ? rootFromSettings(root, write.content) : path5.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);
+  const handle = await fs3.open(path5.join(directory, "settings-after"), "wx", 384);
   try {
     validateOwner(guards);
     await handle.writeFile(write.content);
@@ -259,25 +369,25 @@ async function prepareSessionRootTransition(directory, root, sessionRoot, entrie
   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)))
+  if (!value || typeof value.beforeRoot !== "string" || !path5.isAbsolute(value.beforeRoot) || path5.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 settingsTarget = path5.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);
+    const file = path5.join(directory, "settings-after");
+    const stat = await fs3.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);
+    after = await fs3.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)
+  if ((after ? fileImage(after) : "missing") !== entry.afterImage || (after ? rootFromSettings(root, after) : path5.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.");
@@ -289,13 +399,13 @@ var JOURNAL_VERSION = 4;
 async function applySnapshotTransaction(plan, options = {}) {
   options.validateMutation?.();
   await recoverPendingSnapshotTransactions(options);
-  const coalesced = await coalesceCaseReplacements(path5.resolve(agentDir()), plan);
+  const coalesced = await coalesceCaseReplacements(path6.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 () => {
+  return withTargetQueues(targets, options, async (heldKeys) => {
     options.signal?.throwIfAborted();
     if (targets.some(
       (target) => options.protectedTargets?.some(
@@ -319,7 +429,7 @@ async function applySnapshotTransaction(plan, options = {}) {
     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)
+        (candidate) => candidate !== target && path6.dirname(candidate) === path6.dirname(target) && mergePathIdentity(candidate) === mergePathIdentity(target)
       );
       if (variants.length > 1) throw new Error("Ambiguous reviewed file preimage spellings; review required.");
       const original = variants[0];
@@ -351,79 +461,87 @@ async function applySnapshotTransaction(plan, options = {}) {
         ...entry.afterTarget ? [[entry.afterTarget, entry]] : []
       ])
     );
+    const changesQueueKey = transaction.journal.entries.some(
+      (entry) => !heldKeys.has(entry.target) || entry.afterTarget && !heldKeys.has(entry.afterTarget)
+    );
     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 syncDirectory(path6.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 withMissingTargetQueues(
+        transaction.journal.entries.filter((entry) => entry.removalPending).flatMap((entry) => [entry.target, ...entry.afterTarget ? [entry.afterTarget] : []]),
+        heldKeys,
+        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 fs4.mkdir(path6.dirname(item.target), { recursive: true });
             options.validateMutation?.();
-            await fs3.rename(temp, item.target);
-            await syncDirectory(path5.dirname(item.target));
-          } finally {
-            await fs3.rm(temp, { force: true });
+            options.signal?.throwIfAborted();
+            const temp = path6.join(path6.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);
+            try {
+              let mode = 384;
+              try {
+                const stat = await fs4.lstat(item.target);
+                if (stat.isFile()) mode = stat.mode & 511;
+              } catch (error) {
+                if (error.code !== "ENOENT") throw error;
+              }
+              const handle = await fs4.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 fs4.rename(temp, item.target);
+              await syncDirectory(path6.dirname(item.target));
+            } finally {
+              await fs4.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();
         }
-        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.", {
+      if (changesQueueKey)
+        throw new Error("Snapshot apply failed; guarded transaction evidence retained for review.", {
           cause: error
         });
       try {
-        await restoreTransaction(transaction.directory, transaction.journal, options);
+        await restoreTransaction(transaction.directory, transaction.journal, options, heldKeys);
       } catch (recoveryError) {
         throw new AggregateError(
           [error, recoveryError],
@@ -450,13 +568,13 @@ async function recoverSnapshotTransactionsOnStartup(options = {}) {
 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);
+    const directory = path6.join(transactionRoot(), entry.name);
     let journal;
     try {
-      const file = path5.join(directory, "journal.json");
-      const stat = await fs3.lstat(file);
+      const file = path6.join(directory, "journal.json");
+      const stat = await fs4.lstat(file);
       if (!stat.isFile() || stat.size > 32 * 1024 * 1024) throw new Error("Invalid journal file.");
-      journal = JSON.parse(await fs3.readFile(file, "utf8"));
+      journal = JSON.parse(await fs4.readFile(file, "utf8"));
     } catch (error) {
       if (error.code === "ENOENT") continue;
       throw new Error("Cannot recover malformed pi-sync transaction; preserve private evidence for review.");
@@ -475,7 +593,7 @@ async function recoverPendingSnapshotTransactions(options = {}) {
         journal.sessionRoot,
         journal.sessionRootTransition,
         journal.entries,
-        path5.resolve(sessionStorageRoot(journal.root, sessionDir)),
+        path6.resolve(sessionStorageRoot(journal.root, sessionDir)),
         options
       );
       options.validateMutation?.();
@@ -488,18 +606,19 @@ async function recoverPendingSnapshotTransactions(options = {}) {
     }
     await withTargetQueues(
       journal.entries.map((entry2) => entry2.target).sort(),
-      () => restoreTransaction(directory, journal, { ...options, sessionDir })
+      options,
+      (heldKeys) => restoreTransaction(directory, journal, { ...options, sessionDir }, heldKeys)
     );
   }
 }
 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 root = path6.resolve(agentDir());
+  const sessionRoot = sessionDir ? path6.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 directory = path6.join(transactionRoot(), randomUUID());
+  const backupDirectory = path6.join(directory, "before");
+  await fs4.mkdir(backupDirectory, { recursive: true, mode: 448 });
   const entries = [];
   for (const [index, target] of targets.entries()) {
     options.signal?.throwIfAborted();
@@ -508,15 +627,15 @@ async function prepareTransaction(plan, targets, options, replacements = /* @__P
     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);
+    const backup = path6.join(backupDirectory, entry.backupName);
     try {
-      const stat = await fs3.lstat(target);
+      const stat = await fs4.lstat(target);
       if (stat.isSymbolicLink()) {
         entry.kind = "symlink";
-        entry.linkTarget = await fs3.readlink(target);
+        entry.linkTarget = await fs4.readlink(target);
       } else if (stat.isDirectory()) {
         entry.kind = "directory";
-        await fs3.cp(target, backup, {
+        await fs4.cp(target, backup, {
           recursive: true,
           dereference: false,
           verbatimSymlinks: true,
@@ -529,8 +648,8 @@ async function prepareTransaction(plan, targets, options, replacements = /* @__P
         });
       } else if (stat.isFile()) {
         entry.kind = "file";
-        await fs3.copyFile(target, backup);
-        await fs3.chmod(backup, stat.mode);
+        await fs4.copyFile(target, backup);
+        await fs4.chmod(backup, stat.mode);
       } else throw new Error("Unsupported existing snapshot target.");
     } catch (error) {
       const code = error.code;
@@ -553,7 +672,7 @@ async function prepareTransaction(plan, targets, options, replacements = /* @__P
     entries.push(entry);
   }
   await syncDirectory(backupDirectory);
-  const effectiveRoot = sessionRoot ?? path5.join(root, "sessions");
+  const effectiveRoot = sessionRoot ?? path6.join(root, "sessions");
   const sessionRootTransition = await prepareSessionRootTransition(
     directory,
     root,
@@ -571,13 +690,32 @@ async function prepareTransaction(plan, targets, options, replacements = /* @__P
   };
   options.signal?.throwIfAborted();
   options.validateMutation?.();
-  await writeJson(path5.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
+  await writeJson(path6.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
   await syncDirectory(transactionRoot());
   await syncDirectory(stateDir());
-  await syncDirectory(path5.dirname(stateDir()));
+  await syncDirectory(path6.dirname(stateDir()));
   return { directory, journal, deletes: indexed.deletes, deletedWrites: indexed.deletedWrites };
 }
-async function restoreTransaction(directory, journal, options) {
+async function restoreTransaction(directory, journal, options, heldKeys) {
+  validateJournal(directory, journal, options.sessionDir);
+  const missingSpellings = [];
+  for (const entry of journal.entries) {
+    if (!entry.afterTarget) continue;
+    options.validateMutation?.();
+    options.signal?.throwIfAborted();
+    const spelling = await caseReplacementSpelling(entry.target, entry.afterTarget);
+    options.validateMutation?.();
+    options.signal?.throwIfAborted();
+    if (spelling === void 0) missingSpellings.push(entry.target, entry.afterTarget);
+  }
+  return withMissingTargetQueues(
+    missingSpellings,
+    heldKeys,
+    options,
+    (reservedKeys) => restoreQueuedTransaction(directory, journal, options, reservedKeys)
+  );
+}
+async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
   validateJournal(directory, journal, options.sessionDir);
   options.validateMutation?.();
   options.signal?.throwIfAborted();
@@ -597,7 +735,7 @@ async function restoreTransaction(directory, journal, options) {
     await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
     options.validateMutation?.();
     options.signal?.throwIfAborted();
-    await fs3.rm(recoveryStagePath(directory, entry), { recursive: true, force: true });
+    await fs4.rm(recoveryStagePath(directory, entry), { recursive: true, force: true });
     options.validateMutation?.();
     options.signal?.throwIfAborted();
   }
@@ -611,9 +749,9 @@ async function restoreTransaction(directory, journal, options) {
     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, process.platform === "win32" ? "r+" : "r");
+        await fs4.mkdir(path6.dirname(entry.target), { recursive: true });
+        await fs4.copyFile(path6.join(directory, "before", entry.backupName), temporary2);
+        const handle = await fs4.open(temporary2, process.platform === "win32" ? "r+" : "r");
         try {
           await handle.sync();
         } finally {
@@ -628,8 +766,9 @@ async function restoreTransaction(directory, journal, options) {
           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]] : [],
+        await withMissingTargetQueues(
+          entry.afterTarget && (needsCaseQueue || verified === "missing") ? [entry.target, entry.afterTarget] : verified.startsWith("directory:") ? [entry.target] : [],
+          heldKeys,
           options,
           async () => {
             const atRename = await verifyTarget(directory, entry, journal);
@@ -641,12 +780,12 @@ async function restoreTransaction(directory, journal, options) {
             options.validateMutation?.();
             options.signal?.throwIfAborted();
             if (atInstall === before && await spellingMatches()) return;
-            await fs3.rename(temporary2, entry.target);
-            await syncDirectory(path5.dirname(entry.target));
+            await fs4.rename(temporary2, entry.target);
+            await syncDirectory(path6.dirname(entry.target));
           }
         );
       } finally {
-        await fs3.rm(temporary2, { force: true });
+        await fs4.rm(temporary2, { force: true });
       }
       continue;
     }
@@ -656,10 +795,10 @@ async function restoreTransaction(directory, journal, options) {
     }
     const temporary = await prepareRecoveryStage(directory, journal, entry, options);
     try {
-      await fs3.mkdir(path5.dirname(entry.target), { recursive: true });
+      await fs4.mkdir(path6.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, {
+        await fs4.cp(path6.join(directory, "before", entry.backupName), temporary, {
           recursive: true,
           dereference: false,
           verbatimSymlinks: true,
@@ -670,25 +809,27 @@ async function restoreTransaction(directory, journal, options) {
             return true;
           }
         });
-      } else if (entry.linkTarget !== void 0) await fs3.symlink(entry.linkTarget, temporary);
+      } else if (entry.linkTarget !== void 0) await fs4.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));
+      await withMissingTargetQueues([entry.target], heldKeys, options, async () => {
+        const atRename = await verifyTarget(directory, entry, journal);
+        options.validateMutation?.();
+        options.signal?.throwIfAborted();
+        if (atRename === before) return;
+        await retireRestorationIntent(directory, journal, entry, options);
+        const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
+        options.validateMutation?.();
+        options.signal?.throwIfAborted();
+        if (atInstall === before) return;
+        await fs4.rename(temporary, entry.target);
+        await syncDirectory(path6.dirname(entry.target));
+      });
     } finally {
-      await fs3.rm(temporary, { recursive: true, force: true });
+      await fs4.rm(temporary, { recursive: true, force: true });
     }
   }
   await syncMutationParents(
@@ -733,13 +874,13 @@ async function removeOwnedTarget(directory, entry, journal, options, restoringBe
       affected.replacementStarted = false;
     }
   }
-  await writeJson(path5.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
+  await writeJson(path6.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));
+  await fs4.rm(entry.target, { recursive: true, force: true });
+  await syncDirectory(path6.dirname(entry.target));
   return true;
 }
 function upgradeRemovalEvidence(journal) {
@@ -757,7 +898,7 @@ async function retireRemovalIntent(directory, journal, entries, options) {
     entry.removalPending = false;
     entry.replacementStarted = true;
   }
-  await writeJson(path5.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
+  await writeJson(path6.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
   options.validateMutation?.();
   options.signal?.throwIfAborted();
 }
@@ -772,8 +913,8 @@ async function retireRestorationIntent(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),
+  return path6.join(
+    path6.dirname(entry.target),
     `.pi-sync.json.${token}.${entry.kind === "file" ? "restore" : "restore-tree"}`
   );
 }
@@ -781,7 +922,7 @@ async function prepareRecoveryStage(directory, journal, entry, options) {
   const temporary = recoveryStagePath(directory, entry);
   if (!entry.recoveryStaged) {
     try {
-      await fs3.lstat(temporary);
+      await fs4.lstat(temporary);
       throw new Error("Unowned recovery staging path; preserve evidence for review.");
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
@@ -789,7 +930,7 @@ async function prepareRecoveryStage(directory, journal, entry, options) {
     options.validateMutation?.();
     options.signal?.throwIfAborted();
     entry.recoveryStaged = true;
-    await writeJson(path5.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
+    await writeJson(path6.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
     options.validateMutation?.();
     options.signal?.throwIfAborted();
   }
@@ -798,24 +939,24 @@ async function prepareRecoveryStage(directory, journal, entry, options) {
 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));
+  const value = await image(path6.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);
+    stat = await fs4.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.isSymbolicLink()) return `symlink:${await fs4.readlink(target)}`;
   if (stat.isFile()) {
-    const content = await fs3.readFile(target);
+    const content = await fs4.readFile(target);
     if (durable) {
-      const handle = await fs3.open(target, process.platform === "win32" ? "r+" : "r");
+      const handle = await fs4.open(target, process.platform === "win32" ? "r+" : "r");
       try {
         await handle.sync();
       } finally {
@@ -826,8 +967,8 @@ async function image(target, durable = false) {
   }
   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)]);
+  for (const name of (await fs4.readdir(target)).sort())
+    entries.push([name, await image(path6.join(target, name), durable)]);
   if (durable) await syncDirectory(target);
   return `directory:${createHash2("sha256").update(JSON.stringify(entries)).digest("hex")}`;
 }
@@ -836,22 +977,22 @@ async function ownedPostTree(target, files, requireComplete) {
   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))
+    for (let parent = path6.dirname(relative); parent !== "." && parent !== path6.dirname(parent); parent = path6.dirname(parent))
       prefixes.add(parent);
   }
   const seen = /* @__PURE__ */ new Set();
   async function visit(directory) {
     let stat;
     try {
-      stat = await fs3.lstat(directory);
+      stat = await fs4.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);
+    for (const name of await fs4.readdir(directory)) {
+      const child = path6.join(directory, name);
+      const relative = mergePathIdentity(path6.relative(target, child));
+      const stat2 = await fs4.lstat(child);
       if (stat2.isDirectory() && !stat2.isSymbolicLink()) {
         if (!prefixes.has(relative) || !await visit(child)) return false;
       } else {
@@ -868,23 +1009,23 @@ function validateJournal(directory, journal, sessionDir) {
     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)
+  const root = path6.resolve(agentDir());
+  if (typeof journal.root !== "string" || path6.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))
+  const trustedSessionRoot = sessionDir ? path6.resolve(sessionStorageRoot(root, sessionDir)) : path6.join(root, "sessions");
+  if (journal.sessionRoot !== void 0 && (typeof journal.sessionRoot !== "string" || !path6.isAbsolute(journal.sessionRoot) || path6.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))
+    if (!entry || typeof entry.target !== "string" || !path6.isAbsolute(entry.target) || path6.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));
+    assertWithinRoot(directory, path6.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"))
+    if (entry.afterTarget !== void 0 && (![5, 6, 7].includes(journal.version) || typeof entry.afterTarget !== "string" || !isCaseReplacement(root, entry.target, entry.afterTarget) || path6.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))))
@@ -898,29 +1039,29 @@ function validateJournal(directory, journal, sessionDir) {
     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)))
+      if (typeof file.relative !== "string" || typeof file.image !== "string" || !isStrictlyInside(entry.target, path6.resolve(entry.target, file.relative)))
         throw new Error("Invalid transaction subtree evidence.");
     }
   }
 }
 function transactionHasSessionTargets(journal) {
-  const root = path5.resolve(agentDir());
+  const root = path6.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))
+    (entry) => typeof entry?.target === "string" && (!isPathInside(root, entry.target) || isPathInside(path6.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);
+  return path6.relative(path6.resolve(root), path6.resolve(target)) !== "" && isPathInside(root, target);
 }
 function assertAllowedTarget(root, sessionRoot, target) {
-  const resolved = path5.resolve(target);
+  const resolved = path6.resolve(target);
   if (isStrictlyInside(root, resolved)) {
-    if (isDeniedPath(path5.relative(root, resolved))) throw new Error("Transaction targets denied private storage.");
+    if (isDeniedPath(path6.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)}`))
+    if (isDeniedPath(`sessions/${path6.relative(sessionRoot, resolved)}`))
       throw new Error("Transaction targets denied session storage.");
     assertWithinRoot(sessionRoot, resolved);
     return;
@@ -930,10 +1071,10 @@ function assertAllowedTarget(root, sessionRoot, target) {
 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.");
+  for (let parent = path6.dirname(target); boundary && mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path6.dirname(parent)) {
+    if (path6.dirname(parent) === parent) throw new Error("Transaction parent did not reach its owned boundary.");
     try {
-      const stat = await fs3.lstat(parent);
+      const stat = await fs4.lstat(parent);
       if (!stat.isDirectory() && !stat.isFile() || stat.isSymbolicLink())
         throw new Error("Unsafe transaction parent.");
     } catch (error) {
@@ -942,50 +1083,9 @@ async function assertSafeParents(root, sessionRoot, target) {
     }
   }
 }
-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"),
+    path6.join(directory, "journal.json"),
     { ...journal, version: journal.sessionRootTransition ? 7 : 6, completed: true },
     {
       maxBytes: 32 * 1024 * 1024
@@ -994,15 +1094,16 @@ async function completeTransaction(directory, journal) {
   await removeTransaction(directory);
 }
 async function removeTransaction(directory) {
-  await fs3.rm(directory, { recursive: true, force: true });
+  await fs4.rm(directory, { recursive: true, force: true });
   await syncDirectory(transactionRoot()).catch(() => {
   });
 }
 
 export {
   syncMutationParents,
+  assertCanonicalMutationTargets,
   applySnapshotTransaction,
   recoverSnapshotTransactionsOnStartup,
   recoverPendingSnapshotTransactions
 };
-//# sourceMappingURL=chunk-AAPAHANE.ts.map
+//# sourceMappingURL=chunk-7A35ZAVO.ts.map