@narumitw/pi-sync 0.46.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.46.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",

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,
@@ -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" };
 	}
 }