@narumitw/pi-sync 0.49.5 → 0.49.8

package/README.md

@@ -54,22 +54,36 @@ Remote status: Not checked
 ```
 
 Primary actions include **Sync now**, **Switch sync setup**, **Status & changes**, **Settings**, and
-**More…**. The standard manager also owns setup and connection lists/details plus history and
-recovery. Secondary screens provide **Back**; Escape goes back and Ctrl+C closes the flow.
+**More…**. When pi-sync has already detected a synced-content-list mismatch, the manager instead
+shows **Sync status: Review needed**, puts **Review synced content (recommended)** first, and keeps
+**Sync now** visibly unavailable until the choice is reviewed. Opening the manager still performs no
+new remote request. The standard manager also owns setup and connection lists/details plus history
+and recovery. Secondary screens provide **Back**; Escape goes back and Ctrl+C closes the flow.
 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. If the active remote snapshot explicitly selects different
-content, automatic sync and pulls pause until you adopt the remote policy in Settings or publish the
-local policy with a reviewed force push.
+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:
+An explicit remote content-list mismatch now opens **Synced content differs** inside the same manager flow.
+Nothing changes until you choose an action.
+Choose **Review all paths (recommended)** first to compare exact remote-only paths, device-only paths, and both ordered lists.
+If membership matches but order differs, the review says that only ordering differs.
+Then choose one action:
+
+- **Use remote content list** revalidates the remote snapshot and reviewed local setup before saving only `sync.include`.
+  **Remote content list saved** confirms that no files were pulled and offers a separate **Continue Sync/Pull/Push now…** action plus **Done**.
+  Continue starts a fresh operation and exact preview for the captured setup rather than resuming stale work.
+- **Keep this device's content list and update remote…** opens the existing `push --force` preparation and exact confirmation without `--yes`.
+  Cancelling preparation or confirmation returns to the content-list choice without changing remote data.
+- **Cancel** returns to the manager without changing settings, files, remote data, or sync state.
+- **Later** appears when automatic startup sync detected the mismatch and returns immediately to the
+  Pi editor without changing anything.
+
+Choose **Review differences (recommended)** in an ordinary file-direction conflict 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,
@@ -79,10 +93,22 @@ local files, remote data, or sync state. Then choose one reviewed direction:
 - 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.
+Cancelling a preparation or confirmation returns to conflict resolution with no side effects.
+Back returns to the sync manager, and Ctrl+C closes the complete flow.
+
+When automatic startup sync detects an explicit content-list mismatch in TUI mode, it opens
+**Synced content differs** once for that session instead of ending at a warning. Choosing **Later** or
+closing the flow leaves a compact **Pi Sync needs review** widget above the editor and a
+**review needed** footer status. The attention state is in memory only, contains no credentials or
+file contents, and is revalidated before any settings or remote mutation. It clears after verified
+resolution, invalidation, session replacement, or shutdown.
+
+Interactive TUI `/sync sync`, `/sync pull`, and `/sync push` routes without `--yes` open the same
+review flow when they detect the mismatch. Explicit `--yes` routes remain non-interactive and report
+exact remote-only, device-only, or order-only guidance while leaving visible attention for later
+review. Shutdown automatic sync never opens a dialog because Pi is exiting.
+RPC startup and direct routes remain read-only and notification-based, while print and JSON modes
+remain unsupported for `/sync` because their UI output is not observable.
 
 ## ⚙️ Settings
 
@@ -203,17 +229,16 @@ remote snapshot. Leaving the editor opens an exact Include/Exclude review with *
 the draft and Discard/cancellation preserves the settings bytes. RPC remains a read-only summary with
 the manual `sync.include` path.
 
-Every new snapshot stores the normalized included-content selection separately from the files that
-happened to exist. This preserves selected-but-missing paths without syncing `pi-sync.json`, storage
-credentials, automatic-sync preferences, or setup names. **Settings → Remote included content** reads
-the active snapshot and offers **Adopt remote included content**, **Keep local included content**,
-**Review paths**, and **Cancel** when local and remote selections differ. Adoption revalidates the
-remote head, saves local settings atomically, and does not pull files or write sync state; review
-**Sync now** separately. A reviewed force push keeps local selection and explicitly replaces the
-remote policy while preserving eligible unmanaged remote files.
-
-Automatic sync and pull, including forced pull, pause on an explicit remote-policy difference rather
-than silently expanding local scope. Status reports matches and exact local-only/remote-only paths.
+Every new snapshot stores the normalized included-content selection separately from the files that happened to exist.
+This preserves selected-but-missing paths without syncing `pi-sync.json`, storage credentials, automatic-sync preferences, or setup names.
+**Settings → Compare synced content** opens the same review-first flow as a manager operation when local and remote lists differ.
+Adoption revalidates the remote head, immutable snapshot, reviewed storage coordinates, and local include list before one atomic settings update.
+The saved state changes only `sync.include`, preserves unknown settings fields, and never pulls files or writes sync state.
+Its explicit Continue action starts a fresh **Sync now** route, while **Done** leaves the reviewed settings change saved without implying a file operation.
+Keeping this device's list opens the reviewed force-push path and explicitly replaces the remote policy while preserving eligible unmanaged remote files.
+
+Automatic sync and pull, including forced pull, pause on an explicit remote-policy difference rather than silently expanding local scope.
+Status reports matches and exact local-only/remote-only paths.
 Old snapshots remain readable. Because they have no authoritative selection, pi-sync offers only a
 clearly labeled read-only partial discovery from safe remote file roots; selected-but-missing and
 preserved-unmanaged intent cannot be reconstructed. Use **Add custom path…** for any needed path.
@@ -297,7 +322,7 @@ The operational state root is `<agent-dir>/pi-sync/`. An existing installation c
 
 ## ♿ Conditional terminal accessibility smoke
 
-Pi exposes terminal components rather than a semantic/ARIA tree. Release validation checks textual state, keyboard operation, Escape/Back, control escaping, and narrow rendering. Critical meaning appears in text such as `(current)`, `Warning`, `Invalid`, `Saved`, `Cancelled`, and `Applied`; color is supplementary.
+Pi exposes terminal components rather than a semantic/ARIA tree. Release validation checks textual state, keyboard operation, Escape/Back, control escaping, and narrow rendering. Critical meaning appears in text such as `(current)`, `Review needed`, `Later`, `Warning`, `Invalid`, `Saved`, `Cancelled`, and `Applied`; color is supplementary. The attention widget is informational and does not pretend to be a clickable control.
 
 ## 🗂️ Package layout
 
@@ -305,12 +330,16 @@ Pi exposes terminal components rather than a semantic/ARIA tree. Release validat
 packages/pi-sync/
 ├── src/
 │   ├── index.ts
-│   ├── sync.ts
+│   ├── sync-extension.ts      # Lightweight Pi entry runtime and cached lazy loaders
+│   ├── sync.ts                # Compatibility barrel for package-local helpers
+│   ├── sync-errors.ts         # Lightweight setup/decision error contracts
 │   ├── config.ts
 │   ├── config-file.ts
 │   ├── state-directory.ts
 │   ├── settings-management.ts
 │   ├── manager-ui.ts
+│   ├── manager-attention.ts
+│   ├── sync-attention.ts
 │   ├── storage-connections-ui.ts
 │   ├── sync-setups-ui.ts
 │   ├── file-selection.ts
@@ -322,7 +351,8 @@ packages/pi-sync/
 │   ├── s3-backend.ts
 │   ├── webdav-backend.ts
 │   ├── git-backend.ts
-│   ├── snapshot.ts
+│   ├── snapshot-paths.ts      # Eager recovery-safe session path helpers
+│   ├── snapshot.ts            # Loaded only for snapshot operations/session push
 │   └── *.ts
 ├── test/
 ├── README.md

package/package.json

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

package/src/cancellable-operation.ts

@@ -1,6 +1,6 @@
 import {
 	BorderedLoader,
-	type ExtensionCommandContext,
+	type ExtensionContext,
 	type KeybindingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
@@ -8,10 +8,12 @@ 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";
+import type { RemoteSelectionDecision } from "./sync-policy.js";
 
 export type RunRouteResult =
 	| { kind: "completed"; outcome?: SetupPullOutcome }
 	| { kind: "decision-required"; decision: SyncDecision }
+	| { kind: "remote-selection-required"; decision: RemoteSelectionDecision }
 	| { kind: "failed" };
 
 export type RunRoute = (
@@ -34,7 +36,7 @@ interface CancellableOperationOptions {
 }
 
 export async function runCancellableOperation(
-	ctx: ExtensionCommandContext,
+	ctx: ExtensionContext,
 	message: string,
 	route: string,
 	runRoute: RunRoute,
@@ -51,7 +53,10 @@ export async function runCancellableOperation(
 	}
 	let commitStarted = false;
 	let routeResult: RunRouteResult | undefined;
-	const interaction = await runCustomInteraction<{ cancelled?: boolean; error?: unknown }>(ctx, {
+	const interaction = await runCustomInteraction<
+		{ cancelled?: boolean; error?: unknown },
+		ExtensionContext
+	>(ctx, {
 		signal,
 		isCurrent: () => !signal?.aborted,
 		create: ({ tui, theme, keybindings, signal: interactionSignal, complete }) => {

package/src/config.ts

@@ -142,6 +142,10 @@ export function syncConfigReviewIdentity(config: AnySyncConfig) {
 	]);
 }
 
+export function syncConfigReviewFingerprint(config: AnySyncConfig) {
+	return createHash("sha256").update(syncConfigReviewIdentity(config)).digest("hex");
+}
+
 function storageReviewFromConfig(config: AnySyncConfig): SyncSetupStorageReview {
 	return {
 		connectionName: config.connectionName,

package/src/index.ts

@@ -1 +1 @@
-export { default } from "./sync.js";
+export { default } from "./sync-extension.js";

package/src/manager-attention.ts

@@ -0,0 +1,81 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ActionMenuItem } from "@narumitw/pi-tui-kit";
+import type { RunRoute } from "./cancellable-operation.js";
+import { dispatchManagerResult } from "./manager-result-dispatcher.js";
+import type { ManagerDescription } from "./manager-state.js";
+import type { SyncAttentionState } from "./sync-attention.js";
+
+export interface SyncManagerAttentionOptions {
+	getAttention?: () => SyncAttentionState | undefined;
+	onSelectionResolved?: (expected: SyncAttentionState) => void;
+}
+
+export function attentionMainMenuItems(
+	manager: ManagerDescription,
+): ActionMenuItem<"main" | "more" | "recovery", "review-attention">[] {
+	if (!manager.attention) return [];
+	const disabled = manager.attentionReviewDisabled === true;
+	return [
+		{
+			id: "review-attention",
+			label: "Review synced content (recommended)",
+			action: "review-attention",
+			...(disabled
+				? {
+						disabled: true,
+						disabledReason: "Finish or recover the active operation first.",
+					}
+				: {}),
+		},
+	];
+}
+
+export function blockedSyncMenuItem(
+	label: string,
+	manager: ManagerDescription,
+): ActionMenuItem<"main" | "more" | "recovery", "sync"> | undefined {
+	if (label !== "Sync now (recommended)" || !manager.attentionBlocksSync) return undefined;
+	return {
+		id: "sync",
+		label,
+		description: "Review first.",
+		action: "sync",
+		disabled: true,
+		disabledReason: "Review synced content first.",
+	};
+}
+
+export async function showManagerAttention(
+	ctx: ExtensionCommandContext,
+	attention: SyncAttentionState,
+	runRoute: RunRoute,
+	signal: AbortSignal | undefined,
+	onSelectionResolved: (() => void) | undefined,
+): Promise<"close" | "stay"> {
+	const { showRemoteSelectionReview } = await import("./remote-selection-ui.js");
+	if (signal?.aborted) return "close";
+	const review = await showRemoteSelectionReview(
+		ctx,
+		attention.decision.setupName,
+		signal,
+		undefined,
+		{
+			decision: attention.decision,
+			origin: attention.origin,
+			runRoute,
+			onSelectionResolved,
+		},
+	);
+	if (review.kind === "route-result") {
+		const disposition = await dispatchManagerResult(
+			ctx,
+			review.result,
+			review.route,
+			runRoute,
+			signal,
+			{ onSelectionResolved },
+		);
+		return disposition.kind;
+	}
+	return review.kind === "closed" || review.kind === "stale" ? "close" : "stay";
+}

package/src/manager-result-dispatcher.ts

@@ -0,0 +1,93 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+	CancellableOperationResult,
+	RunRoute,
+	RunRouteResult,
+} from "./cancellable-operation.js";
+import { type RemoteSelectionOrigin, showRemoteSelectionReview } from "./remote-selection-ui.js";
+import { showSyncResolution } from "./sync-resolution-ui.js";
+
+const MAX_DECISION_TRANSITIONS = 32;
+
+export interface ManagerResultDisposition {
+	kind: "close" | "stay";
+	appliedRoute?: "sync" | "pull" | "push";
+}
+
+export interface ManagerResultOptions {
+	cancelLabel?: string;
+	onSelectionResolved?: () => void;
+	withStateAccess?: <T>(task: () => Promise<T>) => Promise<T>;
+}
+
+export async function dispatchManagerResult(
+	ctx: ExtensionContext,
+	initialResult: CancellableOperationResult,
+	origin: Exclude<RemoteSelectionOrigin, "settings">,
+	runRoute: RunRoute,
+	signal?: AbortSignal,
+	options: ManagerResultOptions = {},
+): Promise<ManagerResultDisposition> {
+	let result: CancellableOperationResult | RunRouteResult = initialResult;
+	let currentRoute: "sync" | "pull" | "push" = origin;
+	let resolving = false;
+
+	for (let transition = 0; transition < MAX_DECISION_TRANSITIONS; transition += 1) {
+		if (signal?.aborted) return { kind: "close" };
+		if (result.kind === "remote-selection-required") {
+			resolving = true;
+			const resolution = await showRemoteSelectionReview(
+				ctx,
+				result.decision.setupName,
+				signal,
+				undefined,
+				{
+					decision: result.decision,
+					origin: currentRoute,
+					runRoute,
+					cancelLabel: options.cancelLabel,
+					onSelectionResolved: options.onSelectionResolved,
+					withStateAccess: options.withStateAccess,
+				},
+			);
+			if (resolution.kind === "route-result") {
+				result = resolution.result;
+				currentRoute = resolution.route;
+				continue;
+			}
+			return resolution.kind === "closed" || resolution.kind === "stale"
+				? { kind: "close" }
+				: { kind: "stay" };
+		}
+		if (result.kind === "decision-required") {
+			resolving = true;
+			const resolution = await showSyncResolution(ctx, result.decision, runRoute, signal);
+			if (resolution.kind === "route-result") {
+				result = resolution.result;
+				currentRoute = resolution.route;
+				continue;
+			}
+			if (resolution.kind === "resolved") {
+				return { kind: "close", appliedRoute: resolution.direction };
+			}
+			return resolution.kind === "closed" || resolution.kind === "stale"
+				? { kind: "close" }
+				: { kind: "stay" };
+		}
+		if (result.kind === "closed") return { kind: "close" };
+		if (result.kind === "completed") {
+			const appliedRoute = result.outcome === "applied" ? currentRoute : undefined;
+			if (resolving || (origin === "pull" && result.outcome === "applied")) {
+				return { kind: "close", ...(appliedRoute ? { appliedRoute } : {}) };
+			}
+			return { kind: "stay", ...(appliedRoute ? { appliedRoute } : {}) };
+		}
+		return { kind: "stay" };
+	}
+
+	ctx.ui.notify(
+		"Sync resolution stopped after too many state changes. Start /sync again to review fresh state.",
+		"warning",
+	);
+	return { kind: "stay" };
+}

package/src/manager-state.ts

@@ -7,7 +7,8 @@ import {
 } from "./config.js";
 import { inspectLock, isStaleLock } from "./lock.js";
 import { errorMessage, ownRecord, safeTerminalText } from "./manager-helpers.js";
-import { syncIncludeSelection } from "./sync-policy.js";
+import { type SyncAttentionState, syncAttentionMatchesConfig } from "./sync-attention.js";
+import { compareSyncInclude, syncIncludeSelection } from "./sync-policy.js";
 import { countValidSyncSetups } from "./sync-setups-ui.js";
 import type { AnySyncConfig } from "./types.js";
 
@@ -19,9 +20,18 @@ export const MAIN_MENU_ACTIONS = [
 	"More…",
 ] as const;
 
+export interface ManagerDescription {
+	title: string;
+	actions: string[];
+	attention?: SyncAttentionState;
+	attentionBlocksSync?: boolean;
+	attentionReviewDisabled?: boolean;
+}
+
 export async function describeManagerState(
 	signal?: AbortSignal,
-): Promise<{ title: string; actions: string[] }> {
+	attention?: SyncAttentionState,
+): Promise<ManagerDescription> {
 	let raw: Record<string, unknown> | undefined;
 	try {
 		raw = await readLocalConfigObject();
@@ -66,6 +76,25 @@ export async function describeManagerState(
 		const recoverableLock =
 			lock.status === "unreadable" || (lock.status === "valid" && isStaleLock(lock.lock));
 		const selection = syncIncludeSelection(config.include);
+		let currentAttention: SyncAttentionState | undefined;
+		if (attention) {
+			try {
+				const attentionConfig =
+					attention.decision.setupName === config.setupName
+						? config
+						: await loadConfig(attention.decision.setupName);
+				if (syncAttentionMatchesConfig(attention, attentionConfig)) currentAttention = attention;
+			} catch {
+				currentAttention = undefined;
+			}
+			if (signal?.aborted) throw signal.reason;
+		}
+		const attentionComparison = currentAttention
+			? compareSyncInclude(
+					currentAttention.decision.localInclude,
+					currentAttention.decision.remoteInclude,
+				)
+			: undefined;
 		const noSyncedContent = config.include.length === 0;
 		const syncState =
 			liveLock || recoverableLock
@@ -92,7 +121,18 @@ export async function describeManagerState(
 				`Included: ${selection.builtIns.length} built-in group${selection.builtIns.length === 1 ? "" : "s"} · ${selection.custom.length} extra path${selection.custom.length === 1 ? "" : "s"} · Sessions ${selection.sessions ? "on" : "off"}`,
 				`Automatic sync: ${config.automatic ? "On" : "Off"}`,
 				`Last applied: ${lastAppliedSnapshot}`,
-				"Remote status: Not checked",
+				...(currentAttention
+					? [
+							currentAttention.decision.setupName === config.setupName
+								? "Sync status: Review needed"
+								: `Sync status: Review needed for setup ${safeTerminalText(currentAttention.decision.setupName)}`,
+							attentionComparison?.remoteOnly.length === 0 &&
+							attentionComparison.localOnly.length === 0
+								? "Only the synced-content order differs."
+								: `Remote-only paths: ${attentionComparison?.remoteOnly.length ?? 0} · Device-only paths: ${attentionComparison?.localOnly.length ?? 0}`,
+							"Nothing has been changed.",
+						]
+					: ["Remote status: Not checked"]),
 				...(noSyncedContent
 					? [
 							"",
@@ -117,6 +157,13 @@ export async function describeManagerState(
 					: noSyncedContent
 						? ["Settings", ...(canSwitch ? ["Switch sync setup"] : []), "Status & changes", "More…"]
 						: mainActions,
+			...(currentAttention
+				? {
+						attention: currentAttention,
+						attentionBlocksSync: currentAttention.decision.setupName === config.setupName,
+						attentionReviewDisabled: liveLock || recoverableLock,
+					}
+				: {}),
 		};
 	} catch (error) {
 		if (signal?.aborted) throw error;