@narumitw/pi-sync 0.43.0 → 0.48.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:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-sync",
-	"version": "0.43.0",
+	"version": "0.48.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.40.0",
+		"@narumitw/pi-tui-kit": "^0.45.0",
 		"fast-xml-parser": "^5.10.1",
 		"proper-lockfile": "^4.1.2"
 	},

package/src/cancellable-operation.ts

@@ -0,0 +1,125 @@
+import {
+	BorderedLoader,
+	type ExtensionCommandContext,
+	type KeybindingsManager,
+} from "@earendil-works/pi-coding-agent";
+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<RunRouteResult | undefined>;
+
+export type CancellableOperationResult =
+	| RunRouteResult
+	| { kind: "closed" }
+	| { kind: "cancelled" };
+
+interface CancellableOperationOptions {
+	commitAware?: boolean;
+	cancelledMessage?: string | null;
+	target?: string;
+	signal?: AbortSignal;
+}
+
+export async function runCancellableOperation(
+	ctx: ExtensionCommandContext,
+	message: string,
+	route: string,
+	runRoute: RunRoute,
+	options: CancellableOperationOptions = {},
+): Promise<CancellableOperationResult> {
+	const {
+		commitAware = false,
+		cancelledMessage = "Check cancelled; no settings or files were changed.",
+		target,
+		signal,
+	} = options;
+	if (ctx.mode !== "tui") {
+		return (await runRoute(route, signal, undefined, target)) ?? { kind: "failed" };
+	}
+	let commitStarted = false;
+	let routeResult: RunRouteResult | undefined;
+	const interaction = await runCustomInteraction<{ cancelled?: boolean; error?: unknown }>(ctx, {
+		signal,
+		isCurrent: () => !signal?.aborted,
+		create: ({ tui, theme, keybindings, signal: interactionSignal, complete }) => {
+			const loader = new BorderedLoader(tui, theme, message, { cancellable: false });
+			const cancelHint = `${keybindingText(keybindings, "tui.select.cancel", "esc")} cancel`;
+			const operation = runRoute(
+				route,
+				interactionSignal,
+				commitAware ? () => (commitStarted = true) : undefined,
+				target,
+			).then(
+				(result) => {
+					routeResult = result;
+					complete({});
+				},
+				(error: unknown) => complete({ error }),
+			);
+			return {
+				render(width: number) {
+					const safeWidth = Math.max(1, width);
+					const lines = loader.render(safeWidth);
+					const bottomBorder = lines.at(-1);
+					return [
+						...lines.slice(0, -1),
+						truncateToWidth(theme.fg("dim", cancelHint), safeWidth, ""),
+						...(bottomBorder === undefined ? [] : [bottomBorder]),
+					];
+				},
+				invalidate: () => loader.invalidate(),
+				handleInput(data: string) {
+					if (!keybindings.matches(data, "tui.select.cancel")) return;
+					if (commitStarted) {
+						ctx.ui.notify(
+							"Applying or publishing has started and cannot be cancelled safely.",
+							"warning",
+						);
+						return;
+					}
+					complete({ cancelled: true });
+				},
+				dispose: () => loader.dispose(),
+				waitForPending: () => operation,
+			};
+		},
+	});
+	if (interaction.kind === "error") throw interaction.error;
+	if (interaction.kind !== "completed") return { kind: "closed" };
+	if (interaction.value.cancelled) {
+		if (cancelledMessage) ctx.ui.notify(cancelledMessage, "info");
+		return { kind: "cancelled" };
+	}
+	if (interaction.value.error) throw interaction.value.error;
+	return routeResult ?? { kind: "failed" };
+}
+
+function keybindingText(
+	keybindings: Pick<KeybindingsManager, "getKeys">,
+	binding: Parameters<KeybindingsManager["getKeys"]>[0],
+	fallback: string,
+) {
+	const keys = keybindings
+		.getKeys(binding)
+		.map(String)
+		.map((key) => {
+			if (key === "return") return "enter";
+			if (key === "escape") return "esc";
+			return safeTerminalText(key);
+		})
+		.filter(Boolean);
+	return keys.join("/") || fallback;
+}

package/src/manager-ui.ts

@@ -1,5 +1,10 @@
-import { BorderedLoader, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { type ActionMenuItem, defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import {
+	type CancellableOperationResult,
+	type RunRoute,
+	runCancellableOperation,
+} from "./cancellable-operation.js";
 import { setSyncSetupCompletions } from "./command.js";
 import {
 	configuredSyncSetupNames,
@@ -29,20 +34,14 @@ import {
 	updateSyncSetup,
 } from "./settings-management.js";
 import { showSyncSettings } from "./settings-ui.js";
-import { type SetupPullOutcome, useSyncSetup } from "./setup-switch.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";
 
-type RunRoute = (
-	route: string,
-	signal?: AbortSignal,
-	onCommit?: () => void,
-	target?: string,
-) => Promise<SetupPullOutcome | undefined>;
-
 export async function showSyncManager(
 	ctx: ExtensionCommandContext,
 	runRoute: RunRoute,
@@ -116,16 +115,36 @@ export async function showSyncManager(
 		},
 		actions: {
 			sync: async () => {
-				await runCancellableOperation(ctx, "Checking current sync setup…", "sync", runRoute, true);
-				return { kind: "stay" };
+				const result = await runCancellableOperation(
+					ctx,
+					"Checking current sync setup…",
+					"sync",
+					runRoute,
+					{
+						commitAware: true,
+						signal: sessionSignal,
+					},
+				);
+				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);
-				return result === "pull-attempted" ? { kind: "close" } : { kind: "stay" };
+				return result === "pull-attempted" || result === "closed"
+					? { kind: "close" }
+					: { kind: "stay" };
 			},
 			diff: async () => {
-				await runCancellableOperation(ctx, "Checking current sync setup…", "diff", runRoute);
-				return { kind: "stay" };
+				const result = await runCancellableOperation(
+					ctx,
+					"Checking current sync setup…",
+					"diff",
+					runRoute,
+					{ signal: sessionSignal },
+				);
+				return result.kind === "closed" ? { kind: "close" } : { kind: "stay" };
 			},
 			settings: async () => {
 				await showSyncSettings(ctx, runRoute, sessionSignal);
@@ -137,21 +156,35 @@ export async function showSyncManager(
 					"Checking remote changes…",
 					"pull",
 					runRoute,
-					true,
-					"Pull check cancelled; no local files were changed.",
+					{
+						commitAware: true,
+						cancelledMessage: "Pull check cancelled; no local files were changed.",
+						signal: sessionSignal,
+					},
 				);
-				return result === "applied" ? { 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 () => {
-				await runCancellableOperation(
+				const result = await runCancellableOperation(
 					ctx,
 					"Preparing push preview…",
 					"push",
 					runRoute,
-					true,
-					"Push preparation cancelled; no remote files were changed.",
+					{
+						commitAware: true,
+						cancelledMessage: "Push preparation cancelled; no remote files were changed.",
+						signal: sessionSignal,
+					},
 				);
-				return { 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);
@@ -201,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<
@@ -226,61 +274,6 @@ function syncMainMenuItem(
 	return { id: actions.get(label) ?? "help", label, action: actions.get(label) ?? "help" };
 }
 
-async function runCancellableOperation(
-	ctx: ExtensionCommandContext,
-	message: string,
-	route: string,
-	runRoute: RunRoute,
-	commitAware = false,
-	cancelledMessage: string | null = "Check cancelled; no settings or files were changed.",
-	target?: string,
-) {
-	if (ctx.mode !== "tui") {
-		return await runRoute(route, undefined, undefined, target);
-	}
-	let commitStarted = false;
-	let operation: Promise<void> | undefined;
-	let routeResult: SetupPullOutcome | undefined;
-	const result = await ctx.ui.custom<{ cancelled?: boolean; error?: unknown }>(
-		(tui, theme, _kb, done) => {
-			const loader = new BorderedLoader(tui, theme, message, { cancellable: true });
-			let closed = false;
-			loader.onAbort = () => {
-				if (commitStarted) {
-					ctx.ui.notify(
-						"Applying or publishing has started and cannot be cancelled safely.",
-						"warning",
-					);
-					return;
-				}
-				closed = true;
-				done({ cancelled: true });
-			};
-			operation = runRoute(
-				route,
-				loader.signal,
-				commitAware ? () => (commitStarted = true) : undefined,
-				target,
-			)
-				.then((result) => {
-					routeResult = result;
-					if (!closed) done({});
-				})
-				.catch((error) => {
-					if (!closed) done({ error });
-				});
-			return loader;
-		},
-	);
-	if (result?.cancelled) {
-		await operation;
-		if (cancelledMessage) ctx.ui.notify(cancelledMessage, "info");
-		return "cancelled";
-	}
-	if (result?.error) throw result.error;
-	return routeResult;
-}
-
 export async function showSetupWizard(ctx: ExtensionCommandContext, signal?: AbortSignal) {
 	if (ctx.mode !== "tui") {
 		ctx.ui.notify(
@@ -543,23 +536,48 @@ async function showSetupSwitcher(
 	);
 	if (signal?.aborted || !confirmed) return false;
 	try {
+		let pullClosed = false;
 		const result = await useSyncSetup(
 			ctx,
 			name,
-			(selectedTarget) =>
-				runCancellableOperation(
+			async (selectedTarget) => {
+				const pullResult = await runCancellableOperation(
 					ctx,
 					`Pulling sync setup “${safeTerminalText(name)}”…`,
 					"pull",
 					runRoute,
-					true,
-					null,
-					selectedTarget,
-				),
+					{
+						commitAware: true,
+						cancelledMessage: null,
+						target: selectedTarget,
+						signal,
+					},
+				);
+				if (pullResult.kind === "closed") {
+					pullClosed = true;
+					return undefined;
+				}
+				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,
 			syncConfigReviewIdentity(config),
 		);
+		if (pullClosed) return "closed";
 		return result.pullApplied ? "pull-attempted" : "switched";
 	} catch (error) {
 		if (signal?.aborted) return false;
@@ -587,7 +605,7 @@ async function showSyncSetupManager(
 			},
 			makeCurrent: async (name, setupSignal) => {
 				const result = await showSetupSwitcher(ctx, runRoute, name, setupSignal);
-				return result === "pull-attempted" ? "exit" : undefined;
+				return result === "pull-attempted" || result === "closed" ? "exit" : undefined;
 			},
 			remove: async (name, setupSignal) => {
 				await showRemoveTarget(ctx, name, setupSignal);

package/src/secret-input.ts

@@ -7,6 +7,7 @@ import {
 	Text,
 	truncateToWidth,
 } from "@earendil-works/pi-tui";
+import { runCustomInteraction } from "@narumitw/pi-tui-kit";
 
 const MASK = "•";
 
@@ -16,63 +17,62 @@ export async function promptSecret(
 	options: { required?: boolean; signal?: AbortSignal } = { required: true },
 ) {
 	if (ctx.mode !== "tui" || options.signal?.aborted) return undefined;
-	const value = await ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {
-		const heading = new Text("", 0, 0);
-		const hint = new Text("", 0, 0);
-		const applyTheme = () => {
-			heading.setText(theme.fg("accent", theme.bold(title)));
-			hint.setText(theme.fg("dim", "Enter save • Escape cancel • Input is hidden"));
-		};
-		applyTheme();
-		const input = new MaskedInput(keybindings);
-		let settled = false;
-		const finish = (result: string | undefined) => {
-			if (settled) return;
-			settled = true;
-			done(result);
-		};
-		const onAbort = () => finish(undefined);
-		options.signal?.addEventListener("abort", onAbort, { once: true });
-		const component: Focusable & {
-			render(width: number): string[];
-			invalidate(): void;
-			handleInput(data: string): void;
-			dispose(): void;
-		} = {
-			get focused() {
-				return input.focused;
-			},
-			set focused(focused: boolean) {
-				input.focused = focused;
-			},
-			render(width: number) {
-				const safeWidth = Math.max(1, width);
-				return [
-					...heading.render(safeWidth),
-					...input.render(safeWidth),
-					...hint.render(safeWidth),
-				].map((line) => truncateToWidth(line, safeWidth));
-			},
-			invalidate() {
-				applyTheme();
-				heading.invalidate();
-				input.invalidate();
-				hint.invalidate();
-			},
-			handleInput(data: string) {
-				if (keybindings.matches(data, "tui.select.cancel")) finish(undefined);
-				else if (keybindings.matches(data, "tui.input.submit")) finish(input.getValue());
-				else input.handleInput(data);
-				tui.requestRender();
-			},
-			dispose() {
-				options.signal?.removeEventListener("abort", onAbort);
-				input.clear();
-			},
-		};
-		return component;
+	const result = await runCustomInteraction<string | undefined>(ctx, {
+		signal: options.signal,
+		isCurrent: () => !options.signal?.aborted,
+		create: ({ tui, theme, keybindings, complete }) => {
+			const heading = new Text("", 0, 0);
+			const hint = new Text("", 0, 0);
+			const submitKey = keybindingText(keybindings, "tui.input.submit", "enter");
+			const cancelKey = keybindingText(keybindings, "tui.select.cancel", "esc");
+			const applyTheme = () => {
+				heading.setText(theme.fg("accent", theme.bold(title)));
+				hint.setText(theme.fg("dim", `${submitKey} save • ${cancelKey} cancel • Input is hidden`));
+			};
+			applyTheme();
+			const input = new MaskedInput(keybindings);
+			const component: Focusable & {
+				render(width: number): string[];
+				invalidate(): void;
+				handleInput(data: string): void;
+				dispose(): void;
+			} = {
+				get focused() {
+					return input.focused;
+				},
+				set focused(focused: boolean) {
+					input.focused = focused;
+				},
+				render(width: number) {
+					const safeWidth = Math.max(1, width);
+					return [
+						...heading.render(safeWidth),
+						...input.render(safeWidth),
+						...hint.render(safeWidth),
+					].map((line) => truncateToWidth(line, safeWidth));
+				},
+				invalidate() {
+					applyTheme();
+					heading.invalidate();
+					input.invalidate();
+					hint.invalidate();
+				},
+				handleInput(data: string) {
+					if (keybindings.matches(data, "tui.select.cancel")) complete(undefined);
+					else if (keybindings.matches(data, "tui.input.submit")) complete(input.getValue());
+					else input.handleInput(data);
+					tui.requestRender();
+				},
+				dispose() {
+					input.clear();
+				},
+			};
+			return component;
+		},
 	});
-	if (value === undefined) return undefined;
+	if (result.kind === "error") throw result.error;
+	if (result.kind !== "completed" || result.value === undefined) return undefined;
+	const value = result.value;
 	if (options.required !== false && value.length === 0) {
 		ctx.ui.notify(`${title} is required.`, "warning");
 		return undefined;
@@ -191,6 +191,23 @@ class MaskedInput implements Focusable {
 	}
 }
 
+function keybindingText(
+	keybindings: Pick<KeybindingsManager, "getKeys">,
+	binding: Parameters<KeybindingsManager["getKeys"]>[0],
+	fallback: string,
+) {
+	const keys = keybindings
+		.getKeys(binding)
+		.map(String)
+		.map((key) => {
+			if (key === "return") return "enter";
+			if (key === "escape") return "esc";
+			return hasControlCharacter(key) ? "" : key;
+		})
+		.filter(Boolean);
+	return keys.join("/") || fallback;
+}
+
 function hasControlCharacter(value: string) {
 	return [...value].some((character) => {
 		const code = character.codePointAt(0) ?? 0;

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,
@@ -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(
@@ -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 (
@@ -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);

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,
@@ -33,6 +34,7 @@ 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,
@@ -141,7 +143,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 +155,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,7 +169,7 @@ async function executeCommand(
 		switch (subcommand) {
 			case "help":
 				ctx.ui.notify(usage(), "info");
-				return;
+				return { kind: "completed" };
 			case "use":
 				await useSyncSetup(
 					ctx,
@@ -174,50 +179,58 @@ async function executeCommand(
 					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;
+				return { kind: "completed" };
 			case "status":
 				await status(ctx, options);
-				return;
+				return { kind: "completed" };
 			case "diff":
 				await diff(ctx, options);
-				return;
+				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));
+				return { kind: "completed" };
+			case "push": {
+				const outcome = await withLock("push", () => push(ctx, options));
+				return { kind: "completed", ...(outcome ? { outcome } : {}) };
+			}
+			case "pull": {
+				const outcome = await withLock("pull", () => pull(ctx, options));
+				return { kind: "completed", ...(outcome ? { outcome } : {}) };
+			}
 			case "sync":
 				await withLock("sync", () => syncBoth(ctx, options));
-				return;
+				return { kind: "completed" };
 			case "history":
 				await history(ctx, options);
-				return;
+				return { kind: "completed" };
 			case "rollback":
 				await withLock("rollback", () => rollback(ctx, options));
-				return;
+				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" };
 	}
 }