@narumitw/pi-sync 0.25.0 → 0.28.0

package/src/file-selection.ts

@@ -0,0 +1,192 @@
+import fs from "node:fs/promises";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { Container, type SettingItem, SettingsList, Text } from "@earendil-works/pi-tui";
+import {
+	agentDir,
+	isExplicitlyEnabled,
+	loadPartialConfig,
+	localConfigPath,
+	updateLocalConfig,
+} from "./config.js";
+import {
+	DEFAULT_SYNC_FILES,
+	isSafeExtraFileName,
+	normalizeExtraFiles,
+	normalizeSyncFiles,
+} from "./sync-policy.js";
+
+const INCLUDED = "included";
+const EXCLUDED = "excluded";
+const BUILT_IN_PREFIX = "builtin:";
+const EXTRA_PREFIX = "extra:";
+const SESSIONS_ID = "sessions";
+
+export async function showFileSelection(ctx: ExtensionCommandContext) {
+	const partial = await loadPartialConfig();
+	const selectedBuiltIns = new Set(normalizeSyncFiles(partial.syncFiles));
+	const selectedExtras = new Set(normalizeExtraFiles(partial.extraFiles));
+	const sessionEnvironmentOverride = Object.hasOwn(process.env, "PI_SYNC_SESSIONS");
+	const sessionsIncluded = isExplicitlyEnabled(partial.syncSessions);
+	const extraCandidates = await listExtraFileCandidates(selectedExtras);
+
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(
+			[
+				"pi-sync selected files:",
+				`built-ins: ${[...selectedBuiltIns].join(", ") || "none"}`,
+				`sessions: ${sessionsIncluded ? "included" : "excluded"}${sessionEnvironmentOverride ? " (PI_SYNC_SESSIONS)" : ""}`,
+				`extra files: ${[...selectedExtras].map(safeTerminalText).join(", ") || "none"}`,
+				`Edit syncFiles, syncSessions, and extraFiles in ${safeTerminalText(localConfigPath())}.`,
+			].join("\n"),
+			"info",
+		);
+		return;
+	}
+
+	const items: SettingItem[] = [
+		...DEFAULT_SYNC_FILES.map((fileName) => ({
+			id: `${BUILT_IN_PREFIX}${fileName}`,
+			label: fileName,
+			description: fileName.includes(".")
+				? `Sync the top-level ${fileName} file when present.`
+				: `Recursively sync every safe file under ${fileName}/.`,
+			currentValue: selectedBuiltIns.has(fileName) ? INCLUDED : EXCLUDED,
+			values: [INCLUDED, EXCLUDED],
+		})),
+		{
+			id: SESSIONS_ID,
+			label: "sessions",
+			description: sessionEnvironmentOverride
+				? "Read-only here because PI_SYNC_SESSIONS overrides the local setting. Session JSONL may contain prompts, tool output, paths, images, and secrets."
+				: "Session JSONL may contain prompts, tool output, paths, images, and secrets. Sync only to storage you trust.",
+			currentValue: sessionEnvironmentOverride
+				? `${sessionsIncluded ? INCLUDED : EXCLUDED} (environment)`
+				: sessionsIncluded
+					? INCLUDED
+					: EXCLUDED,
+			...(sessionEnvironmentOverride ? {} : { values: [INCLUDED, EXCLUDED] }),
+		},
+		...extraCandidates.map((fileName) => ({
+			id: `${EXTRA_PREFIX}${fileName}`,
+			label: safeTerminalText(fileName),
+			description:
+				"Additional safe top-level file. It may be absent locally and pulled from another machine.",
+			currentValue: selectedExtras.has(fileName) ? INCLUDED : EXCLUDED,
+			values: [INCLUDED, EXCLUDED],
+		})),
+	];
+
+	let saveQueue = Promise.resolve();
+	let nextOwner = 0;
+	const owners = new Map<string, number>();
+	let closed = false;
+
+	await ctx.ui.custom((tui, theme, _keybindings, done) => {
+		const container = new Container();
+		const title = new Text("", 1, 0);
+		const hint = new Text("", 1, 0);
+		const updateChrome = () => {
+			title.setText(theme.fg("accent", theme.bold("pi-sync Files")));
+			hint.setText(
+				theme.fg("dim", "Changes save immediately and apply to the next manual or automatic sync."),
+			);
+		};
+		updateChrome();
+		container.addChild(title);
+
+		let settingsList: SettingsList;
+		const queueChange = (id: string, newValue: string) => {
+			const previousValue = newValue === INCLUDED ? EXCLUDED : INCLUDED;
+			const owner = ++nextOwner;
+			owners.set(id, owner);
+			const save = async () => {
+				try {
+					await persistSelectionChange(id, newValue === INCLUDED);
+				} catch (error) {
+					if (owners.get(id) === owner && !closed) {
+						settingsList.updateValue(id, previousValue);
+						tui.requestRender();
+					}
+					ctx.ui.notify(`Could not save pi-sync file selection: ${errorMessage(error)}`, "error");
+				}
+			};
+			saveQueue = saveQueue.then(save, save);
+		};
+
+		settingsList = new SettingsList(
+			items,
+			Math.min(items.length + 2, 15),
+			getSettingsListTheme(),
+			queueChange,
+			() => done(undefined),
+			{ enableSearch: true },
+		);
+		container.addChild(settingsList);
+		container.addChild(hint);
+
+		return {
+			render(width: number) {
+				return container.render(width);
+			},
+			invalidate() {
+				updateChrome();
+				container.invalidate();
+			},
+			handleInput(data: string) {
+				settingsList.handleInput(data);
+				tui.requestRender();
+			},
+		};
+	});
+	closed = true;
+	await saveQueue;
+}
+
+async function listExtraFileCandidates(configured: Set<string>) {
+	const candidates = new Map([...configured].map((fileName) => [fileName.toLowerCase(), fileName]));
+	try {
+		for (const entry of await fs.readdir(agentDir(), { withFileTypes: true })) {
+			if (!entry.isFile() || !isSafeExtraFileName(entry.name)) continue;
+			if (!candidates.has(entry.name.toLowerCase())) {
+				candidates.set(entry.name.toLowerCase(), entry.name);
+			}
+		}
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	return [...candidates.values()].sort((left, right) => left.localeCompare(right));
+}
+
+async function persistSelectionChange(id: string, included: boolean) {
+	await updateLocalConfig((current) => {
+		if (id.startsWith(BUILT_IN_PREFIX)) {
+			const fileName = id.slice(BUILT_IN_PREFIX.length);
+			const selected = new Set(normalizeSyncFiles(current.syncFiles));
+			if (included) selected.add(fileName as (typeof DEFAULT_SYNC_FILES)[number]);
+			else selected.delete(fileName as (typeof DEFAULT_SYNC_FILES)[number]);
+			return {
+				...current,
+				syncFiles: DEFAULT_SYNC_FILES.filter((candidate) => selected.has(candidate)),
+			};
+		}
+		if (id.startsWith(EXTRA_PREFIX)) {
+			const fileName = id.slice(EXTRA_PREFIX.length);
+			const selected = new Set(normalizeExtraFiles(current.extraFiles));
+			if (included) selected.add(fileName);
+			else selected.delete(fileName);
+			return { ...current, extraFiles: [...selected] };
+		}
+		if (id === SESSIONS_ID) return { ...current, syncSessions: included };
+		throw new Error(`Unknown file selection: ${id}`);
+	});
+}
+
+function safeTerminalText(value: string) {
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: Escape untrusted terminal controls.
+	return value.replace(/[\u0000-\u001f\u007f-\u009f]/gu, "?");
+}
+
+function errorMessage(error: unknown) {
+	return safeTerminalText(error instanceof Error ? error.message : String(error));
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./sync.js";

package/src/lock.ts

@@ -82,7 +82,7 @@ export async function withLock<T>(command: string, fn: () => Promise<T>): Promis
 		const inspection = await inspectLock();
 		if (inspection.status === "valid" && isStaleLock(inspection.lock)) {
 			throw new Error(
-				`pi-sync lock is stale (pid ${inspection.lock.pid}). Run /pisync unlock --stale, then retry.`,
+				`pi-sync lock is stale (pid ${inspection.lock.pid}). Run /sync unlock --stale, then retry.`,
 			);
 		}
 		if (inspection.status === "valid") {
@@ -92,7 +92,7 @@ export async function withLock<T>(command: string, fn: () => Promise<T>): Promis
 		}
 		if (inspection.status === "unreadable") {
 			throw new Error(
-				"pi-sync lock metadata is unreadable. Run /pisync unlock --stale after verifying no sync is running.",
+				"pi-sync lock metadata is unreadable. Run /sync unlock --stale after verifying no sync is running.",
 			);
 		}
 
@@ -208,7 +208,7 @@ async function unlockGuarded(ctx: ExtensionCommandContext, options: CommandOptio
 	if (inspection.status === "unreadable") {
 		if (!options.stale) {
 			ctx.ui.notify(
-				"Pi-sync lock metadata is unreadable. Use /pisync unlock --stale only after verifying no sync is running.",
+				"Pi-sync lock metadata is unreadable. Use /sync unlock --stale only after verifying no sync is running.",
 				"warning",
 			);
 			return;

package/src/snapshot-apply.ts

@@ -3,7 +3,14 @@ import type { Dirent } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { agentDir } from "./config.js";
-import { assertWithinRoot, isDeniedPath, isPathInside, parentPaths, safeJoin, toPosix } from "./paths.js";
+import {
+	assertWithinRoot,
+	isDeniedPath,
+	isPathInside,
+	parentPaths,
+	safeJoin,
+	toPosix,
+} from "./paths.js";
 import {
 	createSnapshot,
 	isSessionFilePath,
@@ -25,11 +32,12 @@ function fileHashMap(snapshot: Snapshot) {
 export async function applySnapshot(
 	snapshot: Snapshot,
 	protectedRelativePaths = new Set<string>(),
-	options: Pick<SnapshotOptions, "sessionDir" | "extraFiles"> = {},
+	options: Pick<SnapshotOptions, "syncFiles" | "sessionDir" | "extraFiles"> = {},
 ) {
 	const root = agentDir();
 	const { sessionDir } = options;
 	const current = await createSnapshot(snapshot.profile, {
+		syncFiles: options.syncFiles,
 		syncSessions: snapshotIncludesSessions(snapshot),
 		sessionDir,
 		extraFiles: options.extraFiles,
@@ -79,7 +87,8 @@ export function preflightSnapshotApply(
 
 		const target = snapshotTarget(root, normalized, options.sessionDir);
 		const content = decodeBase64Strict(file.contentBase64, normalized);
-		if (sha256(content) !== file.sha256) throw new Error(`Checksum mismatch in snapshot file: ${normalized}`);
+		if (sha256(content) !== file.sha256)
+			throw new Error(`Checksum mismatch in snapshot file: ${normalized}`);
 		writes.push({ target, content });
 	}
 
@@ -108,7 +117,9 @@ export function protectSnapshotApplyPlan(
 ): SnapshotApplyPlan {
 	if (protectedRelativePaths.size === 0) return plan;
 	const protectedTargets = new Set(
-		[...protectedRelativePaths].map((relativePath) => snapshotTarget(root, relativePath, sessionDir)),
+		[...protectedRelativePaths].map((relativePath) =>
+			snapshotTarget(root, relativePath, sessionDir),
+		),
 	);
 	return {
 		writes: plan.writes.filter((item) => !protectedTargets.has(item.target)),
@@ -141,7 +152,11 @@ export async function addTopLevelCaseVariantDeletes(
 	const deletes = new Set(plan.deletes);
 	for (const entry of entries) {
 		const canonicalPath = topLevelPaths.get(entry.name.toLowerCase());
-		if (canonicalPath && entry.name !== canonicalPath && (entry.isFile() || entry.isSymbolicLink())) {
+		if (
+			canonicalPath &&
+			entry.name !== canonicalPath &&
+			(entry.isFile() || entry.isSymbolicLink())
+		) {
 			deletes.add(safeJoin(root, entry.name));
 		}
 	}
@@ -198,7 +213,11 @@ async function preflightSnapshotMutations(
 		await assertNoSymlinkParents(rootForTarget(root, target, sessionDir), target);
 	}
 	for (const item of plan.writes) {
-		await prepareSnapshotWrite(rootForTarget(root, item.target, sessionDir), item.target, deletePaths);
+		await prepareSnapshotWrite(
+			rootForTarget(root, item.target, sessionDir),
+			item.target,
+			deletePaths,
+		);
 	}
 }
 
@@ -212,7 +231,8 @@ async function prepareSnapshotWrite(root: string, target: string, deletePaths: S
 	await ensureSafeDirectory(root, path.dirname(target));
 	try {
 		const stat = await fs.lstat(target);
-		if (stat.isSymbolicLink()) throw new Error(`Refusing to overwrite symlink during snapshot apply: ${target}`);
+		if (stat.isSymbolicLink())
+			throw new Error(`Refusing to overwrite symlink during snapshot apply: ${target}`);
 		if (stat.isDirectory() && !deletePaths.has(target)) {
 			throw new Error(`Refusing to overwrite directory during snapshot apply: ${target}`);
 		}
@@ -230,8 +250,10 @@ async function ensureSafeDirectory(root: string, directory: string) {
 		current = path.join(current, part);
 		try {
 			const stat = await fs.lstat(current);
-			if (stat.isSymbolicLink()) throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
-			if (!stat.isDirectory()) throw new Error(`Snapshot path parent is not a directory: ${current}`);
+			if (stat.isSymbolicLink())
+				throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
+			if (!stat.isDirectory())
+				throw new Error(`Snapshot path parent is not a directory: ${current}`);
 		} catch (error) {
 			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
 			await fs.mkdir(current);
@@ -249,8 +271,10 @@ async function assertNoSymlinkParents(root: string, target: string) {
 		current = path.join(current, part);
 		try {
 			const stat = await fs.lstat(current);
-			if (stat.isSymbolicLink()) throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
-			if (!stat.isDirectory()) throw new Error(`Snapshot path parent is not a directory: ${current}`);
+			if (stat.isSymbolicLink())
+				throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
+			if (!stat.isDirectory())
+				throw new Error(`Snapshot path parent is not a directory: ${current}`);
 		} catch (error) {
 			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
 			throw error;

package/src/snapshot.ts

@@ -5,20 +5,25 @@ import os from "node:os";
 import path from "node:path";
 import { agentDir, configuredSessionDir } from "./config.js";
 import { isDeniedPath, posixJoin, safeJoin, toPosix } from "./paths.js";
+
 export { isDeniedPath } from "./paths.js";
-import type {
-	Snapshot,
-	SnapshotFile,
-	SnapshotOptions,
-	SyncConfig,
-} from "./types.js";
+
+import {
+	canonicalSnapshotPathForConfig,
+	DEFAULT_SYNC_FILES,
+	extraFilePathsByLower,
+	isConfiguredSnapshotPath,
+	isPreservableUnmanagedSnapshotPath,
+	normalizeExtraFiles,
+	normalizeSyncFiles,
+} from "./sync-policy.js";
+import type { Snapshot, SnapshotFile, SnapshotOptions, SyncConfig } from "./types.js";
+
+export { canonicalSnapshotPathForConfig, isConfiguredSnapshotPath } from "./sync-policy.js";
 
 const VERSION = 1;
-const TOP_LEVEL_FILES = new Set(["settings.json", "keybindings.json", "models.json", "AGENTS.md", "APPEND_SYSTEM.md"]);
-const TOP_LEVEL_DIRS = new Set(["skills", "prompts", "themes", "extensions"]);
-const TOP_LEVEL_FILE_PATHS = new Map([...TOP_LEVEL_FILES].map((name) => [name.toLowerCase(), name]));
-const TOP_LEVEL_FILE_NAMES = new Set(TOP_LEVEL_FILE_PATHS.keys());
-const RESERVED_TOP_LEVEL_NAMES = new Set([...TOP_LEVEL_DIRS, "sessions"]);
+const TOP_LEVEL_FILES: readonly string[] = DEFAULT_SYNC_FILES.filter((name) => name.includes("."));
+const TOP_LEVEL_DIRS = new Set<string>(DEFAULT_SYNC_FILES.filter((name) => !name.includes(".")));
 const SECRET_PATTERNS = [
 	/AWS_SECRET_ACCESS_KEY\s*[=:]\s*['"]?[A-Za-z0-9/+]{35,}/i,
 	/(ANTHROPIC|OPENAI|GEMINI|GOOGLE|FIRECRAWL|GITHUB|CLOUDFLARE|R2|S3)_[A-Z0-9_]*(KEY|TOKEN|SECRET)\s*[=:]\s*['"]?[^\s'"]{12,}/i,
@@ -33,27 +38,6 @@ function expandHome(value: string) {
 	return value;
 }
 
-export function normalizeExtraFiles(value: unknown) {
-	if (!Array.isArray(value)) return [];
-	const seen = new Set<string>();
-	return value
-		.filter((item): item is string => typeof item === "string")
-		.map((item) => item.trim())
-		.filter((item) => {
-			const lower = item.toLowerCase();
-			if (
-				item === "" || item === "." || item === ".." || item.includes("/") || item.includes("\\") ||
-				TOP_LEVEL_FILE_NAMES.has(lower) || isDeniedPath(item) || RESERVED_TOP_LEVEL_NAMES.has(lower) || seen.has(lower)
-			) return false;
-			seen.add(lower);
-			return true;
-		});
-}
-
-export function extraFilePathsByLower(value: unknown) {
-	return new Map(normalizeExtraFiles(value).map((fileName) => [fileName.toLowerCase(), fileName]));
-}
-
 function selectTopLevelFileEntry(entries: Dirent[], fileName: string) {
 	const exact = entries.find((entry) => entry.isFile() && entry.name === fileName);
 	if (exact) return exact;
@@ -70,15 +54,24 @@ function sha256(value: Buffer) {
 function isSafeSnapshotPath(relativePath: string) {
 	if (relativePath.includes("\\")) return false;
 	const normalized = toPosix(relativePath);
-	return Boolean(normalized) && normalized !== "." && normalized !== ".." && !normalized.startsWith("../") &&
-		!path.posix.isAbsolute(normalized) && path.posix.normalize(normalized) === normalized && !isDeniedPath(normalized);
+	return (
+		Boolean(normalized) &&
+		normalized !== "." &&
+		normalized !== ".." &&
+		!normalized.startsWith("../") &&
+		!path.posix.isAbsolute(normalized) &&
+		path.posix.normalize(normalized) === normalized &&
+		!isDeniedPath(normalized)
+	);
 }
 
 function snapshotsMatch(left: Snapshot, right: Snapshot) {
 	const leftHashes = new Map(left.files.map((file) => [file.path, file.sha256]));
 	const rightHashes = new Map(right.files.map((file) => [file.path, file.sha256]));
-	return leftHashes.size === rightHashes.size &&
-		[...leftHashes].every(([filePath, hash]) => rightHashes.get(filePath) === hash);
+	return (
+		leftHashes.size === rightHashes.size &&
+		[...leftHashes].every(([filePath, hash]) => rightHashes.get(filePath) === hash)
+	);
 }
 
 function snapshotId() {
@@ -91,6 +84,7 @@ export async function createSnapshot(
 ): Promise<Snapshot> {
 	const syncSessions = Boolean(options.syncSessions);
 	const files = await collectFiles(agentDir(), {
+		syncFiles: options.syncFiles,
 		syncSessions,
 		sessionDir: options.sessionDir ?? (await configuredSessionDir()),
 		extraFiles: options.extraFiles,
@@ -112,12 +106,14 @@ export async function collectFiles(
 ): Promise<SnapshotFile[]> {
 	const results: SnapshotFile[] = [];
 	const entries = await fs.readdir(root, { withFileTypes: true });
+	const selectedFiles = new Set<string>(normalizeSyncFiles(options.syncFiles));
 	for (const entry of entries) {
-		if (entry.isDirectory() && TOP_LEVEL_DIRS.has(entry.name)) {
+		if (entry.isDirectory() && TOP_LEVEL_DIRS.has(entry.name) && selectedFiles.has(entry.name)) {
 			await collectDirectory(results, root, entry.name);
 		}
 	}
 	for (const fileName of TOP_LEVEL_FILES) {
+		if (!selectedFiles.has(fileName)) continue;
 		const entry = selectTopLevelFileEntry(entries, fileName);
 		if (entry) await addFile(results, root, entry.name, fileName);
 	}
@@ -168,7 +164,11 @@ async function addFile(
 	if (!isSafeSnapshotPath(snapshotPath)) return;
 	const absolutePath = safeJoin(root, relativePath);
 	const content = await fs.readFile(absolutePath);
-	results.push({ path: snapshotPath, contentBase64: content.toString("base64"), sha256: sha256(content) });
+	results.push({
+		path: snapshotPath,
+		contentBase64: content.toString("base64"),
+		sha256: sha256(content),
+	});
 }
 
 export function isSessionPath(relativePath: string) {
@@ -181,11 +181,18 @@ export function isSessionFilePath(relativePath: string) {
 }
 
 export function sessionStorageRoot(root: string, configuredSessionDir?: string) {
-	return configuredSessionDir ? path.resolve(expandHome(configuredSessionDir)) : path.resolve(root, "sessions");
+	return configuredSessionDir
+		? path.resolve(expandHome(configuredSessionDir))
+		: path.resolve(root, "sessions");
 }
 
-export function sessionSnapshotPathFromAbsolute(sessionFile: string, configuredSessionDir?: string) {
-	const relativePath = toPosix(path.relative(sessionStorageRoot(agentDir(), configuredSessionDir), sessionFile));
+export function sessionSnapshotPathFromAbsolute(
+	sessionFile: string,
+	configuredSessionDir?: string,
+) {
+	const relativePath = toPosix(
+		path.relative(sessionStorageRoot(agentDir(), configuredSessionDir), sessionFile),
+	);
 	if (!relativePath || relativePath.startsWith("../") || path.posix.isAbsolute(relativePath)) {
 		return undefined;
 	}
@@ -195,23 +202,21 @@ export function sessionSnapshotPathFromAbsolute(sessionFile: string, configuredS
 
 export function snapshotTarget(root: string, relativePath: string, configuredSessionDir?: string) {
 	if (isSessionPath(relativePath)) {
-		return safeJoin(sessionStorageRoot(root, configuredSessionDir), relativePath.slice("sessions/".length));
+		return safeJoin(
+			sessionStorageRoot(root, configuredSessionDir),
+			relativePath.slice("sessions/".length),
+		);
 	}
 	return safeJoin(root, relativePath);
 }
 
-function isPathInside(parent: string, child: string) {
-	const relativePath = path.relative(parent, child);
-	return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
-}
-
 export function snapshotIncludesSessions(snapshot: Snapshot) {
 	return snapshot.syncSessions === true || snapshot.files.some((file) => isSessionPath(file.path));
 }
 
 export function filterSnapshotForConfigPolicy(
 	snapshot: Snapshot,
-	config: Pick<SyncConfig, "syncSessions" | "extraFiles">,
+	config: Pick<SyncConfig, "syncFiles" | "syncSessions" | "extraFiles">,
 	options: { regenerateId?: boolean } = {},
 ) {
 	const extraFilePaths = extraFilePathsByLower(config.extraFiles);
@@ -230,23 +235,9 @@ export function filterSnapshotForConfigPolicy(
 	};
 }
 
-export function isConfiguredSnapshotPath(
-	relativePath: string,
-	config: Pick<SyncConfig, "syncSessions">,
-	extraFiles: Set<string>,
-) {
-	const normalized = toPosix(relativePath);
-	if (isSessionPath(normalized)) return config.syncSessions;
-	if (!normalized.includes("/")) {
-		const lower = normalized.toLowerCase();
-		return TOP_LEVEL_FILE_NAMES.has(lower) || extraFiles.has(lower);
-	}
-	return TOP_LEVEL_DIRS.has(normalized.slice(0, normalized.indexOf("/")));
-}
-
 function canonicalizeSnapshotFilesForConfig(
 	files: SnapshotFile[],
-	config: Pick<SyncConfig, "syncSessions">,
+	config: Pick<SyncConfig, "syncFiles" | "syncSessions">,
 	extraFiles: Set<string>,
 	extraFilePaths: Map<string, string>,
 ) {
@@ -257,14 +248,17 @@ function canonicalizeSnapshotFilesForConfig(
 	>();
 	for (const file of files) {
 		const normalized = toPosix(file.path);
-		if (!isSafeSnapshotPath(file.path) || !isConfiguredSnapshotPath(normalized, config, extraFiles)) {
+		if (
+			!isSafeSnapshotPath(file.path) ||
+			!isConfiguredSnapshotPath(normalized, config, extraFiles)
+		) {
 			continue;
 		}
-		const topLevelPath = canonicalTopLevelFilePath(normalized, extraFilePaths);
-		if (!topLevelPath) {
+		if (normalized.includes("/")) {
 			configuredFiles.push(normalized === file.path ? file : { ...file, path: normalized });
 			continue;
 		}
+		const topLevelPath = canonicalSnapshotPathForConfig(normalized, extraFilePaths);
 		const candidate = {
 			exact: normalized === topLevelPath,
 			file: { ...file, path: topLevelPath },
@@ -281,17 +275,6 @@ function canonicalizeSnapshotFilesForConfig(
 	].sort((left, right) => left.path.localeCompare(right.path));
 }
 
-function canonicalTopLevelFilePath(relativePath: string, extraFilePaths: Map<string, string>) {
-	const normalized = toPosix(relativePath);
-	if (normalized.includes("/")) return undefined;
-	const lower = normalized.toLowerCase();
-	return TOP_LEVEL_FILE_PATHS.get(lower) ?? extraFilePaths.get(lower);
-}
-
-export function canonicalSnapshotPathForConfig(relativePath: string, extraFilePaths: Map<string, string>) {
-	return canonicalTopLevelFilePath(relativePath, extraFilePaths) ?? toPosix(relativePath);
-}
-
 function isPreferredExtraCandidate(
 	left: { exact: boolean; originalPath: string },
 	right: { exact: boolean; originalPath: string },
@@ -332,38 +315,36 @@ export function scanSnapshot(snapshot: Snapshot) {
 export function mergeRemotePreservedFiles(
 	local: Snapshot,
 	remote: Snapshot,
-	config: Pick<SyncConfig, "syncSessions" | "extraFiles">,
+	config: Pick<SyncConfig, "syncFiles" | "syncSessions" | "extraFiles">,
 ) {
-	const withSessions = config.syncSessions ? local : mergeRemoteSessionFiles(local, remote);
-	const paths = new Set(withSessions.files.map((file) => file.path));
-	const pathNames = new Set(withSessions.files.map((file) => file.path.toLowerCase()));
-	const extraFileNames = new Set(normalizeExtraFiles(config.extraFiles).map((file) => file.toLowerCase()));
-	const seenRemoteExtraNames = new Set<string>();
-	const remoteExtras = remote.files.filter((file) => {
+	const localPathNames = new Set(local.files.map((file) => file.path.toLowerCase()));
+	const configuredExtraFiles = new Set(
+		normalizeExtraFiles(config.extraFiles).map((file) => file.toLowerCase()),
+	);
+	const preservedPathNames = new Set<string>();
+	const preserved = remote.files.filter((file) => {
 		const normalized = toPosix(file.path);
 		const lower = normalized.toLowerCase();
 		if (
-			paths.has(normalized) ||
-			pathNames.has(lower) ||
+			localPathNames.has(lower) ||
+			preservedPathNames.has(lower) ||
 			!isSafeSnapshotPath(file.path) ||
-			normalized.includes("/") ||
-			TOP_LEVEL_FILE_NAMES.has(lower) ||
-			RESERVED_TOP_LEVEL_NAMES.has(lower) ||
-			extraFileNames.has(lower) ||
-			seenRemoteExtraNames.has(lower)
+			isConfiguredSnapshotPath(normalized, config, configuredExtraFiles) ||
+			!isPreservableUnmanagedSnapshotPath(normalized)
 		) {
 			return false;
 		}
-		seenRemoteExtraNames.add(lower);
+		preservedPathNames.add(lower);
 		return true;
 	});
-	if (remoteExtras.length === 0) return withSessions;
+	if (preserved.length === 0) return local;
 	return {
-		...withSessions,
+		...local,
 		id: snapshotId(),
 		createdAt: new Date().toISOString(),
 		machine: os.hostname(),
-		files: [...withSessions.files, ...remoteExtras].sort((left, right) =>
+		syncSessions: snapshotIncludesSessions(local) || snapshotIncludesSessions(remote),
+		files: [...local.files, ...preserved].sort((left, right) =>
 			left.path.localeCompare(right.path),
 		),
 	};