@narumitw/pi-sync 0.29.2 → 0.30.0

package/README.md

@@ -79,30 +79,42 @@ A configured manager shows:
 ```text
 Current target: home
 Storage: Cloudflare R2 · personal-pi
-Auto-sync: On · Sessions: Off
-Last known sync: Remote not checked
+Synced content: 9 built-in groups · 0 extra files · Sessions: Off
+Auto-sync: On
+Last applied snapshot: snapshot-id (or Never synced)
+Remote changes: Not checked
 ```
 
 Its primary actions are:
 
-- **Sync now** — conservatively decide whether to push, pull, or do nothing
+- **Sync now (recommended)** — conservatively decide whether to push, pull, or do nothing
+- **Pull from remote** — check the remote snapshot, preview exact local writes/deletes, then confirm
+- **Push to remote** — scan and preview exact remote publication changes, then confirm
 - **Switch target** — preview the target change, then follow the configured pull behavior
 - **Status & changes** — perform a cancellable read-only remote check
 - **Settings** — control post-switch pulling, automatic sync, and synced content
-- **Manage targets & storage** — add, edit, or remove local target/profile definitions
-- **History & recovery** — browse snapshots, preview rollback, diagnose setup, or recover a stale lock
-- **Help**
+- **More…** — open one shallow level containing target/storage management, history/recovery, Help, and Back
 
-Escape exits the main menu. Secondary menus provide Back; dirty synced-content drafts provide Save, Discard, and Continue editing. Cancellation before publication has no side effects.
+The menu does not query remote storage merely to open. It shows the last locally applied snapshot and marks remote changes as unchecked until an operation runs. When no synced content is selected, transfer actions are hidden and Settings becomes the first action. During an active or recoverable lock, mutation actions remain unavailable.
+
+Push and pull keep their existing concrete previews and confirmation prompts. Pull creates a local backup before applying; push scans locally managed content for likely secrets before publication. Escape cancels a pre-commit check without changing local or remote files. Once publication or apply begins, cancellation is disabled. Conflicts never force automatically; inspect **Status & changes** and use an explicit direct route only after reviewing the conflict.
+
+Escape exits the main menu. **More…** and secondary menus provide Back; dirty synced-content drafts provide Save, Discard, and Continue editing. Cancellation before publication has no side effects.
 
 ## ⚙️ Settings
 
 The private user settings file is:
 
 ```text
-${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-sync.local.json
+${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-sync.json
 ```
 
+On first read, an existing `pi-sync.local.json` is migrated byte-for-byte to `pi-sync.json`
+with private POSIX `0600` permissions. The private legacy file is retained as a recovery copy and may
+be deleted after verifying the new file. If both files exist, `pi-sync.json` takes precedence and the
+legacy file remains untouched. Malformed, invalid, symlinked, changed, or otherwise unsafe legacy
+files are never overwritten automatically.
+
 A version 2 example:
 
 ```json
@@ -208,7 +220,7 @@ Environment-overridden fields are read-only in interactive settings. Cloudflare
 
 ### Legacy flat settings
 
-Existing flat `pi-sync.local.json` files continue to work unchanged as a synthetic `default` target/profile. The old flat `profile` remains the remote namespace.
+Existing flat settings continue to work unchanged as a synthetic `default` target/profile, including settings migrated from the legacy `pi-sync.local.json` filename. The old flat `profile` remains the remote namespace.
 
 Adding a second target offers an explicit migration preview. On confirmation pi-sync:
 
@@ -292,7 +304,7 @@ Sessions can contain prompts, model output, tool results, file paths, images, an
 
 ## 🛡️ Safety notes
 
-- Credentials stay local and are never included in snapshots.
+- Credentials stay local; canonical, legacy, temporary, and migration-recovery settings files are always excluded from snapshots.
 - Push refuses common secret patterns in locally managed files.
 - Pull/rollback reject unsafe paths, duplicate paths, checksum mismatches, symlink parents, and file/directory replacement hazards before mutation.
 - Unmanaged local/remote files remain preserved.
@@ -320,6 +332,7 @@ extensions/pi-sync/
 │   ├── sync.ts                  # Command and lifecycle orchestration
 │   ├── manager-ui.ts            # Goal-oriented menus and setup/management flows
 │   ├── file-selection.ts        # Transactional synced-content editor
+│   ├── config-file.ts           # Private settings I/O and legacy filename migration
 │   ├── settings-management.ts   # Profiles, targets, migration, and atomic saves
 │   ├── settings-ui.ts           # SettingsList interaction and serialized saves
 │   ├── target-switch.ts         # Post-switch prompt, policy, and target handoff

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-sync",
-	"version": "0.29.2",
+	"version": "0.30.0",
 	"description": "Pi extension that syncs Pi configuration through Cloudflare R2 or S3-compatible storage.",
 	"type": "module",
 	"license": "MIT",

package/src/command.ts

@@ -230,6 +230,6 @@ export function usage() {
 	return [
 		"Usage: /sync <command>",
 		`Commands: ${commands}`,
-		"Settings: use /sync init or edit profiles and targets in ~/.pi/agent/pi-sync.local.json (or $PI_CODING_AGENT_DIR/pi-sync.local.json). Existing PI_SYNC_* overrides still work but are deprecated for future major-version removal.",
+		"Settings: use /sync init or edit profiles and targets in ~/.pi/agent/pi-sync.json (or $PI_CODING_AGENT_DIR/pi-sync.json). Existing PI_SYNC_* overrides still work but are deprecated for future major-version removal.",
 	].join("\n");
 }

package/src/config-file.ts

@@ -0,0 +1,545 @@
+import { randomUUID } from "node:crypto";
+import {
+	constants as fsConstants,
+	mkdir,
+	mkdirSync,
+	realpath,
+	realpathSync,
+	rmdir,
+	rmdirSync,
+	stat,
+	statSync,
+	utimes,
+	utimesSync,
+} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import lockfile from "proper-lockfile";
+
+const CONFIG_FILE_NAME = "pi-sync.json";
+const LEGACY_CONFIG_FILE_NAME = "pi-sync.local.json";
+const configMigrationNotices = new Map<string, string>();
+const legacyPresenceNoticed = new Set<string>();
+const CONFIG_LOCK_STALE_MS = 30_000;
+const CONFIG_LOCK_UPDATE_MS = 10_000;
+const LOCKFILE_FS_ADAPTER = {
+	mkdir,
+	mkdirSync,
+	realpath,
+	realpathSync,
+	rmdir,
+	rmdirSync,
+	stat,
+	statSync,
+	utimes,
+	utimesSync,
+};
+
+type LinkFile = (source: string, destination: string) => Promise<void>;
+let linkConfigFile: LinkFile = (source, destination) => fs.link(source, destination);
+let afterReplacementInstalledHook: () => Promise<void> = async () => undefined;
+let afterConfigQuarantinedHook: () => Promise<void> = async () => undefined;
+
+export type FileIdentity = { dev: number; ino: number };
+
+export async function withConfigFileLinkForTest<T>(
+	link: LinkFile,
+	run: () => Promise<T>,
+): Promise<T> {
+	const previous = linkConfigFile;
+	linkConfigFile = link;
+	try {
+		return await run();
+	} finally {
+		linkConfigFile = previous;
+	}
+}
+
+export async function withConfigReplacementInstalledHookForTest<T>(
+	hook: () => Promise<void>,
+	run: () => Promise<T>,
+): Promise<T> {
+	const previous = afterReplacementInstalledHook;
+	afterReplacementInstalledHook = hook;
+	try {
+		return await run();
+	} finally {
+		afterReplacementInstalledHook = previous;
+	}
+}
+
+export async function withConfigQuarantinedHookForTest<T>(
+	hook: () => Promise<void>,
+	run: () => Promise<T>,
+): Promise<T> {
+	const previous = afterConfigQuarantinedHook;
+	afterConfigQuarantinedHook = hook;
+	try {
+		return await run();
+	} finally {
+		afterConfigQuarantinedHook = previous;
+	}
+}
+
+type ConfigSnapshot = {
+	bytes: Buffer;
+	identity: FileIdentity;
+	parsed: Record<string, unknown>;
+};
+
+export type LocalConfigDocument = ConfigSnapshot & { path: string };
+
+export function localConfigPath() {
+	return path.join(getAgentDir(), CONFIG_FILE_NAME);
+}
+
+export function legacyLocalConfigPath() {
+	return path.join(getAgentDir(), LEGACY_CONFIG_FILE_NAME);
+}
+
+export async function activeLocalConfigPath() {
+	return withLocalConfigFileLock(async () => {
+		const canonicalPath = localConfigPath();
+		if (await pathExists(canonicalPath)) return canonicalPath;
+		const legacyPath = legacyLocalConfigPath();
+		return (await pathExists(legacyPath)) ? legacyPath : canonicalPath;
+	});
+}
+
+export function consumeLocalConfigMigrationNotice() {
+	const configPath = localConfigPath();
+	const notice = configMigrationNotices.get(configPath);
+	configMigrationNotices.delete(configPath);
+	return notice;
+}
+
+export async function readMigratingLocalConfigDocument(
+	validateForMigration: (settings: Record<string, unknown>) => void,
+): Promise<LocalConfigDocument | undefined> {
+	return withLocalConfigFileLock(async () => {
+		const configPath = await prepareLocalConfigPath(validateForMigration);
+		const snapshot = await readConfigSnapshotIfExists(configPath);
+		return snapshot ? { path: configPath, ...snapshot } : undefined;
+	});
+}
+
+export function replaceLocalConfigDocument(
+	document: LocalConfigDocument,
+	value: Record<string, unknown>,
+) {
+	return withLocalConfigFileLock(() => replaceLocalConfigDocumentUnlocked(document, value));
+}
+
+async function replaceLocalConfigDocumentUnlocked(
+	document: LocalConfigDocument,
+	value: Record<string, unknown>,
+) {
+	const nextBytes = Buffer.from(`${JSON.stringify(value, null, "\t")}\n`, "utf8");
+	const canonicalPath = localConfigPath();
+	if (document.path !== canonicalPath) {
+		if (!(await configDocumentStillMatches(document))) throw settingsChangedError();
+		let installed: FileIdentity;
+		try {
+			installed = await installPrivateConfigExclusively(canonicalPath, nextBytes, true);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+				throw new Error("Canonical settings were created concurrently; no settings were replaced.");
+			}
+			throw error;
+		}
+		if (!(await configDocumentStillMatches(document))) {
+			await quarantineAndRemoveConfigIfMatchesUnlocked(canonicalPath, installed, nextBytes);
+			throw settingsChangedError();
+		}
+		return;
+	}
+
+	const quarantinePath = await claimCanonicalConfigDocument(document);
+	let installed: FileIdentity;
+	try {
+		installed = await installPrivateConfigExclusively(canonicalPath, nextBytes, true);
+	} catch (error) {
+		await restoreQuarantinedConfig(canonicalPath, quarantinePath);
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+			throw new Error("Canonical settings changed concurrently; no settings were replaced.");
+		}
+		throw error;
+	}
+	await afterReplacementInstalledHook();
+	if (!(await fileIdentityAndContentsMatch(quarantinePath, document.identity, document.bytes))) {
+		await quarantineAndRemoveConfigIfMatchesUnlocked(canonicalPath, installed, nextBytes);
+		await restoreQuarantinedConfig(canonicalPath, quarantinePath);
+		throw settingsChangedError();
+	}
+	if (process.platform !== "win32") await fs.chmod(quarantinePath, 0o600);
+	await syncParentDirectory(canonicalPath).catch(() => undefined);
+}
+
+async function prepareLocalConfigPath(
+	validateForMigration: (settings: Record<string, unknown>) => void,
+) {
+	const canonicalPath = localConfigPath();
+	const legacyPath = legacyLocalConfigPath();
+	if (await pathExists(canonicalPath)) {
+		const legacyStatus = await secureIgnoredLegacyIfPresent(legacyPath);
+		if (legacyStatus !== "missing" && !legacyPresenceNoticed.has(canonicalPath)) {
+			legacyPresenceNoticed.add(canonicalPath);
+			recordConfigMigrationNotice(
+				canonicalPath,
+				legacyStatus === "private"
+					? `${LEGACY_CONFIG_FILE_NAME} legacy settings were ignored because ${CONFIG_FILE_NAME} takes precedence. Delete ${LEGACY_CONFIG_FILE_NAME} after confirming your settings.`
+					: `${LEGACY_CONFIG_FILE_NAME} legacy settings were ignored because ${CONFIG_FILE_NAME} takes precedence, but pi-sync could not verify them as a private regular file. Secure or delete the legacy path after confirming your settings.`,
+			);
+		}
+		return canonicalPath;
+	}
+
+	const legacy = await readConfigSnapshotIfExists(legacyPath);
+	if (!legacy) return canonicalPath;
+	validateForMigration(legacy.parsed);
+
+	let installedIdentity: FileIdentity;
+	try {
+		installedIdentity = await installPrivateConfigExclusively(canonicalPath, legacy.bytes);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+			recordConfigMigrationNotice(
+				canonicalPath,
+				`${LEGACY_CONFIG_FILE_NAME} legacy settings were ignored because ${CONFIG_FILE_NAME} was created concurrently and takes precedence.`,
+			);
+			return canonicalPath;
+		}
+		recordConfigMigrationNotice(
+			canonicalPath,
+			`Could not migrate ${LEGACY_CONFIG_FILE_NAME} to ${CONFIG_FILE_NAME}; the legacy settings were used for this session and were not changed.`,
+		);
+		return legacyPath;
+	}
+
+	if (!(await configSnapshotStillMatches(legacyPath, legacy))) {
+		const removed = await quarantineAndRemoveConfigIfMatchesUnlocked(
+			canonicalPath,
+			installedIdentity,
+			legacy.bytes,
+		);
+		recordConfigMigrationNotice(
+			canonicalPath,
+			removed
+				? `${LEGACY_CONFIG_FILE_NAME} changed during migration; the stale ${CONFIG_FILE_NAME} copy was removed and the legacy settings were used for this session.`
+				: `${LEGACY_CONFIG_FILE_NAME} changed during migration, but ${CONFIG_FILE_NAME} was replaced concurrently and takes precedence.`,
+		);
+		return removed ? legacyPath : canonicalPath;
+	}
+
+	legacyPresenceNoticed.add(canonicalPath);
+	recordConfigMigrationNotice(
+		canonicalPath,
+		`pi-sync settings migrated from ${LEGACY_CONFIG_FILE_NAME} to ${CONFIG_FILE_NAME}; the private legacy file was retained as a recovery copy and can be deleted after verification.`,
+	);
+	return canonicalPath;
+}
+
+async function secureIgnoredLegacyIfPresent(filePath: string) {
+	let pathStat: Awaited<ReturnType<typeof fs.lstat>>;
+	try {
+		pathStat = await fs.lstat(filePath);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing" as const;
+		return "unsafe" as const;
+	}
+	if (pathStat.isSymbolicLink() || !pathStat.isFile()) return "unsafe" as const;
+
+	let handle: fs.FileHandle | undefined;
+	try {
+		handle = await fs.open(filePath, "r");
+		const openedStat = await handle.stat();
+		if (openedStat.dev !== pathStat.dev || openedStat.ino !== pathStat.ino) {
+			return "unsafe" as const;
+		}
+		if (process.platform !== "win32" && (openedStat.mode & 0o777) !== 0o600) {
+			await handle.chmod(0o600);
+		}
+		return "private" as const;
+	} catch {
+		return "unsafe" as const;
+	} finally {
+		await handle?.close().catch(() => undefined);
+	}
+}
+
+async function readConfigSnapshotIfExists(filePath: string): Promise<ConfigSnapshot | undefined> {
+	let pathStat: Awaited<ReturnType<typeof fs.lstat>>;
+	try {
+		pathStat = await fs.lstat(filePath);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+	if (pathStat.isSymbolicLink()) {
+		throw new Error(`Refusing to read symlinked pi-sync config: ${filePath}`);
+	}
+	if (!pathStat.isFile()) throw new Error(`pi-sync config is not a regular file: ${filePath}`);
+
+	const handle = await fs.open(filePath, "r");
+	try {
+		const openedStat = await handle.stat();
+		if (openedStat.dev !== pathStat.dev || openedStat.ino !== pathStat.ino) {
+			throw new Error(`pi-sync config changed while opening: ${filePath}`);
+		}
+		if (process.platform !== "win32" && (openedStat.mode & 0o777) !== 0o600) {
+			await handle.chmod(0o600);
+		}
+		const bytes = await handle.readFile();
+		return {
+			bytes,
+			identity: { dev: openedStat.dev, ino: openedStat.ino },
+			parsed: parseConfigObject(bytes, filePath),
+		};
+	} finally {
+		await handle.close();
+	}
+}
+
+function parseConfigObject(bytes: Buffer, filePath: string) {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(bytes.toString("utf8"));
+	} catch {
+		throw new SyntaxError(`Invalid JSON in pi-sync config: ${filePath}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`pi-sync config must contain a JSON object: ${filePath}`);
+	}
+	return parsed as Record<string, unknown>;
+}
+
+async function installPrivateConfigExclusively(
+	filePath: string,
+	bytes: Buffer,
+	allowCopyFallback = false,
+) {
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	const temporaryPath = path.join(
+		path.dirname(filePath),
+		`.${path.basename(filePath)}.${process.pid}.${randomUUID()}.migrate`,
+	);
+	let handle: fs.FileHandle | undefined;
+	try {
+		handle = await fs.open(temporaryPath, "wx", 0o600);
+		await handle.writeFile(bytes);
+		if (process.platform !== "win32") await handle.chmod(0o600);
+		await handle.sync();
+		await handle.close();
+		handle = undefined;
+		try {
+			await linkConfigFile(temporaryPath, filePath);
+		} catch (error) {
+			if (!allowCopyFallback || !isUnsupportedLinkError(error)) throw error;
+			await fs.copyFile(temporaryPath, filePath, fsConstants.COPYFILE_EXCL);
+		}
+		const installed = await fs.lstat(filePath);
+		try {
+			if (process.platform !== "win32") await fs.chmod(filePath, 0o600);
+			await syncParentDirectory(filePath).catch(() => undefined);
+		} catch (error) {
+			await quarantineAndRemoveConfigIfMatchesUnlocked(
+				filePath,
+				{ dev: installed.dev, ino: installed.ino },
+				bytes,
+			);
+			throw error;
+		}
+		return { dev: installed.dev, ino: installed.ino };
+	} finally {
+		await handle?.close().catch(() => undefined);
+		await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+	}
+}
+
+async function configDocumentStillMatches(document: LocalConfigDocument) {
+	return fileIdentityAndContentsMatch(document.path, document.identity, document.bytes);
+}
+
+async function claimCanonicalConfigDocument(document: LocalConfigDocument) {
+	const quarantinePath = path.join(
+		path.dirname(document.path),
+		`.${path.basename(document.path)}.${randomUUID()}.schema-migration-source`,
+	);
+	try {
+		await fs.rename(document.path, quarantinePath);
+		await syncParentDirectory(document.path);
+	} catch (error) {
+		await restoreQuarantinedConfig(document.path, quarantinePath);
+		throw error;
+	}
+	if (!(await fileIdentityAndContentsMatch(quarantinePath, document.identity, document.bytes))) {
+		await restoreQuarantinedConfig(document.path, quarantinePath);
+		throw settingsChangedError();
+	}
+	if (await pathExists(document.path)) {
+		await restoreQuarantinedConfig(document.path, quarantinePath);
+		throw new Error("Canonical settings changed concurrently; no settings were replaced.");
+	}
+	return quarantinePath;
+}
+
+function settingsChangedError() {
+	return new Error("pi-sync settings changed during migration; no settings were replaced.");
+}
+
+function isUnsupportedLinkError(error: unknown) {
+	const code = (error as NodeJS.ErrnoException).code;
+	return code === "ENOTSUP" || code === "EOPNOTSUPP" || code === "EXDEV" || code === "EPERM";
+}
+
+async function configSnapshotStillMatches(filePath: string, snapshot: ConfigSnapshot) {
+	return fileIdentityAndContentsMatch(filePath, snapshot.identity, snapshot.bytes);
+}
+
+export function quarantineAndRemoveConfigIfMatches(
+	filePath: string,
+	identity: FileIdentity,
+	expectedBytes: Buffer,
+) {
+	return withLocalConfigFileLock(() =>
+		quarantineAndRemoveConfigIfMatchesUnlocked(filePath, identity, expectedBytes),
+	);
+}
+
+async function quarantineAndRemoveConfigIfMatchesUnlocked(
+	filePath: string,
+	identity: FileIdentity,
+	expectedBytes: Buffer,
+) {
+	const quarantinePath = path.join(
+		path.dirname(filePath),
+		`.${path.basename(filePath)}.${randomUUID()}.migration-retired`,
+	);
+	try {
+		await fs.rename(filePath, quarantinePath);
+	} catch {
+		return false;
+	}
+	await afterConfigQuarantinedHook();
+	try {
+		await syncParentDirectory(filePath);
+	} catch {
+		await restoreQuarantinedConfig(filePath, quarantinePath);
+		return false;
+	}
+
+	const matches = await fileIdentityAndContentsMatch(quarantinePath, identity, expectedBytes);
+	if (!matches) {
+		await restoreQuarantinedConfig(filePath, quarantinePath);
+		return false;
+	}
+	if (await pathExists(filePath)) {
+		await fs.rm(quarantinePath, { force: true });
+		await syncParentDirectory(filePath);
+		return false;
+	}
+	await fs.rm(quarantinePath);
+	await syncParentDirectory(filePath);
+	return true;
+}
+
+async function fileIdentityAndContentsMatch(
+	filePath: string,
+	identity: FileIdentity,
+	expectedBytes: Buffer,
+) {
+	try {
+		const current = await fs.lstat(filePath);
+		if (current.isSymbolicLink()) return false;
+		if (current.dev !== identity.dev || current.ino !== identity.ino) return false;
+		return (await fs.readFile(filePath)).equals(expectedBytes);
+	} catch {
+		return false;
+	}
+}
+
+async function restoreQuarantinedConfig(filePath: string, quarantinePath: string) {
+	try {
+		await linkConfigFile(quarantinePath, filePath);
+		await fs.rm(quarantinePath);
+		await syncParentDirectory(filePath);
+		return;
+	} catch (error) {
+		if (isUnsupportedLinkError(error)) {
+			try {
+				await fs.copyFile(quarantinePath, filePath, fsConstants.COPYFILE_EXCL);
+				if (process.platform !== "win32") {
+					await fs.chmod(filePath, 0o600);
+					await fs.chmod(quarantinePath, 0o600);
+				}
+				await syncParentDirectory(filePath);
+				return;
+			} catch (copyError) {
+				if ((copyError as NodeJS.ErrnoException).code !== "EEXIST") return;
+			}
+		} else if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+			return;
+		}
+	}
+	try {
+		const [current, quarantined] = await Promise.all([
+			fs.readFile(filePath),
+			fs.readFile(quarantinePath),
+		]);
+		if (current.equals(quarantined)) await fs.rm(quarantinePath);
+		else if (process.platform !== "win32") await fs.chmod(quarantinePath, 0o600);
+		await syncParentDirectory(filePath);
+	} catch {
+		// Preserve the quarantine rather than risk deleting settings that changed concurrently.
+	}
+}
+
+export async function withLocalConfigFileLock<T>(run: () => Promise<T>): Promise<T> {
+	const configPath = localConfigPath();
+	await fs.mkdir(path.dirname(configPath), { recursive: true });
+	let compromisedError: Error | undefined;
+	const release = await lockfile.lock(configPath, {
+		fs: LOCKFILE_FS_ADAPTER,
+		lockfilePath: `${configPath}.mutation-lock`,
+		realpath: false,
+		stale: CONFIG_LOCK_STALE_MS,
+		update: CONFIG_LOCK_UPDATE_MS,
+		retries: { retries: 100, factor: 1.2, minTimeout: 10, maxTimeout: 100 },
+		onCompromised: (error) => {
+			compromisedError = error;
+		},
+	});
+	try {
+		const result = await run();
+		if (compromisedError) throw compromisedError;
+		return result;
+	} finally {
+		await release();
+	}
+}
+
+async function syncParentDirectory(filePath: string) {
+	if (process.platform === "win32") return;
+	let handle: fs.FileHandle | undefined;
+	try {
+		handle = await fs.open(path.dirname(filePath), "r");
+		await handle.sync();
+	} finally {
+		await handle?.close().catch(() => undefined);
+	}
+}
+
+async function pathExists(filePath: string) {
+	try {
+		await fs.lstat(filePath);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+function recordConfigMigrationNotice(configPath: string, notice: string) {
+	if (!configMigrationNotices.has(configPath)) configMigrationNotices.set(configPath, notice);
+}

package/src/config.ts

@@ -7,6 +7,16 @@ import {
 	type ExtensionContext,
 	getAgentDir,
 } from "@earendil-works/pi-coding-agent";
+import {
+	activeLocalConfigPath,
+	consumeLocalConfigMigrationNotice,
+	legacyLocalConfigPath,
+	localConfigPath,
+	quarantineAndRemoveConfigIfMatches,
+	readMigratingLocalConfigDocument,
+	replaceLocalConfigDocument,
+	withLocalConfigFileLock,
+} from "./config-file.js";
 import { safeName } from "./paths.js";
 import { DEFAULT_SYNC_FILES, normalizeExtraFiles, normalizeSyncFiles } from "./sync-policy.js";
 import type {
@@ -25,6 +35,15 @@ const DEFAULT_PREFIX = "pi-sync";
 const DEFAULT_REGION = "auto";
 export const DEFAULT_TARGET_SWITCH_ACTION: TargetSwitchAction = "ask";
 
+export {
+	activeLocalConfigPath,
+	consumeLocalConfigMigrationNotice,
+	legacyLocalConfigPath,
+	localConfigPath,
+	quarantineAndRemoveConfigIfMatches,
+	replaceLocalConfigDocument,
+};
+
 export const DEPRECATED_PI_SYNC_ENV_NAMES = [
 	"PI_SYNC_ENDPOINT",
 	"PI_SYNC_BUCKET",
@@ -491,10 +510,6 @@ export function stateDir() {
 	return path.join(agentDir(), ".pisync");
 }
 
-export function localConfigPath() {
-	return path.join(agentDir(), "pi-sync.local.json");
-}
-
 export function localConfigTemplate(): Record<string, unknown> {
 	return {
 		version: 2,
@@ -524,22 +539,91 @@ export function localConfigTemplate(): Record<string, unknown> {
 	};
 }
 
+export async function readLocalConfigDocument() {
+	return readMigratingLocalConfigDocument(validateConfigDocumentForMigration);
+}
+
 export async function readLocalConfigObject(): Promise<Record<string, unknown> | undefined> {
-	const configPath = localConfigPath();
-	try {
-		const stat = await fs.lstat(configPath);
-		if (stat.isSymbolicLink())
-			throw new Error(`Refusing to read symlinked pi-sync config: ${configPath}`);
-		if (!stat.isFile()) throw new Error(`pi-sync config is not a regular file: ${configPath}`);
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
-		throw error;
+	return (await readLocalConfigDocument())?.parsed;
+}
+
+function validateConfigDocumentForMigration(settings: Record<string, unknown>) {
+	if (!isV2SettingsObject(settings)) {
+		for (const field of [
+			"endpoint",
+			"bucket",
+			"region",
+			"accessKeyId",
+			"secretAccessKey",
+			"sessionToken",
+			"profile",
+			"prefix",
+		] as const) {
+			asOptionalString(settings[field]);
+		}
+		for (const field of ["autoSync", "syncSessions"] as const) {
+			const value = settings[field];
+			if (value !== undefined && typeof value !== "boolean" && typeof value !== "string") {
+				throw new Error(`Invalid pi-sync settings: ${field} must be a boolean or string.`);
+			}
+		}
+		normalizeSyncFiles(settings.syncFiles);
+		normalizeExtraFiles(settings.extraFiles);
+		return;
+	}
+
+	normalizeTargetSwitchAction(settings.targetSwitchAction);
+	const profiles = requireNamedObjectMap(settings.profiles, "profiles");
+	const targets = requireNamedObjectMap(settings.targets, "targets");
+	validateUniqueRemoteTargets(targets);
+	for (const [name, value] of Object.entries(profiles)) {
+		const profile = ownObject(profiles, name);
+		if (!profile || value !== profile) {
+			throw new Error(`Invalid pi-sync settings: storage profile "${name}" must be an object.`);
+		}
+		const kind = asOptionalString(profile.kind);
+		if (kind !== undefined && kind !== "r2" && kind !== "s3-compatible") {
+			throw new Error(
+				`Invalid pi-sync settings: profile "${name}" has unsupported kind "${kind}".`,
+			);
+		}
+		for (const field of [
+			"endpoint",
+			"region",
+			"accessKeyId",
+			"secretAccessKey",
+			"sessionToken",
+		] as const) {
+			asOptionalString(profile[field]);
+		}
 	}
-	const parsed = JSON.parse(await fs.readFile(configPath, "utf8")) as unknown;
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-		throw new Error(`pi-sync config must contain a JSON object: ${configPath}`);
+	for (const [name, value] of Object.entries(targets)) {
+		const target = ownObject(targets, name);
+		if (!target || value !== target) {
+			throw new Error(`Invalid pi-sync settings: target "${name}" must be an object.`);
+		}
+		const profileName = normalizeOptionalString(asOptionalString(target.profile));
+		if (!profileName || !Object.hasOwn(profiles, profileName)) {
+			throw new Error(`Invalid pi-sync settings: target "${name}" references a missing profile.`);
+		}
+		for (const field of ["bucket", "prefix", "namespace"] as const) {
+			asOptionalString(target[field]);
+		}
+		asOptionalBoolean(target.autoSync);
+		asOptionalBoolean(target.syncSessions);
+		normalizeSyncFiles(target.syncFiles);
+		normalizeExtraFiles(target.extraFiles);
+	}
+	const activeTarget = normalizeOptionalString(asOptionalString(settings.activeTarget));
+	if (Object.keys(targets).length === 0) {
+		if (activeTarget) {
+			throw new Error("Invalid pi-sync settings: targetless settings cannot have activeTarget.");
+		}
+		return;
+	}
+	if (!activeTarget || !Object.hasOwn(targets, activeTarget)) {
+		throw new Error("Invalid pi-sync settings: activeTarget must reference an existing target.");
 	}
-	return parsed as Record<string, unknown>;
 }
 
 let configUpdateQueue: Promise<void> = Promise.resolve();
@@ -564,7 +648,11 @@ async function performLocalConfigUpdate(
 	return next;
 }
 
-export async function writeLocalConfigObject(value: Record<string, unknown>) {
+export function writeLocalConfigObject(value: Record<string, unknown>) {
+	return withLocalConfigFileLock(() => writeLocalConfigObjectUnlocked(value));
+}
+
+async function writeLocalConfigObjectUnlocked(value: Record<string, unknown>) {
 	const configPath = localConfigPath();
 	await fs.mkdir(path.dirname(configPath), { recursive: true });
 	try {

package/src/manager-ui.ts

@@ -1,6 +1,7 @@
 import { BorderedLoader, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { setSyncTargetCompletions } from "./command.js";
 import {
+	activeLocalConfigPath,
 	configuredTargetNames,
 	deprecatedPiSyncEnvironmentWarnings,
 	isCloudflareR2Endpoint,
@@ -10,6 +11,7 @@ import {
 	localConfigPath,
 	normalizeSyncFiles,
 	readLocalConfigObject,
+	readStateForConfig,
 } from "./config.js";
 import { inspectLock, isStaleLock } from "./lock.js";
 import {
@@ -28,18 +30,25 @@ import { type TargetPullOutcome, useSyncTarget } from "./target-switch.js";
 import type { SyncConfig } from "./types.js";
 
 export const MAIN_MENU_ACTIONS = [
-	"Sync now",
+	"Sync now (recommended)",
+	"Pull from remote",
+	"Push to remote",
 	"Switch target",
 	"Status & changes",
 	"Settings",
+	"More…",
+] as const;
+
+const MORE_MENU_ACTIONS = [
 	"Manage targets & storage",
 	"History & recovery",
 	"Help",
+	"Back",
 ] as const;
-
 const BACK = "Back";
 
 type MainMenuAction = (typeof MAIN_MENU_ACTIONS)[number];
+type ContextualMenuAction = "Manage targets & storage" | "History & recovery" | "Help";
 type RunRoute = (
 	route: string,
 	signal?: AbortSignal,
@@ -59,10 +68,34 @@ export async function showSyncManager(
 		const state = await describeManagerState();
 		const selected = await ctx.ui.select(state.title, state.actions);
 		if (!selected) return;
-		switch (selected as MainMenuAction | "Set up sync" | "Use existing settings") {
-			case "Sync now":
+		switch (
+			selected as MainMenuAction | ContextualMenuAction | "Set up sync" | "Use existing settings"
+		) {
+			case "Sync now (recommended)":
 				await runCancellableOperation(ctx, "Checking current target…", "sync", runRoute, true);
 				break;
+			case "Pull from remote": {
+				const result = await runCancellableOperation(
+					ctx,
+					"Checking remote changes…",
+					"pull",
+					runRoute,
+					true,
+					"Pull check cancelled; no local files were changed.",
+				);
+				if (result === "applied") return;
+				break;
+			}
+			case "Push to remote":
+				await runCancellableOperation(
+					ctx,
+					"Preparing push preview…",
+					"push",
+					runRoute,
+					true,
+					"Push preparation cancelled; no remote files were changed.",
+				);
+				break;
 			case "Switch target": {
 				const result = await showTargetSwitcher(ctx, runRoute);
 				if (result === "pull-attempted") return;
@@ -75,23 +108,37 @@ export async function showSyncManager(
 			case "Settings":
 				await showSyncSettings(ctx, runRoute);
 				break;
+			case "More…":
+				if ((await showMoreMenu(ctx, runRoute)) === "exit") return;
+				break;
 			case "Manage targets & storage":
 				await showManageMenu(ctx, runRoute);
 				break;
 			case "History & recovery":
 				await showRecoveryMenu(ctx, runRoute);
 				break;
+			case "Help":
+				await runRoute("help");
+				return;
 			case "Set up sync":
 			case "Use existing settings":
 				await runRoute("init");
 				continue;
-			case "Help":
-				await runRoute("help");
-				return;
 		}
 	}
 }
 
+async function showMoreMenu(ctx: ExtensionCommandContext, runRoute: RunRoute) {
+	const selected = await ctx.ui.select("More options", [...MORE_MENU_ACTIONS]);
+	if (!selected || selected === BACK) return;
+	if (selected === "Manage targets & storage") await showManageMenu(ctx, runRoute);
+	else if (selected === "History & recovery") await showRecoveryMenu(ctx, runRoute);
+	else {
+		await runRoute("help");
+		return "exit" as const;
+	}
+}
+
 async function runCancellableOperation(
 	ctx: ExtensionCommandContext,
 	message: string,
@@ -158,7 +205,7 @@ async function describeManagerState(): Promise<{ title: string; actions: string[
 				"",
 				"Settings file needs repair. Automatic sync and settings writes are paused.",
 				`Error: ${safeTerminalText(errorMessage(error))}`,
-				`File: ${safeTerminalText(localConfigPath())}`,
+				`File: ${safeTerminalText(await activeLocalConfigPath())}`,
 				"",
 				"Repair the JSON file, then reopen /sync.",
 			].join("\n"),
@@ -194,15 +241,34 @@ async function describeManagerState(): Promise<{ title: string; actions: string[
 		const liveLock = lock.status === "valid" && !isStaleLock(lock.lock);
 		const recoverableLock =
 			lock.status === "unreadable" || (lock.status === "valid" && isStaleLock(lock.lock));
+		const builtInCount = normalizeSyncFiles(config.syncFiles).length;
+		const extraFileCount = config.extraFiles.length;
+		const noSyncedContent = builtInCount === 0 && extraFileCount === 0 && !config.syncSessions;
+		const stateReadDisabled = liveLock || recoverableLock;
+		const syncState = stateReadDisabled
+			? undefined
+			: await readStateForConfig(config).catch(() => undefined);
+		const lastAppliedSnapshot = stateReadDisabled
+			? "Unavailable while operations are locked"
+			: syncState?.lastAppliedSnapshot
+				? safeTerminalText(syncState.lastAppliedSnapshot)
+				: syncState
+					? "Never synced"
+					: "Unavailable";
 		return {
 			title: [
 				"Pi Sync",
 				"",
 				`Current target: ${safeTerminalText(target)}`,
 				`Storage: ${storage}`,
-				`Auto-sync: ${config.autoSync ? "On" : "Off"} · Sessions: ${config.syncSessions ? "On" : "Off"}`,
-				"Last known sync: Remote not checked",
+				`Synced content: ${builtInCount} built-in group${builtInCount === 1 ? "" : "s"} · ${extraFileCount} extra file${extraFileCount === 1 ? "" : "s"} · Sessions: ${config.syncSessions ? "On" : "Off"}`,
+				`Auto-sync: ${config.autoSync ? "On" : "Off"}`,
+				`Last applied snapshot: ${lastAppliedSnapshot}`,
+				"Remote changes: Not checked",
 				...warnings.map((warning) => `Warning: ${safeTerminalText(warning)}`),
+				...(noSyncedContent
+					? ["", "No synced content is selected. Choose synced content in Settings before syncing."]
+					: []),
 				...(liveLock
 					? [
 							"",
@@ -218,7 +284,9 @@ async function describeManagerState(): Promise<{ title: string; actions: string[
 			actions:
 				liveLock || recoverableLock
 					? ["Status & changes", "History & recovery", "Help"]
-					: [...MAIN_MENU_ACTIONS],
+					: noSyncedContent
+						? ["Settings", "Switch target", "Status & changes", "More…"]
+						: [...MAIN_MENU_ACTIONS],
 		};
 	} catch (error) {
 		const targets = ownRecord(raw.targets);
@@ -229,7 +297,7 @@ async function describeManagerState(): Promise<{ title: string; actions: string[
 				"Settings need attention. Automatic sync is paused.",
 				`Current target: ${safeTerminalText(typeof raw.activeTarget === "string" ? raw.activeTarget : "default")}`,
 				`Error: ${safeTerminalText(errorMessage(error))}`,
-				`File: ${safeTerminalText(localConfigPath())}`,
+				`File: ${safeTerminalText(await activeLocalConfigPath())}`,
 				"",
 				"What do you want to do?",
 			].join("\n"),

package/src/paths.ts

@@ -14,7 +14,12 @@ export function isDeniedPath(relativePath: string) {
 		base.endsWith(".env") ||
 		base.includes("secret") ||
 		base.includes("token") ||
-		base === "pi-sync.local.json"
+		base === "pi-sync.json" ||
+		base.startsWith("pi-sync.json.") ||
+		base.startsWith(".pi-sync.json.") ||
+		base === "pi-sync.local.json" ||
+		base.startsWith("pi-sync.local.json.") ||
+		base.startsWith(".pi-sync.local.json.")
 	);
 }
 

package/src/settings-management.ts

@@ -5,7 +5,9 @@ import {
 	DEFAULT_TARGET_SWITCH_ACTION,
 	effectiveTargetRemoteIdentity,
 	localConfigPath,
+	readLocalConfigDocument,
 	readLocalConfigObject,
+	replaceLocalConfigDocument,
 	resolveLegacyPartialConfig,
 	resolveV2PartialConfig,
 	stateDir,
@@ -15,6 +17,21 @@ import {
 import { withLock } from "./lock.js";
 import type { PartialConfig, StorageProfileSettings, SyncTargetSettings } from "./types.js";
 
+let afterLegacySettingsReadHook: () => Promise<void> = async () => undefined;
+
+export async function withLegacySettingsReadHookForTest<T>(
+	hook: () => Promise<void>,
+	run: () => Promise<T>,
+) {
+	const previous = afterLegacySettingsReadHook;
+	afterLegacySettingsReadHook = hook;
+	try {
+		return await run();
+	} finally {
+		afterLegacySettingsReadHook = previous;
+	}
+}
+
 const LEGACY_FIELDS = new Set([
 	"endpoint",
 	"bucket",
@@ -42,21 +59,17 @@ export async function migrateLegacySettings(
 	validateName(targetName, "target");
 	validateName(storageProfileName, "storage profile");
 	return withLock("settings-migration", async () => {
-		const configPath = localConfigPath();
-		const originalBytes = await fs.readFile(configPath);
-		const current = await readLocalConfigObject();
-		if (!current) throw new Error("No legacy pi-sync settings are available to migrate.");
+		const document = await readLocalConfigDocument();
+		if (!document) throw new Error("No legacy pi-sync settings are available to migrate.");
+		const { bytes: originalBytes, parsed: current } = document;
 		if (current.version === 2) {
 			throw new Error("pi-sync settings already use profiles and targets.");
 		}
+		await afterLegacySettingsReadHook();
 		const next = legacySettingsAsV2(current, targetName, storageProfileName);
 		const backupPath = await writeMigrationBackup(originalBytes);
 		await adoptLegacyState(current, next, targetName);
-		const latestBytes = await fs.readFile(configPath);
-		if (!latestBytes.equals(originalBytes)) {
-			throw new Error("pi-sync settings changed during migration; no settings were replaced.");
-		}
-		await writeLocalConfigObject(next);
+		await replaceLocalConfigDocument(document, next);
 		return { settings: next, backupPath };
 	});
 }

package/src/sync.ts

@@ -1,4 +1,3 @@
-import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
@@ -17,7 +16,9 @@ import {
 	validateCommandOptions,
 } from "./command.js";
 import {
+	activeLocalConfigPath,
 	configuredTargetNames,
+	consumeLocalConfigMigrationNotice,
 	deprecatedPiSyncEnvironmentWarnings,
 	ensureStateDir,
 	isEnabled,
@@ -29,6 +30,7 @@ import {
 	localConfigTemplate,
 	normalizeExtraFiles,
 	normalizeSyncFiles,
+	readLocalConfigObject,
 	readStateForConfig,
 	sessionDirForApply,
 	sessionTokenWarnings,
@@ -142,6 +144,8 @@ export default function sync(pi: ExtensionAPI) {
 		} catch {
 			setSyncTargetCompletions([]);
 		}
+		const migrationNotice = consumeLocalConfigMigrationNotice();
+		if (migrationNotice) ctx.ui.notify(migrationNotice, "warning");
 		const warnings = deprecatedPiSyncEnvironmentWarnings();
 		if (warnings.length > 0) ctx.ui.notify(warnings.join("\n"), "warning");
 		await autoSync(ctx);
@@ -279,12 +283,9 @@ async function autoPushSessions(ctx: ExtensionContext) {
 
 async function initConfig(ctx: ExtensionCommandContext) {
 	const configPath = localConfigPath();
-	try {
-		await fs.access(configPath, fsConstants.F_OK);
-		ctx.ui.notify(`Config already exists: ${configPath}`, "info");
+	if (await readLocalConfigObject()) {
+		ctx.ui.notify(`Config already exists: ${await activeLocalConfigPath()}`, "info");
 		return;
-	} catch {
-		// Create or guide setup below.
 	}
 
 	if (ctx.mode === "tui") {