@narumitw/pi-sync 0.49.6 → 0.49.9

package/README.md

@@ -54,22 +54,57 @@ 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.
 
+### Restore sync access
+
+When an operation is currently running, the manager shows its command and process ID, keeps sync and
+settings changes unavailable, and puts **Refresh operation status** first.
+When lock metadata is still protected by an active guard, the manager explains that another pi-sync
+process may be starting or finishing and asks the user to wait before refreshing.
+It never offers lock removal while an owner or guard may still be active.
+
+When a previous operation appears to have stopped without releasing its local lock, the manager shows
+**Sync paused** and puts **Restore sync access… (recommended)** first instead of hiding recovery
+inside **History & recovery…**.
+Unreadable metadata receives a stronger warning because pi-sync cannot verify who owns it.
+Close every other Pi session that may still be syncing, review the local-lock-only confirmation, then
+choose **Remove local lock and continue**.
+The guarded recovery path rechecks metadata and ownership before removal, changes no settings, local
+files, sync state, or remote data, and returns directly to the normal manager when access is restored.
+Cancellation leaves the lock unchanged.
+If ownership changes or a guard is still expiring, pi-sync refuses removal and keeps actionable status
+available for refresh or retry.
+The deterministic fallback remains `/sync unlock --stale` after the same no-other-sync verification.
+
 ### 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.
+
+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)** to inspect the exact affected paths without changing
-local files, remote data, or sync state. Then choose one reviewed direction:
+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 +114,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 +250,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 +343,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
 
@@ -313,6 +359,11 @@ packages/pi-sync/
 │   ├── state-directory.ts
 │   ├── settings-management.ts
 │   ├── manager-ui.ts
+│   ├── manager-state.ts
+│   ├── manager-recovery.ts
+│   ├── operation-availability.ts
+│   ├── manager-attention.ts
+│   ├── sync-attention.ts
 │   ├── storage-connections-ui.ts
 │   ├── sync-setups-ui.ts
 │   ├── file-selection.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-sync",
-	"version": "0.49.6",
+	"version": "0.49.9",
 	"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/lock.ts

@@ -152,7 +152,9 @@ export function isStaleLock(lock: LockFile) {
 }
 
 export async function unlock(ctx: ExtensionCommandContext, options: CommandOptions) {
+	throwIfAborted(options.signal);
 	await ensureStateDir();
+	throwIfAborted(options.signal);
 	let guard: Guard;
 	try {
 		guard = await acquireGuard();
@@ -179,7 +181,9 @@ export async function unlock(ctx: ExtensionCommandContext, options: CommandOptio
 }
 
 async function unlockGuarded(ctx: ExtensionCommandContext, options: CommandOptions) {
+	throwIfAborted(options.signal);
 	let inspection = await inspectLock();
+	throwIfAborted(options.signal);
 	if (inspection.status === "missing") {
 		ctx.ui.notify("No pi-sync lock is present.", "info");
 		return;
@@ -193,12 +197,19 @@ async function unlockGuarded(ctx: ExtensionCommandContext, options: CommandOptio
 			return;
 		}
 		inspection = await inspectLock();
+		throwIfAborted(options.signal);
 		if (inspection.status === "unreadable") {
 			// Legacy writers expose an empty file before writing owner metadata, so no
 			// automatic test can prove this file is abandoned. The explicit --stale
 			// flag is the user's confirmation that no legacy sync is still running.
+			throwIfAborted(options.signal);
 			await fs.rm(lockPath(), { force: true });
-			ctx.ui.notify("Removed unreadable pi-sync lock.", "info");
+			if (!options.signal?.aborted) {
+				ctx.ui.notify(
+					"Removed unreadable pi-sync lock. No settings, files, sync state, or remote data were changed.",
+					"info",
+				);
+			}
 			return;
 		}
 		if (inspection.status === "missing") {
@@ -210,8 +221,21 @@ async function unlockGuarded(ctx: ExtensionCommandContext, options: CommandOptio
 		ctx.ui.notify("Lock owner is still live; refusing to remove it.", "warning");
 		return;
 	}
+	throwIfAborted(options.signal);
 	await fs.rm(lockPath(), { force: true });
-	ctx.ui.notify("Removed stale pi-sync lock.", "info");
+	if (!options.signal?.aborted) {
+		ctx.ui.notify(
+			"Removed stale pi-sync lock. No settings, files, sync state, or remote data were changed.",
+			"info",
+		);
+	}
+}
+
+function throwIfAborted(signal?: AbortSignal) {
+	if (!signal?.aborted) return;
+	throw signal.reason instanceof Error
+		? signal.reason
+		: new DOMException("The operation was aborted", "AbortError");
 }
 
 async function releaseGuard(guard: Guard) {

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-recovery.ts

@@ -0,0 +1,65 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { runConfirmation } from "@narumitw/pi-tui-kit";
+import type { RunRoute } from "./cancellable-operation.js";
+import { errorMessage, safeTerminalText } from "./manager-helpers.js";
+import type { ManagerDescription } from "./manager-state.js";
+import { inspectOperationAvailability, operationCanRecover } from "./operation-availability.js";
+
+export type RecoveryDisposition = "restored" | "stay" | "close";
+
+export async function recoverSyncAccess(
+	ctx: ExtensionCommandContext,
+	manager: ManagerDescription,
+	runRoute: RunRoute,
+	sessionSignal: AbortSignal | undefined,
+	actionSignal: AbortSignal,
+): Promise<RecoveryDisposition> {
+	const operation = manager.operation;
+	if (!operation || !operationCanRecover(operation)) {
+		ctx.ui.notify(
+			"Operation status changed. Refresh the manager before retrying recovery.",
+			"warning",
+		);
+		return "stay";
+	}
+	const signal = sessionSignal ? AbortSignal.any([sessionSignal, actionSignal]) : actionSignal;
+	if (signal.aborted) return "close";
+	const unreadable = operation.kind === "recoverable-unreadable";
+	const details = unreadable
+		? "Pi-sync cannot verify who owns the unreadable lock. Close other Pi sessions that may be syncing before continuing."
+		: `The recorded ${safeTerminalText(operation.lock.command)} operation (pid ${operation.lock.pid}) appears to have stopped. Close other Pi sessions that may still be syncing before continuing.`;
+	const confirmation = await runConfirmation(ctx, {
+		title: "Restore sync access?",
+		message: [
+			details,
+			"",
+			"This removes only the local operation lock.",
+			"It does not change settings, local files, sync state, or remote data.",
+		].join("\n"),
+		confirmLabel: "Remove local lock and continue",
+		cancelLabel: "Cancel",
+		signal,
+		isCurrent: () => !signal.aborted,
+		onError: (_currentCtx, error) => {
+			ctx.ui.notify(
+				`Recovery confirmation failed: ${safeTerminalText(errorMessage(error))}`,
+				"error",
+			);
+		},
+	});
+	if (confirmation.kind === "stale") return "close";
+	if (confirmation.kind === "closed") {
+		if (confirmation.reason === "close") return "close";
+		if (!signal.aborted) {
+			ctx.ui.notify("Recovery cancelled; the local operation lock was not changed.", "info");
+		}
+		return "stay";
+	}
+	if (confirmation.kind !== "confirmed") return "stay";
+	if (signal.aborted) return "close";
+	await runRoute(unreadable ? "unlock --stale" : "unlock", signal);
+	if (signal.aborted) return "close";
+	const latest = await inspectOperationAvailability();
+	if (signal.aborted) return "close";
+	return latest.kind === "free" ? "restored" : "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" };
+}