@narumitw/pi-sync 0.57.9 → 0.57.11

package/src/snapshot/snapshot-mutation-queues.ts

@@ -0,0 +1,142 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+
+type MutationGuards = { signal?: AbortSignal; validateMutation?: () => void };
+
+function assertCurrent(options: MutationGuards) {
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+}
+
+function isMissing(error: unknown) {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
+async function targetMissing(target: string, options: MutationGuards) {
+  assertCurrent(options);
+  try {
+    await fs.lstat(target);
+    assertCurrent(options);
+    return false;
+  } catch (error) {
+    assertCurrent(options);
+    if (!isMissing(error)) throw error;
+    return true;
+  }
+}
+
+async function queueKey(target: string, options: MutationGuards) {
+  assertCurrent(options);
+  try {
+    const key = await fs.realpath(target);
+    assertCurrent(options);
+    return key;
+  } catch (error) {
+    assertCurrent(options);
+    if (!isMissing(error)) throw error;
+    return path.resolve(target);
+  }
+}
+
+/** Resolve missing descendants too, including descendants of a file scheduled for removal. */
+async function assertCanonicalParent(target: string, options: MutationGuards) {
+  const parent = path.dirname(path.resolve(target));
+  const suffix: string[] = [];
+  for (let current = parent; ; current = path.dirname(current)) {
+    assertCurrent(options);
+    let canonical: string;
+    try {
+      canonical = await fs.realpath(current);
+    } catch (error) {
+      assertCurrent(options);
+      if (!isMissing(error) || path.dirname(current) === current) throw error;
+      suffix.unshift(path.basename(current));
+      continue;
+    }
+    assertCurrent(options);
+    // Pi queues existing paths by realpath and missing paths by lexical resolve.
+    // Its public API cannot reserve a missing alias key while that alias exists,
+    // or report a key that changes during registration. Refuse aliased parents
+    // before mutation rather than risk a non-reentrant queue or overwrite a writer.
+    if (path.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;
+  }
+}
+
+export async function assertCanonicalMutationTargets(targets: readonly string[], options: MutationGuards) {
+  for (const target of targets) await assertCanonicalParent(target, options);
+}
+
+export async function withTargetQueues<T>(
+  targets: readonly string[],
+  options: MutationGuards,
+  action: (heldKeys: ReadonlySet<string>) => Promise<T>,
+): Promise<T> {
+  // Check the whole group before reserving any key or changing live files.
+  await assertCanonicalMutationTargets(targets, options);
+  const keys = new Set<string>();
+  const missing = new Set<string>();
+  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: number): Promise<T> {
+    assertCurrent(options);
+    const key = ordered[index];
+    // Pass the resolved key, not an alias whose lookup can select a different key.
+    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);
+}
+
+export async function withMissingTargetQueues<T>(
+  targets: readonly string[],
+  heldKeys: ReadonlySet<string>,
+  options: MutationGuards,
+  action: (heldKeys: ReadonlySet<string>) => Promise<T>,
+): Promise<T> {
+  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.");
+    }
+  };
+  // Canonical parents make each missing key equal to the intended installed key.
+  // Retain the old physical key and exclude it from these non-reentrant queues.
+  const keys = unique
+    .map((target) => path.resolve(target))
+    .filter((key) => !heldKeys.has(key))
+    .sort();
+  await requireAbsent();
+  const combined = new Set([...heldKeys, ...keys]);
+  async function acquire(index: number): Promise<T> {
+    assertCurrent(options);
+    const key = keys[index];
+    if (key) return withFileMutationQueue(key, () => acquire(index + 1));
+    // A writer registered in the removal gap must finish before this check.
+    // Even recognizable pre/postimages belong to that writer, not this transaction.
+    await requireAbsent();
+    assertCurrent(options);
+    return action(combined);
+  }
+  return acquire(0);
+}

package/src/snapshot/snapshot-transaction-directory.ts

@@ -0,0 +1,16 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stateDir } from "../state/state-directory.js";
+
+export function transactionRoot() {
+  return path.join(stateDir(), "transactions");
+}
+
+export async function pendingTransactionEntries() {
+  try {
+    return await fs.readdir(transactionRoot(), { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}

package/src/snapshot/snapshot-transaction.ts

@@ -2,7 +2,6 @@ import { createHash, randomUUID } from "node:crypto";
 import type { Stats } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { assertWithinRoot, isDeniedPath, isPathInside } from "../paths.js";
 import { syncDirectory, writeJson } from "../state/json-file.js";
 import { withLock } from "../state/lock.js";
@@ -11,6 +10,7 @@ import { stateDir } from "../state/state-directory.js";
 import { mergePathIdentity } from "../sync/file-merge-planner.js";
 import { agentDir, configuredSessionDir } from "./session-paths.js";
 import { caseReplacementSpelling, coalesceCaseReplacements, isCaseReplacement } from "./snapshot-case-replacement.js";
+import { withMissingTargetQueues, withTargetQueues } from "./snapshot-mutation-queues.js";
 import { sessionStorageRoot } from "./snapshot-paths.js";
 import {
   prepareSessionRootTransition,
@@ -18,6 +18,7 @@ import {
   type SessionRootTransition,
   validateSessionRootTransition,
 } from "./snapshot-root-transition.js";
+import { pendingTransactionEntries, transactionRoot } from "./snapshot-transaction-directory.js";
 import { fileImage, indexTransactionPlan } from "./snapshot-transaction-plan.js";
 import type { SnapshotApplyPlan } from "./snapshot-types.js";
 
@@ -68,7 +69,7 @@ export async function applySnapshotTransaction(plan: SnapshotApplyPlan, options:
   const targets = [...new Set([...coalesced.plan.deletes, ...coalesced.plan.writes.map((item) => item.target)])].sort();
   if (targets.length > 16_384)
     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) =>
@@ -133,6 +134,10 @@ export async function applySnapshotTransaction(plan: SnapshotApplyPlan, options:
         ...(entry.afterTarget ? [[entry.afterTarget, entry] as const] : []),
       ]),
     );
+    // A released additional key cannot authorize rollback, even for recognized raced bytes.
+    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();
@@ -141,75 +146,81 @@ export async function applySnapshotTransaction(plan: SnapshotApplyPlan, options:
         await removeOwnedTarget(transaction.directory, entry, transaction.journal, options);
         await syncDirectory(path.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,
-        );
-        // Only this uninterrupted call knows which deleted writes have not attempted installation yet.
-        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 fs.mkdir(path.dirname(item.target), { recursive: true });
-          options.validateMutation?.();
-          options.signal?.throwIfAborted();
-          const temp = path.join(path.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);
-          try {
-            let mode = 0o600;
-            try {
-              const stat = await fs.lstat(item.target);
-              if (stat.isFile()) mode = stat.mode & 0o777;
-            } catch (error) {
-              if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-            }
-            const handle = await fs.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,
+          );
+          // Only this uninterrupted call knows which deleted writes have not attempted installation yet.
+          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 fs.mkdir(path.dirname(item.target), { recursive: true });
             options.validateMutation?.();
-            await fs.rename(temp, item.target);
-            await syncDirectory(path.dirname(item.target));
-          } finally {
-            await fs.rm(temp, { force: true });
+            options.signal?.throwIfAborted();
+            const temp = path.join(path.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);
+            try {
+              let mode = 0o600;
+              try {
+                const stat = await fs.lstat(item.target);
+                if (stat.isFile()) mode = stat.mode & 0o777;
+              } catch (error) {
+                if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+              }
+              const handle = await fs.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 fs.rename(temp, item.target);
+              await syncDirectory(path.dirname(item.target));
+            } finally {
+              await fs.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) {
       // Aborted owners cannot roll back files after another session has replaced them.
       if (options.signal?.aborted)
         throw new Error("Snapshot apply cancelled; guarded transaction evidence retained for review.");
-      // Additional spelling queues have been released: do not start a case rollback
-      // under only the original key. Startup recovery reserves its own destination key.
-      if (coalesced.replacements.size)
-        throw new Error("Case replacement apply failed; guarded transaction evidence retained for review.", {
+      // Additional queues have been released. Recovery must reserve missing keys afresh.
+      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],
@@ -284,21 +295,12 @@ export async function recoverPendingSnapshotTransactions(options: TransactionOpt
       await removeTransaction(directory);
       continue;
     }
-    await withTargetQueues(journal.entries.map((entry) => entry.target).sort(), () =>
-      restoreTransaction(directory, journal, { ...options, sessionDir }),
+    await withTargetQueues(journal.entries.map((entry) => entry.target).sort(), options, (heldKeys) =>
+      restoreTransaction(directory, journal, { ...options, sessionDir }, heldKeys),
     );
   }
 }
 
-async function pendingTransactionEntries() {
-  try {
-    return await fs.readdir(transactionRoot(), { withFileTypes: true });
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
-    throw error;
-  }
-}
-
 async function prepareTransaction(
   plan: SnapshotApplyPlan,
   targets: string[],
@@ -396,7 +398,36 @@ async function prepareTransaction(
   return { directory, journal, deletes: indexed.deletes, deletedWrites: indexed.deletedWrites };
 }
 
-async function restoreTransaction(directory: string, journal: TransactionJournal, options: TransactionOptions) {
+async function restoreTransaction(
+  directory: string,
+  journal: TransactionJournal,
+  options: TransactionOptions,
+  heldKeys: ReadonlySet<string>,
+) {
+  validateJournal(directory, journal, options.sessionDir);
+  const missingSpellings: string[] = [];
+  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 === undefined) missingSpellings.push(entry.target, entry.afterTarget);
+  }
+  // Reserve an interrupted removal's other spelling before staging or image checks:
+  // recognizable bytes installed by a writer in that gap are not our postimage.
+  return withMissingTargetQueues(missingSpellings, heldKeys, options, (reservedKeys) =>
+    restoreQueuedTransaction(directory, journal, options, reservedKeys),
+  );
+}
+
+async function restoreQueuedTransaction(
+  directory: string,
+  journal: TransactionJournal,
+  options: TransactionOptions,
+  heldKeys: ReadonlySet<string>,
+) {
   validateJournal(directory, journal, options.sessionDir);
   options.validateMutation?.();
   options.signal?.throwIfAborted();
@@ -461,8 +492,13 @@ async function restoreTransaction(directory: string, journal: TransactionJournal
           !(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);
@@ -509,17 +545,19 @@ async function restoreTransaction(directory: string, journal: TransactionJournal
       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 fs.rename(temporary, entry.target);
-      await syncDirectory(path.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 fs.rename(temporary, entry.target);
+        await syncDirectory(path.dirname(entry.target));
+      });
     } finally {
       await fs.rm(temporary, { recursive: true, force: true });
     }
@@ -875,55 +913,6 @@ async function assertSafeParents(root: string, sessionRoot: string | undefined,
     }
   }
 }
-async function withTargetQueues<T>(targets: string[], action: () => Promise<T>) {
-  const keys = new Set<string>();
-  for (const target of targets) {
-    let key = path.resolve(target);
-    try {
-      key = await fs.realpath(target);
-    } catch (error) {
-      const code = (error as NodeJS.ErrnoException).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: number): Promise<T> {
-    const target = targets[index];
-    return target ? withFileMutationQueue(target, () => acquire(index + 1)) : action();
-  }
-  return acquire(0);
-}
-async function withCaseDestinationQueues<T>(
-  spellings: readonly (readonly [string, string])[],
-  options: TransactionOptions,
-  action: () => Promise<T>,
-): Promise<T> {
-  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 !== undefined)
-        throw new Error("Case replacement changed before destination queue reservation; evidence retained.");
-    }
-  };
-  // Existing aliases share one non-reentrant realpath queue. Only after removal can
-  // we reserve the distinct missing spelling while retaining the original queue.
-  // Pi writers that registered in the gap finish before this callback; refuse their
-  // bytes, including recognizable pre/postimages, rather than treating them as ours.
-  await requireAbsent();
-  return withTargetQueues(
-    spellings.map(([, after]) => after),
-    async () => {
-      await requireAbsent();
-      return action();
-    },
-  );
-}
 async function completeTransaction(directory: string, journal: TransactionJournal) {
   // Publish completion before deleting any backup. A surviving journal after power loss
   // may only retry cleanup, never roll back already accepted files.
@@ -943,6 +932,3 @@ async function removeTransaction(directory: string) {
   // was established before cleanup; a surviving completed journal allows only cleanup.
   await syncDirectory(transactionRoot()).catch(() => {});
 }
-function transactionRoot() {
-  return path.join(stateDir(), "transactions");
-}

package/src/sync/automatic-sync.ts

@@ -7,17 +7,17 @@ import { consumeLocalConfigMigrationNotice } from "../settings/config-file.js";
 import { readLocalConfigObject } from "../settings/settings-store.js";
 import type { AnySyncConfig } from "../settings/settings-types.js";
 import { sessionDirFromContext, snapshotOptionsForContext } from "../snapshot/session-paths.js";
-import { recoverSnapshotTransactionsOnStartup } from "../snapshot/snapshot-transaction.js";
+import { pendingTransactionEntries } from "../snapshot/snapshot-transaction-directory.js";
 import { withLock } from "../state/lock.js";
 import { stateDirectoryMigrationNotice } from "../state/state-directory.js";
 import { ensureStateDir, readStateForConfig } from "../state/sync-state-store.js";
 import { configureSyncStatus, setSyncStatus } from "../ui/sync-status.js";
 import { safeTerminalText } from "../ui/terminal-text.js";
+import { captureMutationOwner } from "./mutation-owner.js";
 import { throwIfAborted } from "./signals.js";
 import { createStartupTimings, type StartupTimingPublisher } from "./startup-timings.js";
 import { errorMessage } from "./sync-errors.js";
 import type { SyncLoaders } from "./sync-loaders.js";
-import { captureMutationOwner } from "./sync-local.js";
 
 const AUTO_SYNC_OPTIONS: CommandOptions = {
   yes: true,
@@ -45,14 +45,20 @@ export async function startSession(
     // Unlike remote inspection, it must never be detached behind startup.
     const validateMutation = captureMutationOwner(ctx, signal);
     const currentFile = ctx.sessionManager.getSessionFile?.();
-    await timings.measure("transaction recovery", () =>
-      recoverSnapshotTransactionsOnStartup({
+    await timings.measure("transaction recovery", async () => {
+      const pending = await pendingTransactionEntries();
+      validateMutation();
+      if (!pending.some((entry) => entry.isDirectory())) return;
+      // Normal startup needs only the directory probe, not the recovery/snapshot graph.
+      const { recoverSnapshotTransactionsOnStartup } = await import("../snapshot/snapshot-transaction.js");
+      validateMutation();
+      await recoverSnapshotTransactionsOnStartup({
         signal,
         sessionDir: sessionDirFromContext(ctx),
         protectedTargets: currentFile ? [currentFile] : [],
         validateMutation,
-      }),
-    );
+      });
+    });
     throwIfAborted(signal);
     try {
       const settings = await timings.measure("settings read", () => readLocalConfigObject());

package/src/sync/local-field-policy.ts

@@ -0,0 +1,29 @@
+/** Initial rules select whole root fields of the global settings.json only. */
+export function normalizeLocalFields(value: unknown): string[] {
+  if (value === undefined) return [];
+  if (
+    !Array.isArray(value) ||
+    value.length > 128 ||
+    value.some(
+      (field) =>
+        typeof field !== "string" ||
+        !field ||
+        field.length > 128 ||
+        /[\p{Cc}\p{Cf}\p{Cs}]/u.test(field) ||
+        ["__proto__", "constructor", "prototype"].includes(field),
+    )
+  )
+    throw new Error("localFields must be at most 128 safe settings.json root field names.");
+  if (new Set(value).size !== value.length) throw new Error("Duplicate localFields rule.");
+  for (const [first, second] of [
+    ["defaultProvider", "defaultModel"],
+    ["skills", "enableSkillCommands"],
+    ["queueMode", "steeringMode"],
+    ["websockets", "transport"],
+    ["enableAnalytics", "trackingId"],
+  ]) {
+    if (value.includes(first) !== value.includes(second))
+      throw new Error("Coupled settings fields must be excluded together.");
+  }
+  return [...value].sort();
+}

package/src/sync/local-fields.ts

@@ -8,36 +8,10 @@ import {
   parseSettingsDocument,
   renderSettingsMembers,
 } from "./json-document.js";
+import { normalizeLocalFields } from "./local-field-policy.js";
+
+export { normalizeLocalFields } from "./local-field-policy.js";
 
-/** Initial rules select whole root fields of the global settings.json only. */
-export function normalizeLocalFields(value: unknown): string[] {
-  if (value === undefined) return [];
-  if (
-    !Array.isArray(value) ||
-    value.length > 128 ||
-    value.some(
-      (field) =>
-        typeof field !== "string" ||
-        !field ||
-        field.length > 128 ||
-        /[\p{Cc}\p{Cf}\p{Cs}]/u.test(field) ||
-        ["__proto__", "constructor", "prototype"].includes(field),
-    )
-  )
-    throw new Error("localFields must be at most 128 safe settings.json root field names.");
-  if (new Set(value).size !== value.length) throw new Error("Duplicate localFields rule.");
-  for (const [first, second] of [
-    ["defaultProvider", "defaultModel"],
-    ["skills", "enableSkillCommands"],
-    ["queueMode", "steeringMode"],
-    ["websockets", "transport"],
-    ["enableAnalytics", "trackingId"],
-  ]) {
-    if (value.includes(first) !== value.includes(second))
-      throw new Error("Coupled settings fields must be excluded together.");
-  }
-  return [...value].sort();
-}
 /** Shared transport contract: older snapshots cannot carry portable policy metadata. */
 export function validateSnapshotFieldPolicy(snapshot: Pick<Snapshot, "version" | "localFields">) {
   if (snapshot.version !== 1 && snapshot.version !== 2 && snapshot.version !== 3)

package/src/sync/merge-apply.ts

@@ -5,6 +5,7 @@ import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { agentDir } from "../snapshot/session-paths.js";
 import { createSnapshot, snapshotTarget } from "../snapshot/snapshot.js";
 import { preflightSnapshotApply, preflightSnapshotMutations } from "../snapshot/snapshot-apply.js";
+import { assertCanonicalMutationTargets } from "../snapshot/snapshot-mutation-queues.js";
 import { sessionStorageRoot } from "../snapshot/snapshot-paths.js";
 import type { Snapshot, SnapshotOptions } from "../snapshot/snapshot-types.js";
 import { syncDirectory } from "../state/json-file.js";
@@ -34,6 +35,10 @@ export async function preflightMergedTargets(
   for (const relative of paths) {
     if (changed.has(relative)) await assertFilesystemTarget(root, relative, options, removedTargets, beforeHashes);
   }
+  await assertCanonicalMutationTargets(
+    [...changed].map((relative) => snapshotTarget(root, relative, options.sessionDir)),
+    options,
+  );
 }
 
 function replacementPaths(removed: Set<string>, afterHashes: Readonly<Record<string, string>>) {
@@ -244,6 +249,7 @@ export async function applyMergedSnapshot(
     protectedTarget,
     new Set(Object.keys(afterHashes)),
   );
+  await assertCanonicalMutationTargets(targets, options);
   // Existing case aliases share Pi's non-reentrant realpath queue. Reserve the
   // missing destination separately only after deleting its reviewed preimage.
   const targetsByQueue = new Map<string, string[]>();