@narumitw/pi-sync 0.54.1 → 0.54.3

package/src/ui/settings-ui.ts

@@ -1,5 +1,5 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import { defineMenu, type MenuSettingItem, runMenu } from "@narumitw/pi-tui-kit";
 import { loadConfig } from "../settings/config.js";
 import { localConfigPath } from "../settings/config-file.js";
 import { updateSyncSetup } from "../settings/settings-management.js";
@@ -14,9 +14,10 @@ import {
 import { captureMutationOwner } from "../sync/sync-local.js";
 import type { RunRoute } from "./cancellable-operation.js";
 import { dispatchManagerResult } from "./manager-result-dispatcher.js";
+import { boundedSettingsUI } from "./settings-frame.js";
 import { showEditSyncSetupStorage, showSyncSetupManager } from "./setup/setup-actions.js";
-import { AUTOMATIC_SYNC_DESCRIPTION } from "./setup/setup-prompts.js";
 import { showStorageConnections } from "./storage-connections-ui.js";
+import { AUTOMATIC_SYNC_DESCRIPTION, STARTUP_TRANSFER_DESCRIPTION, startupTransferSummary } from "./sync-behavior.js";
 import { configureSyncStatus } from "./sync-status.js";
 import { safeTerminalText } from "./terminal-text.js";
 
@@ -75,50 +76,64 @@ export async function showSyncSettings(
     | "content-policy"
     | "skip-secret-scan"
     | "show-status"
+    | "debug"
     | "on-switch"
     | "include"
     | "remote-include"
     | "storage-location"
     | "setups"
     | "connections";
-  const menu = defineMenu<Awaited<ReturnType<typeof loadConfig>>, "settings", Action, ExtensionCommandContext>({
-    start: "settings",
-    screens: {
-      settings: ({ state }) => ({
-        kind: "settings",
-        title: "Pi Sync Settings",
-        lines: [
-          `Sync setup: ${safeTerminalText(state.setupName)} · Storage connection: ${safeTerminalText(state.connectionName)}`,
-        ],
-        // Flat, searchable task ordering: Content, Destination, Automation, Merge, Other.
-        // Kit has no heading rows; avoid focusable fake headings or a new component.
-        items: [
+  type Group = "content" | "behavior" | "storage" | "advanced" | "all";
+  type Screen = "categories" | Group;
+  const groups: Record<Group, { label: string; ids: readonly string[] }> = {
+    content: { label: "Sync content", ids: ["include", "remoteInclude", "localFields"] },
+    behavior: { label: "Sync behavior", ids: ["automatic", "automaticTransfer", "onSwitch"] },
+    storage: { label: "Storage & setups", ids: ["storageLocation", "setups", "connections"] },
+    advanced: { label: "Advanced", ids: ["mergeSettings", "contentPolicy", "skipSecretScan", "showStatus", "debug"] },
+    all: { label: "All settings (search)", ids: [] },
+  };
+  let saveStatus = "Simple choices save immediately. Back does not undo saved changes.";
+  // Keep Kit's existing settings adapter: native SettingsList has no async save/rollback
+  // contract or injected keybindings. Kit preserves these safety and accessibility behaviors.
+  // Categories use public navigation; All settings retains cross-category search.
+  const settingsScreen = (state: Awaited<ReturnType<typeof loadConfig>>, group: Group) =>
+    ({
+      kind: "settings",
+      title: `Pi Sync Settings · ${groups[group].label}`,
+      lines: [
+        `Setup: ${safeTerminalText(state.setupName)} · Connection: ${safeTerminalText(state.connectionName)}`,
+        saveStatus,
+      ],
+      items: (
+        [
           {
             id: "include",
-            label: "Included content",
-            description: `${state.include.length} selected path${state.include.length === 1 ? "" : "s"}. Choose which paths this setup syncs.`,
-            currentValue: "Open editor",
+            label: "Included paths",
+            description:
+              "This setup: choose paths in a draft, then review and Save or Discard. No transfer is started.",
+            currentValue: `${state.include.length} paths · Edit`,
             action: "include",
           },
           {
             id: "remoteInclude",
-            label: "Compare synced content",
-            description: "Review this device and remote content lists before choosing either one.",
+            label: "Compare included paths",
+            description:
+              "This setup: compare included-path policies, not file contents. Review before saving either list; no files transfer unless you explicitly Continue.",
             currentValue: "Review",
             action: "remote-include",
           },
           {
             id: "localFields",
-            label: "Machine-local settings fields",
+            label: "Machine-local fields",
             description:
-              "Root field names omitted from future portable snapshots. Policy changes require directional migration; old history remains.",
+              "This setup: settings.json root fields excluded from future portable snapshots, not project overrides. Policy changes require reviewed directional migration; old history remains.",
             currentValue: `${state.localFields?.length ?? 0} fields · Edit`,
             action: "local-fields",
           },
           {
             id: "storageLocation",
             label: "Storage location",
-            description: "Destination: edit this setup's bucket, branch, or path; remote history is not moved.",
+            description: "This setup: review and save bucket, branch, or path changes. Remote history is not moved.",
             currentValue:
               state.backend.type === "s3"
                 ? `${safeTerminalText(state.backend.destination.bucket)} · ${safeTerminalText(state.backend.destination.prefix)}`
@@ -130,7 +145,8 @@ export async function showSyncSettings(
           {
             id: "setups",
             label: "Manage sync setups",
-            description: "Destination: add, switch, edit, or remove sync setups.",
+            description:
+              "This device: add, switch, edit, or remove sync setups. Each edit identifies its owner before saving.",
             currentValue: "Open",
             action: "setups",
           },
@@ -138,7 +154,7 @@ export async function showSyncSettings(
             id: "connections",
             label: "Manage storage connections",
             description:
-              "Destination: manage shared server addresses and credentials; edits may affect multiple setups.",
+              "Shared connections on this device: review affected setups before saving server or credential changes.",
             currentValue: "Open",
             action: "connections",
           },
@@ -152,63 +168,98 @@ export async function showSyncSettings(
           },
           {
             id: "automaticTransfer",
-            label: "Automatic transfer at startup",
-            description:
-              "May upload, replace, or delete selected files once at idle startup in TUI/RPC. Requires a baseline and conditional/lease publication; never reloads resources. Turning off cancels pending work.",
+            label: "Startup transfer",
+            description: `${STARTUP_TRANSFER_DESCRIPTION} Saved preference and requirements: ${startupTransferSummary(state)}.`,
             currentValue: state.automaticTransfer ? "On" : "Off",
             values: ["On", "Off"],
             action: "automatic-transfer",
           },
           {
             id: "onSwitch",
-            label: "After switching setup (all setups)",
-            description: "All setups: ask before a pull review, open it automatically, or switch without pulling.",
+            label: "On setup switch",
+            description:
+              "All setups on this device: ask before a pull review, open it automatically, or switch without pulling. Applies to subsequent switches.",
             currentValue: setupSwitchActionLabel(state.onSwitch),
             values: SETUP_SWITCH_ACTION_OPTIONS.map(({ label }) => label),
             action: "on-switch",
           },
           {
             id: "mergeSettings",
-            label: "Settings field merge (experimental)",
+            label: "Merge settings fields",
             description:
-              "Combine independent global settings.json fields using a verified private ancestor; arrays and nested objects remain atomic. No reload.",
+              "This setup, experimental opt-in: merge independent global settings.json root fields with a verified private ancestor. Arrays and nested objects remain atomic. Applies to subsequent sync; no reload.",
             currentValue: state.mergeSettings ? "On" : "Off",
             values: ["On", "Off"],
             action: "merge-settings",
           },
           {
             id: "contentPolicy",
-            label: "Content / partial sync (experimental)",
+            label: "Content merge / partial progress",
             description:
-              "Version-5 opt-in: bounded text and prefix-only sessions; partial progress keeps full withheld versions and old baseline hashes.",
+              "This setup, experimental opt-in: review the version-5 upgrade before saving. Merge bounded text and prefix-only sessions; partial progress keeps withheld versions and baselines. Applies to subsequent sync; disabling does not clear recovery evidence.",
             currentValue: state.mergeContent
               ? state.partialSync
-                ? "Content & partial"
-                : "Content only"
+                ? "Merge + partial"
+                : "Merge only"
               : state.partialSync
                 ? "Partial only"
                 : "Off",
-            values: ["Off", "Content only", "Content & partial", "Partial only"],
+            values: ["Off", "Merge only", "Merge + partial", "Partial only"],
             action: "content-policy",
           },
           {
             id: "skipSecretScan",
-            label: "Skip secret scan (all setups)",
-            description: "All setups: allow pushes without checking managed local files for possible secrets.",
+            label: "Skip secret scan",
+            description:
+              "All setups on this device: skip possible-secret checks on subsequent pushes, including automatic pushes. Other safety checks remain. Diagnostics still scans.",
             currentValue: state.skipSecretScan ? "On" : "Off",
             values: ["On", "Off"],
             action: "skip-secret-scan",
           },
           {
             id: "showStatus",
-            label: "Show status (all setups)",
-            description: "All setups: show sync progress and attention in Pi status.",
+            label: "Show sync status",
+            description:
+              "All setups on this device: saved and applied immediately to Pi status. Review widgets and notifications remain available.",
             currentValue: state.showStatus ? "On" : "Off",
             values: ["On", "Off"],
             action: "show-status",
           },
+          {
+            id: "debug",
+            label: "Debug startup timings",
+            description:
+              "All setups on this device: show startup durations in TUI/RPC notifications. Applies next session start; no credentials or file contents.",
+            currentValue: state.debug ? "On" : "Off",
+            values: ["On", "Off"],
+            action: "debug",
+          },
+        ] satisfies MenuSettingItem<Action>[]
+      ).filter((item) => group === "all" || groups[group].ids.includes(item.id)),
+    }) as const;
+  const menu = defineMenu<Awaited<ReturnType<typeof loadConfig>>, Screen, Action, ExtensionCommandContext>({
+    start: "categories",
+    screens: {
+      categories: ({ state }) => ({
+        kind: "actions",
+        title: "Pi Sync Settings",
+        lines: [
+          `Setup: ${safeTerminalText(state.setupName)} · Connection: ${safeTerminalText(state.connectionName)}`,
+          "Choose a task, or search all settings. Scope is shown in each setting's description.",
+          saveStatus,
         ],
+        items: (Object.entries(groups) as [Group, (typeof groups)[Group]][]).map(([id, group]) => ({
+          id,
+          label: group.label,
+          to: id,
+        })),
+        hint: "back",
       }),
+      content: ({ state }) => settingsScreen(state, "content"),
+      behavior: ({ state }) => settingsScreen(state, "behavior"),
+      storage: ({ state }) => settingsScreen(state, "storage"),
+      advanced: ({ state }) => settingsScreen(state, "advanced"),
+      all: ({ state }) => settingsScreen(state, "all"),
     },
     actions: {
       "storage-location": async ({ signal: actionSignal }) => {
@@ -232,8 +283,8 @@ export async function showSyncSettings(
         try {
           const previous = await loadConfig(setupName);
           validate();
-          const mergeContent = value === "Content only" || value === "Content & partial";
-          const partialSync = value === "Partial only" || value === "Content & partial";
+          const mergeContent = value === "Merge only" || value === "Merge + partial";
+          const partialSync = value === "Partial only" || value === "Merge + partial";
           if (
             !(await ctx.ui.confirm(
               "Save experimental content policy?",
@@ -243,6 +294,7 @@ export async function showSyncSettings(
           )
             return { kind: "rejected" };
           validate();
+          ctx.ui.notify("Saving reviewed Pi Sync policy…", "info");
           await updateLocalConfig((current) => {
             validate();
             const setup = current.syncSetups[setupName];
@@ -262,6 +314,9 @@ export async function showSyncSettings(
             };
           }, mutationSignal);
           validate();
+          saveStatus =
+            "Saved reviewed policy for this setup. Applies to subsequent sync operations; recovery evidence is retained.";
+          ctx.ui.notify(saveStatus, "info");
           return { kind: "stay" };
         } catch (error) {
           if (!mutationSignal.aborted) notifySaveFailure(ctx, error);
@@ -312,6 +367,7 @@ export async function showSyncSettings(
           );
           validate();
           if (!confirmed) return { kind: "rejected" };
+          ctx.ui.notify("Saving reviewed Pi Sync policy…", "info");
           await updateLocalConfig((current) => {
             validate();
             const setup = current.syncSetups[setupName];
@@ -327,6 +383,9 @@ export async function showSyncSettings(
             };
           }, mutationSignal);
           validate();
+          saveStatus =
+            "Saved reviewed policy for this setup. Applies to subsequent sync operations; recovery evidence is retained.";
+          ctx.ui.notify(saveStatus, "info");
           return { kind: "stay" };
         } catch (error) {
           if (!mutationSignal.aborted) notifySaveFailure(ctx, error);
@@ -405,6 +464,18 @@ export async function showSyncSettings(
           return { kind: "rejected" };
         }
       },
+      debug: async ({ value, signal: actionSignal }) => {
+        const debug = value === "On";
+        const mutationSignal = signal ? AbortSignal.any([signal, actionSignal]) : actionSignal;
+        try {
+          await updateLocalConfig((settings) => ({ ...settings, debug }), mutationSignal);
+          if (mutationSignal.aborted) return { kind: "rejected" };
+          return { kind: "stay" };
+        } catch (error) {
+          if (!mutationSignal.aborted) notifySaveFailure(ctx, error);
+          return { kind: "rejected" };
+        }
+      },
       "on-switch": async ({ value, signal: actionSignal }) => {
         const action = value ? setupSwitchActionFromLabel(value) : undefined;
         if (!action) return { kind: "rejected" };
@@ -444,6 +515,33 @@ export async function showSyncSettings(
       },
     },
   });
+  for (const id of [
+    "automatic",
+    "automatic-transfer",
+    "merge-settings",
+    "skip-secret-scan",
+    "show-status",
+    "debug",
+    "on-switch",
+  ] as const) {
+    const save = menu.actions[id];
+    menu.actions[id] = async (action) => {
+      const validate = captureMutationOwner(ctx, action.signal);
+      validate();
+      ctx.ui.notify("Saving Pi Sync setting…", "info");
+      const result = await save(action);
+      if (action.signal.aborted || signal?.aborted) return { kind: "rejected" };
+      validate();
+      saveStatus =
+        result?.kind === "rejected"
+          ? "Save failed or rejected. Previous value retained; retry is available."
+          : id === "automatic-transfer" || id === "automatic" || id === "debug"
+            ? "Saved. Enabling startup work applies next session start; completed transfers are not undone."
+            : "Saved. Applies to subsequent operations; status visibility applies immediately.";
+      ctx.ui.notify(saveStatus, result?.kind === "rejected" ? "warning" : "info");
+      return result;
+    };
+  }
   async function resumeSettings(editorSignal: AbortSignal) {
     if (editorSignal.aborted) return { kind: "close" as const };
     try {
@@ -455,7 +553,7 @@ export async function showSyncSettings(
       return { kind: "close" as const };
     }
   }
-  await runMenu(ctx, menu, {
+  await runMenu({ ...ctx, ui: boundedSettingsUI(ctx) }, menu, {
     getState: () => loadConfig(setupName),
     signal,
     isCurrent: () => !signal?.aborted,

package/src/ui/setup/setup-prompts.ts

@@ -2,7 +2,11 @@ import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { readLocalConfigObject } from "../../settings/settings-store.js";
 import { validateConfigName } from "../../settings/settings-validation.js";
 import { DEFAULT_SYNC_INCLUDE } from "../../sync/sync-policy.js";
+import { AUTOMATIC_SYNC_DESCRIPTION } from "../sync-behavior.js";
 import { safeTerminalText } from "../terminal-text.js";
+
+export { AUTOMATIC_SYNC_DESCRIPTION } from "../sync-behavior.js";
+
 import { promptTextInput } from "./text-input.js";
 
 export async function readSetupConnection(name: string, signal?: AbortSignal) {
@@ -12,9 +16,6 @@ export async function readSetupConnection(name: string, signal?: AbortSignal) {
   return connection;
 }
 
-export const AUTOMATIC_SYNC_DESCRIPTION =
-  "Check the current setup in the background at startup; review changes in /sync before transferring. At shutdown, automatically push selected content only when sessions are included. No startup dialogs.";
-
 export async function chooseSetupContent(ctx: ExtensionCommandContext, signal?: AbortSignal) {
   const choice = await ctx.ui.select(
     "Choose included content\n\nRecommended: Pi settings, instructions, skills, prompts, themes, and extensions.\nMinimal: settings.json and AGENTS.md.\nReview the exact paths before saving.",

package/src/ui/sync-behavior.ts

@@ -0,0 +1,15 @@
+export const AUTOMATIC_SYNC_DESCRIPTION =
+  "This setup: check remote state once at startup in TUI/RPC. At shutdown, push all selected content only when sessions are included; reload skips that push. Saves apply to subsequent operations; a new check waits for the next session start. This does not enable startup transfer.";
+
+export const STARTUP_TRANSFER_DESCRIPTION =
+  "This setup: separate opt-in for one idle startup transfer in TUI/RPC. Requires an accepted baseline, matching remote included paths, and conditional or lease-protected publication (Git, verified WebDAV, or R2/S3 with verified conditional writes). May upload, replace, or remove selected files. Never reloads resources. Enabling applies next session start; opening Settings cancels pending work. Completed transfers are not undone.";
+
+export function startupTransferSummary(config: {
+  automaticTransfer?: boolean;
+  backend: { type: "s3" | "git" | "webdav" };
+}) {
+  if (!config.automaticTransfer) return "Off";
+  return config.backend.type === "s3"
+    ? "On (next idle startup; R2/S3 conditional-write verification required)"
+    : "On (next idle startup; baseline and remote policy checks required)";
+}

package/src/ui/sync-format.ts

@@ -5,12 +5,17 @@ import type { Snapshot } from "../snapshot/snapshot-types.js";
 import { inspectRemoteSelection } from "../sync/sync-policy.js";
 import { fileHashMap } from "../sync/sync-state.js";
 import { safeTerminalText, snapshotPathLabel } from "./terminal-text.js";
+import { transferChanges, transferCounts } from "./transfer-changes.js";
 
 export function formatDiff(local: Snapshot, remote: Snapshot) {
   const localMap = fileHashMap(local);
   const remoteMap = fileHashMap(remote);
   const allPaths = [...new Set([...Object.keys(localMap), ...Object.keys(remoteMap)])].sort();
-  const lines = [`local: ${local.files.length} files`, `remote: ${remote.id} (${remote.files.length} files)`, ""];
+  const lines = [
+    `local: ${local.files.length} files`,
+    `remote: ${safeTerminalText(remote.id)} (${remote.files.length} files)`,
+    "",
+  ];
   let changed = 0;
   for (const filePath of allPaths) {
     if (!Object.hasOwn(localMap, filePath)) {
@@ -29,9 +34,10 @@ export function formatDiff(local: Snapshot, remote: Snapshot) {
 }
 
 export function formatSnapshotOnlyDiff(title: string, snapshot: Snapshot) {
-  return [`${title}: ${snapshot.id}`, ...snapshot.files.map((file) => `Add: ${snapshotPathLabel(file.path)}`)].join(
-    "\n",
-  );
+  return [
+    `${safeTerminalText(title)}: ${safeTerminalText(snapshot.id)}`,
+    ...snapshot.files.map((file) => `Add: ${snapshotPathLabel(file.path)}`),
+  ].join("\n");
 }
 
 export function formatPushSummary(
@@ -45,26 +51,40 @@ export function formatPushSummary(
   return [
     `Sync setup: ${safeTerminalText(config.setupName)}`,
     `Storage location: ${safeTerminalText(destination)}`,
-    `Upload ${upload.files.length} files from ${safeTerminalText(agentDir())}.`,
+    `Direction: Local → Remote. Source: ${safeTerminalText(agentDir())}.`,
+    `Publish a snapshot containing ${upload.files.length} files; unchanged and preserved files are not counted as changes.`,
     `Sessions: ${upload.syncSessions ? "included — may contain private conversations" : "not included"}`,
-    head ? `Remote latest: ${head.snapshotId}` : "Remote latest: empty",
-    "Publication effect: the backend's active head will reference the new immutable snapshot.",
+    head ? `Remote latest: ${safeTerminalText(head.snapshotId)}` : "Remote latest: empty",
+    "Publication effect: the backend's active head will reference the new immutable snapshot. Removed paths leave the active snapshot; retained history is not erased.",
     ...(remote && inspectRemoteSelection(config.include, remote).kind === "different"
       ? ["Included-content policy effect: replace the differing remote selection with this setup's local selection."]
       : []),
     formatPublicationPreview(remote, upload),
-    preservedRemoteFileCount > 0
-      ? `Possible secrets in locally managed files were scanned before this prompt; ${preservedRemoteFileCount} preserved remote file(s) were not rescanned.`
-      : "Possible secrets were scanned before this prompt.",
+    config.skipSecretScan
+      ? "Warning: possible-secret scanning is disabled for this push."
+      : preservedRemoteFileCount > 0
+        ? `Possible secrets in locally managed files were scanned before this prompt; ${preservedRemoteFileCount} preserved remote file(s) were not rescanned.`
+        : "Possible secrets were scanned before this prompt.",
   ].join("\n");
 }
 
-export function formatApplyPreview(local: Snapshot, remote: Snapshot) {
-  return formatDirectionalChanges(local, remote, {
-    add: "Add locally",
-    update: "Update locally",
-    remove: "Remove locally",
-  });
+export function formatApplyPreview(
+  local: Snapshot,
+  remote: Snapshot,
+  protectedPaths: ReadonlySet<string> = new Set(),
+  additionalRemovals: readonly string[] = [],
+) {
+  return formatDirectionalChanges(
+    local,
+    remote,
+    {
+      add: "Add locally",
+      update: "Update locally",
+      remove: "Remove locally",
+    },
+    protectedPaths,
+    additionalRemovals,
+  );
 }
 
 export function formatPullSummary(
@@ -72,15 +92,20 @@ export function formatPullSummary(
   destination: string,
   local: Snapshot,
   remote: Snapshot,
-  protectedSessionCount: number,
+  protectedPaths: ReadonlySet<string>,
+  additionalRemovals: readonly string[] = [],
 ) {
   return [
     `Sync setup: ${safeTerminalText(config.setupName)}`,
     `Storage location: ${safeTerminalText(destination)}`,
+    "Direction: Remote → Local.",
     `Snapshot: ${safeTerminalText(remote.id)}`,
     `Sessions: ${remote.syncSessions ? "included — may contain private conversations" : "not included"}`,
-    `Protected live sessions: ${protectedSessionCount || "none"}`,
-    formatApplyPreview(local, remote),
+    `Protected live sessions: ${protectedPaths.size || "none"}`,
+    formatApplyPreview(local, remote, protectedPaths, additionalRemovals),
+    ...(additionalRemovals.length
+      ? ["Case-variant aliases listed above are removed before writing canonical paths."]
+      : []),
     "A local backup is created before these writes/deletes. The remote active snapshot is unchanged.",
   ].join("\n");
 }
@@ -91,25 +116,25 @@ export function formatRollbackSummary(
   local: Snapshot,
   remote: Snapshot,
   requestedSnapshot: string,
-  protectedSessionCount: number,
+  protectedPaths: ReadonlySet<string>,
+  additionalRemovals: readonly string[] = [],
 ) {
   return [
     `Sync setup: ${safeTerminalText(config.setupName)}`,
     `Storage location: ${safeTerminalText(destination)}`,
+    "Direction: Historical snapshot → Local and remote active head.",
     `Snapshot: ${safeTerminalText(requestedSnapshot)}`,
     `Sessions: ${remote.syncSessions ? "included — may contain private conversations" : "not included"}`,
-    `Protected live sessions: ${protectedSessionCount || "none"}`,
-    formatApplyPreview(local, remote),
+    `Protected live sessions: ${protectedPaths.size || "none"}`,
+    formatApplyPreview(local, remote, protectedPaths, additionalRemovals),
+    ...(additionalRemovals.length
+      ? ["Case-variant aliases listed above are removed before writing canonical paths."]
+      : []),
     "A local backup is created before applying; the backend's active head will change.",
   ].join("\n");
 }
 
 export function formatPublicationPreview(remote: Snapshot | undefined, upload: Snapshot) {
-  if (!remote) {
-    return ["Remote is empty.", ...upload.files.map((file) => `Add remotely: ${snapshotPathLabel(file.path)}`)].join(
-      "\n",
-    );
-  }
   return formatDirectionalChanges(remote, upload, {
     add: "Add remotely",
     update: "Update remotely",
@@ -118,21 +143,27 @@ export function formatPublicationPreview(remote: Snapshot | undefined, upload: S
 }
 
 function formatDirectionalChanges(
-  before: Snapshot,
+  before: Snapshot | undefined,
   after: Snapshot,
   labels: { add: string; update: string; remove: string },
+  protectedPaths: ReadonlySet<string> = new Set(),
+  additionalRemovals: readonly string[] = [],
 ) {
-  const beforeMap = fileHashMap(before);
-  const afterMap = fileHashMap(after);
-  const paths = [...new Set([...Object.keys(beforeMap), ...Object.keys(afterMap)])].sort();
-  const lines: string[] = [];
-  for (const filePath of paths) {
-    if (!Object.hasOwn(beforeMap, filePath)) lines.push(`${labels.add}: ${snapshotPathLabel(filePath)}`);
-    else if (!Object.hasOwn(afterMap, filePath)) lines.push(`${labels.remove}: ${snapshotPathLabel(filePath)}`);
-    else if (beforeMap[filePath] !== afterMap[filePath]) lines.push(`${labels.update}: ${snapshotPathLabel(filePath)}`);
+  const changes = transferChanges(before, after, protectedPaths);
+  const known = new Set(changes.map((change) => change.path));
+  for (const filePath of additionalRemovals) {
+    if (!known.has(filePath) && !protectedPaths.has(filePath)) {
+      changes.push({ path: filePath, action: "Delete" });
+      known.add(filePath);
+    }
   }
-  if (lines.length === 0) lines.push("No file changes.");
-  return lines.join("\n");
+  const counts = transferCounts(changes);
+  const label = { Add: labels.add, Update: labels.update, Delete: labels.remove };
+  return [
+    `Changes: ${counts.add} add · ${counts.update} update · ${counts.remove} remove`,
+    ...changes.map((change) => `${label[change.action]}: ${snapshotPathLabel(change.path)}`),
+    ...(changes.length ? [] : ["No file changes."]),
+  ].join("\n");
 }
 
 export function countPreservedRemoteFiles(local: Snapshot, upload: Snapshot) {

package/src/ui/transfer-changes.ts

@@ -0,0 +1,33 @@
+import type { Snapshot } from "../snapshot/snapshot-types.js";
+import { fileHashMap } from "../sync/sync-state.js";
+
+export interface TransferChange {
+  path: string;
+  action: "Add" | "Update" | "Delete";
+}
+
+/** Compare effective before/after snapshots, not raw planner decisions. */
+export function transferChanges(
+  before: Snapshot | undefined,
+  after: Snapshot,
+  protectedPaths: ReadonlySet<string> = new Set(),
+): TransferChange[] {
+  const beforeMap = before ? fileHashMap(before) : {};
+  const afterMap = fileHashMap(after);
+  return [...new Set([...Object.keys(beforeMap), ...Object.keys(afterMap)])]
+    .sort()
+    .flatMap((filePath): TransferChange[] => {
+      if (protectedPaths.has(filePath)) return [];
+      if (!Object.hasOwn(beforeMap, filePath)) return [{ path: filePath, action: "Add" }];
+      if (!Object.hasOwn(afterMap, filePath)) return [{ path: filePath, action: "Delete" }];
+      return beforeMap[filePath] !== afterMap[filePath] ? [{ path: filePath, action: "Update" }] : [];
+    });
+}
+
+export function transferCounts(changes: readonly TransferChange[]) {
+  return {
+    add: changes.filter((change) => change.action === "Add").length,
+    update: changes.filter((change) => change.action === "Update").length,
+    remove: changes.filter((change) => change.action === "Delete").length,
+  };
+}

package/src/ui/transfer-review.ts

@@ -0,0 +1,27 @@
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { confirmMergeReview } from "./merge-review.js";
+
+/** Reuse the scrollable safe-default review in TUI; retain RPC's confirmation protocol. */
+export async function confirmTransferReview(
+  ctx: ExtensionCommandContext | ExtensionContext,
+  title: string,
+  content: string,
+  signal: AbortSignal | undefined,
+  validate: () => void,
+) {
+  validate();
+  const isCurrent = () => {
+    try {
+      validate();
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const confirmed =
+    ctx.mode === "tui" && ctx.hasUI
+      ? await confirmMergeReview(ctx, title, content, signal, isCurrent, "apply reviewed transfer", content.split("\n"))
+      : await ctx.ui.confirm(title, content, { signal });
+  validate();
+  return confirmed;
+}