@narumitw/pi-sync 0.51.1 → 0.52.1

package/src/snapshot/snapshot-types.ts

@@ -19,11 +19,16 @@ export interface Snapshot {
   syncSessions?: boolean;
   /** Portable, credential-free included-content intent. Absent on legacy snapshots. */
   selection?: SnapshotSelection;
+  localFields?: string[];
   files: SnapshotFile[];
 }
 
 export interface SnapshotOptions {
   signal?: AbortSignal;
+  /** Caller-owned session/generation guard, rechecked at file-mutation boundaries. */
+  validateMutation?: () => void;
+  /** Reviewed regular-file preimages; null means the path was absent. Checked under mutation queues. */
+  expectedFileHashes?: Readonly<Record<string, string | null>>;
   include?: string[];
   sessionDir?: string;
   /** Temporary internal projections while snapshot storage remains wire-compatible. */

package/src/state/json-file.ts

@@ -11,10 +11,37 @@ export async function readJsonIfExists<T>(filePath: string): Promise<T | undefin
   }
 }
 
-export async function writeJson(filePath: string, value: unknown) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
+export async function writeJson(filePath: string, value: unknown, options: { maxBytes?: number } = {}) {
+  const content = `${JSON.stringify(value, null, "\t")}\n`;
+  if (options.maxBytes !== undefined && Buffer.byteLength(content) > options.maxBytes)
+    throw new Error(
+      "Private state document exceeds its storage bound; preserve existing evidence and use reviewed recovery.",
+    );
+  await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
   const temp = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
-  await fs.writeFile(temp, `${JSON.stringify(value, null, "\t")}\n`, { mode: 0o600 });
-  if (process.platform !== "win32") await fs.chmod(temp, 0o600);
-  await fs.rename(temp, filePath);
+  try {
+    const handle = await fs.open(temp, "wx", 0o600);
+    try {
+      await handle.writeFile(content);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    if (process.platform !== "win32") await fs.chmod(temp, 0o600);
+    await fs.rename(temp, filePath);
+    await syncDirectory(path.dirname(filePath));
+  } finally {
+    await fs.rm(temp, { force: true });
+  }
+}
+
+/** POSIX rename/unlink durability; Windows does not expose directory fsync through Node. */
+export async function syncDirectory(directory: string) {
+  if (process.platform === "win32") return;
+  const handle = await fs.open(directory, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
 }

package/src/state/merge-baseline-store.ts

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { backendIdentityCoordinates } from "../backends/backend-identity.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import type { Snapshot, SnapshotFile } from "../snapshot/snapshot-types.js";
+import { collidingPaths, planFileMerge } from "../sync/file-merge-planner.js";
+import { parseSettingsDocument } from "../sync/json-document.js";
+import { validateSession } from "../sync/session-merge.js";
+import { isMergeTextPath, text } from "../sync/text-merge.js";
+import { syncDirectory, writeJson } from "./json-file.js";
+import type { SyncState } from "./state-types.js";
+import { statePathForConfig, syncStateFingerprint } from "./sync-state-store.js";
+
+interface MergeBaseline {
+  version: 1;
+  identity: string;
+  acceptedState: string;
+  files: SnapshotFile[];
+}
+const MAX_BYTES = 192 * 1024 * 1024;
+function eligible(file: SnapshotFile) {
+  try {
+    const bytes = Buffer.from(file.contentBase64, "base64");
+    if (file.path === "settings.json") parseSettingsDocument(bytes);
+    else if (isMergeTextPath(file.path)) text(bytes);
+    else if (file.path.startsWith("sessions/") && file.path.endsWith(".jsonl")) validateSession(bytes);
+    else return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function identity(config: AnySyncConfig) {
+  return JSON.stringify([
+    config.setupName,
+    backendIdentityCoordinates(config),
+    config.include,
+    config.localFields ?? [],
+  ]);
+}
+function directory(config: AnySyncConfig) {
+  return `${statePathForConfig(config)}.ancestors`;
+}
+async function checkDirectory(config: AnySyncConfig, create = false) {
+  const target = directory(config);
+  if (create) await fs.mkdir(target, { recursive: true, mode: 0o700 });
+  const stat = await fs.lstat(target);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (process.platform !== "win32" && (stat.mode & 0o077) !== 0))
+    throw new Error("Unsafe private ancestor directory; preserve evidence.");
+}
+function baselinePath(config: AnySyncConfig, state: SyncState) {
+  return path.join(directory(config), `${syncStateFingerprint(state)}.json`);
+}
+
+/** Stage before accepted state, retain its previous ancestor until journal retirement. Never bootstrap from current edits. */
+export async function stageMergeBaseline(
+  config: AnySyncConfig,
+  snapshot: Snapshot,
+  accepted: SyncState,
+  previous?: SyncState,
+) {
+  const collisions = collidingPaths(snapshot.files.map((file) => file.path));
+  const files = snapshot.files.filter((file) => {
+    return (
+      !collisions.has(file.path) &&
+      accepted.lastFileHashes[file.path] === file.sha256 &&
+      (file.path === "settings.json" || config.mergeContent) &&
+      eligible(file)
+    );
+  });
+  if (previous) {
+    const stagedPaths = new Set(files.map((file) => file.path));
+    let ancestors: SnapshotFile[] = [];
+    try {
+      ancestors = (await readMergeAncestors(config, previous)) ?? [];
+    } catch {
+      /* Keep unknown evidence; missing bytes are never invented. */
+    }
+    for (const ancestor of ancestors)
+      if (
+        !collisions.has(ancestor.path) &&
+        accepted.lastFileHashes[ancestor.path] === ancestor.sha256 &&
+        !stagedPaths.has(ancestor.path)
+      ) {
+        files.push(ancestor);
+        stagedPaths.add(ancestor.path);
+      }
+  }
+  const plan = planFileMerge({ baseline: {}, local: files, remote: [], selectionCompatible: true });
+  if (plan.kind !== "planned" || plan.conflicts.length)
+    throw new Error("Cannot stage unverified merge ancestor bytes.");
+  const record: MergeBaseline = {
+    version: 1,
+    identity: identity(config),
+    acceptedState: syncStateFingerprint(accepted),
+    files,
+  };
+  await checkDirectory(config, true);
+  await writeJson(baselinePath(config, accepted), record, { maxBytes: MAX_BYTES });
+}
+
+async function readBaselineRecord(
+  config: AnySyncConfig,
+  target: string,
+  acceptedState: string,
+  validate: () => void = () => {},
+): Promise<MergeBaseline> {
+  const stat = await fs.lstat(target);
+  validate();
+  if (!stat.isFile() || stat.size > MAX_BYTES || (process.platform !== "win32" && (stat.mode & 0o077) !== 0))
+    throw new Error("Unsafe cache.");
+  const record = JSON.parse(await fs.readFile(target, "utf8")) as MergeBaseline;
+  validate();
+  if (
+    record.version !== 1 ||
+    record.identity !== identity(config) ||
+    record.acceptedState !== acceptedState ||
+    !Array.isArray(record.files) ||
+    record.files.length > 16_384 ||
+    record.files.some((file) => !eligible(file))
+  )
+    throw new Error("Invalid cache identity.");
+  const plan = planFileMerge({ baseline: {}, local: record.files, remote: [], selectionCompatible: true });
+  if (plan.kind !== "planned" || plan.conflicts.length) throw new Error("Invalid cache bytes.");
+  return record;
+}
+
+export async function readMergeAncestors(config: AnySyncConfig, state: SyncState): Promise<SnapshotFile[] | undefined> {
+  let record: MergeBaseline;
+  try {
+    await checkDirectory(config);
+    record = await readBaselineRecord(config, baselinePath(config, state), syncStateFingerprint(state));
+    for (const file of record.files) {
+      if (
+        state.lastFileHashes[file.path] !== file.sha256 ||
+        createHash("sha256").update(Buffer.from(file.contentBase64, "base64")).digest("hex") !== file.sha256
+      )
+        throw new Error("Cache hash mismatch.");
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw new Error("Merge ancestor is invalid; preserve its private cache and review the conflict.");
+  }
+  return record.files;
+}
+export async function readMergeAncestor(config: AnySyncConfig, state: SyncState, filePath: string) {
+  const file = (await readMergeAncestors(config, state))?.find((file) => file.path === filePath);
+  return file ? Buffer.from(file.contentBase64, "base64") : undefined;
+}
+
+/** Caller must hold the sync operation lock and retire the commit journal before pruning. */
+export async function pruneMergeBaselines(config: AnySyncConfig, state: SyncState, validate: () => void) {
+  validate();
+  const keep = path.basename(baselinePath(config, state));
+  let names: string[];
+  try {
+    await checkDirectory(config);
+    validate();
+    names = await fs.readdir(directory(config));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  for (const name of names) {
+    validate();
+    if (name === keep || !/^[a-f0-9]{64}\.json$/u.test(name)) continue;
+    const target = path.join(directory(config), name);
+    try {
+      await readBaselineRecord(config, target, name.slice(0, -5), validate);
+    } catch {
+      validate();
+      continue; // Unknown/corrupted evidence is not an owned pruning candidate.
+    }
+    validate();
+    await fs.rm(target);
+    validate();
+  }
+  await syncDirectory(directory(config));
+  validate();
+}

package/src/state/mutation-directory-sync.ts

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { isPathInside } from "../paths.js";
+import { mergePathIdentity } from "../sync/file-merge-planner.js";
+import { syncDirectory } from "./json-file.js";
+
+/** Persist created ancestor names as well as the immediate rename/delete directory. */
+export async function syncMutationParents(
+  targets: readonly string[],
+  roots: readonly string[],
+  options: { signal?: AbortSignal; validateMutation?: () => void } = {},
+) {
+  const directories = new Set<string>();
+  for (const target of targets) {
+    const root = roots.map((root) => path.resolve(root)).find((root) => isPathInside(root, 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 as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+    }
+    options.signal?.throwIfAborted();
+    options.validateMutation?.();
+  }
+}

package/src/state/state-types.ts

@@ -6,6 +6,10 @@ export interface SyncState {
   lastRemoteEtag?: string;
   lastFileHashes: Record<string, string>;
   include?: string[];
+  localFields?: string[];
+  lastObservedSnapshot?: string;
+  lastObservedRevision?: string;
+  unresolved?: { paths: string[]; artifact: string }[];
   /** Legacy state fields are read only so v3 can detect and replace stale policy state. */
   syncFiles?: string[];
   syncSessions?: boolean;

package/src/state/sync-state-store.ts

@@ -39,8 +39,21 @@ export async function readStateForConfig(config: AnySyncConfig): Promise<SyncSta
   );
 }
 
-export async function writeStateForConfig(config: AnySyncConfig, state: SyncState) {
+export async function writeStateForConfig(
+  config: AnySyncConfig,
+  state: SyncState,
+  snapshot?: import("../snapshot/snapshot-types.js").Snapshot,
+  validate: () => void = () => {},
+) {
+  validate();
+  if (snapshot) {
+    const { stageMergeBaseline } = await import("./merge-baseline-store.js");
+    validate();
+    await stageMergeBaseline(config, snapshot, state);
+    validate();
+  }
   await writeJson(statePathForConfig(config), state);
+  validate();
 }
 
 export function statePathForConfig(config: AnySyncConfig) {

package/src/sync/automatic-sync.ts

@@ -5,7 +5,7 @@ import { loadConfig, loadPartialConfig } from "../settings/config.js";
 import { isMissingConfigError } from "../settings/config-errors.js";
 import { consumeLocalConfigMigrationNotice } from "../settings/config-file.js";
 import { readLocalConfigObject } from "../settings/settings-store.js";
-import { snapshotOptionsForContext } from "../snapshot/session-paths.js";
+import { sessionDirFromContext, snapshotOptionsForContext } from "../snapshot/session-paths.js";
 import { recoverSnapshotTransactionsOnStartup } from "../snapshot/snapshot-transaction.js";
 import { withLock } from "../state/lock.js";
 import { stateDirectoryMigrationNotice } from "../state/state-directory.js";
@@ -15,6 +15,7 @@ import { safeTerminalText } from "../ui/terminal-text.js";
 import { throwIfAborted } from "./signals.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,
@@ -32,7 +33,14 @@ export async function startSession(ctx: ExtensionContext, signal: AbortSignal) {
   if (stateNotice && ctx.hasUI) ctx.ui.notify(stateNotice, "warning");
   // Recovery can restore managed files: finish it before Pi accepts user edits.
   // Unlike remote inspection, it must never be detached behind startup.
-  await recoverSnapshotTransactionsOnStartup();
+  const validateMutation = captureMutationOwner(ctx, signal);
+  const currentFile = ctx.sessionManager.getSessionFile?.();
+  await recoverSnapshotTransactionsOnStartup({
+    signal,
+    sessionDir: sessionDirFromContext(ctx),
+    protectedTargets: currentFile ? [currentFile] : [],
+    validateMutation,
+  });
   throwIfAborted(signal);
   try {
     const settings = await readLocalConfigObject();
@@ -52,7 +60,7 @@ export async function startSession(ctx: ExtensionContext, signal: AbortSignal) {
     const config = await loadConfig();
     throwIfAborted(signal);
     configureSyncStatus(ctx, config.showStatus);
-    return config.automatic ? config : undefined;
+    return config.automatic || config.automaticTransfer ? config : undefined;
   } catch (error) {
     throwIfAborted(signal);
     if (!isMissingConfigError(error)) {

package/src/sync/conflict-artifact-ownership.ts

@@ -0,0 +1,63 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import { syncDirectory } from "../state/json-file.js";
+import { readStateForConfig, statePathForConfig } from "../state/sync-state-store.js";
+import {
+  type ConflictArtifact,
+  type CreatedConflictArtifact,
+  conflictArtifactFingerprint,
+  conflictDirectory,
+} from "./conflict-artifacts.js";
+import { readMergeJournal } from "./merge-journal.js";
+
+/** Attempt-owned cleanup only: unknown evidence remains the retention policy's responsibility. */
+export async function releaseConflictArtifacts(
+  config: AnySyncConfig,
+  statePath: string,
+  created: readonly CreatedConflictArtifact[],
+) {
+  if (!created.length || statePathForConfig(config) !== statePath) return;
+  try {
+    const state = await readStateForConfig(config);
+    if (statePathForConfig(config) !== statePath) return;
+    const journal = await readMergeJournal(config);
+    if (statePathForConfig(config) !== statePath) return;
+    const referenced = new Set([
+      ...(state.unresolved ?? []).map((group) => group.artifact),
+      ...(journal?.progress?.groups ?? []).map((group) => group.artifact),
+    ]);
+    for (const lease of created) {
+      if (referenced.has(lease.token) || lease.target !== path.join(conflictDirectory(config), `${lease.token}.json`))
+        continue;
+      try {
+        const stat = await fs.lstat(lease.target);
+        if (
+          !stat.isFile() ||
+          stat.nlink !== 1 ||
+          stat.dev !== lease.dev ||
+          stat.ino !== lease.ino ||
+          stat.size !== lease.size
+        )
+          continue;
+        const artifact = JSON.parse(await fs.readFile(lease.target, "utf8")) as ConflictArtifact;
+        if (conflictArtifactFingerprint(artifact) !== lease.fingerprint || statePathForConfig(config) !== statePath)
+          continue;
+        const latest = await fs.lstat(lease.target);
+        if (
+          latest.dev !== lease.dev ||
+          latest.ino !== lease.ino ||
+          latest.nlink !== 1 ||
+          statePathForConfig(config) !== statePath
+        )
+          continue;
+        await fs.unlink(lease.target);
+        await syncDirectory(path.dirname(lease.target));
+      } catch {
+        /* Missing, replaced or unreadable evidence is not ours to delete. */
+      }
+    }
+  } catch {
+    /* Invalid state/journal or unavailable storage cannot prove lack of references. */
+  }
+}

package/src/sync/conflict-artifacts.ts

@@ -0,0 +1,195 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import type { Snapshot, SnapshotFile } from "../snapshot/snapshot-types.js";
+import { syncDirectory, writeJson } from "../state/json-file.js";
+import type { SyncState } from "../state/state-types.js";
+import { statePathForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
+import { planFileMerge } from "./file-merge-planner.js";
+
+export { conflictGroups } from "./conflict-groups.js";
+
+import { mergeJournalIdentity } from "./merge-journal.js";
+export interface ConflictArtifact {
+  version: 1;
+  identity: string;
+  ancestors?: SnapshotFile[];
+  state: SyncState;
+  local: Snapshot;
+  remote: Snapshot;
+  groups: { paths: string[]; reasons: string[] }[];
+  observed: { snapshotId: string; revision: string };
+}
+const LIMIT = 192 * 1024 * 1024;
+export function conflictArtifactFingerprint(artifact: ConflictArtifact) {
+  return createHash("sha256").update(JSON.stringify(artifact)).digest("hex");
+}
+export function conflictDirectory(config: AnySyncConfig) {
+  return `${statePathForConfig(config)}.conflicts`;
+}
+async function directory(config: AnySyncConfig, create = false) {
+  const target = conflictDirectory(config);
+  if (create) await fs.mkdir(target, { recursive: true, mode: 0o700 });
+  const stat = await fs.lstat(target);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (process.platform !== "win32" && (stat.mode & 0o077) !== 0))
+    throw new Error("Unsafe private conflict directory.");
+  return target;
+}
+function tokenPath(config: AnySyncConfig, token: string) {
+  if (!/^[a-f0-9-]{36}$/u.test(token)) throw new Error("Invalid conflict token.");
+  return path.join(conflictDirectory(config), `${token}.json`);
+}
+export interface CreatedConflictArtifact {
+  token: string;
+  target: string;
+  dev: number;
+  ino: number;
+  size: number;
+  fingerprint: string;
+}
+export async function saveConflictArtifact(
+  config: AnySyncConfig,
+  backend: string,
+  artifact: Omit<ConflictArtifact, "version" | "identity">,
+  validate: () => void,
+  onCreated?: (created: CreatedConflictArtifact) => void,
+) {
+  validate();
+  const identity = mergeJournalIdentity(config, backend);
+  const local = Object.fromEntries(artifact.local.files.map((file) => [file.path, file.sha256]));
+  const remote = Object.fromEntries(artifact.remote.files.map((file) => [file.path, file.sha256]));
+  const fingerprint = createHash("sha256")
+    .update(
+      JSON.stringify([
+        identity,
+        artifact.groups.map((group) =>
+          group.paths.map((filePath) => [
+            filePath,
+            artifact.state.lastFileHashes[filePath] ?? null,
+            local[filePath] ?? null,
+            remote[filePath] ?? null,
+          ]),
+        ),
+      ]),
+    )
+    .digest("hex")
+    .slice(0, 32);
+  const token = `${fingerprint.slice(0, 8)}-${fingerprint.slice(8, 12)}-${fingerprint.slice(12, 16)}-${fingerprint.slice(16, 20)}-${fingerprint.slice(20)}`;
+  await directory(config, true);
+  validate();
+  const reuse = async () => {
+    const existing = await readConflictArtifact(config, backend, token);
+    validate();
+    const oldLocal = Object.fromEntries(existing.local.files.map((file) => [file.path, file.sha256]));
+    const oldRemote = Object.fromEntries(existing.remote.files.map((file) => [file.path, file.sha256]));
+    if (
+      JSON.stringify(existing.groups.map((group) => group.paths)) !==
+        JSON.stringify(artifact.groups.map((group) => group.paths)) ||
+      artifact.groups.some((group) =>
+        group.paths.some(
+          (filePath) =>
+            existing.state.lastFileHashes[filePath] !== artifact.state.lastFileHashes[filePath] ||
+            oldLocal[filePath] !== local[filePath] ||
+            oldRemote[filePath] !== remote[filePath],
+        ),
+      )
+    )
+      throw new Error("Conflict identity does not match retained immutable evidence.");
+    return token;
+  };
+  const target = tokenPath(config, token);
+  try {
+    await fs.lstat(target);
+    validate();
+    return await reuse();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  const temporary = `${target}.${randomUUID()}.pending`;
+  const candidate: ConflictArtifact = { version: 1, identity, ...artifact };
+  try {
+    await writeJson(temporary, candidate, { maxBytes: LIMIT });
+    validate();
+    const stat = await fs.lstat(temporary);
+    validate();
+    try {
+      // Publish immutable evidence without replacing a concurrent/pre-existing owner.
+      await fs.link(temporary, target);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      validate();
+      return await reuse();
+    }
+    // Register ownership before any cancellation or durability await can fail.
+    onCreated?.({
+      token,
+      target,
+      dev: stat.dev,
+      ino: stat.ino,
+      size: stat.size,
+      fingerprint: conflictArtifactFingerprint(candidate),
+    });
+    validate();
+    await syncDirectory(path.dirname(target));
+    validate();
+    await syncDirectory(path.dirname(conflictDirectory(config)));
+    validate();
+    return token;
+  } finally {
+    await fs.rm(temporary, { force: true });
+  }
+}
+export async function readConflictArtifact(config: AnySyncConfig, backend: string, token: string) {
+  try {
+    await directory(config);
+    const target = tokenPath(config, token);
+    const stat = await fs.lstat(target);
+    if (!stat.isFile() || stat.size > LIMIT || (process.platform !== "win32" && (stat.mode & 0o077) !== 0))
+      throw new Error("Unsafe conflict artifact.");
+    const artifact = JSON.parse(await fs.readFile(target, "utf8")) as ConflictArtifact;
+    if (
+      artifact.version !== 1 ||
+      artifact.identity !== mergeJournalIdentity(config, backend) ||
+      !Array.isArray(artifact.groups) ||
+      artifact.groups.length > 16_384 ||
+      artifact.groups.some(
+        (group) =>
+          !Array.isArray(group.paths) ||
+          !group.paths.length ||
+          group.paths.length > 16_384 ||
+          !Array.isArray(group.reasons),
+      )
+    )
+      throw new Error("Invalid conflict artifact.");
+    const plan = planFileMerge({
+      baseline: artifact.state.lastFileHashes,
+      local: artifact.local.files,
+      remote: artifact.remote.files,
+      selectionCompatible: true,
+    });
+    if (plan.kind !== "planned") throw new Error("Invalid conflict versions.");
+    const known = new Set(plan.decisions.map((item) => item.path));
+    if (artifact.groups.some((group) => group.paths.some((value) => !known.has(value))))
+      throw new Error("Invalid conflict paths.");
+    if (artifact.ancestors) {
+      if (
+        !Array.isArray(artifact.ancestors) ||
+        artifact.ancestors.length > 16_384 ||
+        artifact.ancestors.some((file) => artifact.state.lastFileHashes[file.path] !== file.sha256)
+      )
+        throw new Error("Invalid artifact ancestor.");
+      const basePlan = planFileMerge({
+        baseline: {},
+        local: artifact.ancestors,
+        remote: [],
+        selectionCompatible: true,
+      });
+      if (basePlan.kind !== "planned" || basePlan.conflicts.length) throw new Error("Invalid ancestor bytes.");
+    }
+    syncStateFingerprint(artifact.state);
+    return artifact;
+  } catch {
+    throw new Error("Cannot verify private conflict artifact; preserve evidence and review a fresh sync.");
+  }
+}

package/src/sync/conflict-groups.ts

@@ -0,0 +1,68 @@
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import { type FileMergePlan, mergePathIdentity } from "./file-merge-planner.js";
+
+/** Indexed connected closure; path relationships are identical to the conservative merge policy. */
+export function conflictGroups(plan: Extract<FileMergePlan, { kind: "planned" }>, config: AnySyncConfig) {
+  const paths = plan.decisions.map((item) => item.path);
+  const parents = paths.map((_, index) => index);
+  const ranks = paths.map(() => 0);
+  const find = (index: number): number => {
+    while (parents[index] !== index) {
+      parents[index] = parents[parents[index] ?? index] ?? index;
+      index = parents[index] ?? index;
+    }
+    return index;
+  };
+  const join = (left: number, right: number) => {
+    let a = find(left);
+    let b = find(right);
+    if (a === b) return;
+    if ((ranks[a] ?? 0) < (ranks[b] ?? 0)) [a, b] = [b, a];
+    parents[b] = a;
+    if (ranks[a] === ranks[b]) ranks[a] = (ranks[a] ?? 0) + 1;
+  };
+  const identities = paths.map(mergePathIdentity);
+  const byIdentity = new Map<string, number>();
+  const byPath = new Map(paths.map((value, index) => [value, index]));
+  identities.forEach((value, index) => {
+    const previous = byIdentity.get(value);
+    if (previous !== undefined) join(index, previous);
+    else byIdentity.set(value, index);
+  });
+  const includes = new Set(
+    config.include
+      .filter((value) => !["settings.json", "AGENTS.md", "sessions"].includes(value))
+      .map(mergePathIdentity),
+  );
+  const buckets = new Map<string, number>();
+  const bucket = (key: string, index: number) => {
+    const previous = buckets.get(key);
+    if (previous === undefined) buckets.set(key, index);
+    else join(index, previous);
+  };
+  paths.forEach((value, index) => {
+    const root = value.split("/")[0] ?? "";
+    if (["extensions", "themes", "skills", "prompts"].includes(root)) bucket(`resource:${root}`, index);
+    const segments = (identities[index] ?? "").split("/");
+    let ancestor = "";
+    for (let length = 0; length < segments.length - 1; length++) {
+      ancestor = ancestor ? `${ancestor}/${segments[length]}` : (segments[length] ?? "");
+      const parent = byIdentity.get(ancestor);
+      if (parent !== undefined) join(index, parent);
+      if (includes.has(ancestor)) bucket(`include:${ancestor}`, index);
+    }
+  });
+  const groups = new Map<number, { paths: string[]; reasons: string[] }>();
+  for (const conflict of plan.conflicts) {
+    const index = byPath.get(conflict.path);
+    if (index === undefined) throw new Error("Conflict is missing from managed decisions.");
+    const key = find(index);
+    const group = groups.get(key) ?? { paths: [], reasons: [] };
+    if (!group.reasons.includes(conflict.reason)) group.reasons.push(conflict.reason);
+    groups.set(key, group);
+  }
+  paths.forEach((value, index) => {
+    groups.get(find(index))?.paths.push(value);
+  });
+  return [...groups.values()].map((group) => ({ ...group, paths: group.paths.sort() }));
+}