@narumitw/pi-sync 0.29.1 → 0.29.2

package/README.md

@@ -10,7 +10,7 @@ The extension uses immutable snapshot bundles, a `latest.json` publication point
 
 - Opens a goal-oriented `/sync` manager showing the current target, storage, auto-sync, session scope, and relevant next actions.
 - Supports multiple named **sync targets** and reusable R2/S3 **storage profiles**.
-- Switches targets without syncing or modifying files; only the current target runs automatic startup/shutdown sync.
+- Asks to review a pull after switching targets by default, with settings to start that review automatically or switch only.
 - Previews concrete local or remote file changes before push, pull, force resolution, or rollback.
 - Uses transactional synced-content drafts with explicit Save, Discard, and Continue editing choices.
 - Keeps direct `help`, `use`, `init`, `config`, `files`, `status`, `diff`, `doctor`, `push`, `pull`, `sync`, `history`, `rollback`, and `unlock` routes for compatibility and automation.
@@ -86,9 +86,9 @@ Last known sync: Remote not checked
 Its primary actions are:
 
 - **Sync now** — conservatively decide whether to push, pull, or do nothing
-- **Switch target** — preview and change the current target without syncing
+- **Switch target** — preview the target change, then follow the configured pull behavior
 - **Status & changes** — perform a cancellable read-only remote check
-- **Settings** — control automatic sync and synced content for the current target
+- **Settings** — control post-switch pulling, automatic sync, and synced content
 - **Manage targets & storage** — add, edit, or remove local target/profile definitions
 - **History & recovery** — browse snapshots, preview rollback, diagnose setup, or recover a stale lock
 - **Help**
@@ -109,6 +109,7 @@ A version 2 example:
 {
   "version": 2,
   "activeTarget": "home",
+  "targetSwitchAction": "ask",
   "profiles": {
     "r2": {
       "kind": "r2",
@@ -155,15 +156,22 @@ A version 2 example:
 - A **storage profile** owns connection/authentication fields: `kind`, `endpoint`, `region`, `accessKeyId`, `secretAccessKey`, and optional `sessionToken`.
 - A **sync target** references a storage profile and owns `bucket`, `prefix`, `namespace`, `autoSync`, and its synced-content policy.
 - `activeTarget` is used by bare commands and automatic sync.
+- `targetSwitchAction` controls what happens after a target switch: `ask` (default), `pull`, or `switch-only`.
 - `namespace` is the old flat `profile` concept. The remote layout and snapshot wire field remain named `profiles`/`profile` for compatibility.
 
 When adding another target with the same storage profile, pi-sync recommends reusing the current target's bucket and prefix while deriving a separate namespace from the new target name. For example, `home` and `work` may both use profile `r2`, bucket `pi-sync`, and prefix `pi-sync`, producing `pi-sync/profiles/home/` and `pi-sync/profiles/work/`.
 
 Two targets may intentionally overlap local files, but only one is automatic. pi-sync rejects duplicate effective target remote identities—including deprecated bucket/prefix/namespace environment overrides—to prevent independent local states from controlling the same remote pointer. Removing a target/profile removes local configuration only; it never deletes buckets or snapshots. A referenced profile cannot be removed, and users must switch away before removing one of several current targets.
 
+### Target switching
+
+The default `targetSwitchAction: "ask"` changes `activeTarget` atomically, then asks in TUI mode whether to review a pull for that target. Choosing not to review leaves local files unchanged. Accepting starts the normal pull flow, which fetches the remote snapshot and shows the exact writes and deletions before apply. In print, JSON, or RPC mode, `ask` switches without pulling and directs interactive users to `/sync pull` where notifications are available.
+
+Set `targetSwitchAction` to `"pull"` to start that reviewed pull automatically after a confirmed target switch. The exact pull summary and apply confirmation remain enabled, conflict detection still stops unsafe merges, a local backup is created before apply, and pi-sync never adds `--force`; Pi may separately ask whether to reload changed resources after a successful pull. Because that confirmation requires observable UI, `/sync use` rejects `"pull"` in print and JSON modes before changing `activeTarget`; use TUI or RPC mode instead. Set it to `"switch-only"` to retain the previous no-pull behavior. Selecting an already-current target is a no-op. If a pull fails or its concrete review is declined, the new target remains active and pi-sync reports that synced files were not changed before `/sync pull` is retried.
+
 ### Synced content
 
-The **Settings → Choose synced content** screen edits a draft. Enter or Space toggles, typing searches, and Escape opens the Save/Discard/Continue decision. A single Save atomically updates the target while preserving unknown fields and POSIX `0600` permissions. Saving settings never starts network sync.
+The **Settings → Choose synced content** screen edits a draft. Arrow keys navigate, Enter or Space toggles, and Escape opens the Save/Discard/Continue decision. A single Save atomically updates the target while preserving unknown fields and POSIX `0600` permissions. Saving settings never starts network sync.
 
 Omitting `syncFiles` preserves the legacy default of every built-in item. An empty array is valid and means the target manages nothing; **Sync now** reports that state instead of publishing an empty sync. Unknown built-in names fail validation.
 
@@ -254,7 +262,7 @@ For the current target, startup auto-sync uses conservative decisions:
 - first-sync mismatch or both changed → stop and require review
 - no selected content → report/skip
 
-Switching targets changes only `activeTarget`; it never starts sync. The next startup uses the new target's `autoSync`, or the user can choose **Sync now** immediately.
+Switching targets first changes `activeTarget`, then follows `targetSwitchAction`: ask before reviewing a pull in TUI by default, start a reviewed pull automatically when configured, or stop after switching. Pulls remain pinned to the selected target and retain exact summaries, locking, backups, and conflict safeguards. The next startup uses the new target's `autoSync` regardless of the switch action.
 
 Remote layout remains compatible:
 
@@ -313,6 +321,8 @@ extensions/pi-sync/
 │   ├── manager-ui.ts            # Goal-oriented menus and setup/management flows
 │   ├── file-selection.ts        # Transactional synced-content editor
 │   ├── settings-management.ts   # Profiles, targets, migration, and atomic saves
+│   ├── settings-ui.ts           # SettingsList interaction and serialized saves
+│   ├── target-switch.ts         # Post-switch prompt, policy, and target handoff
 │   ├── snapshot-transaction.ts  # Local apply journal, rollback, and recovery
 │   └── *.ts                     # Config, policy, snapshot, S3, lock, and format modules
 ├── test/

package/package.json

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

package/src/config.ts

@@ -9,7 +9,13 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { safeName } from "./paths.js";
 import { DEFAULT_SYNC_FILES, normalizeExtraFiles, normalizeSyncFiles } from "./sync-policy.js";
-import type { PartialConfig, Snapshot, SyncConfig, SyncState } from "./types.js";
+import type {
+	PartialConfig,
+	Snapshot,
+	SyncConfig,
+	SyncState,
+	TargetSwitchAction,
+} from "./types.js";
 
 export { extraFilePathsByLower, normalizeExtraFiles, normalizeSyncFiles } from "./sync-policy.js";
 
@@ -17,6 +23,7 @@ const VERSION = 1;
 const DEFAULT_PROFILE = "default";
 const DEFAULT_PREFIX = "pi-sync";
 const DEFAULT_REGION = "auto";
+export const DEFAULT_TARGET_SWITCH_ACTION: TargetSwitchAction = "ask";
 
 export const DEPRECATED_PI_SYNC_ENV_NAMES = [
 	"PI_SYNC_ENDPOINT",
@@ -121,6 +128,20 @@ export async function loadPartialConfig(targetName?: string): Promise<PartialCon
 	return resolveLegacyPartialConfig(fileConfig as PartialConfig);
 }
 
+export async function loadTargetSwitchAction(): Promise<TargetSwitchAction> {
+	const settings = await readLocalConfigObject();
+	if (!settings || !isV2SettingsObject(settings)) return DEFAULT_TARGET_SWITCH_ACTION;
+	return normalizeTargetSwitchAction(settings.targetSwitchAction);
+}
+
+export function normalizeTargetSwitchAction(value: unknown): TargetSwitchAction {
+	if (value === undefined) return DEFAULT_TARGET_SWITCH_ACTION;
+	if (value === "ask" || value === "pull" || value === "switch-only") return value;
+	throw new Error(
+		'Invalid pi-sync settings: targetSwitchAction must be "ask", "pull", or "switch-only".',
+	);
+}
+
 export function deprecatedPiSyncEnvironmentNames() {
 	return DEPRECATED_PI_SYNC_ENV_NAMES.filter((name) => hasEnv(name));
 }
@@ -160,6 +181,7 @@ export function resolveV2PartialConfig(
 	settings: Record<string, unknown>,
 	targetName?: string,
 ): PartialConfig {
+	normalizeTargetSwitchAction(settings.targetSwitchAction);
 	const targets = requireNamedObjectMap(settings.targets, "targets");
 	const profiles = requireNamedObjectMap(settings.profiles, "profiles");
 	validateUniqueRemoteTargets(targets);
@@ -477,6 +499,7 @@ export function localConfigTemplate(): Record<string, unknown> {
 	return {
 		version: 2,
 		activeTarget: DEFAULT_PROFILE,
+		targetSwitchAction: DEFAULT_TARGET_SWITCH_ACTION,
 		profiles: {
 			[DEFAULT_PROFILE]: {
 				kind: "r2",

package/src/file-selection.ts

@@ -145,7 +145,6 @@ async function showDraftEditor(
 			getSettingsListTheme(),
 			(id, newValue) => updateDraft(draft, id, newValue === INCLUDED),
 			() => done(undefined),
-			{ enableSearch: true },
 		);
 		container.addChild(settingsList);
 		container.addChild(hint);

package/src/manager-ui.ts

@@ -4,14 +4,12 @@ import {
 	configuredTargetNames,
 	deprecatedPiSyncEnvironmentWarnings,
 	isCloudflareR2Endpoint,
-	isEnabled,
 	loadConfig,
 	loadPartialConfig,
+	loadTargetSwitchAction,
 	localConfigPath,
-	normalizeExtraFiles,
 	normalizeSyncFiles,
 	readLocalConfigObject,
-	updateLocalConfig,
 } from "./config.js";
 import { inspectLock, isStaleLock } from "./lock.js";
 import {
@@ -24,7 +22,9 @@ import {
 	updateStorageProfile,
 	updateSyncTarget,
 } from "./settings-management.js";
+import { showSyncSettings } from "./settings-ui.js";
 import { DEFAULT_SYNC_FILES } from "./sync-policy.js";
+import { type TargetPullOutcome, useSyncTarget } from "./target-switch.js";
 import type { SyncConfig } from "./types.js";
 
 export const MAIN_MENU_ACTIONS = [
@@ -40,7 +40,12 @@ export const MAIN_MENU_ACTIONS = [
 const BACK = "Back";
 
 type MainMenuAction = (typeof MAIN_MENU_ACTIONS)[number];
-type RunRoute = (route: string, signal?: AbortSignal, onCommit?: () => void) => Promise<void>;
+type RunRoute = (
+	route: string,
+	signal?: AbortSignal,
+	onCommit?: () => void,
+	target?: string,
+) => Promise<TargetPullOutcome | undefined>;
 
 export async function showSyncManager(
 	ctx: ExtensionCommandContext,
@@ -58,14 +63,17 @@ export async function showSyncManager(
 			case "Sync now":
 				await runCancellableOperation(ctx, "Checking current target…", "sync", runRoute, true);
 				break;
-			case "Switch target":
-				if (await showTargetSwitcher(ctx)) continue;
+			case "Switch target": {
+				const result = await showTargetSwitcher(ctx, runRoute);
+				if (result === "pull-attempted") return;
+				if (result === "switched") continue;
 				break;
+			}
 			case "Status & changes":
 				await runCancellableOperation(ctx, "Checking current target…", "diff", runRoute);
 				break;
 			case "Settings":
-				await showSettingsMenu(ctx, runRoute);
+				await showSyncSettings(ctx, runRoute);
 				break;
 			case "Manage targets & storage":
 				await showManageMenu(ctx, runRoute);
@@ -90,13 +98,15 @@ async function runCancellableOperation(
 	route: string,
 	runRoute: RunRoute,
 	commitAware = false,
+	cancelledMessage: string | null = "Check cancelled; no settings or files were changed.",
+	target?: string,
 ) {
 	if (ctx.mode !== "tui") {
-		await runRoute(route);
-		return;
+		return await runRoute(route, undefined, undefined, target);
 	}
 	let commitStarted = false;
 	let operation: Promise<void> | undefined;
+	let routeResult: TargetPullOutcome | undefined;
 	const result = await ctx.ui.custom<{ cancelled?: boolean; error?: unknown }>(
 		(tui, theme, _kb, done) => {
 			const loader = new BorderedLoader(tui, theme, message, { cancellable: true });
@@ -116,8 +126,10 @@ async function runCancellableOperation(
 				route,
 				loader.signal,
 				commitAware ? () => (commitStarted = true) : undefined,
+				target,
 			)
-				.then(() => {
+				.then((result) => {
+					routeResult = result;
 					if (!closed) done({});
 				})
 				.catch((error) => {
@@ -128,10 +140,11 @@ async function runCancellableOperation(
 	);
 	if (result?.cancelled) {
 		await operation;
-		ctx.ui.notify("Check cancelled; no settings or files were changed.", "info");
-		return;
+		if (cancelledMessage) ctx.ui.notify(cancelledMessage, "info");
+		return "cancelled";
 	}
 	if (result?.error) throw result.error;
+	return routeResult;
 }
 
 async function describeManagerState(): Promise<{ title: string; actions: string[] }> {
@@ -346,7 +359,7 @@ export async function showSetupWizard(ctx: ExtensionCommandContext) {
 	return true;
 }
 
-async function showTargetSwitcher(ctx: ExtensionCommandContext) {
+async function showTargetSwitcher(ctx: ExtensionCommandContext, runRoute: RunRoute) {
 	const raw = await readLocalConfigObject();
 	if (raw?.version !== 2) {
 		ctx.ui.notify("Add a second sync target before switching targets.", "info");
@@ -395,6 +408,13 @@ async function showTargetSwitcher(ctx: ExtensionCommandContext) {
 		);
 		return false;
 	}
+	const targetSwitchAction = await loadTargetSwitchAction();
+	const switchEffect =
+		targetSwitchAction === "ask"
+			? "After switching, pi-sync will ask whether to review a pull for the target."
+			: targetSwitchAction === "pull"
+				? "After switching, pi-sync will check the target and show exact changes before applying them."
+				: "After switching, pi-sync will not pull or modify synced files.";
 	const choice = await ctx.ui.select(
 		[
 			"Switch target",
@@ -405,70 +425,23 @@ async function showTargetSwitcher(ctx: ExtensionCommandContext) {
 			`Synced content: ${normalizeSyncFiles(config.syncFiles).length} built-in groups · ${config.extraFiles.length} extra files`,
 			`Auto-sync: ${config.autoSync ? "On" : "Off"} · Sessions: ${config.syncSessions ? "On" : "Off"}`,
 			"",
-			"Switching does not sync or modify files now.",
+			switchEffect,
 		].join("\n"),
 		[`Switch to ${safeTerminalText(name)}`, "Cancel"],
 	);
 	if (choice !== `Switch to ${safeTerminalText(name)}`) return false;
-	await useSyncTarget(ctx, name);
-	return true;
-}
-
-export async function useSyncTarget(ctx: ExtensionCommandContext, name: string) {
-	const normalized = name.trim();
-	if (!normalized) throw new Error("Usage: /sync use <target>");
-	await loadConfig(normalized);
-	await updateLocalConfig((current) => {
-		if (current.version !== 2) throw new Error("Target switching requires version 2 settings.");
-		return { ...current, activeTarget: normalized };
-	});
-	await refreshTargetCompletions();
-	ctx.ui.notify(
-		`Switched to “${safeTerminalText(normalized)}”. No files were synced; use Sync now when ready.`,
-		"info",
-	);
-}
-
-async function showSettingsMenu(ctx: ExtensionCommandContext, runRoute: RunRoute) {
-	const partial = await loadPartialConfig();
-	const automaticSyncOverridden = Object.hasOwn(process.env, "PI_SYNC_AUTO_SYNC");
-	const selected = await ctx.ui.select(
-		[
-			`Settings for target “${safeTerminalText(partial.target ?? "default")}”`,
-			`Storage: ${storageDescription(partial.storageKind, partial.endpoint, partial.bucket)}`,
-			"Automatic sync changes save immediately; synced-content changes use a reviewed draft.",
-			"",
-			`Auto-sync: ${isEnabled(partial.autoSync, true) ? "On" : "Off"}`,
-			`Synced content: ${normalizeSyncFiles(partial.syncFiles).length} built-ins · ${normalizeExtraFiles(partial.extraFiles).length} extra`,
-		].join("\n"),
-		[
-			"Choose synced content",
-			automaticSyncOverridden
-				? "Automatic sync (environment override, deprecated)"
-				: "Toggle automatic sync",
-			BACK,
-		],
-	);
-	if (!selected || selected === BACK) return;
-	if (selected === "Choose synced content") {
-		await runRoute("files");
-		return;
-	}
-	if (automaticSyncOverridden) {
-		ctx.ui.notify(
-			"Automatic sync is read-only because deprecated PI_SYNC_AUTO_SYNC currently overrides this target. Move it into target settings before the future major removal.",
-			"warning",
-		);
-		return;
-	}
-	await updateCurrentTarget((target) => ({
-		...target,
-		autoSync: !isEnabled(partial.autoSync, true),
-	}));
-	ctx.ui.notify(
-		`Automatic sync ${isEnabled(partial.autoSync, true) ? "disabled" : "enabled"} for “${safeTerminalText(partial.target ?? "default")}”.`,
-		"info",
+	const result = await useSyncTarget(ctx, name, (selectedTarget) =>
+		runCancellableOperation(
+			ctx,
+			`Pulling target “${safeTerminalText(name)}”…`,
+			"pull",
+			runRoute,
+			true,
+			null,
+			selectedTarget,
+		),
 	);
+	return result.pullApplied ? "pull-attempted" : "switched";
 }
 
 async function showManageMenu(ctx: ExtensionCommandContext, _runRoute: RunRoute) {
@@ -903,20 +876,6 @@ function formatRemotePath(prefix: string, namespace: string) {
 	return safeTerminalText(`${prefix}/profiles/${namespace}/`);
 }
 
-async function updateCurrentTarget(
-	update: (target: Record<string, unknown>) => Record<string, unknown>,
-) {
-	await updateLocalConfig((current) => {
-		if (current.version !== 2) return update(current);
-		const targets = ownRecord(current.targets);
-		const active = typeof current.activeTarget === "string" ? current.activeTarget : undefined;
-		if (!targets || !active) throw new Error("Current target is not configured.");
-		const target = ownRecord(targets[active]);
-		if (!target) throw new Error(`Current target “${active}” is invalid.`);
-		return { ...current, targets: { ...targets, [active]: update(target) } };
-	});
-}
-
 async function requiredExistingBucket(ctx: ExtensionCommandContext, example: string) {
 	const value = await ctx.ui.input("Existing bucket", `Example: ${example}`);
 	if (value === undefined) return undefined;

package/src/settings-management.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import {
+	DEFAULT_TARGET_SWITCH_ACTION,
 	effectiveTargetRemoteIdentity,
 	localConfigPath,
 	readLocalConfigObject,
@@ -112,6 +113,7 @@ export async function saveNewV2Settings(input: {
 	const settings = {
 		version: 2,
 		activeTarget: input.targetName,
+		targetSwitchAction: DEFAULT_TARGET_SWITCH_ACTION,
 		profiles: { [input.storageProfileName]: { ...input.profile } },
 		targets: {
 			[input.targetName]: { ...input.target, profile: input.storageProfileName },

package/src/settings-ui.ts

@@ -0,0 +1,199 @@
+import {
+	type ExtensionCommandContext,
+	getSettingsListTheme,
+} from "@earendil-works/pi-coding-agent";
+import { Container, type SettingItem, SettingsList, Text } from "@earendil-works/pi-tui";
+import {
+	isCloudflareR2Endpoint,
+	isEnabled,
+	loadPartialConfig,
+	loadTargetSwitchAction,
+	localConfigPath,
+	normalizeExtraFiles,
+	normalizeSyncFiles,
+	readLocalConfigObject,
+	updateLocalConfig,
+} from "./config.js";
+import { errorMessage, safeTerminalText } from "./sync-format.js";
+import {
+	saveTargetSwitchAction,
+	TARGET_SWITCH_ACTION_OPTIONS,
+	type TargetPullOutcome,
+	targetSwitchActionFromLabel,
+	targetSwitchActionLabel,
+} from "./target-switch.js";
+
+export type SyncSettingsRoute = (
+	route: string,
+	signal?: AbortSignal,
+	onCommit?: () => void,
+	target?: string,
+) => Promise<TargetPullOutcome | undefined>;
+
+export async function showSyncSettings(ctx: ExtensionCommandContext, runRoute: SyncSettingsRoute) {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(`Edit pi-sync settings manually: ${safeTerminalText(localConfigPath())}`, "info");
+		return;
+	}
+	while (true) {
+		const raw = await readLocalConfigObject();
+		const version2 = raw?.version === 2;
+		const partial = await loadPartialConfig();
+		const action = await showSettingsList(ctx, partial, version2);
+		if (action !== "files") return;
+		await runRoute("files", undefined, undefined, version2 ? partial.target : undefined);
+	}
+}
+
+async function showSettingsList(
+	ctx: ExtensionCommandContext,
+	partial: Awaited<ReturnType<typeof loadPartialConfig>>,
+	version2: boolean,
+) {
+	const targetName = version2 ? partial.target : undefined;
+	const automaticSyncOverridden = Object.hasOwn(process.env, "PI_SYNC_AUTO_SYNC");
+	const automaticSyncValue = isEnabled(partial.autoSync, true) ? "On" : "Off";
+	const targetSwitchAction = await loadTargetSwitchAction();
+	const targetSwitchValue = targetSwitchActionLabel(targetSwitchAction);
+	let saveQueue = Promise.resolve();
+	const latestRequested = new Map<string, string>();
+
+	return ctx.ui.custom<"files" | undefined>((tui, theme, _keybindings, done) => {
+		const items: SettingItem[] = [
+			{
+				id: "automaticSync",
+				label: automaticSyncOverridden ? "Automatic sync (environment override)" : "Automatic sync",
+				description: automaticSyncOverridden
+					? "Read-only while deprecated PI_SYNC_AUTO_SYNC overrides this target. Move the value into target settings before the future major removal."
+					: "Run conservative synchronization automatically at session startup and shutdown.",
+				currentValue: automaticSyncValue,
+				...(automaticSyncOverridden ? {} : { values: ["On", "Off"] }),
+			},
+			...(version2
+				? [
+						{
+							id: "targetSwitchAction",
+							label: "After target switch",
+							description:
+								"Ask before starting a pull, start a pull review automatically, or switch without checking remote files. Every pull still shows exact changes before apply.",
+							currentValue: targetSwitchValue,
+							values: TARGET_SWITCH_ACTION_OPTIONS.map(({ label }) => label),
+						},
+					]
+				: []),
+			{
+				id: "syncFiles",
+				label: "Synced content",
+				description: `${normalizeSyncFiles(partial.syncFiles).length} built-in groups and ${normalizeExtraFiles(partial.extraFiles).length} extra files. Opens the reviewed content-selection draft.`,
+				currentValue: "Open editor",
+				values: ["Open editor"],
+			},
+		];
+		const container = new Container();
+		container.addChild(new Text(theme.fg("accent", theme.bold("Pi Sync Settings")), 1, 0));
+		container.addChild(
+			new Text(
+				theme.fg(
+					"muted",
+					`Target: ${safeTerminalText(partial.target ?? "default")} · ${storageDescription(partial.storageKind, partial.endpoint, partial.bucket)}`,
+				),
+				1,
+				0,
+			),
+		);
+		let settingsList: SettingsList;
+		let closing = false;
+		const closeAfterSaves = (result: "files" | undefined) => {
+			if (closing) return;
+			closing = true;
+			void saveQueue.then(() => done(result));
+		};
+		settingsList = new SettingsList(
+			items,
+			Math.min(items.length + 2, 15),
+			getSettingsListTheme(),
+			(id, newValue) => {
+				if (id === "syncFiles") {
+					closeAfterSaves("files");
+					return;
+				}
+				latestRequested.set(id, newValue);
+				const fallbackValue = id === "automaticSync" ? automaticSyncValue : targetSwitchValue;
+				const operation = saveQueue.then(async () => {
+					let previousValue = fallbackValue;
+					try {
+						if (id === "automaticSync") {
+							const latest = await loadPartialConfig(targetName);
+							previousValue = isEnabled(latest.autoSync, true) ? "On" : "Off";
+							const enabled = newValue === "On";
+							await updateSettingsTarget(targetName, (target) => ({
+								...target,
+								autoSync: enabled,
+							}));
+							ctx.ui.notify(
+								`Automatic sync ${enabled ? "enabled" : "disabled"} for “${safeTerminalText(partial.target ?? "default")}”.`,
+								"info",
+							);
+						} else if (id === "targetSwitchAction") {
+							const latest = await loadTargetSwitchAction();
+							previousValue = targetSwitchActionLabel(latest);
+							const action = targetSwitchActionFromLabel(newValue);
+							if (!action) throw new Error(`Invalid target-switch action: ${newValue}`);
+							await saveTargetSwitchAction(action);
+							ctx.ui.notify(`After target switch: ${newValue}.`, "info");
+						}
+					} catch (error) {
+						if (latestRequested.get(id) === newValue) {
+							settingsList.updateValue(id, previousValue);
+						}
+						ctx.ui.notify(`Pi Sync settings save failed: ${errorMessage(error)}`, "error");
+						tui.requestRender();
+					}
+				});
+				saveQueue = operation.catch(() => undefined);
+			},
+			() => closeAfterSaves(undefined),
+		);
+		container.addChild(settingsList);
+		return {
+			render: (width: number) => container.render(width),
+			invalidate: () => container.invalidate(),
+			handleInput(data: string) {
+				settingsList.handleInput?.(data);
+				tui.requestRender();
+			},
+		};
+	});
+}
+
+async function updateSettingsTarget(
+	targetName: string | undefined,
+	update: (target: Record<string, unknown>) => Record<string, unknown>,
+) {
+	await updateLocalConfig((current) => {
+		if (current.version !== 2) return update(current);
+		const targets = ownRecord(current.targets);
+		const selected =
+			targetName ?? (typeof current.activeTarget === "string" ? current.activeTarget : undefined);
+		if (!targets || !selected) throw new Error("Settings target is not configured.");
+		const target = ownRecord(targets[selected]);
+		if (!target) throw new Error(`Settings target “${selected}” is invalid.`);
+		return { ...current, targets: { ...targets, [selected]: update(target) } };
+	});
+}
+
+function storageDescription(
+	kind: string | undefined,
+	endpoint: string | undefined,
+	bucket: string | undefined,
+) {
+	const label =
+		kind === "r2" || isCloudflareR2Endpoint(endpoint) ? "Cloudflare R2" : "S3-compatible";
+	return `${label} · ${safeTerminalText(bucket ?? "bucket missing")}`;
+}
+
+function ownRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}

package/src/sync.ts

@@ -39,7 +39,7 @@ import {
 } from "./config.js";
 import { showFileSelection } from "./file-selection.js";
 import { inspectLock, isLockGuardHeld, isStaleLock, unlock, withLock } from "./lock.js";
-import { showSetupWizard, showSyncManager, useSyncTarget } from "./manager-ui.js";
+import { showSetupWizard, showSyncManager } from "./manager-ui.js";
 import {
 	historyKey,
 	latestKey,
@@ -86,6 +86,7 @@ import {
 	snapshotsMatch,
 	syncPolicyChanged,
 } from "./sync-state.js";
+import { TargetPullRequiresUiError, useSyncTarget } from "./target-switch.js";
 import type {
 	CommandOptions,
 	LatestPointer,
@@ -96,9 +97,7 @@ import type {
 	SyncState,
 } from "./types.js";
 
-const gzipAsync = promisify(gzip);
-const gunzipAsync = promisify(gunzip);
-
+const [gzipAsync, gunzipAsync] = [promisify(gzip), promisify(gunzip)];
 const STATUS_KEY = "sync";
 const VERSION = 1;
 const DEFAULT_PROFILE = "default";
@@ -159,8 +158,8 @@ export default function sync(pi: ExtensionAPI) {
 async function handleCommand(rawArgs: string, ctx: ExtensionCommandContext) {
 	if (!rawArgs.trim()) {
 		try {
-			await showSyncManager(ctx, (route, signal, onCommit) =>
-				executeCommand(route, ctx, signal, onCommit),
+			await showSyncManager(ctx, (route, signal, onCommit, target) =>
+				executeCommand(route, ctx, signal, onCommit, target),
 			);
 		} catch (error) {
 			ctx.ui.setStatus(STATUS_KEY, undefined);
@@ -176,12 +175,14 @@ async function executeCommand(
 	ctx: ExtensionCommandContext,
 	signal?: AbortSignal,
 	onCommit?: () => void,
+	target?: string,
 ) {
 	try {
 		const command = await resolveSyncCommand(rawArgs, ctx);
 		if (!command) return;
 		const { subcommand, rest } = command;
 		const options = parseOptions(rest);
+		if (target !== undefined) options.target = target;
 		if (signal) options.signal = signal;
 		if (onCommit) options.onCommit = onCommit;
 		validateCommandOptions(subcommand, options);
@@ -191,7 +192,9 @@ async function executeCommand(
 				ctx.ui.notify(usage(), "info");
 				return;
 			case "use":
-				await useSyncTarget(ctx, options.args[0] ?? "");
+				await useSyncTarget(ctx, options.args[0] ?? "", (selectedTarget) =>
+					withLock("pull", () => pull(ctx, { ...options, target: selectedTarget })),
+				);
 				return;
 			case "init":
 				await initConfig(ctx);
@@ -215,8 +218,7 @@ async function executeCommand(
 				await withLock("push", () => push(ctx, options));
 				return;
 			case "pull":
-				await withLock("pull", () => pull(ctx, options));
-				return;
+				return await withLock("pull", () => pull(ctx, options));
 			case "sync":
 				await withLock("sync", () => syncBoth(ctx, options));
 				return;
@@ -235,6 +237,7 @@ async function executeCommand(
 	} catch (error) {
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 		if (signal?.aborted && error instanceof Error && error.name === "AbortError") return;
+		if (error instanceof TargetPullRequiresUiError) throw error;
 		ctx.ui.notify(errorMessage(error), "error");
 	}
 }
@@ -552,7 +555,7 @@ async function pull(ctx: ExtensionCommandContext | ExtensionContext, options: Co
 	) {
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 		ctx.ui.notify("Pull cancelled.", "info");
-		return;
+		return "cancelled" as const;
 	}
 
 	options.onCommit?.();
@@ -586,6 +589,7 @@ async function pull(ctx: ExtensionCommandContext | ExtensionContext, options: Co
 		);
 	}
 	if (options.reload) await maybeReload(ctx);
+	return "applied" as const;
 }
 
 async function syncBoth(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions) {

package/src/target-switch.ts

@@ -0,0 +1,119 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { setSyncTargetCompletions } from "./command.js";
+import {
+	configuredTargetNames,
+	loadConfig,
+	loadTargetSwitchAction,
+	readLocalConfigObject,
+	updateLocalConfig,
+} from "./config.js";
+import { safeTerminalText } from "./sync-format.js";
+import type { TargetSwitchAction } from "./types.js";
+
+export const TARGET_SWITCH_ACTION_OPTIONS: ReadonlyArray<{
+	label: string;
+	value: TargetSwitchAction;
+}> = [
+	{ label: "Ask before pull", value: "ask" },
+	{ label: "Start pull", value: "pull" },
+	{ label: "Switch only", value: "switch-only" },
+];
+
+export function targetSwitchActionLabel(action: TargetSwitchAction) {
+	return TARGET_SWITCH_ACTION_OPTIONS.find((option) => option.value === action)?.label ?? action;
+}
+
+export function targetSwitchActionFromLabel(label: string): TargetSwitchAction | undefined {
+	return TARGET_SWITCH_ACTION_OPTIONS.find((option) => option.label === label)?.value;
+}
+
+export async function saveTargetSwitchAction(action: TargetSwitchAction) {
+	await updateLocalConfig((settings) => {
+		if (settings.version !== 2) {
+			throw new Error("Target-switch settings require version 2 settings.");
+		}
+		return { ...settings, targetSwitchAction: action };
+	});
+}
+
+export type TargetPullOutcome = "applied" | "cancelled";
+
+export class TargetPullRequiresUiError extends Error {}
+
+export interface TargetSwitchResult {
+	pullApplied: boolean;
+}
+
+export async function useSyncTarget(
+	ctx: ExtensionCommandContext,
+	name: string,
+	pullCurrentTarget?: (target: string) => Promise<TargetPullOutcome | undefined>,
+): Promise<TargetSwitchResult> {
+	const normalized = name.trim();
+	if (!normalized) throw new Error("Usage: /sync use <target>");
+	await loadConfig(normalized);
+	const before = await readLocalConfigObject();
+	if (before?.version === 2 && before.activeTarget === normalized) {
+		ctx.ui.notify(`Target “${safeTerminalText(normalized)}” is already current.`, "info");
+		return { pullApplied: false };
+	}
+	const action = await loadTargetSwitchAction();
+	if (action === "pull" && !ctx.hasUI) {
+		throw new TargetPullRequiresUiError(
+			`Automatic target pulls require interactive confirmation; target “${safeTerminalText(normalized)}” was not switched. Use TUI or RPC mode.`,
+		);
+	}
+	let switched = false;
+	await updateLocalConfig((current) => {
+		if (current.version !== 2) throw new Error("Target switching requires version 2 settings.");
+		if (current.activeTarget === normalized) return current;
+		switched = true;
+		return { ...current, activeTarget: normalized };
+	});
+	if (!switched) {
+		ctx.ui.notify(`Target “${safeTerminalText(normalized)}” is already current.`, "info");
+		return { pullApplied: false };
+	}
+	setSyncTargetCompletions(await configuredTargetNames());
+
+	if (action === "switch-only") {
+		ctx.ui.notify(`Switched to “${safeTerminalText(normalized)}”. No files were pulled.`, "info");
+		return { pullApplied: false };
+	}
+	if (action === "ask") {
+		if (ctx.mode !== "tui") {
+			ctx.ui.notify(
+				`Switched to “${safeTerminalText(normalized)}”. No files were pulled because confirmation requires TUI mode; run /sync pull to apply the target.`,
+				"info",
+			);
+			return { pullApplied: false };
+		}
+		const confirmed = await ctx.ui.confirm(
+			`Review a pull for target “${safeTerminalText(normalized)}” now?`,
+			"pi-sync will check the remote snapshot and show the exact local writes and deletions before applying anything.",
+		);
+		if (!confirmed) {
+			ctx.ui.notify(
+				`Switched to “${safeTerminalText(normalized)}”; files were not pulled.`,
+				"info",
+			);
+			return { pullApplied: false };
+		}
+	}
+
+	ctx.ui.notify(
+		`Switched to “${safeTerminalText(normalized)}”. Checking remote files for a reviewed pull…`,
+		"info",
+	);
+	if (!pullCurrentTarget) {
+		throw new Error(`Switched to “${safeTerminalText(normalized)}”, but pull is unavailable.`);
+	}
+	const pullOutcome = await pullCurrentTarget(normalized);
+	if (pullOutcome === "cancelled") {
+		ctx.ui.notify(
+			`Pull cancelled; target “${safeTerminalText(normalized)}” remains active and synced files were not changed.`,
+			"info",
+		);
+	}
+	return { pullApplied: pullOutcome === "applied" };
+}

package/src/types.ts

@@ -1,4 +1,5 @@
 export type StorageProfileKind = "r2" | "s3-compatible";
+export type TargetSwitchAction = "ask" | "pull" | "switch-only";
 
 export interface StorageProfileSettings {
 	kind?: StorageProfileKind;
@@ -23,6 +24,7 @@ export interface SyncTargetSettings {
 export interface PiSyncSettingsV2 {
 	version: 2;
 	activeTarget?: string;
+	targetSwitchAction?: TargetSwitchAction;
 	profiles?: Record<string, StorageProfileSettings>;
 	targets?: Record<string, SyncTargetSettings>;
 	[key: string]: unknown;