@narumitw/pi-sync 0.54.1 → 0.54.3

package/src/sync/startup-timings.ts

@@ -0,0 +1,90 @@
+import { performance } from "node:perf_hooks";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+type StartupStage =
+  | "transaction recovery"
+  | "settings read"
+  | "config resolution"
+  | "inspection import"
+  | "inspection and guards"
+  | "backend initialization"
+  | "local snapshot"
+  | "sync state read"
+  | "remote head"
+  | "operations import"
+  | "automatic transfer"
+  | "transfer authorization"
+  | "transfer backend initialization"
+  | "transfer journal read"
+  | "transfer journal recovery"
+  | "transfer state read"
+  | "transfer local snapshot"
+  | "transfer remote head"
+  | "transfer snapshot download"
+  | "transfer unchanged verification"
+  | "transfer merge planning"
+  | "transfer settings merge"
+  | "transfer content merge"
+  | "transfer preflight"
+  | "transfer backup"
+  | "transfer journal write"
+  | "transfer remote publication"
+  | "transfer local apply"
+  | "transfer baseline write"
+  | "transfer cleanup";
+
+/** Fixed labels and durations only: never retain errors, paths, settings, or payloads. */
+export function createStartupTimings() {
+  const started = performance.now();
+  const stages = new Map<StartupStage, { ms: number; calls: number; interrupted: boolean }>();
+  let unchanged = false;
+  return {
+    markUnchanged() {
+      unchanged = true;
+    },
+    async measure<T>(stage: StartupStage, run: () => T | Promise<T>): Promise<T> {
+      const start = performance.now();
+      let completed = false;
+      try {
+        const result = await run();
+        completed = true;
+        return result;
+      } finally {
+        const previous = stages.get(stage);
+        stages.set(stage, {
+          ms: (previous?.ms ?? 0) + performance.now() - start,
+          calls: (previous?.calls ?? 0) + 1,
+          interrupted: Boolean(previous?.interrupted || !completed),
+        });
+      }
+    },
+    publish(
+      ctx: ExtensionContext,
+      enabled: boolean,
+      sessionSignal: AbortSignal,
+      scope: "local initialization" | "background startup",
+      outcome: "completed" | "stopped" = "completed",
+    ) {
+      if (!enabled || !ctx.hasUI || sessionSignal.aborted) return;
+      try {
+        ctx.ui.notify(
+          [
+            `pi-sync debug: ${scope} (${outcome})`,
+            ...Array.from(
+              stages,
+              ([stage, value]) =>
+                `${stage}: ${value.ms.toFixed(1)} ms${value.calls > 1 ? ` (${value.calls} calls)` : ""}${value.interrupted ? " (interrupted)" : ""}`,
+            ),
+            ...(unchanged ? ["transfer result: unchanged (fast path)"] : []),
+            `total: ${(performance.now() - started).toFixed(1)} ms`,
+          ].join("\n"),
+          "info",
+        );
+      } catch {
+        // Diagnostics must not change sync behavior if the UI is unavailable during teardown.
+      }
+    },
+  };
+}
+
+export type StartupTimings = ReturnType<typeof createStartupTimings>;

package/src/sync/sync-inspection.ts

@@ -4,6 +4,7 @@ import { createSnapshot } from "../snapshot/snapshot.js";
 import type { SnapshotOptions } from "../snapshot/snapshot-types.js";
 import { readStateForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
 import { throwIfAborted } from "./signals.js";
+import { createStartupTimings, type StartupTimings } from "./startup-timings.js";
 import { inspectRemoteSelection } from "./sync-policy.js";
 import { hasLocalChanges, remoteChangedSinceState } from "./sync-state.js";
 
@@ -13,15 +14,18 @@ export async function inspectSync(
   options: SnapshotOptions,
   signal?: AbortSignal,
   factory: SyncBackendFactory = createSyncBackend,
+  timings: StartupTimings = createStartupTimings(),
 ) {
   throwIfAborted(signal);
-  const backend = await factory(config);
+  const backend = await timings.measure("backend initialization", () => factory(config));
   throwIfAborted(signal);
-  const local = await createSnapshot(config.snapshotIdentity, { ...options, signal });
+  const local = await timings.measure("local snapshot", () =>
+    createSnapshot(config.snapshotIdentity, { ...options, signal }),
+  );
   throwIfAborted(signal);
-  const state = await readStateForConfig(config);
+  const state = await timings.measure("sync state read", () => readStateForConfig(config));
   throwIfAborted(signal);
-  const head = await backend.readHead(signal);
+  const head = await timings.measure("remote head", () => backend.readHead(signal));
   throwIfAborted(signal);
   return {
     head,

package/src/sync/sync-mutations.ts

@@ -23,7 +23,7 @@ import { applySnapshot } from "../snapshot/snapshot-apply.js";
 import type { Snapshot } from "../snapshot/snapshot-types.js";
 import { pruneMergeBaselines } from "../state/merge-baseline-store.js";
 import type { SyncState } from "../state/state-types.js";
-import { readStateForConfig, writeStateForConfig } from "../state/sync-state-store.js";
+import { readStateForConfig, syncStateFingerprint, writeStateForConfig } from "../state/sync-state-store.js";
 import {
   countPreservedRemoteFiles,
   formatPullSummary,
@@ -31,6 +31,8 @@ import {
   formatRollbackSummary,
 } from "../ui/sync-format.js";
 import { setSyncStatus } from "../ui/sync-status.js";
+import { confirmTransferReview } from "../ui/transfer-review.js";
+import { inspectCaseCleanup, revalidateCaseCleanup } from "./apply-review.js";
 import { confirmFieldMigration } from "./field-migration.js";
 import { overlayLocalFields, portableSnapshot, sameLocalFields, validatePortableSnapshot } from "./local-fields.js";
 import { readMergeJournal, requireNoMergeJournal, retireMergeJournal } from "./merge-journal.js";
@@ -155,7 +157,7 @@ export async function push(
     }
   }
 
-  if (!remoteForUpload && head && config.localFields !== undefined)
+  if (!remoteForUpload && head && (config.localFields !== undefined || !options.yes))
     remoteForUpload = await readSnapshotForHead(backend, head, options.signal);
   if (!(await confirmFieldMigration(ctx, config, state, remoteForUpload, options.force, options.signal))) {
     setSyncStatus(ctx, undefined);
@@ -208,12 +210,15 @@ export async function push(
   if (configIdentity !== syncCheckConfigFingerprint(await loadConfig(options.setup)))
     throw new Error("Settings changed during push review.");
   validateMutation();
-  if (config.localFields !== undefined || (await readMergeJournal(config))) {
+  if (!options.yes || config.localFields !== undefined || (await readMergeJournal(config))) {
     const current = await createSnapshot(config.snapshotIdentity, snapshotOptionsForContext(ctx, config));
     if (!sameHashes(fileHashMap(current), fileHashMap(localRaw)))
-      throw new Error("Local content changed during recovery review; retry from current bytes.");
+      throw new Error("Local content changed during push review; retry from current bytes.");
   }
-  requireResolvedDirectionalProgress(await readStateForConfig(config), options);
+  const currentState = await readStateForConfig(config);
+  if (!options.yes && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
+    throw new Error("Baseline changed during push review.");
+  requireResolvedDirectionalProgress(currentState, options);
   validateMutation();
   const result = await backend.publishSnapshot(upload, expectedRemoteHead(head), {
     signal: options.signal,
@@ -316,11 +321,23 @@ export async function pull(
     });
   }
 
+  const caseCleanup = options.yes ? [] : await inspectCaseCleanup(physical, options.signal);
+  validateMutation();
   if (
     !options.yes &&
-    !(await ctx.ui.confirm(
+    !(await confirmTransferReview(
+      ctx,
       snapshotIncludesSessions(remote) ? "Pull pi settings and sessions?" : "Pull pi settings?",
-      formatPullSummary(config, backend.destination, local, physical, protectedSessionPaths(ctx).size),
+      formatPullSummary(
+        config,
+        backend.destination,
+        local,
+        physical,
+        protectedSessionPaths(ctx),
+        caseCleanup.map((item) => item.path),
+      ),
+      options.signal,
+      validateMutation,
     ))
   ) {
     setSyncStatus(ctx, undefined);
@@ -353,7 +370,11 @@ export async function pull(
   const backup = await backupLocal(config.snapshotIdentity, snapshotOptionsForContext(ctx, config), options.signal);
   const applySessionDir = await sessionDirForApply(ctx, physical);
   if (recoveringMerge) await requireFreshRecovery();
-  requireResolvedDirectionalProgress(await readStateForConfig(config), options);
+  const currentState = await readStateForConfig(config);
+  if (!options.yes && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
+    throw new Error("Baseline changed during pull review.");
+  requireResolvedDirectionalProgress(currentState, options);
+  if (!options.yes) await revalidateCaseCleanup(caseCleanup, physical, options.signal);
   validateMutation();
   options.onCommit?.();
   const lastFileHashes = await applySnapshot(physical, protectedSessionPaths(ctx), {
@@ -573,11 +594,21 @@ export async function rollback(
   if (!(await confirmFieldMigration(ctx, config, state, currentRemote, true, options.signal))) return;
   validateMutation();
   const physical = overlayLocalFields(remote, local, config.localFields);
+  const caseCleanup = options.yes ? [] : await inspectCaseCleanup(physical, options.signal);
+  validateMutation();
 
   if (!options.yes) {
     const confirmed = await ctx.ui.confirm(
       snapshotIncludesSessions(remote) ? "Rollback pi settings and sessions?" : "Rollback pi settings?",
-      formatRollbackSummary(config, backend.destination, local, physical, target, protectedSessionPaths(ctx).size),
+      formatRollbackSummary(
+        config,
+        backend.destination,
+        local,
+        physical,
+        target,
+        protectedSessionPaths(ctx),
+        caseCleanup.map((item) => item.path),
+      ),
       { signal: options.signal },
     );
     validateMutation();
@@ -599,7 +630,11 @@ export async function rollback(
   throwIfAborted(options.signal);
   const backup = await backupLocal(config.snapshotIdentity, snapshotOptionsForContext(ctx, config), options.signal);
   const applySessionDir = await sessionDirForApply(ctx, remote);
-  requireResolvedDirectionalProgress(await readStateForConfig(config), options, false);
+  const currentState = await readStateForConfig(config);
+  if (!options.yes && syncStateFingerprint(currentState) !== syncStateFingerprint(state))
+    throw new Error("Baseline changed during rollback review.");
+  requireResolvedDirectionalProgress(currentState, options, false);
+  if (!options.yes) await revalidateCaseCleanup(caseCleanup, physical, options.signal);
   validateMutation();
   options.onCommit?.();
   const lastFileHashes = await applySnapshot(physical, protectedSessionPaths(ctx), {
@@ -724,9 +759,12 @@ async function confirmPush(
 ) {
   throwIfAborted(options.signal);
   if (options.yes) return true;
-  const confirmed = await ctx.ui.confirm(
+  const confirmed = await confirmTransferReview(
+    ctx,
     title,
     formatPushSummary(config, backend.destination, upload, head, countPreservedRemoteFiles(local, upload), remote),
+    options.signal,
+    captureMutationOwner(ctx, options.signal),
   );
   throwIfAborted(options.signal);
   if (confirmed) return true;

package/src/sync/sync-queries.ts

@@ -7,6 +7,7 @@ import { snapshotOptionsForContext } from "../snapshot/session-paths.js";
 import { createSnapshot, scanSnapshot } from "../snapshot/snapshot.js";
 import type { SnapshotOptions } from "../snapshot/snapshot-types.js";
 import { inspectLock, isLockGuardHeld, isStaleLock, withLock } from "../state/lock.js";
+import { readStateForConfig } from "../state/sync-state-store.js";
 import { formatDiff, formatSnapshotOnlyDiff, publicationCapabilityDescription } from "../ui/sync-format.js";
 import { setSyncStatus } from "../ui/sync-status.js";
 import { safeTerminalText } from "../ui/terminal-text.js";
@@ -185,8 +186,15 @@ export async function history(
   const backend = await factory(config);
   const snapshots = (await backend.listHistory(options.signal)).slice(-20).reverse();
   throwIfAborted(options.signal);
+  const lastApplied = await readStateForConfig(config)
+    .then((state) => state.lastAppliedSnapshot)
+    .catch(() => undefined);
+  throwIfAborted(options.signal);
+  const appliedDetails = lastApplied
+    ? `Last applied snapshot ID: ${safeTerminalText(lastApplied)}\nApplication time: unavailable. Snapshot dates are creation times.`
+    : "Last applied snapshot ID: unavailable.";
   if (snapshots.length === 0) {
-    ctx.ui.notify("No remote pi-sync history found.", "info");
+    ctx.ui.notify(`No remote pi-sync history found.\n${appliedDetails}`, "info");
     return;
   }
 
@@ -197,7 +205,7 @@ export async function history(
         `${index + 1}. ${item.createdAt} · ${safeTerminalText(item.machine)} · ${item.snapshotId}${item.snapshotId === currentSnapshot ? " (current)" : ""}${item.syncSessions ? " · sessions" : ""}`,
     );
     const selected = await ctx.ui.select(
-      `History for sync setup “${safeTerminalText(config.setupName)}”\n\nChoose a snapshot to preview rollback.`,
+      `History for sync setup “${safeTerminalText(config.setupName)}”\n\n${appliedDetails}\n\nChoose a snapshot to preview rollback.`,
       [...labels, "Back"],
       { signal: options.signal },
     );
@@ -215,7 +223,10 @@ export async function history(
     return;
   }
   ctx.ui.notify(
-    snapshots.map((item) => `${item.snapshotRef} ${item.createdAt} ${safeTerminalText(item.machine)}`).join("\n"),
+    [
+      appliedDetails,
+      ...snapshots.map((item) => `${item.snapshotRef} ${item.createdAt} ${safeTerminalText(item.machine)}`),
+    ].join("\n"),
     "info",
   );
 }

package/src/ui/manager-state.ts

@@ -21,6 +21,7 @@ import {
   type SyncAttentionState,
   syncAttentionMatchesConfig,
 } from "./sync-attention.js";
+import { startupTransferSummary } from "./sync-behavior.js";
 import { countValidSyncSetups } from "./sync-setups-ui.js";
 import { safeTerminalText } from "./terminal-text.js";
 
@@ -28,6 +29,8 @@ export const MAIN_MENU_ACTIONS = [
   "Sync now",
   "Pull from remote…",
   "Push to remote…",
+  "View differences",
+  "Check remote status",
   "Settings",
   "History",
   "Diagnostics",
@@ -121,7 +124,7 @@ export async function describeManagerState(
     const lastAppliedSnapshot = changesBlocked
       ? "Unavailable while operations are locked"
       : syncState?.lastAppliedSnapshot
-        ? safeTerminalText(syncState.lastAppliedSnapshot)
+        ? `${truncateToWidth(safeTerminalText(syncState.lastAppliedSnapshot), 20, "…")} (application time unavailable; full ID in History)`
         : syncState
           ? "Never synced"
           : "Unavailable";
@@ -134,10 +137,7 @@ export async function describeManagerState(
       "",
       `Current sync setup: ${safeTerminalText(config.setupName)}`,
       `Storage: ${backendStorageDescription(config)}`,
-      `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: ${automaticSyncSummary(config.automatic)}`,
-      `Automatic transfer at startup: ${config.automaticTransfer ? "On — upload/replace/delete at idle; no reload" : "Off"}`,
-      `Last applied: ${lastAppliedSnapshot}`,
+      "CURRENT STATE",
       ...(syncState?.unresolved?.length
         ? [
             `Unresolved: ${syncState.unresolved.length} dependency groups · choose Review unresolved conflicts`,
@@ -160,11 +160,15 @@ export async function describeManagerState(
               "Check-time observation only; synchronization rechecks current content.",
             ]
           : ["Remote status: Not checked"]),
+      `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: ${automaticSyncSummary(config.automatic)}`,
+      `Startup transfer: ${startupTransferSummary(config)}`,
+      `Last applied: ${lastAppliedSnapshot}`,
       ...(noSyncedContent
         ? ["", "No included content is selected. Choose included content in Settings before syncing."]
         : []),
       "",
-      "What do you want to do?",
+      "ACTIONS · transfer, inspect, or manage",
     ];
     return {
       title: (changesBlocked ? ["Manage sync", ...operationStatusLines(operation)] : ordinaryTitle).join("\n"),

package/src/ui/manager-ui.ts

@@ -1,7 +1,8 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { type ActionMenuItem, defineMenu, runMenu } from "@narumitw/pi-tui-kit";
-import { loadConfig } from "../settings/config.js";
+import { loadConfig, syncCheckConfigFingerprint } from "../settings/config.js";
 import { operationBlocksChanges } from "../state/operation-availability.js";
+import { captureMutationOwner } from "../sync/sync-local.js";
 import { type RunRoute, runCancellableOperation } from "./cancellable-operation.js";
 import {
   attentionMainMenuItems,
@@ -11,12 +12,13 @@ import {
 } from "./manager-attention.js";
 import { recoverSyncAccess } from "./manager-recovery.js";
 import { dispatchManagerResult } from "./manager-result-dispatcher.js";
-import { describeManagerState } from "./manager-state.js";
+import { backendStorageDescription, describeManagerState } from "./manager-state.js";
 import { showSyncSettings } from "./settings-ui.js";
 import { showSyncSetupManager } from "./setup/setup-actions.js";
 import { showSetupSwitcher } from "./setup/setup-switcher.js";
 import { showStorageConnections } from "./storage-connections-ui.js";
 import { observationMatchesConfig } from "./sync-attention.js";
+import { safeTerminalText } from "./terminal-text.js";
 
 export async function showSyncManager(
   ctx: ExtensionCommandContext,
@@ -36,6 +38,8 @@ export async function showSyncManager(
     | "settings"
     | "pull"
     | "push"
+    | "diff"
+    | "status"
     | "setups"
     | "connections"
     | "history"
@@ -167,12 +171,43 @@ export async function showSyncManager(
         });
         return { kind: result.kind === "closed" ? "close" : "stay" };
       },
-      doctor: async () => {
-        const result = await runCancellableOperation(ctx, "Checking setup access…", "doctor", runRoute, {
+      diff: async () => {
+        const result = await runCancellableOperation(ctx, "Comparing local and remote…", "diff", runRoute, {
+          signal: sessionSignal,
+        });
+        return { kind: result.kind === "closed" ? "close" : "stay" };
+      },
+      status: async () => {
+        const result = await runCancellableOperation(ctx, "Checking remote status…", "status", runRoute, {
           signal: sessionSignal,
         });
         return { kind: result.kind === "closed" ? "close" : "stay" };
       },
+      doctor: async ({ signal: actionSignal }) => {
+        const signal = sessionSignal ? AbortSignal.any([sessionSignal, actionSignal]) : actionSignal;
+        const validate = captureMutationOwner(ctx, signal);
+        const config = await loadConfig();
+        validate();
+        const confirmed = await ctx.ui.confirm(
+          "Run diagnostics?",
+          `Setup: ${safeTerminalText(config.setupName)}\nStorage: ${backendStorageDescription(config)}\nS3/R2 reads the latest pointer without writing. Git reads remote snapshots and checks its cache. WebDAV probes conditional writes and cleanup, and can repair a missing history entry. Possible-secret checks still run. This is not the read-only Check remote status action.`,
+          { signal },
+        );
+        if (signal.aborted) return { kind: "close" };
+        validate();
+        if (!confirmed) return { kind: "stay" };
+        const latest = await loadConfig();
+        validate();
+        if (syncCheckConfigFingerprint(config) !== syncCheckConfigFingerprint(latest)) {
+          ctx.ui.notify("Setup changed during diagnostics review; reopen Diagnostics.", "warning");
+          return { kind: "stay" };
+        }
+        const result = await runCancellableOperation(ctx, "Checking setup access…", "doctor", runRoute, {
+          signal,
+          target: config.setupName,
+        });
+        return { kind: result.kind === "closed" ? "close" : "stay" };
+      },
       recover: async ({ state, signal: actionSignal }) => {
         const result = await recoverSyncAccess(ctx, state.manager, runRoute, sessionSignal, actionSignal);
         return { kind: result === "close" ? "close" : "stay" };
@@ -228,6 +263,8 @@ function syncMainMenuItem(
   | "sync"
   | "pull"
   | "push"
+  | "diff"
+  | "status"
   | "switch"
   | "settings"
   | "setups"
@@ -244,6 +281,8 @@ function syncMainMenuItem(
     "Sync now": "sync",
     "Pull from remote…": "pull",
     "Push to remote…": "push",
+    "View differences": "diff",
+    "Check remote status": "status",
     "Switch sync setup": "switch",
     Settings: "settings",
     History: "history",
@@ -263,8 +302,19 @@ function syncMainMenuItem(
     id: action,
     label,
     action,
-    ...(action === "doctor"
-      ? { description: "Check setup access; WebDAV also probes writes and repairs history." }
-      : {}),
+    description:
+      action === "doctor"
+        ? "Manage: review backend checks before running."
+        : action === "settings" || action === "history" || action === "switch"
+          ? "Manage"
+          : action === "sync"
+            ? "Transfer: choose a safe direction or review conflicts."
+            : action === "pull"
+              ? "Transfer: remote → local; review writes and removals."
+              : action === "push"
+                ? "Transfer: local → remote active snapshot; review publication."
+                : action === "status" || action === "diff"
+                  ? "Inspect: read current local and remote state without transferring files."
+                  : undefined,
   };
 }

package/src/ui/merge-review.ts

@@ -60,9 +60,9 @@ export async function confirmMergeReview(
           })
         : await runMenu(ctx, menu, { getState: () => undefined, signal, isCurrent, onError: () => {} });
     if (!isCurrent() || signal?.aborted) return false;
-    if (result.kind === "error") throw new Error("Merge review failed; no transfer was performed.");
+    if (result.kind === "error") throw new Error("Sync review failed; no transfer was performed.");
     if (result.kind === "unsupported")
-      throw new Error("Merge review requires observable TUI or RPC; review the plan before using --yes.");
+      throw new Error("Sync review requires observable TUI or RPC; review the plan before using --yes.");
     if (result.kind === "completed") choice.value = result.value;
     else if (result.kind !== "closed") return false;
     // Keep authorization separate from UI termination in both adapters.
@@ -79,7 +79,7 @@ export async function confirmMergeReview(
       onError: () => {},
     });
     if (!isCurrent() || signal?.aborted) return false;
-    if (detail.kind === "error") throw new Error("Merge review failed; no transfer was performed.");
+    if (detail.kind === "error") throw new Error("Sync review failed; no transfer was performed.");
     if (detail.kind !== "cancelled" || detail.reason !== "back") return false;
     // A fresh menu discards remembered selection: returning from details always selects No.
     // Unlike Pi's native Yes-first dialog, approval requires moving off the safe default.

package/src/ui/merged-sync-summary.ts

@@ -2,13 +2,8 @@ import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { PublicationCapability } from "../backends/sync-backend.js";
 import type { Snapshot } from "../snapshot/snapshot-types.js";
 import type { FileMergeDecision } from "../sync/file-merge-planner.js";
-import { fileHashMap } from "../sync/sync-state.js";
 import { safeTerminalText, snapshotPathLabel } from "./terminal-text.js";
-
-interface FileChange {
-  path: string;
-  action: "Add" | "Update" | "Delete";
-}
+import { transferChanges as changes, type TransferChange as FileChange } from "./transfer-changes.js";
 
 export interface MergedSyncSummaryInput {
   setupName: string;
@@ -78,6 +73,7 @@ export function mergedSyncSummary(input: MergedSyncSummaryInput) {
   const context = [`Setup: ${safeTerminalText(input.setupName)}`, `Remote: ${safeTerminalText(input.destination)}`];
   const safety = [
     `Remote snapshot publication: ${input.publish ? "yes" : "no"}`,
+    "Remote removals affect the active snapshot; retained history is not erased.",
     `Sessions: ${input.sessions ? "included — may contain private conversations" : "not included"}`,
     input.groups.length
       ? `Unresolved groups: ${input.groups.length} — these paths stay unchanged on each side`
@@ -114,15 +110,3 @@ export function mergedSyncSummary(input: MergedSyncSummaryInput) {
     ].join("\n"),
   };
 }
-
-function changes(before: Snapshot, after: Snapshot): FileChange[] {
-  const beforeMap = fileHashMap(before);
-  const afterMap = fileHashMap(after);
-  return [...new Set([...Object.keys(beforeMap), ...Object.keys(afterMap)])]
-    .sort()
-    .flatMap((filePath): FileChange[] => {
-      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" }] : [];
-    });
-}

package/src/ui/settings-frame.ts

@@ -0,0 +1,55 @@
+import { stripVTControlCharacters } from "node:util";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+/** Adapt only public rendering/input boundaries; Kit still owns search, saves and focus. */
+export function boundedSettingsUI(ctx: ExtensionCommandContext): ExtensionCommandContext["ui"] {
+  return {
+    ...ctx.ui,
+    custom: (factory, options) =>
+      ctx.ui.custom((tui, ...args) => {
+        // Kit pins search before the selected setting at a one-row budget. Render its
+        // smallest complete frame, then retain the active row when the real budget is smaller.
+        const terminal = new Proxy(tui.terminal, {
+          get: (target, key) => (key === "rows" ? Math.max(8, target.rows) : Reflect.get(target, key)),
+        });
+        const screenTui = new Proxy(tui, {
+          get(target, key) {
+            if (key === "terminal") return terminal;
+            const value = Reflect.get(target, key);
+            return typeof value === "function" ? value.bind(target) : value;
+          },
+        });
+        const guard = <
+          T extends {
+            render(width: number): string[];
+            handleMouse?: import("@earendil-works/pi-tui").Component["handleMouse"];
+          },
+        >(
+          component: T,
+        ): T => {
+          const render = component.render.bind(component);
+          const handleMouse = component.handleMouse?.bind(component);
+          let sourceRow = 0;
+          const compact = () => tui.terminal.rows < 8;
+          component.render = (width) => {
+            if (width <= 0) return [];
+            const lines = render(width);
+            if (!compact()) return lines;
+            const active = lines.findIndex((line) => stripVTControlCharacters(line).startsWith("→"));
+            const search = lines.findIndex((line) => stripVTControlCharacters(line).startsWith(">"));
+            sourceRow = active < 0 ? Math.max(0, search) : active;
+            return lines.slice(sourceRow, sourceRow + 1);
+          };
+          if (handleMouse)
+            component.handleMouse = (event) => {
+              if (event.width <= 0 || (compact() && event.y !== 0)) return undefined;
+              component.render(event.width);
+              return handleMouse(compact() ? { ...event, y: event.y + sourceRow } : event);
+            };
+          return component;
+        };
+        const component = factory(screenTui, ...args);
+        return component instanceof Promise ? component.then(guard) : guard(component);
+      }, options),
+  };
+}