@narumitw/pi-sync 0.49.4 → 0.49.5

package/README.md

@@ -252,6 +252,7 @@ The menu is preferred, while deterministic routes remain available:
 /sync sync [--setup <name>]
 /sync history [--setup <name>]
 /sync rollback <snapshot-id> [--setup <name>]
+/sync migrate-state [--yes]
 /sync unlock --stale
 ```
 
@@ -274,17 +275,19 @@ dialog/notification protocol and does not gain settings mutation. Print and JSON
 | WebDAV | Verified strong conditional requests | Private settings username/app password | `<url>/<storage.path>` |
 | R2/S3 | Read-check-write-verify | Private settings credentials | `<bucket>/<storage.path>` |
 
-Git requires Git 2.30 or newer and a SHA-1-format remote repository. HTTPS userinfo, URL passwords, local paths, `file`, `git`, `ext`, and remote-helper transports are rejected. When editing a Git setup, changing its storage path also requires a new owned branch so the existing branch remains readable at its reviewed path. The private bare cache under `.pisync/git/` is rebuildable.
+Git requires Git 2.30 or newer and a SHA-1-format remote repository. HTTPS userinfo, URL passwords, local paths, `file`, `git`, `ext`, and remote-helper transports are rejected. When editing a Git setup, changing its storage path also requires a new owned branch so the existing branch remains readable at its reviewed path. The private bare cache under `<agent-dir>/pi-sync/git/` is rebuildable.
 
 WebDAV requires HTTPS except loopback tests. URL credentials, query strings, fragments, unsafe redirects, weak/missing ETags, and ignored conditional headers fail closed. `/sync doctor` verifies collection and conditional-write behavior with an isolated probe.
 
 S3/R2 stages immutable bundles, rechecks the visible head before publication, and verifies afterward. Unlike Git/WebDAV, generic S3 does not provide an atomic compare-and-swap for `latest.json`; status review remains important for simultaneous writers.
 
-Before pull or rollback, pi-sync writes a backup under `.pisync/backups/`. Apply preflights paths and checksums, journals all mutations, restores the prior state after failures, and recovers interrupted journals on startup. Removing a local setup or connection never deletes remote data.
+Before pull or rollback, pi-sync writes a backup under `<agent-dir>/pi-sync/backups/`. Apply preflights paths and checksums, journals all mutations, restores the prior state after failures, and recovers interrupted journals on startup. Removing a local setup or connection never deletes remote data.
+
+The operational state root is `<agent-dir>/pi-sync/`. An existing installation continues using `<agent-dir>/.pisync/` and shows migration guidance on startup; it is never moved merely because no sync is active. Close every other Pi process, then run `/sync migrate-state` and confirm the review (or pass `--yes` for an already reviewed RPC workflow). The command serializes against every upgraded state/cache user and atomically renames `.pisync/` only when no legacy sync lock or guard is active. Close Pi instances running older pi-sync versions during the migration because they do not understand the migration guard. If both roots exist, or either root is a symlink or non-directory, pi-sync refuses stateful work instead of merging, following, or deleting data. Preserve both roots before manual recovery; with every Pi process closed and no destination conflict, rollback is an atomic rename from `pi-sync/` back to `.pisync/`.
 
 ## 🛡️ Safety notes
 
-- Canonical, legacy, temporary, and recovery settings paths are denied from snapshots.
+- Canonical, legacy, temporary, and recovery settings paths are denied from snapshots; both `pi-sync/` and `.pisync/` state roots are permanently denied.
 - Push scans managed local content for common secret patterns.
 - Remote snapshot references, checksums, paths, manifests, response sizes, and publication revisions are validated.
 - Symlink parents, path escapes, duplicate paths, and unsafe file/directory replacement fail before local mutation.
@@ -305,6 +308,7 @@ packages/pi-sync/
 │   ├── sync.ts
 │   ├── config.ts
 │   ├── config-file.ts
+│   ├── state-directory.ts
 │   ├── settings-management.ts
 │   ├── manager-ui.ts
 │   ├── storage-connections-ui.ts

package/package.json

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

package/src/command.ts

@@ -19,6 +19,7 @@ export const SYNC_COMMANDS = [
 	{ name: "sync", description: "Push or pull as needed" },
 	{ name: "history", description: "Show recent remote snapshots" },
 	{ name: "rollback", description: "Apply a previous snapshot", usageSuffix: " <snapshot>" },
+	{ name: "migrate-state", description: "Move legacy state into pi-sync/" },
 	{ name: "unlock", description: "Remove a stale local lock", usageSuffix: " --stale" },
 ] as const;
 
@@ -60,6 +61,7 @@ const SYNC_FLAG_COMPLETIONS: Record<string, readonly CommandArgumentCompletion[]
 	],
 	history: [SETUP_FLAG_COMPLETION],
 	rollback: [...YES_FLAG_COMPLETIONS, SETUP_FLAG_COMPLETION],
+	"migrate-state": YES_FLAG_COMPLETIONS,
 	unlock: [{ value: "--stale", label: "--stale", description: "Remove only a stale lock" }],
 };
 
@@ -119,7 +121,10 @@ export function validateCommandOptions(command: string, options: CommandOptions)
 	if (options.setup && !setupAllowed.has(command)) {
 		throw new Error(`--setup is not supported by /sync ${command}.`);
 	}
-	if ((options.yes || options.force) && !["push", "pull", "sync", "rollback"].includes(command)) {
+	if (options.yes && !["push", "pull", "sync", "rollback", "migrate-state"].includes(command)) {
+		throw new Error(`Confirmation/force options are not supported by /sync ${command}.`);
+	}
+	if (options.force && !["push", "pull", "sync", "rollback"].includes(command)) {
 		throw new Error(`Confirmation/force options are not supported by /sync ${command}.`);
 	}
 	if (options.stale && command !== "unlock") {

package/src/config.ts

@@ -26,6 +26,7 @@ import {
 	normalizeGitRemoteIdentity,
 } from "./git-config.js";
 import { safeName } from "./paths.js";
+import { stateDir } from "./state-directory.js";
 import { normalizeSyncInclude } from "./sync-policy.js";
 import type {
 	AnySyncConfig,
@@ -751,9 +752,7 @@ function expandHome(value: string) {
 	return value === "~" || value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
 }
 
-export function stateDir() {
-	return path.join(agentDir(), ".pisync");
-}
+export { stateDir } from "./state-directory.js";
 
 export function localConfigTemplate(): PiSyncSettingsV3 {
 	return {

package/src/git-backend.ts

@@ -1,7 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import {
 	normalizeGitBranch,
 	normalizeGitDirectory,
@@ -23,6 +22,7 @@ import {
 	validateGitSnapshot,
 } from "./git-storage.js";
 import { posixJoin } from "./paths.js";
+import { stateDir } from "./state-directory.js";
 import {
 	type BackendDiagnostic,
 	type ExpectedRemoteHead,
@@ -74,7 +74,7 @@ export class GitSyncBackend implements SyncBackend {
 		if (!this.allowLocalRemotes) assertProductionRemote(config.profile.remote);
 		this.identity = gitBackendIdentity(config);
 		this.destination = gitDestination(config);
-		this.cacheRoot = options.cacheRoot ?? path.join(getAgentDir(), ".pisync", "git");
+		this.cacheRoot = options.cacheRoot ?? path.join(stateDir(), "git");
 		this.cacheDir = path.join(this.cacheRoot, this.identity.slice("git:".length), "repository.git");
 		this.commandTimeoutMs = options.commandTimeoutMs ?? COMMAND_TIMEOUT_MS;
 		this.postCommitTimeoutMs = options.postCommitTimeoutMs ?? POST_COMMIT_TIMEOUT_MS;

package/src/lock-policy.ts

@@ -0,0 +1,2 @@
+export const LOCK_GUARD_STALE_MS = 30_000;
+export const LOCK_GUARD_UPDATE_MS = 10_000;

package/src/lock.ts

@@ -1,53 +1,15 @@
 import { randomUUID } from "node:crypto";
-import {
-	mkdir,
-	mkdirSync,
-	realpath,
-	realpathSync,
-	rmdir,
-	rmdirSync,
-	stat,
-	statSync,
-	utimes,
-	utimesSync,
-} from "node:fs";
 import fs from "node:fs/promises";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import lockfile from "proper-lockfile";
 import { ensureStateDir, lockPath } from "./config.js";
+import { LOCK_GUARD_STALE_MS, LOCK_GUARD_UPDATE_MS } from "./lock-policy.js";
+import { LOCKFILE_FS_ADAPTER } from "./lockfile-fs.js";
 import type { CommandOptions, LockFile } from "./types.js";
 
 const LOCK_STALE_MS = 30 * 60 * 1000;
-const GUARD_STALE_MS = 30_000;
-const GUARD_UPDATE_MS = 10_000;
 const MAX_PROCESS_ID = 2_147_483_647;
 
-type LockfileFsAdapter = {
-	mkdir: typeof mkdir;
-	mkdirSync: typeof mkdirSync;
-	realpath: typeof realpath;
-	realpathSync: typeof realpathSync;
-	rmdir: typeof rmdir;
-	rmdirSync: typeof rmdirSync;
-	stat: typeof stat;
-	statSync: typeof statSync;
-	utimes: typeof utimes;
-	utimesSync: typeof utimesSync;
-};
-
-const LOCKFILE_FS_ADAPTER: LockfileFsAdapter = {
-	mkdir,
-	mkdirSync,
-	realpath,
-	realpathSync,
-	rmdir,
-	rmdirSync,
-	stat,
-	statSync,
-	utimes,
-	utimesSync,
-};
-
 interface Guard {
 	release: () => Promise<void>;
 	throwIfCompromised: () => void;
@@ -175,7 +137,7 @@ export function isLockGuardHeld() {
 		fs: LOCKFILE_FS_ADAPTER,
 		lockfilePath: `${lockPath()}.guard`,
 		realpath: false,
-		stale: GUARD_STALE_MS,
+		stale: LOCK_GUARD_STALE_MS,
 	});
 }
 
@@ -267,8 +229,8 @@ async function acquireGuard(): Promise<Guard> {
 		fs: LOCKFILE_FS_ADAPTER,
 		lockfilePath: `${lockPath()}.guard`,
 		realpath: false,
-		stale: GUARD_STALE_MS,
-		update: GUARD_UPDATE_MS,
+		stale: LOCK_GUARD_STALE_MS,
+		update: LOCK_GUARD_UPDATE_MS,
 		onCompromised: (error) => {
 			compromisedError = error;
 		},

package/src/lockfile-fs.ts

@@ -0,0 +1,25 @@
+import {
+	mkdir,
+	mkdirSync,
+	realpath,
+	realpathSync,
+	rmdir,
+	rmdirSync,
+	stat,
+	statSync,
+	utimes,
+	utimesSync,
+} from "node:fs";
+
+export const LOCKFILE_FS_ADAPTER = {
+	mkdir,
+	mkdirSync,
+	realpath,
+	realpathSync,
+	rmdir,
+	rmdirSync,
+	stat,
+	statSync,
+	utimes,
+	utimesSync,
+};

package/src/paths.ts

@@ -9,6 +9,8 @@ export function isDeniedPath(relativePath: string) {
 		segments.includes("node_modules") ||
 		segments.includes(".git") ||
 		segments.includes(".pisync") ||
+		segments.includes("pi-sync") ||
+		segments.includes(".pi-sync-state-migration.lock") ||
 		base === ".env" ||
 		base.startsWith(".env.") ||
 		base.endsWith(".env") ||

package/src/state-directory.ts

@@ -0,0 +1,184 @@
+import { lstatSync } 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";
+import { LOCK_GUARD_STALE_MS } from "./lock-policy.js";
+import { LOCKFILE_FS_ADAPTER } from "./lockfile-fs.js";
+
+const CANONICAL_DIRECTORY_NAME = "pi-sync";
+const LEGACY_DIRECTORY_NAME = ".pisync";
+const MIGRATION_LOCK_NAME = ".pi-sync-state-migration.lock";
+const MIGRATION_LOCK_STALE_MS = 30_000;
+const MIGRATION_LOCK_UPDATE_MS = 10_000;
+
+export type StateDirectoryPreparation =
+	| { status: "ready" }
+	| { status: "migrated"; message: string }
+	| { status: "deferred"; message: string };
+
+interface StateDirectoryGuard {
+	release: () => Promise<void>;
+	throwIfCompromised: () => void;
+}
+
+export function stateDir() {
+	const roots = inspectStateRoots();
+	if (roots.canonical) return canonicalStateDir();
+	if (roots.legacy) return legacyStateDir();
+	return canonicalStateDir();
+}
+
+export function legacyStateDir() {
+	return path.join(getAgentDir(), LEGACY_DIRECTORY_NAME);
+}
+
+export function stateDirectoryMigrationNotice() {
+	const roots = inspectStateRoots();
+	if (!roots.legacy) return undefined;
+	return "Legacy pi-sync state is still stored in .pisync. Close other Pi sessions, then run /sync migrate-state to move it to pi-sync/.";
+}
+
+export async function withStateDirectoryAccess<T>(fn: () => Promise<T>): Promise<T> {
+	return runWithStateDirectoryGuard(await acquireStateDirectoryGuard(), fn);
+}
+
+export async function migrateLegacyStateDirectory(): Promise<StateDirectoryPreparation> {
+	const initial = inspectStateRoots();
+	if (initial.canonical || !initial.legacy) return { status: "ready" };
+
+	let guard: StateDirectoryGuard;
+	try {
+		guard = await acquireStateDirectoryGuard();
+	} catch (error) {
+		if (!isLockHeldError(error)) throw error;
+		return {
+			status: "deferred",
+			message:
+				"pi-sync state migration was deferred because another state user is active. Close other Pi sessions and retry.",
+		};
+	}
+	return runWithStateDirectoryGuard(guard, async () => {
+		const roots = inspectStateRoots();
+		if (roots.canonical || !roots.legacy) return { status: "ready" };
+
+		const legacyLock = path.join(legacyStateDir(), "lock");
+		const legacyGuardHeld = await lockfile.check(legacyLock, {
+			fs: LOCKFILE_FS_ADAPTER,
+			lockfilePath: `${legacyLock}.guard`,
+			realpath: false,
+			stale: LOCK_GUARD_STALE_MS,
+		});
+		if (legacyGuardHeld || (await pathExists(legacyLock))) {
+			return {
+				status: "deferred",
+				message:
+					"pi-sync state migration was deferred because the legacy directory is busy. Close other Pi sessions, clear any confirmed stale sync lock, and retry.",
+			};
+		}
+		guard.throwIfCompromised();
+		await fs.rename(legacyStateDir(), canonicalStateDir());
+		guard.throwIfCompromised();
+		inspectStateRoots();
+		return {
+			status: "migrated",
+			message: `Migrated pi-sync state from ${legacyStateDir()} to ${canonicalStateDir()}.`,
+		};
+	});
+}
+
+async function acquireStateDirectoryGuard(): Promise<StateDirectoryGuard> {
+	let compromisedError: Error | undefined;
+	const release = await lockfile.lock(getAgentDir(), {
+		fs: LOCKFILE_FS_ADAPTER,
+		lockfilePath: migrationLockPath(),
+		realpath: false,
+		stale: MIGRATION_LOCK_STALE_MS,
+		update: MIGRATION_LOCK_UPDATE_MS,
+		retries: { retries: 20, minTimeout: 10, maxTimeout: 50 },
+		onCompromised: (error) => {
+			compromisedError = error;
+		},
+	});
+	return {
+		release,
+		throwIfCompromised: () => {
+			if (compromisedError) throw compromisedError;
+		},
+	};
+}
+
+async function runWithStateDirectoryGuard<T>(guard: StateDirectoryGuard, fn: () => Promise<T>) {
+	let result: T | undefined;
+	let failed = false;
+	let failure: unknown;
+	try {
+		guard.throwIfCompromised();
+		result = await fn();
+		guard.throwIfCompromised();
+	} catch (error) {
+		failed = true;
+		failure = error;
+	}
+	try {
+		await guard.release();
+	} catch (error) {
+		if (!failed) {
+			failed = true;
+			failure = error;
+		}
+	}
+	if (failed) throw failure;
+	return result as T;
+}
+
+function isLockHeldError(error: unknown) {
+	return (error as NodeJS.ErrnoException).code === "ELOCKED";
+}
+
+function canonicalStateDir() {
+	return path.join(getAgentDir(), CANONICAL_DIRECTORY_NAME);
+}
+
+function migrationLockPath() {
+	return path.join(getAgentDir(), MIGRATION_LOCK_NAME);
+}
+
+function inspectStateRoots() {
+	const canonical = isDirectoryRoot(canonicalStateDir(), "canonical");
+	const legacy = isDirectoryRoot(legacyStateDir(), "legacy");
+	if (canonical && legacy) {
+		throw new Error(
+			`Both legacy ${legacyStateDir()} and canonical ${canonicalStateDir()} pi-sync state directories exist. Close all Pi sessions and reconcile the directories manually; pi-sync will not merge or delete either directory.`,
+		);
+	}
+	return { canonical, legacy };
+}
+
+function isDirectoryRoot(directory: string, label: string) {
+	try {
+		const entry = lstatSync(directory);
+		if (entry.isSymbolicLink()) {
+			throw new Error(
+				`Refusing to use ${label} pi-sync state directory symbolic link: ${directory}`,
+			);
+		}
+		if (!entry.isDirectory()) {
+			throw new Error(`${label} pi-sync state path is not a directory: ${directory}`);
+		}
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+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;
+	}
+}

package/src/sync.ts

@@ -9,6 +9,7 @@ import {
 	parseOptions,
 	resolveSyncCommand,
 	setSyncSetupCompletions,
+	splitArgs,
 	usage,
 	validateCommandOptions,
 } from "./command.js";
@@ -32,6 +33,11 @@ import { unlock, withLock } from "./lock.js";
 import { SetupPullRequiresUiError, useSyncSetup } from "./setup-switch.js";
 import { createSnapshot } from "./snapshot.js";
 import { recoverSnapshotTransactionsOnStartup } from "./snapshot-transaction.js";
+import {
+	migrateLegacyStateDirectory,
+	stateDirectoryMigrationNotice,
+	withStateDirectoryAccess,
+} from "./state-directory.js";
 import { isSyncDecisionRequiredError } from "./sync-decision.js";
 import { errorMessage } from "./sync-format.js";
 import { hasLocalChanges } from "./sync-state.js";
@@ -74,7 +80,9 @@ export default function sync(pi: ExtensionAPI) {
 					"/sync requires TUI or RPC mode so results and safety prompts are observable.",
 				);
 			}
-			await handleCommand(args, ctx, sessionAbort.signal);
+			const run = () => handleCommand(args, ctx, sessionAbort.signal);
+			if (splitArgs(args)[0] === "migrate-state") await run();
+			else await withStateDirectoryAccess(run);
 		},
 	});
 
@@ -86,24 +94,11 @@ export default function sync(pi: ExtensionAPI) {
 		const signal = sessionAbort.signal;
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 		try {
-			await recoverSnapshotTransactionsOnStartup();
-			if (signal.aborted) return;
+			await withStateDirectoryAccess(() => startSession(ctx, signal));
 		} catch (error) {
 			if (signal.aborted) return;
-			ctx.ui.notify(`pi-sync recovery required: ${errorMessage(error)}`, "error");
-			return;
-		}
-		try {
-			setSyncSetupCompletions(await configuredSyncSetupNames());
-			if (signal.aborted) return;
-		} catch {
-			if (signal.aborted) return;
-			setSyncSetupCompletions([]);
+			ctx.ui.notify(`pi-sync state access failed: ${errorMessage(error)}`, "error");
 		}
-		const migrationNotice = consumeLocalConfigMigrationNotice();
-		if (migrationNotice) ctx.ui.notify(migrationNotice, "warning");
-		if (signal.aborted) return;
-		await autoSync(ctx, signal);
 	});
 
 	pi.on("session_shutdown", async (event, ctx) => {
@@ -115,7 +110,16 @@ export default function sync(pi: ExtensionAPI) {
 		const reason =
 			typeof event === "object" && event ? (event as { reason?: string }).reason : undefined;
 		try {
-			if (reason !== "reload") await autoPushSessions(ctx, signal);
+			if (reason !== "reload") {
+				await withStateDirectoryAccess(async () => {
+					if (signal.aborted) return;
+					await autoPushSessions(ctx, signal);
+				});
+			}
+		} catch (error) {
+			if (!signal.aborted) {
+				ctx.ui.notify(`pi-sync session push skipped: ${errorMessage(error)}`, "warning");
+			}
 		} finally {
 			if (shutdownAbort === controller) shutdownAbort = undefined;
 		}
@@ -124,6 +128,36 @@ export default function sync(pi: ExtensionAPI) {
 	});
 }
 
+async function startSession(ctx: ExtensionContext, signal: AbortSignal) {
+	if (signal.aborted) return;
+	try {
+		const migrationNotice = stateDirectoryMigrationNotice();
+		if (migrationNotice) ctx.ui.notify(migrationNotice, "warning");
+	} catch (error) {
+		ctx.ui.notify(`pi-sync state directory requires attention: ${errorMessage(error)}`, "error");
+		return;
+	}
+	try {
+		await recoverSnapshotTransactionsOnStartup();
+		if (signal.aborted) return;
+	} catch (error) {
+		if (signal.aborted) return;
+		ctx.ui.notify(`pi-sync recovery required: ${errorMessage(error)}`, "error");
+		return;
+	}
+	try {
+		setSyncSetupCompletions(await configuredSyncSetupNames());
+		if (signal.aborted) return;
+	} catch {
+		if (signal.aborted) return;
+		setSyncSetupCompletions([]);
+	}
+	const migrationNotice = consumeLocalConfigMigrationNotice();
+	if (migrationNotice) ctx.ui.notify(migrationNotice, "warning");
+	if (signal.aborted) return;
+	await autoSync(ctx, signal);
+}
+
 async function handleCommand(
 	rawArgs: string,
 	ctx: ExtensionCommandContext,
@@ -237,6 +271,9 @@ async function executeCommand(
 				await withLock("rollback", () => operations.rollback(ctx, options));
 				return { kind: "completed" };
 			}
+			case "migrate-state":
+				await migrateStateDirectory(ctx, options);
+				return { kind: "completed" };
 			case "unlock":
 				await unlock(ctx, options);
 				return { kind: "completed" };
@@ -256,6 +293,33 @@ async function executeCommand(
 	}
 }
 
+async function migrateStateDirectory(ctx: ExtensionCommandContext, options: CommandOptions) {
+	const notice = stateDirectoryMigrationNotice();
+	if (!notice) {
+		ctx.ui.notify("pi-sync already uses the canonical pi-sync/ state directory.", "info");
+		return;
+	}
+	if (
+		!options.yes &&
+		!(await ctx.ui.confirm(
+			"Migrate pi-sync state directory",
+			"Confirm that every other Pi process is closed. pi-sync will atomically rename .pisync/ to pi-sync/ without merging or deleting either root.",
+			{ signal: options.signal },
+		))
+	) {
+		ctx.ui.notify("pi-sync state migration cancelled.", "info");
+		return;
+	}
+	throwIfAborted(options.signal);
+	const result = await migrateLegacyStateDirectory();
+	throwIfAborted(options.signal);
+	if (result.status === "ready") {
+		ctx.ui.notify("pi-sync already uses the canonical pi-sync/ state directory.", "info");
+		return;
+	}
+	ctx.ui.notify(result.message, result.status === "migrated" ? "info" : "warning");
+}
+
 async function autoSync(ctx: ExtensionContext, signal: AbortSignal) {
 	try {
 		const partial = await loadPartialConfig();