@narumitw/pi-sync 0.24.0 → 0.28.0

package/src/sync.ts

@@ -1,38 +1,37 @@
 import { createHash } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
-import { gunzip, gzip } from "node:zlib";
 import { promisify } from "node:util";
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { completeSyncArguments, parseOptions, splitArgs, usage } from "./command.js";
+import { gunzip, gzip } from "node:zlib";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { completeSyncArguments, parseOptions, resolveSyncCommand, usage } from "./command.js";
 import {
 	agentDir,
 	ensureStateDir,
-	extraFilePathsByLower,
+	isEnabled,
+	isExplicitlyEnabled,
 	isMissingConfigError,
-	isStaleLock,
+	loadConfig,
 	loadPartialConfig,
 	localConfigPath,
-	lockPath,
+	localConfigTemplate,
 	normalizeExtraFiles,
-	readLock,
-	stateDir,
-	writeJson,
-	configuredSessionDir,
-	isCloudflareR2Endpoint,
-	isEnabled,
-	isExplicitlyEnabled,
-	loadConfig,
+	normalizeSyncFiles,
 	readState,
 	sessionDirForApply,
 	sessionTokenWarnings,
+	stateDir,
 	syncSessionsWarnings,
-	withLock,
+	writeLocalConfigObject,
 	writeState,
 } from "./config.js";
-import { encodeKey, posixJoin, safeJoin, safeName, toPosix } from "./paths.js";
+import { showFileSelection } from "./file-selection.js";
+import { inspectLock, isLockGuardHeld, isStaleLock, unlock, withLock } from "./lock.js";
 import {
 	historyKey,
 	latestKey,
@@ -42,27 +41,28 @@ import {
 	snapshotKey,
 } from "./s3-client.js";
 import {
-	addTopLevelCaseVariantDeletes,
-	appliedFileHashMap,
-	applySnapshot,
-	preflightSnapshotApply,
-	protectSnapshotApplyPlan,
-} from "./snapshot-apply.js";
-import {
-	collectFiles,
 	createSnapshot,
-	canonicalSnapshotPathForConfig,
 	filterSnapshotForConfigPolicy,
-	isConfiguredSnapshotPath,
-	isDeniedPath,
-	isSessionPath,
-	sessionSnapshotPathFromAbsolute,
 	mergeRemotePreservedFiles,
-	mergeRemoteSessionFiles,
 	scanSnapshot,
+	sessionSnapshotPathFromAbsolute,
 	snapshotIncludesSessions,
 	snapshotWithoutSessions,
 } from "./snapshot.js";
+import { applySnapshot } from "./snapshot-apply.js";
+import {
+	canPullRemoteSessionsOnFirstSync,
+	canPullRemoteSettingsOnFirstSync,
+	fileHashMap,
+	hasLocalChanges,
+	hasRemoteChanges,
+	remoteChangedSinceState,
+	sameHashes,
+	shouldRefreshSyncedState,
+	snapshotHashesMatchState,
+	snapshotsMatch,
+	syncPolicyChanged,
+} from "./sync-state.js";
 import type {
 	CommandOptions,
 	LatestPointer,
@@ -76,12 +76,11 @@ import type {
 const gzipAsync = promisify(gzip);
 const gunzipAsync = promisify(gunzip);
 
-const STATUS_KEY = "pisync";
+const STATUS_KEY = "sync";
 const VERSION = 1;
 const DEFAULT_PROFILE = "default";
 const DEFAULT_PREFIX = "pi-sync";
 const DEFAULT_REGION = "auto";
-const LOCK_STALE_MS = 30 * 60 * 1000;
 
 interface PushInput {
 	config: SyncConfig;
@@ -100,7 +99,7 @@ const AUTO_SYNC_OPTIONS: CommandOptions = {
 	args: [],
 };
 export default function sync(pi: ExtensionAPI) {
-	pi.registerCommand("pisync", {
+	pi.registerCommand("sync", {
 		description: "Sync Pi settings through Cloudflare R2 or S3-compatible storage",
 		getArgumentCompletions: completeSyncArguments,
 		handler: async (args, ctx) => {
@@ -114,17 +113,19 @@ export default function sync(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_shutdown", async (event, ctx) => {
-		const reason = typeof event === "object" && event ? (event as { reason?: string }).reason : undefined;
+		const reason =
+			typeof event === "object" && event ? (event as { reason?: string }).reason : undefined;
 		if (reason !== "reload") await autoPushSessions(ctx);
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 	});
 }
 
 async function handleCommand(rawArgs: string, ctx: ExtensionCommandContext) {
-	const [subcommand = "status", ...rest] = splitArgs(rawArgs);
-	const options = parseOptions(rest);
-
 	try {
+		const command = await resolveSyncCommand(rawArgs, ctx);
+		if (!command) return;
+		const { subcommand, rest } = command;
+		const options = parseOptions(rest);
 		await ensureStateDir();
 
 		switch (subcommand) {
@@ -137,6 +138,9 @@ async function handleCommand(rawArgs: string, ctx: ExtensionCommandContext) {
 			case "config":
 				await showConfig(ctx);
 				return;
+			case "files":
+				await showFileSelection(ctx);
+				return;
 			case "status":
 				await status(ctx);
 				return;
@@ -165,7 +169,7 @@ async function handleCommand(rawArgs: string, ctx: ExtensionCommandContext) {
 				await unlock(ctx, options);
 				return;
 			default:
-				ctx.ui.notify(`Unknown /pisync command: ${subcommand}\n\n${usage()}`, "warning");
+				ctx.ui.notify(`Unknown /sync command: ${subcommand}\n\n${usage()}`, "warning");
 		}
 	} catch (error) {
 		ctx.ui.setStatus(STATUS_KEY, undefined);
@@ -218,20 +222,8 @@ async function initConfig(ctx: ExtensionCommandContext) {
 		// Create below.
 	}
 
-	const sample = {
-		endpoint: "https://<account-id>.r2.cloudflarestorage.com",
-		bucket: "pi-sync",
-		region: DEFAULT_REGION,
-		accessKeyId: "<access-key-id>",
-		secretAccessKey: "<secret-access-key>",
-		profile: DEFAULT_PROFILE,
-		prefix: DEFAULT_PREFIX,
-		autoSync: true,
-		syncSessions: false,
-		extraFiles: [],
-	};
-	await writeJson(configPath, sample);
-	ctx.ui.notify(`Created ${configPath}. Fill in R2 credentials, then run /pisync doctor.`, "info");
+	await writeLocalConfigObject(localConfigTemplate());
+	ctx.ui.notify(`Created ${configPath}. Fill in R2 credentials, then run /sync doctor.`, "info");
 }
 
 async function showConfig(ctx: ExtensionCommandContext) {
@@ -250,6 +242,7 @@ async function showConfig(ctx: ExtensionCommandContext) {
 			`profile: ${partial.profile ?? DEFAULT_PROFILE}`,
 			`prefix: ${partial.prefix ?? DEFAULT_PREFIX}`,
 			`autoSync: ${isEnabled(partial.autoSync ?? process.env.PI_SYNC_AUTO_SYNC, true) ? "enabled" : "disabled"}`,
+			`syncFiles: ${normalizeSyncFiles(partial.syncFiles).join(", ") || "none"}`,
 			`syncSessions: ${syncSessions ? "enabled" : "disabled"}`,
 			`extraFiles: ${normalizeExtraFiles(partial.extraFiles).join(", ") || "none"}`,
 			`local config: ${localConfigPath()}`,
@@ -269,7 +262,7 @@ async function status(ctx: ExtensionCommandContext) {
 	const localChanged = hasLocalChanges(local, state, config);
 
 	let remoteText = "remote: empty";
-	let remoteChanged = remoteChangedSinceState(latest, state, config);
+	const remoteChanged = remoteChangedSinceState(latest, state, config);
 	if (!latest.missing && latest.value) {
 		remoteText = `remote: ${latest.value.snapshot} from ${latest.value.machine} at ${latest.value.createdAt}`;
 	}
@@ -279,6 +272,8 @@ async function status(ctx: ExtensionCommandContext) {
 	ctx.ui.notify(
 		[
 			`profile: ${config.profile}`,
+			`sync files: ${normalizeSyncFiles(config.syncFiles).join(", ") || "none"}`,
+			`extra files: ${config.extraFiles.join(", ") || "none"}`,
 			`sessions: ${config.syncSessions ? "included" : "excluded"}`,
 			remoteText,
 			`local files: ${local.files.length}`,
@@ -299,9 +294,12 @@ async function diff(ctx: ExtensionCommandContext) {
 	ctx.ui.setStatus(STATUS_KEY, undefined);
 
 	const warnings = syncSessionsWarnings(config);
-	const header = [`sessions: ${config.syncSessions ? "included" : "excluded"}`, ...warnings].join(
-		"\n",
-	);
+	const header = [
+		`sync files: ${normalizeSyncFiles(config.syncFiles).join(", ") || "none"}`,
+		`extra files: ${config.extraFiles.join(", ") || "none"}`,
+		`sessions: ${config.syncSessions ? "included" : "excluded"}`,
+		...warnings,
+	].join("\n");
 	const level = warnings.length > 0 ? "warning" : "info";
 	if (!remote) {
 		ctx.ui.notify(
@@ -325,6 +323,8 @@ async function doctor(ctx: ExtensionCommandContext) {
 		profile = config.profile;
 		snapshotOptions = snapshotOptionsForContext(ctx, config);
 		messages.push(`config: ok (${config.bucket}/${profilePrefix(config)})`);
+		messages.push(`sync files: ${normalizeSyncFiles(config.syncFiles).join(", ") || "none"}`);
+		messages.push(`extra files: ${config.extraFiles.join(", ") || "none"}`);
 		messages.push(`sessions: ${config.syncSessions ? "included" : "excluded"}`);
 		const warnings = [...sessionTokenWarnings(config), ...syncSessionsWarnings(config)];
 		if (warnings.length > 0) {
@@ -346,8 +346,25 @@ async function doctor(ctx: ExtensionCommandContext) {
 		messages.push(`secret scan: ok (${local.files.length} files checked)`);
 	}
 
-	const lock = await readLock();
-	messages.push(lock ? `lock: held by pid ${lock.pid} since ${lock.startedAt}` : "lock: free");
+	const lock = await inspectLock();
+	if (lock.status === "valid" && isStaleLock(lock.lock)) {
+		level = "warning";
+		messages.push(
+			`lock: stale (pid ${lock.lock.pid}); run /sync unlock after verifying no sync is running`,
+		);
+	} else if (lock.status === "valid") {
+		messages.push(`lock: held by pid ${lock.lock.pid} since ${lock.lock.startedAt}`);
+	} else if (lock.status === "unreadable") {
+		level = "warning";
+		messages.push(
+			"lock: unreadable; use /sync unlock --stale only after verifying no sync is running",
+		);
+	} else if (await isLockGuardHeld()) {
+		level = "warning";
+		messages.push("lock: guard active while metadata is missing or still being initialized");
+	} else {
+		messages.push("lock: free");
+	}
 	ctx.ui.notify(messages.join("\n"), level);
 }
 
@@ -360,29 +377,28 @@ async function push(
 	const config = input?.config ?? (await loadConfig());
 	const client = input?.client ?? new S3Client(config);
 	const state = input?.state ?? (await readState(config.profile));
-	const local = input?.local ?? (await createSnapshot(config.profile, snapshotOptionsForContext(ctx, config)));
+	const local =
+		input?.local ?? (await createSnapshot(config.profile, snapshotOptionsForContext(ctx, config)));
 
 	const latest = await client.getJson<LatestPointer>(latestKey(config));
-	const remoteForUpload = options.force
-		? undefined
-		: await readRemoteSnapshotForUpload(client, config, latest, state);
+	const remoteForUpload = await readRemoteSnapshotForUpload(client, config, latest, state);
 	if (remoteChangedSinceState(latest, state, config) && !options.force) {
 		const remoteForConflict = remoteForUpload
 			? filterSnapshotForConfigPolicy(remoteForUpload, config)
 			: undefined;
 		if (!remoteForConflict || !snapshotHashesMatchState(remoteForConflict, state, config)) {
 			throw new Error(
-				"Remote or sync policy changed since last sync. Run /pisync pull first or /pisync push --force.",
+				"Remote or sync policy changed since last sync. Run /sync pull first or /sync push --force.",
 			);
 		}
 	}
 
-	const upload = await snapshotForUpload(client, config, local, latest, remoteForUpload, {
-		preserveRemote: !options.force,
-	});
+	const upload = await snapshotForUpload(client, config, local, latest, remoteForUpload);
 	const secrets = scanSnapshot(local);
 	if (secrets.length > 0) {
-		throw new Error(`Refusing to push possible secrets:\n${secrets.map((s) => `- ${s}`).join("\n")}`);
+		throw new Error(
+			`Refusing to push possible secrets:\n${secrets.map((s) => `- ${s}`).join("\n")}`,
+		);
 	}
 
 	const preservedRemoteFileCount = countPreservedRemoteFiles(local, upload);
@@ -406,6 +422,7 @@ async function push(
 		lastAppliedSnapshot: pointer.snapshot,
 		lastRemoteEtag: undefined,
 		lastFileHashes: fileHashMap(local),
+		syncFiles: config.syncFiles,
 		syncSessions: config.syncSessions,
 		extraFiles: config.extraFiles,
 	});
@@ -422,12 +439,14 @@ async function pull(ctx: ExtensionCommandContext | ExtensionContext, options: Co
 	const state = await readState(config.profile);
 	const local = await createSnapshot(config.profile, snapshotOptionsForContext(ctx, config));
 	const remote = await readRemoteSnapshot(client, config);
-	if (!remote) throw new Error("Remote is empty. Run /pisync push from a configured machine first.");
+	if (!remote) throw new Error("Remote is empty. Run /sync push from a configured machine first.");
 
 	const localChanged = hasLocalChanges(local, state, config);
 	const remoteChanged = hasRemoteChanges(remote, state, config, protectedSessionPaths(ctx));
 	if (localChanged && remoteChanged && state.lastAppliedSnapshot && !options.force) {
-		throw new Error("Both local and remote changed since last sync. Run /pisync diff, then choose /pisync pull --force or /pisync push --force.");
+		throw new Error(
+			"Both local and remote changed since last sync. Run /sync diff, then choose /sync pull --force or /sync push --force.",
+		);
 	}
 
 	if (
@@ -445,6 +464,7 @@ async function pull(ctx: ExtensionCommandContext | ExtensionContext, options: Co
 	const backup = await backupLocal(config.profile, snapshotOptionsForContext(ctx, config));
 	const applySessionDir = await sessionDirForApply(ctx, remote);
 	const lastFileHashes = await applySnapshot(remote, protectedSessionPaths(ctx), {
+		syncFiles: config.syncFiles,
 		sessionDir: applySessionDir,
 		extraFiles: config.extraFiles,
 	});
@@ -454,12 +474,16 @@ async function pull(ctx: ExtensionCommandContext | ExtensionContext, options: Co
 		lastAppliedSnapshot: remote.id,
 		lastRemoteEtag: undefined,
 		lastFileHashes,
+		syncFiles: config.syncFiles,
 		syncSessions: config.syncSessions,
 		extraFiles: config.extraFiles,
 	});
 	ctx.ui.setStatus(STATUS_KEY, undefined);
 	if (!options.silent) {
-		ctx.ui.notify(`Pulled ${remote.files.length} files from ${remote.id}. Backup: ${backup}`, "info");
+		ctx.ui.notify(
+			`Pulled ${remote.files.length} files from ${remote.id}. Backup: ${backup}`,
+			"info",
+		);
 	} else if (options.auto && config.syncSessions && snapshotIncludesSessions(remote)) {
 		ctx.ui.notify(
 			"Pulled Pi sessions after startup selected the current session. Restart Pi or resume a pulled session to use newly synced conversations.",
@@ -483,11 +507,15 @@ async function syncBoth(ctx: ExtensionCommandContext | ExtensionContext, options
 
 	if (firstSync && remote && remote.files.length > 0 && local.files.length > 0) {
 		if (!canPullRemoteSettingsOnFirstSync(local, remote)) {
-			throw new Error("Remote settings exist and this machine has different local Pi settings. Run /pisync diff, then manually choose /pisync pull or /pisync push.");
+			throw new Error(
+				"Remote settings exist and this machine has different local Pi settings. Run /sync diff, then manually choose /sync pull or /sync push.",
+			);
 		}
 		if (!sameHashes(fileHashMap(local), fileHashMap(remote))) {
 			if (!canPullRemoteSessionsOnFirstSync(local, remote)) {
-				throw new Error("Remote settings match, but local and remote Pi sessions differ. Run /pisync diff, then manually choose /pisync pull or /pisync push.");
+				throw new Error(
+					"Remote settings match, but local and remote Pi sessions differ. Run /sync diff, then manually choose /sync pull or /sync push.",
+				);
 			}
 			await pull(ctx, options);
 			return;
@@ -498,10 +526,12 @@ async function syncBoth(ctx: ExtensionCommandContext | ExtensionContext, options
 			lastAppliedSnapshot: remote.id,
 			lastRemoteEtag: undefined,
 			lastFileHashes: fileHashMap(remote),
+			syncFiles: config.syncFiles,
 			syncSessions: config.syncSessions,
 			extraFiles: config.extraFiles,
 		});
-		if (!options.silent) ctx.ui.notify("pi-sync state initialized; local settings already match remote.", "info");
+		if (!options.silent)
+			ctx.ui.notify("pi-sync state initialized; local settings already match remote.", "info");
 		return;
 	}
 	if (localChanged && remoteChanged && remote && snapshotsMatch(local, remote)) {
@@ -511,6 +541,7 @@ async function syncBoth(ctx: ExtensionCommandContext | ExtensionContext, options
 			lastAppliedSnapshot: remote.id,
 			lastRemoteEtag: undefined,
 			lastFileHashes: fileHashMap(remote),
+			syncFiles: config.syncFiles,
 			syncSessions: config.syncSessions,
 			extraFiles: config.extraFiles,
 		});
@@ -518,7 +549,9 @@ async function syncBoth(ctx: ExtensionCommandContext | ExtensionContext, options
 		return;
 	}
 	if (localChanged && remoteChanged && state.lastAppliedSnapshot) {
-		throw new Error("Both local and remote changed. Run /pisync diff and resolve with push --force or pull --force.");
+		throw new Error(
+			"Both local and remote changed. Run /sync diff and resolve with push --force or pull --force.",
+		);
 	}
 	if (remoteChanged) {
 		await pull(ctx, options);
@@ -535,6 +568,7 @@ async function syncBoth(ctx: ExtensionCommandContext | ExtensionContext, options
 			lastAppliedSnapshot: remote.id,
 			lastRemoteEtag: undefined,
 			lastFileHashes: fileHashMap(remote),
+			syncFiles: config.syncFiles,
 			syncSessions: config.syncSessions,
 			extraFiles: config.extraFiles,
 		});
@@ -563,7 +597,7 @@ async function history(ctx: ExtensionCommandContext) {
 
 async function rollback(ctx: ExtensionCommandContext, options: CommandOptions) {
 	const target = options.args[0];
-	if (!target) throw new Error("Usage: /pisync rollback <snapshot-id> [--yes]");
+	if (!target) throw new Error("Usage: /sync rollback <snapshot-id> [--yes]");
 
 	const config = await loadConfig();
 	const client = new S3Client(config);
@@ -592,6 +626,7 @@ async function rollback(ctx: ExtensionCommandContext, options: CommandOptions) {
 	const backup = await backupLocal(config.profile, snapshotOptionsForContext(ctx, config));
 	const applySessionDir = await sessionDirForApply(ctx, remote);
 	const lastFileHashes = await applySnapshot(remote, protectedSessionPaths(ctx), {
+		syncFiles: config.syncFiles,
 		sessionDir: applySessionDir,
 		extraFiles: config.extraFiles,
 	});
@@ -612,6 +647,7 @@ async function rollback(ctx: ExtensionCommandContext, options: CommandOptions) {
 		lastAppliedSnapshot: pointer.snapshot,
 		lastRemoteEtag: undefined,
 		lastFileHashes,
+		syncFiles: config.syncFiles,
 		syncSessions: config.syncSessions,
 		extraFiles: config.extraFiles,
 	});
@@ -619,20 +655,6 @@ async function rollback(ctx: ExtensionCommandContext, options: CommandOptions) {
 	await maybeReload(ctx);
 }
 
-async function unlock(ctx: ExtensionCommandContext, options: CommandOptions) {
-	const lock = await readLock();
-	if (!lock) {
-		ctx.ui.notify("No pi-sync lock is present.", "info");
-		return;
-	}
-	if (!options.stale && !isStaleLock(lock)) {
-		ctx.ui.notify("Lock is not stale. Use /pisync unlock --stale only after verifying no sync is running.", "warning");
-		return;
-	}
-	await fs.rm(lockPath(), { force: true });
-	ctx.ui.notify("Removed stale pi-sync lock.", "info");
-}
-
 function protectedSessionPaths(ctx: ExtensionCommandContext | ExtensionContext) {
 	const getSessionFile = ctx.sessionManager.getSessionFile;
 	if (typeof getSessionFile !== "function") return new Set<string>();
@@ -648,6 +670,7 @@ function snapshotOptionsForContext(
 	config: SyncConfig,
 ): SnapshotOptions {
 	return {
+		syncFiles: config.syncFiles,
 		syncSessions: config.syncSessions,
 		sessionDir: sessionDirFromContext(ctx),
 		extraFiles: config.extraFiles,
@@ -670,7 +693,13 @@ function sessionDirFromContext(ctx: ExtensionCommandContext | ExtensionContext)
 
 async function maybeReload(ctx: ExtensionCommandContext | ExtensionContext) {
 	if (!("reload" in ctx)) return;
-	if (ctx.hasUI && (await ctx.ui.confirm("Reload Pi resources now?", "This reloads extensions, skills, prompts, themes, and context files."))) {
+	if (
+		ctx.hasUI &&
+		(await ctx.ui.confirm(
+			"Reload Pi resources now?",
+			"This reloads extensions, skills, prompts, themes, and context files.",
+		))
+	) {
 		await ctx.reload();
 	}
 }
@@ -697,9 +726,9 @@ async function snapshotForUpload(
 	local: Snapshot,
 	latest: RemoteObject<LatestPointer>,
 	remote?: Snapshot,
-	options: { preserveRemote?: boolean; ignoreUnreadableRemote?: boolean } = {},
+	options: { ignoreUnreadableRemote?: boolean } = {},
 ) {
-	if (options.preserveRemote === false || latest.missing || !latest.value) return local;
+	if (latest.missing || !latest.value) return local;
 	let snapshot = remote;
 	if (!snapshot) {
 		try {
@@ -724,12 +753,14 @@ async function uploadSnapshot(
 	await client.putBuffer(snapshotKey(config, snapshot.id), encoded, "application/gzip");
 	const current = await client.getJson<LatestPointer>(latestKey(config));
 	if (!force && remoteIdentity(current) !== remoteIdentity(latest)) {
-		throw new Error("Remote changed while pushing. Run /pisync pull first, then retry.");
+		throw new Error("Remote changed while pushing. Run /sync pull first, then retry.");
 	}
 	await client.putJson(latestKey(config), pointer);
 	const verified = await client.getJson<LatestPointer>(latestKey(config));
 	if (verified.value?.snapshot !== pointer.snapshot) {
-		throw new Error("Remote latest changed immediately after push. Run /pisync status before continuing.");
+		throw new Error(
+			"Remote latest changed immediately after push. Run /sync status before continuing.",
+		);
 	}
 	return pointer;
 }
@@ -743,8 +774,10 @@ async function readRemoteSnapshotRaw(client: S3Client, config: SyncConfig) {
 	const latest = await client.getJson<LatestPointer>(latestKey(config));
 	if (latest.missing || !latest.value) return undefined;
 	const object = await client.getBuffer(snapshotKey(config, latest.value.snapshot));
-	if (!object.value) throw new Error(`Remote latest points to missing snapshot: ${latest.value.snapshot}`);
-	if (sha256(object.value) !== latest.value.sha256) throw new Error("Remote snapshot checksum mismatch.");
+	if (!object.value)
+		throw new Error(`Remote latest points to missing snapshot: ${latest.value.snapshot}`);
+	if (sha256(object.value) !== latest.value.sha256)
+		throw new Error("Remote snapshot checksum mismatch.");
 	return decodeSnapshot(object.value);
 }
 
@@ -755,7 +788,8 @@ async function encodeSnapshot(snapshot: Snapshot) {
 async function decodeSnapshot(buffer: Buffer): Promise<Snapshot> {
 	const decoded = await gunzipAsync(buffer);
 	const parsed = JSON.parse(decoded.toString("utf8")) as Snapshot;
-	if (parsed.version !== VERSION || !Array.isArray(parsed.files)) throw new Error("Unsupported snapshot format.");
+	if (parsed.version !== VERSION || !Array.isArray(parsed.files))
+		throw new Error("Unsupported snapshot format.");
 	return parsed;
 }
 
@@ -769,7 +803,9 @@ export async function backupLocal(profile: string, options: SnapshotOptions = {}
 }
 
 async function updateHistory(client: S3Client, config: SyncConfig, pointer: LatestPointer) {
-	const object = await client.getJson<{ version: number; snapshots: LatestPointer[] }>(historyKey(config));
+	const object = await client.getJson<{ version: number; snapshots: LatestPointer[] }>(
+		historyKey(config),
+	);
 	const snapshots = object.value?.snapshots ?? [];
 	const next = [
 		...snapshots.filter((snapshot) => snapshot.snapshot !== pointer.snapshot),
@@ -782,7 +818,11 @@ function formatDiff(local: Snapshot, remote: Snapshot) {
 	const localMap = fileHashMap(local);
 	const remoteMap = fileHashMap(remote);
 	const allPaths = [...new Set([...Object.keys(localMap), ...Object.keys(remoteMap)])].sort();
-	const lines = [`local: ${local.files.length} files`, `remote: ${remote.id} (${remote.files.length} files)`, ""];
+	const lines = [
+		`local: ${local.files.length} files`,
+		`remote: ${remote.id} (${remote.files.length} files)`,
+		"",
+	];
 	let changed = 0;
 	for (const filePath of allPaths) {
 		if (!localMap[filePath]) {
@@ -818,145 +858,15 @@ function formatPushSummary(
 	].join("\n");
 }
 
-function hasLocalChanges(local: Snapshot, state: SyncState, config: SyncConfig) {
-	return !sameHashes(fileHashMap(local), stateHashMapForConfig(state, config));
-}
-
-function remoteChangedSinceState(
-	latest: RemoteObject<LatestPointer>,
-	state: SyncState,
-	config: SyncConfig,
-) {
-	if (latest.missing) return Boolean(state.lastAppliedSnapshot);
-	if (latest.value?.snapshot !== state.lastAppliedSnapshot) return true;
-	if (extraFilesChanged(state, config)) return true;
-	return config.syncSessions && state.syncSessions !== true && latest.value?.syncSessions === true;
-}
-
-export function hasRemoteChanges(
-	remote: Snapshot,
-	state: SyncState,
-	config: SyncConfig,
-	ignoredPaths = new Set<string>(),
-) {
-	if (remote.id === state.lastAppliedSnapshot && !syncPolicyChanged(state, config)) return false;
-	return !snapshotHashesMatchState(filterSnapshotForConfigPolicy(remote, config), state, config, ignoredPaths);
-}
-
 function remoteIdentity(remote: RemoteObject<LatestPointer>) {
 	return remote.missing ? "missing" : (remote.value?.snapshot ?? "unknown");
 }
 
-function sameHashes(left: Record<string, string>, right: Record<string, string>) {
-	const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
-	for (const key of keys) {
-		if (left[key] !== right[key]) return false;
-	}
-	return true;
-}
-
-function fileHashMap(snapshot: Snapshot) {
-	return Object.fromEntries(snapshot.files.map((file) => [file.path, file.sha256]));
-}
-
-function stateHashMapForConfig(state: SyncState, config: Pick<SyncConfig, "syncSessions" | "extraFiles">) {
-	const extraFilePaths = extraFilePathsByLower(config.extraFiles);
-	const extraFiles = new Set(extraFilePaths.keys());
-	return Object.fromEntries(
-		Object.entries(state.lastFileHashes)
-			.filter(([filePath]) => isConfiguredSnapshotPath(filePath, config, extraFiles))
-			.map(([filePath, hash]) => [canonicalSnapshotPathForConfig(filePath, extraFilePaths), hash]),
-	);
-}
-
-function snapshotHashesMatchState(
-	snapshot: Snapshot,
-	state: SyncState,
-	config: Pick<SyncConfig, "syncSessions" | "extraFiles">,
-	ignoredPaths = new Set<string>(),
-) {
-	return sameHashes(
-		withoutHashPaths(fileHashMap(snapshot), ignoredPaths),
-		withoutHashPaths(stateHashMapForConfig(state, config), ignoredPaths),
-	);
-}
-
-function snapshotsMatch(left: Snapshot, right: Snapshot) {
-	return left.syncSessions === right.syncSessions && sameHashes(fileHashMap(left), fileHashMap(right));
-}
-
-function withoutHashPaths(hashes: Record<string, string>, ignoredPaths: Set<string>) {
-	if (ignoredPaths.size === 0) return hashes;
-	return Object.fromEntries(
-		Object.entries(hashes).filter(([filePath]) => !ignoredPaths.has(toPosix(filePath))),
-	);
-}
-
-function syncPolicyChanged(state: SyncState, config: Pick<SyncConfig, "syncSessions" | "extraFiles">) {
-	return (state.syncSessions ?? false) !== config.syncSessions || extraFilesChanged(state, config);
-}
-
-function shouldRefreshSyncedState(
-	remote: Snapshot,
-	state: SyncState,
-	config: Pick<SyncConfig, "syncSessions" | "extraFiles">,
-) {
-	return remote.id !== state.lastAppliedSnapshot || syncPolicyChanged(state, config);
-}
-
-function extraFilesChanged(state: SyncState, config: Pick<SyncConfig, "extraFiles">) {
-	return !sameStringSet(normalizeExtraFiles(state.extraFiles), normalizeExtraFiles(config.extraFiles));
-}
-
-function sameStringSet(left: string[], right: string[]) {
-	const leftSet = new Set(left);
-	const rightSet = new Set(right);
-	if (leftSet.size !== rightSet.size) return false;
-	return [...leftSet].every((item) => rightSet.has(item));
-}
-
 function countPreservedRemoteFiles(local: Snapshot, upload: Snapshot) {
 	const localPaths = new Set(local.files.map((file) => file.path));
 	return upload.files.filter((file) => !localPaths.has(file.path)).length;
 }
 
-export function settingsHashMap(snapshot: Snapshot) {
-	return Object.fromEntries(
-		snapshot.files
-			.filter((file) => !isSessionPath(file.path))
-			.map((file) => [file.path, file.sha256]),
-	);
-}
-
-export function sessionHashMap(snapshot: Snapshot) {
-	return Object.fromEntries(
-		snapshot.files.filter((file) => isSessionPath(file.path)).map((file) => [file.path, file.sha256]),
-	);
-}
-
-export function settingsHashMapFromState(state: SyncState) {
-	return Object.fromEntries(
-		Object.entries(state.lastFileHashes).filter(([filePath]) => !isSessionPath(filePath)),
-	);
-}
-
-export function settingsHashesMatchState(remote: Snapshot, state: SyncState) {
-	return sameHashes(settingsHashMap(remote), settingsHashMapFromState(state));
-}
-
-export function canPullRemoteSettingsOnFirstSync(local: Snapshot, remote: Snapshot) {
-	const remoteSettings = settingsHashMap(remote);
-	return Object.entries(settingsHashMap(local)).every(
-		([filePath, hash]) => remoteSettings[filePath] === hash,
-	);
-}
-
-export function canPullRemoteSessionsOnFirstSync(local: Snapshot, remote: Snapshot) {
-	const localSessions = sessionHashMap(local);
-	const remoteSessions = sessionHashMap(remote);
-	return Object.entries(localSessions).every(([filePath, hash]) => remoteSessions[filePath] === hash);
-}
-
 function sha256(value: Buffer) {
 	return createHash("sha256").update(value).digest("hex");
 }
@@ -970,24 +880,39 @@ function errorMessage(error: unknown) {
 }
 
 export { completeSyncArguments, parseOptions, splitArgs } from "./command.js";
-export { isCloudflareR2Endpoint, isEnabled, isExplicitlyEnabled, loadConfig, sessionTokenWarnings } from "./config.js";
-export { encodeKey, posixJoin, safeJoin, safeName } from "./paths.js";
 export {
-	addTopLevelCaseVariantDeletes,
-	appliedFileHashMap,
-	preflightSnapshotApply,
-	protectSnapshotApplyPlan,
-} from "./snapshot-apply.js";
+	isCloudflareR2Endpoint,
+	isEnabled,
+	isExplicitlyEnabled,
+	loadConfig,
+	sessionTokenWarnings,
+} from "./config.js";
+export { encodeKey, posixJoin, safeJoin, safeName } from "./paths.js";
 export {
-	collectFiles,
 	canonicalSnapshotPathForConfig,
+	collectFiles,
 	filterSnapshotForConfigPolicy,
 	isConfiguredSnapshotPath,
 	isDeniedPath,
 	isSessionPath,
-	sessionSnapshotPathFromAbsolute,
 	mergeRemotePreservedFiles,
 	mergeRemoteSessionFiles,
 	scanSnapshot,
+	sessionSnapshotPathFromAbsolute,
 	snapshotWithoutSessions,
 } from "./snapshot.js";
+export {
+	addTopLevelCaseVariantDeletes,
+	appliedFileHashMap,
+	preflightSnapshotApply,
+	protectSnapshotApplyPlan,
+} from "./snapshot-apply.js";
+export {
+	canPullRemoteSessionsOnFirstSync,
+	canPullRemoteSettingsOnFirstSync,
+	hasRemoteChanges,
+	sessionHashMap,
+	settingsHashesMatchState,
+	settingsHashMap,
+	settingsHashMapFromState,
+} from "./sync-state.js";