@narumitw/pi-sync 0.46.0 → 0.49.0

package/README.md

@@ -58,6 +58,29 @@ recovery. Secondary screens provide **Back**; Escape goes back and Ctrl+C closes
 Destructive, credential-bearing, and externally visible operations retain exact specialized previews
 and confirmations.
 
+### Resolve conflicts in the manager
+
+When **Sync now**, **Pull from remote…**, or **Push to remote…** finds changes that require a human
+direction choice, the manager opens **Resolve sync conflict** instead of ending at a command-only
+error. The flow names the current sync setup and explains whether local content, remote content, or
+the included-content policy changed.
+
+Choose **Review differences (recommended)** to inspect the exact affected paths without changing
+local files, remote data, or sync state. Then choose one reviewed direction:
+
+- **Keep local content and replace remote…** uses the existing forced-push path. It scans managed
+  local files for secrets, shows the exact remote publication effect, re-reads a changed remote head,
+  and asks again if the reviewed plan changed.
+- **Use remote content and replace local…** uses the existing forced-pull path. It shows exact local
+  writes and deletions, protects the live session, and creates a local backup before applying.
+- First sync uses **Use local as initial source…** and **Use remote as initial source…** labels. An
+  empty remote offers **Push local content…** only.
+
+Cancelling a preparation or confirmation returns to conflict resolution with no side effects. Back
+returns to the sync manager; Ctrl+C closes the complete flow. Automatic startup/shutdown sync never
+opens this interactive flow and continues to report an actionable warning. Deterministic direct
+routes remain available and keep their command-oriented error guidance.
+
 ## ⚙️ Settings
 
 The canonical private user file is:
@@ -269,6 +292,7 @@ extensions/pi-sync/
 │   ├── file-selection.ts
 │   ├── sync-operations.ts
 │   ├── sync-backend.ts
+│   ├── backend-factory.ts      # lazy selected-backend loader
 │   ├── s3-backend.ts
 │   ├── webdav-backend.ts
 │   ├── git-backend.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-sync",
-	"version": "0.46.0",
+	"version": "0.49.0",
 	"description": "Pi extension that syncs Pi configuration through Git, WebDAV, Cloudflare R2, or S3-compatible storage.",
 	"type": "module",
 	"license": "MIT",
@@ -36,7 +36,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@narumitw/pi-tui-kit": "^0.45.0",
+		"@narumitw/pi-tui-kit": "^0.46.0",
 		"fast-xml-parser": "^5.10.1",
 		"proper-lockfile": "^4.1.2"
 	},

package/src/backend-factory.ts

@@ -1,20 +1,23 @@
-import { GitSyncBackend } from "./git-backend.js";
-import { S3SyncBackend } from "./s3-backend.js";
 import type { SyncBackend } from "./sync-backend.js";
 import type { AnySyncConfig } from "./types.js";
-import { WebDavSyncBackend } from "./webdav-backend.js";
 
 export type SyncBackendFactory = {
-	bivarianceHack(config: AnySyncConfig): SyncBackend;
+	bivarianceHack(config: AnySyncConfig): SyncBackend | Promise<SyncBackend>;
 }["bivarianceHack"];
 
-export const createSyncBackend: SyncBackendFactory = (config) => {
+export const createSyncBackend: SyncBackendFactory = async (config) => {
 	switch (config.backend.type) {
-		case "s3":
+		case "s3": {
+			const { S3SyncBackend } = await import("./s3-backend.js");
 			return new S3SyncBackend(config.backend);
-		case "webdav":
+		}
+		case "webdav": {
+			const { WebDavSyncBackend } = await import("./webdav-backend.js");
 			return new WebDavSyncBackend(config.backend);
-		case "git":
+		}
+		case "git": {
+			const { GitSyncBackend } = await import("./git-backend.js");
 			return new GitSyncBackend(config.backend);
+		}
 	}
 };

package/src/cancellable-operation.ts

@@ -7,15 +7,24 @@ import { truncateToWidth } from "@earendil-works/pi-tui";
 import { runCustomInteraction } from "@narumitw/pi-tui-kit";
 import { safeTerminalText } from "./manager-helpers.js";
 import type { SetupPullOutcome } from "./setup-switch.js";
+import type { SyncDecision } from "./sync-decision.js";
+
+export type RunRouteResult =
+	| { kind: "completed"; outcome?: SetupPullOutcome }
+	| { kind: "decision-required"; decision: SyncDecision }
+	| { kind: "failed" };
 
 export type RunRoute = (
 	route: string,
 	signal?: AbortSignal,
 	onCommit?: () => void,
 	target?: string,
-) => Promise<SetupPullOutcome | undefined>;
+) => Promise<RunRouteResult | undefined>;
 
-export type CancellableOperationResult = SetupPullOutcome | "closed" | undefined;
+export type CancellableOperationResult =
+	| RunRouteResult
+	| { kind: "closed" }
+	| { kind: "cancelled" };
 
 interface CancellableOperationOptions {
 	commitAware?: boolean;
@@ -38,10 +47,10 @@ export async function runCancellableOperation(
 		signal,
 	} = options;
 	if (ctx.mode !== "tui") {
-		return await runRoute(route, undefined, undefined, target);
+		return (await runRoute(route, signal, undefined, target)) ?? { kind: "failed" };
 	}
 	let commitStarted = false;
-	let routeResult: SetupPullOutcome | undefined;
+	let routeResult: RunRouteResult | undefined;
 	const interaction = await runCustomInteraction<{ cancelled?: boolean; error?: unknown }>(ctx, {
 		signal,
 		isCurrent: () => !signal?.aborted,
@@ -89,13 +98,13 @@ export async function runCancellableOperation(
 		},
 	});
 	if (interaction.kind === "error") throw interaction.error;
-	if (interaction.kind !== "completed") return "closed";
+	if (interaction.kind !== "completed") return { kind: "closed" };
 	if (interaction.value.cancelled) {
 		if (cancelledMessage) ctx.ui.notify(cancelledMessage, "info");
-		return "cancelled";
+		return { kind: "cancelled" };
 	}
 	if (interaction.value.error) throw interaction.value.error;
-	return routeResult;
+	return routeResult ?? { kind: "failed" };
 }
 
 function keybindingText(

package/src/manager-ui.ts

@@ -1,6 +1,10 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { type ActionMenuItem, defineMenu, runMenu } from "@narumitw/pi-tui-kit";
-import { type RunRoute, runCancellableOperation } from "./cancellable-operation.js";
+import {
+	type CancellableOperationResult,
+	type RunRoute,
+	runCancellableOperation,
+} from "./cancellable-operation.js";
 import { setSyncSetupCompletions } from "./command.js";
 import {
 	configuredSyncSetupNames,
@@ -33,6 +37,7 @@ import { showSyncSettings } from "./settings-ui.js";
 import { useSyncSetup } from "./setup-switch.js";
 import { showAddStorageConnection, showStorageConnections } from "./storage-connections-ui.js";
 import { DEFAULT_SYNC_INCLUDE, syncIncludeSelection } from "./sync-policy.js";
+import { showSyncResolution } from "./sync-resolution-ui.js";
 import { showSyncSetups } from "./sync-setups-ui.js";
 import type { AnySyncConfig } from "./types.js";
 import { showAddWebDavTarget, showEditWebDavTarget, showWebDavSetup } from "./webdav-ui.js";
@@ -120,7 +125,10 @@ export async function showSyncManager(
 						signal: sessionSignal,
 					},
 				);
-				return result === "closed" ? { kind: "close" } : { kind: "stay" };
+				const resolution = await resolveManagerDecision(ctx, result, runRoute, sessionSignal);
+				return result.kind === "closed" || resolution === "close"
+					? { kind: "close" }
+					: { kind: "stay" };
 			},
 			switch: async () => {
 				const result = await showSetupSwitcher(ctx, runRoute, undefined, sessionSignal);
@@ -136,7 +144,7 @@ export async function showSyncManager(
 					runRoute,
 					{ signal: sessionSignal },
 				);
-				return result === "closed" ? { kind: "close" } : { kind: "stay" };
+				return result.kind === "closed" ? { kind: "close" } : { kind: "stay" };
 			},
 			settings: async () => {
 				await showSyncSettings(ctx, runRoute, sessionSignal);
@@ -154,7 +162,12 @@ export async function showSyncManager(
 						signal: sessionSignal,
 					},
 				);
-				return result === "applied" || result === "closed" ? { kind: "close" } : { kind: "stay" };
+				const resolution = await resolveManagerDecision(ctx, result, runRoute, sessionSignal);
+				return result.kind === "closed" ||
+					(result.kind === "completed" && result.outcome === "applied") ||
+					resolution === "close"
+					? { kind: "close" }
+					: { kind: "stay" };
 			},
 			push: async () => {
 				const result = await runCancellableOperation(
@@ -168,7 +181,10 @@ export async function showSyncManager(
 						signal: sessionSignal,
 					},
 				);
-				return result === "closed" ? { kind: "close" } : { kind: "stay" };
+				const resolution = await resolveManagerDecision(ctx, result, runRoute, sessionSignal);
+				return result.kind === "closed" || resolution === "close"
+					? { kind: "close" }
+					: { kind: "stay" };
 			},
 			setups: async () => {
 				const result = await showSyncSetupManager(ctx, runRoute, sessionSignal);
@@ -218,6 +234,21 @@ export async function showSyncManager(
 	});
 }
 
+async function resolveManagerDecision(
+	ctx: ExtensionCommandContext,
+	result: CancellableOperationResult,
+	runRoute: RunRoute,
+	signal?: AbortSignal,
+) {
+	if (result.kind !== "decision-required") return undefined;
+	const resolution = await showSyncResolution(ctx, result.decision, runRoute, signal);
+	return resolution.kind === "resolved" ||
+		resolution.kind === "closed" ||
+		resolution.kind === "stale"
+		? "close"
+		: "stay";
+}
+
 function syncMainMenuItem(
 	label: string,
 ): ActionMenuItem<
@@ -522,11 +553,25 @@ async function showSetupSwitcher(
 						signal,
 					},
 				);
-				if (pullResult === "closed") {
+				if (pullResult.kind === "closed") {
 					pullClosed = true;
 					return undefined;
 				}
-				return pullResult;
+				if (pullResult.kind === "decision-required") {
+					const resolution = await showSyncResolution(ctx, pullResult.decision, runRoute, signal);
+					if (
+						resolution.kind === "resolved" ||
+						resolution.kind === "closed" ||
+						resolution.kind === "stale"
+					) {
+						pullClosed = true;
+					}
+					return resolution.kind === "resolved" && resolution.direction === "pull"
+						? "applied"
+						: undefined;
+				}
+				if (pullResult.kind === "completed") return pullResult.outcome;
+				return pullResult.kind === "cancelled" ? "cancelled" : undefined;
 			},
 			onSwitch,
 			signal,

package/src/settings-ui.ts

@@ -1,22 +1,17 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import type { RunRoute } from "./cancellable-operation.js";
 import { loadConfig, localConfigPath } from "./config.js";
 import { updateSyncSetup } from "./settings-management.js";
 import {
 	SETUP_SWITCH_ACTION_OPTIONS,
-	type SetupPullOutcome,
 	saveOnSwitch,
 	setupSwitchActionFromLabel,
 	setupSwitchActionLabel,
 } from "./setup-switch.js";
 import { safeTerminalText } from "./sync-format.js";
 
-export type SyncSettingsRoute = (
-	route: string,
-	signal?: AbortSignal,
-	onCommit?: () => void,
-	setup?: string,
-) => Promise<SetupPullOutcome | undefined>;
+export type SyncSettingsRoute = RunRoute;
 
 export async function showSyncSettings(
 	ctx: ExtensionCommandContext,

package/src/sync-decision.ts

@@ -0,0 +1,113 @@
+import { syncConfigReviewIdentity } from "./config.js";
+import { formatDiff, formatSnapshotOnlyDiff, safeTerminalText } from "./sync-format.js";
+import { includeFromSelectionConfig } from "./sync-policy.js";
+import { syncPolicyChanged } from "./sync-state.js";
+import type { AnySyncConfig, Snapshot, SyncState } from "./types.js";
+
+export type SyncDecisionKind =
+	| "remote-or-policy-changed"
+	| "both-changed"
+	| "first-sync-settings-diverged"
+	| "first-sync-sessions-diverged"
+	| "remote-empty";
+
+export type SyncResolutionDirection = "push" | "pull";
+
+export interface SyncDecision {
+	kind: SyncDecisionKind;
+	setupName: string;
+	configIdentity: string;
+	causes: {
+		localChanged: boolean;
+		remoteChanged: boolean;
+		policyChanged: boolean;
+	};
+	previousInclude?: readonly string[];
+	currentInclude: readonly string[];
+	review: string;
+	directions: readonly SyncResolutionDirection[];
+	directMessage: string;
+}
+
+export class SyncDecisionRequiredError extends Error {
+	readonly decision: SyncDecision;
+
+	constructor(decision: SyncDecision) {
+		super(decision.directMessage);
+		this.name = "SyncDecisionRequiredError";
+		this.decision = decision;
+	}
+}
+
+interface CreateSyncDecisionOptions {
+	kind: SyncDecisionKind;
+	config: AnySyncConfig;
+	state: SyncState;
+	local: Snapshot;
+	remote?: Snapshot;
+	localChanged: boolean;
+	remoteChanged: boolean;
+	directMessage: string;
+}
+
+export function createSyncDecision(options: CreateSyncDecisionOptions) {
+	const { config, state, local, remote, kind } = options;
+	const policyChanged = Boolean(state.lastAppliedSnapshot) && syncPolicyChanged(state, config);
+	const previousInclude = includeFromSelectionConfig(state);
+	const currentInclude = [...config.include];
+	const causes = {
+		localChanged: options.localChanged,
+		remoteChanged: options.remoteChanged,
+		policyChanged,
+	};
+	const causeLines =
+		kind === "first-sync-settings-diverged"
+			? ["This machine and the remote have different Pi settings on first sync."]
+			: kind === "first-sync-sessions-diverged"
+				? ["Pi settings match, but local and remote sessions differ on first sync."]
+				: kind === "remote-empty"
+					? ["The remote storage location is empty."]
+					: [
+							...(causes.localChanged ? ["Local content changed since the last sync."] : []),
+							...(causes.remoteChanged ? ["Remote content changed since the last sync."] : []),
+							...(causes.policyChanged ? ["Included content changed since the last sync."] : []),
+						];
+	const comparison = remote
+		? formatDiff(local, remote)
+		: formatSnapshotOnlyDiff("Remote is empty. Local push would upload", local);
+	const review = [
+		`Sync setup: ${safeTerminalText(config.setupName)}`,
+		"",
+		"Why a decision is required:",
+		...causeLines,
+		...(policyChanged
+			? [
+					"",
+					`Previously included: ${safeList(previousInclude)}`,
+					`Currently included: ${safeList(currentInclude)}`,
+				]
+			: []),
+		"",
+		"Observed differences:",
+		...comparison.split("\n").map(safeTerminalText),
+	].join("\n");
+	return new SyncDecisionRequiredError({
+		kind,
+		setupName: config.setupName,
+		configIdentity: syncConfigReviewIdentity(config),
+		causes,
+		...(policyChanged ? { previousInclude: [...previousInclude] } : {}),
+		currentInclude,
+		review,
+		directions: kind === "remote-empty" ? ["push"] : ["push", "pull"],
+		directMessage: options.directMessage,
+	});
+}
+
+export function isSyncDecisionRequiredError(error: unknown): error is SyncDecisionRequiredError {
+	return error instanceof SyncDecisionRequiredError;
+}
+
+function safeList(values: readonly string[]) {
+	return values.length > 0 ? values.map(safeTerminalText).join(", ") : "none";
+}

package/src/sync-operations.ts

@@ -29,6 +29,7 @@ import {
 	type RemoteHead,
 	type SyncBackend,
 } from "./sync-backend.js";
+import { createSyncDecision } from "./sync-decision.js";
 import {
 	countPreservedRemoteFiles,
 	errorMessage,
@@ -113,7 +114,7 @@ export async function status(
 	const config = await loadConfig(options.setup);
 	throwIfAborted(options.signal);
 	ctx.ui.setStatus(STATUS_KEY, `checking ${config.setupName}`);
-	const backend = backendFor(config, factory);
+	const backend = await backendFor(config, factory);
 	const local = await createSnapshot(
 		config.snapshotIdentity,
 		snapshotOptionsForContext(ctx, config),
@@ -159,7 +160,7 @@ export async function diff(
 	const config = await loadConfig(options.setup);
 	throwIfAborted(options.signal);
 	ctx.ui.setStatus(STATUS_KEY, `checking ${config.setupName}`);
-	const backend = backendFor(config, factory);
+	const backend = await backendFor(config, factory);
 	const local = await createSnapshot(
 		config.snapshotIdentity,
 		snapshotOptionsForContext(ctx, config),
@@ -205,7 +206,7 @@ export async function doctor(
 	try {
 		const config = await loadConfig(options.setup);
 		throwIfAborted(options.signal);
-		backend = backendFor(config, factory);
+		backend = await backendFor(config, factory);
 		profile = config.snapshotIdentity;
 		snapshotOptions = snapshotOptionsForContext(ctx, config);
 		messages.push(
@@ -282,7 +283,7 @@ export async function push(
 	const config = input?.config ?? (await loadConfig(options.setup));
 	throwIfAborted(options.signal);
 	ctx.ui.setStatus(STATUS_KEY, `pushing ${config.setupName}`);
-	const backend = input?.backend ?? backendFor(config, factory);
+	const backend = input?.backend ?? (await backendFor(config, factory));
 	const state = input?.state ?? (await readStateForConfig(config));
 	throwIfAborted(options.signal);
 	const local =
@@ -308,9 +309,17 @@ export async function push(
 			? filterSnapshotForConfigPolicy(remoteForUpload, config)
 			: undefined;
 		if (!remoteForConflict || !snapshotHashesMatchState(remoteForConflict, state, config)) {
-			throw new Error(
-				"Remote or sync policy changed since last sync. Run /sync pull first or /sync push --force.",
-			);
+			throw createSyncDecision({
+				kind: head ? "remote-or-policy-changed" : "remote-empty",
+				config,
+				state,
+				local,
+				remote: remoteForConflict,
+				localChanged: hasLocalChanges(local, state, config),
+				remoteChanged: true,
+				directMessage:
+					"Remote or sync policy changed since last sync. Run /sync pull first or /sync push --force.",
+			});
 		}
 	}
 
@@ -330,7 +339,7 @@ export async function push(
 	}
 
 	if (!(await confirmPush(ctx, options, config, backend, local, upload, head, remoteForUpload))) {
-		return;
+		return "cancelled" as const;
 	}
 
 	if (options.force) {
@@ -361,7 +370,7 @@ export async function push(
 					"Remote changed during review. Push the refreshed plan?",
 				))
 			) {
-				return;
+				return "cancelled" as const;
 			}
 		}
 	}
@@ -395,6 +404,7 @@ export async function push(
 			result.warnings.length > 0 ? "warning" : "info",
 		);
 	}
+	return "applied" as const;
 }
 
 export async function pull(
@@ -405,7 +415,7 @@ export async function pull(
 	const config = await loadConfig(options.setup);
 	throwIfAborted(options.signal);
 	ctx.ui.setStatus(STATUS_KEY, `pulling ${config.setupName}`);
-	const backend = backendFor(config, factory);
+	const backend = await backendFor(config, factory);
 	const state = await readStateForConfig(config);
 	throwIfAborted(options.signal);
 	const local = await createSnapshot(
@@ -415,14 +425,32 @@ export async function pull(
 	throwIfAborted(options.signal);
 	const { head, snapshot: remote } = await readRemoteSnapshot(backend, config, options.signal);
 	throwIfAborted(options.signal);
-	if (!remote) throw new Error("Remote is empty. Run /sync push from a configured machine first.");
-
 	const localChanged = hasLocalChanges(local, state, config);
+	if (!remote) {
+		throw createSyncDecision({
+			kind: "remote-empty",
+			config,
+			state,
+			local,
+			localChanged,
+			remoteChanged: false,
+			directMessage: "Remote is empty. Run /sync push from a configured machine first.",
+		});
+	}
+
 	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 /sync diff, then choose /sync pull --force or /sync push --force.",
-		);
+		throw createSyncDecision({
+			kind: "both-changed",
+			config,
+			state,
+			local,
+			remote,
+			localChanged,
+			remoteChanged,
+			directMessage:
+				"Both local and remote changed since last sync. Run /sync diff, then choose /sync pull --force or /sync push --force.",
+		});
 	}
 
 	if (
@@ -492,7 +520,7 @@ export async function syncBoth(
 ) {
 	const config = await loadConfig(options.setup);
 	throwIfAborted(options.signal);
-	const backend = backendFor(config, factory);
+	const backend = await backendFor(config, factory);
 	const state = await readStateForConfig(config);
 	throwIfAborted(options.signal);
 	const local = await createSnapshot(
@@ -519,15 +547,31 @@ export async function syncBoth(
 
 	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 /sync diff, then manually choose /sync pull or /sync push.",
-			);
+			throw createSyncDecision({
+				kind: "first-sync-settings-diverged",
+				config,
+				state,
+				local,
+				remote,
+				localChanged: true,
+				remoteChanged: true,
+				directMessage:
+					"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 /sync diff, then manually choose /sync pull or /sync push.",
-				);
+				throw createSyncDecision({
+					kind: "first-sync-sessions-diverged",
+					config,
+					state,
+					local,
+					remote,
+					localChanged: true,
+					remoteChanged: true,
+					directMessage:
+						"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, factory);
 			return;
@@ -557,9 +601,17 @@ export async function syncBoth(
 		return;
 	}
 	if (localChanged && remoteChanged && state.lastAppliedSnapshot) {
-		throw new Error(
-			"Both local and remote changed. Run /sync diff and resolve with push --force or pull --force.",
-		);
+		throw createSyncDecision({
+			kind: "both-changed",
+			config,
+			state,
+			local,
+			remote,
+			localChanged,
+			remoteChanged,
+			directMessage:
+				"Both local and remote changed. Run /sync diff and resolve with push --force or pull --force.",
+		});
 	}
 	if (remoteChanged) {
 		await pull(ctx, options, factory);
@@ -593,7 +645,7 @@ export async function history(
 ) {
 	const config = await loadConfig(options.setup);
 	throwIfAborted(options.signal);
-	const backend = backendFor(config, factory);
+	const backend = await backendFor(config, factory);
 	const snapshots = (await backend.listHistory(options.signal)).slice(-20).reverse();
 	throwIfAborted(options.signal);
 	if (snapshots.length === 0) {
@@ -643,7 +695,7 @@ export async function rollback(
 
 	const config = await loadConfig(options.setup);
 	throwIfAborted(options.signal);
-	const backend = backendFor(config, factory);
+	const backend = await backendFor(config, factory);
 	if (
 		expectedSelection &&
 		(backend.identity !== expectedSelection.backendIdentity ||

package/src/sync-resolution-ui.ts

@@ -0,0 +1,166 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import { type RunRoute, runCancellableOperation } from "./cancellable-operation.js";
+import { loadConfig, syncConfigReviewIdentity } from "./config.js";
+import type { SyncDecision, SyncResolutionDirection } from "./sync-decision.js";
+import { errorMessage, safeTerminalText } from "./sync-format.js";
+
+export type SyncResolutionResult =
+	| { kind: "resolved"; direction: SyncResolutionDirection }
+	| { kind: "back" }
+	| { kind: "closed" }
+	| { kind: "stale" };
+
+export async function showSyncResolution(
+	ctx: ExtensionCommandContext,
+	initialDecision: SyncDecision,
+	runRoute: RunRoute,
+	sessionSignal?: AbortSignal,
+): Promise<SyncResolutionResult> {
+	type Screen = "resolve" | "review";
+	type Action = "push" | "pull" | "back";
+	let currentDecision = initialDecision;
+	let resolvedDirection: SyncResolutionDirection | undefined;
+	const menu = defineMenu<SyncDecision, Screen, Action, ExtensionCommandContext>({
+		start: "resolve",
+		screens: {
+			resolve: ({ state }) => ({
+				kind: "actions",
+				title: resolutionTitle(state),
+				lines: resolutionLines(state),
+				items: [
+					{ id: "review", label: "Review differences (recommended)", to: "review" },
+					...(state.directions.includes("push")
+						? [
+								{
+									id: "push",
+									label: pushLabel(state),
+									description: "Review an exact push before replacing the remote version.",
+									action: "push" as const,
+								},
+							]
+						: []),
+					...(state.directions.includes("pull")
+						? [
+								{
+									id: "pull",
+									label: pullLabel(state),
+									description: "Review exact local changes and create a backup before applying.",
+									action: "pull" as const,
+								},
+							]
+						: []),
+					{ id: "back", label: "Back", action: "back" },
+				],
+				hint: "back",
+			}),
+			review: ({ state }) => ({
+				kind: "review",
+				title: `Review differences · ${safeTerminalText(state.setupName)}`,
+				content: state.review,
+				format: { kind: "text" },
+				viewportSize: "adaptive",
+				hint: "back",
+			}),
+		},
+		actions: {
+			push: ({ state, signal }) => resolveDirection("push", state, signal),
+			pull: ({ state, signal }) => resolveDirection("pull", state, signal),
+			back: async () => ({ kind: "back" }),
+		},
+	});
+
+	async function resolveDirection(
+		direction: SyncResolutionDirection,
+		decision: SyncDecision,
+		actionSignal: AbortSignal,
+	) {
+		const signal = sessionSignal ? AbortSignal.any([sessionSignal, actionSignal]) : actionSignal;
+		const config = await loadConfig(decision.setupName);
+		if (signal.aborted) return { kind: "close" as const };
+		if (syncConfigReviewIdentity(config) !== decision.configIdentity) {
+			throw new Error(
+				`Sync setup “${safeTerminalText(decision.setupName)}” changed while conflict resolution was open; return to the sync manager and retry.`,
+			);
+		}
+		const result = await runCancellableOperation(
+			ctx,
+			direction === "push"
+				? "Preparing local-wins push preview…"
+				: "Preparing remote-wins pull preview…",
+			`${direction} --force`,
+			runRoute,
+			{
+				commitAware: true,
+				cancelledMessage:
+					direction === "push"
+						? "Push preparation cancelled; no remote files were changed."
+						: "Pull check cancelled; no local files were changed.",
+				target: decision.setupName,
+				signal,
+			},
+		);
+		if (result.kind === "decision-required") {
+			currentDecision = result.decision;
+			return { kind: "stay" as const };
+		}
+		if (result.kind === "completed") {
+			if (result.outcome === "cancelled") return { kind: "stay" as const };
+			resolvedDirection = direction;
+			return { kind: "close" as const };
+		}
+		return result.kind === "closed" ? { kind: "close" as const } : { kind: "stay" as const };
+	}
+
+	const result = await runMenu(ctx, menu, {
+		getState: () => currentDecision,
+		signal: sessionSignal,
+		isCurrent: () => !sessionSignal?.aborted,
+		onError: (_menuCtx, error) => ctx.ui.notify(errorMessage(error), "error"),
+	});
+	if (sessionSignal?.aborted || result.kind === "stale") return { kind: "stale" };
+	if (resolvedDirection) return { kind: "resolved", direction: resolvedDirection };
+	if (result.kind === "closed") {
+		return result.reason === "back" ? { kind: "back" } : { kind: "closed" };
+	}
+	return { kind: "closed" };
+}
+
+function resolutionTitle(decision: SyncDecision) {
+	return decision.kind === "remote-empty" ? "Remote is empty" : "Resolve sync conflict";
+}
+
+function resolutionLines(decision: SyncDecision) {
+	return [
+		`Sync setup: ${safeTerminalText(decision.setupName)}`,
+		...causeSummary(decision),
+		"No files have been changed by this failed operation.",
+	];
+}
+
+function causeSummary(decision: SyncDecision) {
+	if (decision.kind === "first-sync-settings-diverged") {
+		return ["This machine and the remote have different Pi settings on first sync."];
+	}
+	if (decision.kind === "first-sync-sessions-diverged") {
+		return ["Pi settings match, but local and remote sessions differ on first sync."];
+	}
+	if (decision.kind === "remote-empty") return ["The remote storage location has no snapshot."];
+	return [
+		...(decision.causes.localChanged ? ["Local content changed since the last sync."] : []),
+		...(decision.causes.remoteChanged ? ["Remote content changed since the last sync."] : []),
+		...(decision.causes.policyChanged ? ["Included content changed since the last sync."] : []),
+	];
+}
+
+function pushLabel(decision: SyncDecision) {
+	if (decision.kind === "remote-empty") return "Push local content…";
+	if (decision.kind.startsWith("first-sync-")) return "Use local as initial source…";
+	return "Keep local content and replace remote…";
+}
+
+function pullLabel(decision: SyncDecision) {
+	return decision.kind.startsWith("first-sync-")
+		? "Use remote as initial source…"
+		: "Use remote content and replace local…";
+}

package/src/sync.ts

@@ -3,6 +3,7 @@ import type {
 	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import type { RunRouteResult } from "./cancellable-operation.js";
 import {
 	completeSyncArguments,
 	parseOptions,
@@ -27,28 +28,30 @@ import {
 	sessionTokenWarnings,
 	syncSessionsWarnings,
 } from "./config.js";
-import { showFileSelection } from "./file-selection.js";
 import { unlock, withLock } from "./lock.js";
-import { showSetupWizard, showSyncManager } from "./manager-ui.js";
 import { SetupPullRequiresUiError, useSyncSetup } from "./setup-switch.js";
 import { createSnapshot } from "./snapshot.js";
 import { recoverSnapshotTransactionsOnStartup } from "./snapshot-transaction.js";
+import { isSyncDecisionRequiredError } from "./sync-decision.js";
 import { errorMessage } from "./sync-format.js";
-import {
-	diff,
-	doctor,
-	history,
-	pull,
-	push,
-	rollback,
-	status,
-	syncBoth,
-} from "./sync-operations.js";
 import { hasLocalChanges } from "./sync-state.js";
 import type { AnySyncConfig, CommandOptions, SnapshotOptions } from "./types.js";
 
 const STATUS_KEY = "sync";
 
+type SyncOperations = typeof import("./sync-operations.js");
+let syncOperationsPromise: Promise<SyncOperations> | undefined;
+
+function loadSyncOperations(): Promise<SyncOperations> {
+	if (!syncOperationsPromise) {
+		syncOperationsPromise = import("./sync-operations.js").catch((error) => {
+			syncOperationsPromise = undefined;
+			throw error;
+		});
+	}
+	return syncOperationsPromise;
+}
+
 const AUTO_SYNC_OPTIONS: CommandOptions = {
 	yes: true,
 	force: false,
@@ -128,6 +131,8 @@ async function handleCommand(
 ) {
 	if (!rawArgs.trim()) {
 		try {
+			const { showSyncManager } = await import("./manager-ui.js");
+			if (sessionSignal.aborted) return;
 			await showSyncManager(
 				ctx,
 				(route, signal, onCommit, target) =>
@@ -141,7 +146,10 @@ async function handleCommand(
 		}
 		return;
 	}
-	await executeCommand(rawArgs, ctx, sessionSignal);
+	const result = await executeCommand(rawArgs, ctx, sessionSignal);
+	if (result.kind === "decision-required") {
+		ctx.ui.notify(result.decision.directMessage, "error");
+	}
 }
 
 async function executeCommand(
@@ -150,10 +158,10 @@ async function executeCommand(
 	signal?: AbortSignal,
 	onCommit?: () => void,
 	setup?: string,
-) {
+): Promise<RunRouteResult> {
 	try {
 		const command = await resolveSyncCommand(rawArgs, ctx);
-		if (signal?.aborted || !command) return;
+		if (signal?.aborted || !command) return { kind: "completed" };
 		const { subcommand, rest } = command;
 		const options = parseOptions(rest);
 		if (setup !== undefined) options.setup = setup;
@@ -164,60 +172,87 @@ async function executeCommand(
 		switch (subcommand) {
 			case "help":
 				ctx.ui.notify(usage(), "info");
-				return;
+				return { kind: "completed" };
 			case "use":
 				await useSyncSetup(
 					ctx,
 					options.args[0] ?? "",
-					(selectedSetup) =>
-						withLock("pull", () => pull(ctx, { ...options, setup: selectedSetup })),
+					async (selectedSetup) => {
+						const operations = await loadSyncOperations();
+						throwIfAborted(options.signal);
+						return withLock("pull", () =>
+							operations.pull(ctx, { ...options, setup: selectedSetup }),
+						);
+					},
 					undefined,
 					options.signal,
 				);
-				return;
+				return { kind: "completed" };
 			case "init":
 				await initConfig(ctx, signal);
-				return;
+				return { kind: "completed" };
 			case "config":
 				await showConfig(ctx, options);
-				return;
+				return { kind: "completed" };
 			case "files":
-				await showFileSelection(ctx, options.setup, options.signal);
-				return;
+				await (await import("./file-selection.js")).showFileSelection(
+					ctx,
+					options.setup,
+					options.signal,
+				);
+				return { kind: "completed" };
 			case "status":
-				await status(ctx, options);
-				return;
+				await (await loadSyncOperations()).status(ctx, options);
+				return { kind: "completed" };
 			case "diff":
-				await diff(ctx, options);
-				return;
+				await (await loadSyncOperations()).diff(ctx, options);
+				return { kind: "completed" };
 			case "doctor":
-				await doctor(ctx, options);
-				return;
-			case "push":
-				await withLock("push", () => push(ctx, options));
-				return;
-			case "pull":
-				return await withLock("pull", () => pull(ctx, options));
-			case "sync":
-				await withLock("sync", () => syncBoth(ctx, options));
-				return;
+				await (await loadSyncOperations()).doctor(ctx, options);
+				return { kind: "completed" };
+			case "push": {
+				const operations = await loadSyncOperations();
+				throwIfAborted(options.signal);
+				const outcome = await withLock("push", () => operations.push(ctx, options));
+				return { kind: "completed", ...(outcome ? { outcome } : {}) };
+			}
+			case "pull": {
+				const operations = await loadSyncOperations();
+				throwIfAborted(options.signal);
+				const outcome = await withLock("pull", () => operations.pull(ctx, options));
+				return { kind: "completed", ...(outcome ? { outcome } : {}) };
+			}
+			case "sync": {
+				const operations = await loadSyncOperations();
+				throwIfAborted(options.signal);
+				await withLock("sync", () => operations.syncBoth(ctx, options));
+				return { kind: "completed" };
+			}
 			case "history":
-				await history(ctx, options);
-				return;
-			case "rollback":
-				await withLock("rollback", () => rollback(ctx, options));
-				return;
+				await (await loadSyncOperations()).history(ctx, options);
+				return { kind: "completed" };
+			case "rollback": {
+				const operations = await loadSyncOperations();
+				throwIfAborted(options.signal);
+				await withLock("rollback", () => operations.rollback(ctx, options));
+				return { kind: "completed" };
+			}
 			case "unlock":
 				await unlock(ctx, options);
-				return;
+				return { kind: "completed" };
 			default:
 				ctx.ui.notify(`Unknown /sync command: ${subcommand}\n\n${usage()}`, "warning");
+				return { kind: "failed" };
 		}
 	} catch (error) {
-		if (signal?.aborted) return;
+		if (signal?.aborted) return { kind: "failed" };
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 		if (error instanceof SetupPullRequiresUiError) throw error;
+		if (isSyncDecisionRequiredError(error)) {
+			return { kind: "decision-required", decision: error.decision };
+		}
 		ctx.ui.notify(errorMessage(error), "error");
+		return { kind: "failed" };
 	}
 }
 
@@ -230,9 +265,11 @@ async function autoSync(ctx: ExtensionContext, signal: AbortSignal) {
 		throwIfAborted(signal);
 		await loadConfig();
 		throwIfAborted(signal);
+		const operations = await loadSyncOperations();
+		throwIfAborted(signal);
 		await withLock("auto-sync", () => {
 			throwIfAborted(signal);
-			return syncBoth(ctx, { ...AUTO_SYNC_OPTIONS, signal });
+			return operations.syncBoth(ctx, { ...AUTO_SYNC_OPTIONS, signal });
 		});
 	} catch (error) {
 		if (signal.aborted || isMissingConfigError(error)) return;
@@ -252,6 +289,8 @@ async function autoPushSessions(ctx: ExtensionContext, signal: AbortSignal) {
 		const config = await loadConfig();
 		throwIfAborted(signal);
 		if (!config.include.includes("sessions")) return;
+		const operations = await loadSyncOperations();
+		throwIfAborted(signal);
 		await withLock("auto-session-push", async () => {
 			throwIfAborted(signal);
 			const state = await readStateForConfig(config);
@@ -262,7 +301,7 @@ async function autoPushSessions(ctx: ExtensionContext, signal: AbortSignal) {
 			);
 			throwIfAborted(signal);
 			if (!hasLocalChanges(local, state, config)) return;
-			await push(ctx, { ...AUTO_SYNC_OPTIONS, signal }, { config, state, local });
+			await operations.push(ctx, { ...AUTO_SYNC_OPTIONS, signal }, { config, state, local });
 		});
 	} catch (error) {
 		if (signal.aborted || isMissingConfigError(error)) return;
@@ -279,6 +318,8 @@ async function initConfig(ctx: ExtensionCommandContext, signal?: AbortSignal) {
 	}
 
 	if (ctx.mode === "tui") {
+		const { showSetupWizard } = await import("./manager-ui.js");
+		throwIfAborted(signal);
 		await showSetupWizard(ctx, signal);
 		return;
 	}
@@ -370,8 +411,8 @@ function displayWebDavUrl(value: string | undefined, username: string | undefine
 	}
 }
 
-function throwIfAborted(signal: AbortSignal) {
-	if (!signal.aborted) return;
+function throwIfAborted(signal?: AbortSignal) {
+	if (!signal?.aborted) return;
 	throw signal.reason instanceof Error
 		? signal.reason
 		: new DOMException("The operation was aborted", "AbortError");
@@ -433,7 +474,6 @@ export {
 	preflightSnapshotApply,
 	protectSnapshotApplyPlan,
 } from "./snapshot-apply.js";
-export { backupLocal } from "./sync-operations.js";
 export {
 	canPullRemoteSessionsOnFirstSync,
 	canPullRemoteSettingsOnFirstSync,