@narumitw/pi-sync 0.57.2 → 0.57.5

package/src/sync/continuous-record.ts

@@ -3,7 +3,13 @@ import { withLock } from "../state/lock.js";
 import { withStateDirectoryAccess } from "../state/state-directory.js";
 import { ContinuousError, type ContinuousErrorKind } from "./continuous-errors.js";
 import { type ContinuousLease, continuousLeaseOwner } from "./continuous-lease.js";
-import { continuousBinding, readContinuousPrivate, writeContinuousPrivate } from "./continuous-storage.js";
+import {
+  CONTINUOUS_RECORD_MAX_BYTES,
+  continuousBinding,
+  readContinuousPrivate,
+  readContinuousPrivateDocument,
+  writeContinuousPrivate,
+} from "./continuous-storage.js";
 
 export const REQUEST_WINDOW_MS = 15 * 60_000;
 export interface ContinuousRecord {
@@ -93,10 +99,12 @@ export function validateContinuousRecord(value: unknown, binding: string): asser
   )
     throw new Error("Invalid continuous sync state; evidence retained.");
 }
+function emptyContinuousRecord(binding: string): ContinuousRecord {
+  return { version: 1, binding, pending: true, phase: "waiting", next: 0, failures: 0, calls: [], attempts: {} };
+}
 export async function readContinuousRecord(binding: string): Promise<ContinuousRecord> {
   const value = await readContinuousPrivate(`${binding}.json`);
-  if (value === undefined)
-    return { version: 1, binding, pending: true, phase: "waiting", next: 0, failures: 0, calls: [], attempts: {} };
+  if (value === undefined) return emptyContinuousRecord(binding);
   validateContinuousRecord(value, binding);
   return value;
 }
@@ -131,16 +139,20 @@ export async function reserveContinuousRequest(
   lease: ContinuousLease,
   key: string,
   clock: () => number = Date.now,
+  signal?: AbortSignal,
 ) {
+  signal?.throwIfAborted();
   if (!digest(key)) throw new Error("Invalid continuous candidate key.");
   let failure: ContinuousError | undefined;
   await updateContinuousRecord(binding, lease, (record) => {
+    signal?.throwIfAborted();
     const now = clock();
+    signal?.throwIfAborted();
     normalizeContinuousClock(record, now);
     if ((record.attempts[key] ?? 0) >= 2)
       failure = new ContinuousError(
         "model",
-        "Automatic request limit reached for this evidence. Use Sync now for an explicit retry.",
+        "Automatic request limit reached for this evidence. Change the evidence or review /sync; Sync now does not reset this limit.",
       );
     else if (record.calls.length >= 2)
       failure = new ContinuousError(
@@ -153,27 +165,97 @@ export async function reserveContinuousRequest(
       record.calls.push({ key, at: now });
     }
   });
+  // Atomic publication is not interruptible. A reservation written before cancellation stays spent.
+  signal?.throwIfAborted();
   if (failure) throw failure;
 }
 
+const recoveryActions: Record<ContinuousErrorKind, string> = {
+  transient: "Wait for the scheduled retry. Check network and service availability if failures continue.",
+  contention: "Wait for the active sync operation to finish. Do not remove a live lock.",
+  stale: "Wait for a fresh inspection after the retry delay. Local or remote evidence changed.",
+  authentication: "Repair storage or Pi model authentication, then reopen /sync. Do not share credentials.",
+  storage: "Repair private-state permissions, free space or storage access. Retain accounting and recovery evidence.",
+  unsafe:
+    "Remove secrets or repair unsupported conflicts. Changed evidence is inspected again; review /sync if needed.",
+  model:
+    "Review conflict evidence and Pi model access. Sync now reuses cached refusals; a refusal needs changed evidence or a separately confirmed retry.",
+  budget:
+    "Wait for the window allowance shown above. Waiting does not restore exhausted candidates or accounting capacity.",
+  unknown:
+    "Review /sync diagnostics and reconcile pending recovery before retrying. Do not delete private evidence or blindly republish.",
+};
+
+function serializedBytes(record: ContinuousRecord): number {
+  // Keep this aligned with writeJson's private-document encoding.
+  return Buffer.byteLength(`${JSON.stringify(record, null, "\t")}\n`);
+}
+
+/** Check space for one reservation without retaining or publishing the synthetic candidate. */
+function hasReservationCapacity(record: ContinuousRecord, now: number): boolean {
+  const existing = Object.keys(record.attempts).find((key) => record.attempts[key] === 1);
+  let key = existing ?? "0".repeat(64);
+  if (!existing) {
+    for (let index = 1; record.attempts[key] !== undefined; index++) key = index.toString(16).padStart(64, "0");
+  }
+  return (
+    serializedBytes({
+      ...record,
+      calls: [...record.calls, { key, at: now }],
+      attempts: { ...record.attempts, [key]: (record.attempts[key] ?? 0) + 1 },
+    }) <= CONTINUOUS_RECORD_MAX_BYTES
+  );
+}
+
 /** Read-only status: no directory creation, lease, mutation, request reservation or provider call. */
-export async function continuousStatusLines(config: AnySyncConfig): Promise<string[]> {
+export async function continuousStatusLines(config: AnySyncConfig, clock: () => number = Date.now): Promise<string[]> {
   if (!config.continuous) return ["Continuous sync: Off"];
   if (!config.agentMode) return ["Continuous sync: paused; enable Agent mode first"];
   try {
-    const record = await readContinuousRecord(await continuousBinding(config));
+    const binding = await continuousBinding(config);
+    const document = await readContinuousPrivateDocument(`${binding}.json`);
+    const record = document === undefined ? emptyContinuousRecord(binding) : document.value;
+    validateContinuousRecord(record, binding);
+    const bytes = serializedBytes(record);
+    // Only this detached read is normalized. A Status read never publishes clock repairs or expires durable calls.
+    const now = clock();
+    normalizeContinuousClock(record, now);
+    const spent = Object.values(record.attempts).filter((count) => count === 2).length;
+    const eligible =
+      record.calls.length < 2 ? now : Math.min(...record.calls.map((call) => call.at)) + REQUEST_WINDOW_MS;
+    const capacityRecord = { ...record, calls: [...record.calls] };
+    normalizeContinuousClock(capacityRecord, eligible);
+    const available = hasReservationCapacity(capacityRecord, eligible);
+    const owner = await continuousLeaseOwner(binding).catch(
+      () => "Local scheduler lease: private owner metadata unavailable; retain evidence and repair access",
+    );
     return [
-      `Continuous sync: ${record.phase}${record.error ? ` (${record.error})` : ""}`,
-      await continuousLeaseOwner(record.binding),
-      `Last successful background check: ${record.checked ? new Date(record.checked).toISOString() : "not yet checked"}`,
-      `Last successful background transfer: ${record.transferred ? new Date(record.transferred).toISOString() : "none"}`,
+      `Continuous sync: ${record.phase}${record.error ? ` (${record.error})` : ""}${document === undefined ? "; no accounting record yet" : ""}`,
+      owner,
+      "Scheduler owner model: unavailable; the observing session's selected model is not proof of the owner's model.",
+      `Automatic requests (rolling 15 minutes, window only): ${record.calls.length}/2 used; ${2 - record.calls.length} remaining.`,
+      `Next request eligibility: ${available ? (eligible === now ? "now (window allowance)" : `${new Date(eligible).toISOString()} (window allowance)`) : "unavailable (accounting full)"}. Candidate, capacity, ownership and safety checks still apply.`,
+      `Spent candidates: ${spent} exhausted / ${Object.keys(record.attempts).length} tracked; 2 automatic requests per candidate. Expired windows do not clear this limit.`,
+      `Accounting: ${bytes}/${CONTINUOUS_RECORD_MAX_BYTES} serialized bytes; ${Math.max(0, CONTINUOUS_RECORD_MAX_BYTES - bytes)} bytes free; ${document?.bytes ?? 0} bytes on disk${available ? "." : "; full for another reservation."}`,
+      ...(!available
+        ? [
+            "Accounting recovery: pause Continuous sync and seek reviewed recovery. Do not delete accounting, prune candidates or reset limits to regain requests.",
+          ]
+        : []),
+      `Last successful background check: ${record.checked !== undefined ? new Date(record.checked).toISOString() : "not yet checked"}`,
+      `Last successful background transfer: ${record.transferred !== undefined ? new Date(record.transferred).toISOString() : "none"}`,
       ...(record.phase === "retry" ? [`Next background attempt: ${new Date(record.next).toISOString()}`] : []),
-      ...(record.phase === "blocked"
-        ? ["Background sync needs changed evidence or repair. Review /sync, or use Sync now for an explicit retry."]
+      ...(record.error ? [`Recovery (${record.error}): ${recoveryActions[record.error]}`] : []),
+      ...(record.phase === "blocked" && !record.error
+        ? ["Review /sync diagnostics and repair changed evidence. Retain private recovery state."]
         : []),
       "Monitoring requires an eligible open Pi session. Status does not spend model requests or clear retry limits.",
     ];
   } catch {
-    return ["Continuous sync: private state unavailable; retain evidence and repair access before retrying."];
+    return [
+      "Continuous sync: private state unavailable; usage, eligibility and accounting bytes cannot be verified.",
+      `Accounting capacity: ${CONTINUOUS_RECORD_MAX_BYTES} bytes; do not treat unavailable accounting as unused allowance.`,
+      "Recovery: pause Continuous sync, retain malformed, unknown or unsafe evidence, and repair private-state access. Do not delete accounting or reset limits.",
+    ];
   }
 }

package/src/sync/continuous-storage.ts

@@ -8,6 +8,8 @@ import { writeJson } from "../state/json-file.js";
 import { stateDir } from "../state/state-directory.js";
 import { ensureStateDir } from "../state/sync-state-store.js";
 
+export const CONTINUOUS_RECORD_MAX_BYTES = 131072;
+
 export function hashContinuous(value: unknown) {
   return createHash("sha256")
     .update(JSON.stringify(value) ?? "null")
@@ -30,6 +32,12 @@ export async function checkContinuousRoot() {
     throw new Error("Unsafe continuous sync directory; evidence retained.");
 }
 export async function readContinuousPrivate(name: string): Promise<unknown> {
+  return (await readContinuousPrivateDocument(name))?.value;
+}
+/** Read-only metadata; uses the same private-file checks as runtime reads. */
+export async function readContinuousPrivateDocument(
+  name: string,
+): Promise<{ value: unknown; bytes: number } | undefined> {
   try {
     await checkContinuousRoot();
     const file = path.join(continuousRoot(), name);
@@ -38,11 +46,12 @@ export async function readContinuousPrivate(name: string): Promise<unknown> {
       !stat.isFile() ||
       stat.isSymbolicLink() ||
       stat.nlink !== 1 ||
-      stat.size > 131072 ||
+      stat.size > CONTINUOUS_RECORD_MAX_BYTES ||
       (process.platform !== "win32" && stat.mode & 0o077)
     )
       throw new Error("Unsafe continuous sync record; evidence retained.");
-    return JSON.parse(await fs.readFile(file, "utf8"));
+    const bytes = await fs.readFile(file);
+    return { value: JSON.parse(bytes.toString("utf8")), bytes: bytes.byteLength };
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
     throw error;
@@ -51,5 +60,5 @@ export async function readContinuousPrivate(name: string): Promise<unknown> {
 export async function writeContinuousPrivate(name: string, value: unknown) {
   await checkContinuousRoot();
   await readContinuousPrivate(name); // Never replace unsafe or malformed evidence.
-  await writeJson(path.join(continuousRoot(), name), value, { maxBytes: 131072 });
+  await writeJson(path.join(continuousRoot(), name), value, { maxBytes: CONTINUOUS_RECORD_MAX_BYTES });
 }

package/src/sync/continuous-sync.ts

@@ -451,7 +451,8 @@ export function createContinuousSync(loaders: SyncLoaders, clock: ContinuousCloc
             signal,
             background: {
               validate,
-              reserve: (key) => reserveContinuousRequest(binding, lease, key, () => clock.now()),
+              reserve: (key, requestSignal) =>
+                reserveContinuousRequest(binding, lease, key, () => clock.now(), requestSignal),
             },
           },
           (options) => operations.syncBoth(ctx, options),

package/src/sync/merged-sync.ts

@@ -48,6 +48,7 @@ import {
 import { type ConflictResolution, resolveReviewedGroup } from "./conflict-resolution.js";
 import { pruneCompletedConflicts } from "./conflict-retention.js";
 import { resolveContentConflicts } from "./content-conflicts.js";
+import { ContinuousError } from "./continuous-errors.js";
 import { planFileMerge } from "./file-merge-planner.js";
 import { overlayLocalFields, portableSnapshot, sameLocalFields } from "./local-fields.js";
 import { applyMergedSnapshot, preflightMergedTargets } from "./merge-apply.js";
@@ -96,8 +97,16 @@ export async function mergeSync(
       return false;
     }
   };
+  const validateRetryAuthorization = (config: AnySyncConfig) => {
+    if (
+      options.agentRetryRefusal &&
+      (!config.agentMode || options.auto || options.background || !ctx.hasUI || !["tui", "rpc"].includes(ctx.mode))
+    )
+      throw new Error("Refused-candidate retry requires foreground Agent mode in TUI or RPC.");
+  };
   const config = await loadConfig(options.setup);
   validateOwner(config);
+  validateRetryAuthorization(config);
   const configToken = syncCheckConfigFingerprint(config);
   const modelToken = JSON.stringify(ctx.model);
   const sessionRoot = config.include.includes("sessions") ? await effectiveSessionRoot(ctx) : undefined;
@@ -112,6 +121,7 @@ export async function mergeSync(
       validateOwner();
       const latest = await loadConfig(options.setup);
       validateOwner(latest);
+      validateRetryAuthorization(latest);
       if (configToken !== syncCheckConfigFingerprint(latest))
         throw new Error("Sync setup or settings changed during transfer; reopen sync.");
       if (sessionRoot !== undefined) {
@@ -130,6 +140,8 @@ export async function mergeSync(
   await validate();
   const pending = await timings.measure("transfer journal read", () => readMergeJournal(config));
   await validate();
+  if (pending && options.agentRetryRefusal)
+    throw new Error("A pending merge journal requires ordinary Sync now before retrying a refused candidate.");
   if (pending) {
     const recovered = await timings.measure("transfer journal recovery", () =>
       completeJournal(
@@ -339,7 +351,8 @@ export async function mergeSync(
         );
         await validate();
         if (plan.kind !== "planned" || (plan.conflicts.length && !config.partialSync))
-          throw new Error(
+          throw new ContinuousError(
+            "unsafe",
             "Agent mode paused: unsupported or refused conflict groups remain; no transfer was performed.",
           );
       }
@@ -456,7 +469,10 @@ export async function mergeSync(
         const beforeEvidence = await timings.measure("transfer remote head", () => backend.readHead(options.signal));
         await validate();
         if (!beforeEvidence || !backend.sameRevision(beforeEvidence.revision, head.revision))
-          throw new Error("Remote changed before baseline acceptance; retry from a fresh observation.");
+          throw new ContinuousError(
+            "stale",
+            "Remote changed before baseline acceptance; retry from a fresh observation.",
+          );
         progress = await persistProgress();
         await validate();
         const currentLocal = await timings.measure("transfer local snapshot", () =>
@@ -468,14 +484,20 @@ export async function mergeSync(
           syncStateFingerprint(await timings.measure("transfer state read", () => readStateForConfig(config))) !==
             syncStateFingerprint(state)
         )
-          throw new Error(
+          throw new ContinuousError(
+            "stale",
             "Local content or baseline changed before baseline acceptance; retry from a fresh observation.",
           );
         await validate();
         const currentHead = await timings.measure("transfer remote head", () => backend.readHead(options.signal));
         await validate();
         if (!currentHead || !backend.sameRevision(currentHead.revision, head.revision))
-          throw new Error("Remote changed before baseline acceptance; retry from a fresh observation.");
+          throw new ContinuousError(
+            "stale",
+            "Remote changed before baseline acceptance; retry from a fresh observation.",
+          );
+        await options.agentAcceptance?.commitCandidate?.();
+        await validate();
         await timings.measure("transfer baseline write", () =>
           writeAcceptedState(config, head, accepted, validate, progress),
         );
@@ -512,7 +534,10 @@ export async function mergeSync(
       );
       await validate();
       if (!config.skipSecretScan && scanSnapshot(upload).length)
-        throw new Error("Refusing to merge possible secrets. Review managed content before syncing.");
+        throw new ContinuousError(
+          "unsafe",
+          "Refusing to merge possible secrets. Review managed content before syncing.",
+        );
       if (!options.yes && !config.agentMode) {
         const summary = mergedSyncSummary({
           setupName: config.setupName,
@@ -545,17 +570,19 @@ export async function mergeSync(
         createSnapshot(config.snapshotIdentity, snapshotOptions),
       );
       if (!sameHashes(fileHashMap(refreshed), fileHashMap(localRaw)))
-        throw new Error("Local content changed during review; no merged transfer was performed.");
+        throw new ContinuousError("stale", "Local content changed during review; no merged transfer was performed.");
       if (
         syncStateFingerprint(await timings.measure("transfer state read", () => readStateForConfig(config))) !==
         syncStateFingerprint(state)
       )
-        throw new Error("Sync baseline changed during review; retry from a fresh observation.");
+        throw new ContinuousError("stale", "Sync baseline changed during review; retry from a fresh observation.");
       await validate();
       const refreshedHead = await timings.measure("transfer remote head", () => backend.readHead(options.signal));
       await validate();
       if (!refreshedHead || !backend.sameRevision(refreshedHead.revision, head.revision))
-        throw new Error("Remote changed during review; no merged transfer was performed.");
+        throw new ContinuousError("stale", "Remote changed during review; no merged transfer was performed.");
+      await options.agentAcceptance?.commitCandidate?.();
+      await validate();
       progress = await persistProgress();
       await validate();
       const backup = await timings.measure("transfer backup", () =>
@@ -589,7 +616,8 @@ export async function mergeSync(
       if (!sameHashes(fileHashMap(atCommit), fileHashMap(localRaw)) || atCommitState !== journal.stateIdentity) {
         await validate();
         await clearMergeJournal(config);
-        throw new Error(
+        throw new ContinuousError(
+          "stale",
           "Local content or baseline changed before publication; candidate retired without transfer. Review a fresh sync.",
         );
       }

package/src/sync/sync-mutations.ts

@@ -431,6 +431,17 @@ export async function syncBoth(
   const config = await loadConfig(options.setup);
   throwIfAborted(options.signal);
   options.background?.validate(config);
+  if (options.agentRetryRefusal) {
+    if (!config.agentMode || options.auto || options.background || !ctx.hasUI)
+      throw new Error("Enable Agent mode and use the foreground manager to retry a cached refusal.");
+    const state = await readStateForConfig(config);
+    validateMutation();
+    const pending = await readMergeJournal(config);
+    validateMutation();
+    if (!config.include.length || !state.lastAppliedSnapshot || pending)
+      throw new Error("Retry requires an accepted baseline and no pending journal. Use Sync now or reviewed recovery.");
+    return mergeSync(ctx, options, factory);
+  }
   if (config.include.length > 0 && options.auto && startupTransferEnabled(config))
     return mergeSync(ctx, options, factory);
   if (!options.auto && config.include.length > 0 && (await readMergeJournal(config)))

package/src/ui/cancellable-operation.ts

@@ -17,6 +17,7 @@ export type RunRoute = (
   onCommit?: () => void,
   target?: string,
   onDialog?: (active: boolean) => void,
+  retryRefusal?: boolean,
 ) => Promise<RunRouteResult | undefined>;
 
 export type CancellableOperationResult = RunRouteResult | { kind: "closed" } | { kind: "cancelled" };
@@ -106,6 +107,7 @@ export async function runCancellableOperation(
       );
       return {
         render(width: number) {
+          if (width <= 0) return [];
           const safeWidth = Math.max(1, width);
           const lines = loader.render(safeWidth);
           const bottomBorder = lines.at(-1);

package/src/ui/manager-state.ts

@@ -130,6 +130,7 @@ export async function describeManagerState(
           : "Unavailable";
     const canSwitch = (await countValidSyncSetups(configuredTargets, signal)) > 1;
     const mainActions: string[] = [...MAIN_MENU_ACTIONS];
+    if (config.agentMode && !noSyncedContent) mainActions.splice(1, 0, "Retry refused model result…");
     if (canSwitch) mainActions.push("Switch sync setup");
     if (syncState?.unresolved?.length) mainActions.unshift("Review unresolved conflicts");
     const ordinaryTitle = [

package/src/ui/manager-ui.ts

@@ -1,4 +1,5 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
 import { type ActionMenuItem, defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 import { loadConfig, syncCheckConfigFingerprint } from "../settings/config.js";
 import { operationBlocksChanges } from "../state/operation-availability.js";
@@ -33,6 +34,7 @@ export async function showSyncManager(
   type Screen = "main";
   type Action =
     | "review-attention"
+    | "retry-refusal"
     | "sync"
     | "switch"
     | "settings"
@@ -128,6 +130,27 @@ export async function showSyncManager(
         const disposition = await dispatchManagerResult(ctx, result, "sync", runRoute, sessionSignal);
         return disposition.kind === "close" ? { kind: "close" } : { kind: "stay" };
       },
+      "retry-refusal": async ({ signal: actionSignal }) => {
+        const signal = sessionSignal ? AbortSignal.any([sessionSignal, actionSignal]) : actionSignal;
+        const validate = captureMutationOwner(ctx, signal);
+        validate();
+        const retryRoute: RunRoute = (route, operationSignal, onCommit, target, onDialog) =>
+          runRoute(route, operationSignal, onCommit, target, onDialog, true);
+        const result = await runCancellableOperation(ctx, "Checking cached refusal…", "sync", retryRoute, {
+          commitAware: true,
+          cancelAcrossDialogs: true,
+          signal,
+          cancelledMessage: "Model retry cancelled. Submitted requests and committed writes cannot be undone.",
+        });
+        if (signal.aborted) return { kind: "close" };
+        validate();
+        if (result.kind === "decision-required" || result.kind === "remote-selection-required")
+          ctx.ui.notify(
+            "Model retry needs an established source and matching synced content. Use Sync now to review changed selection or recovery before retrying.",
+            "warning",
+          );
+        return { kind: result.kind === "closed" ? "close" : "stay" };
+      },
       switch: async () => {
         const result = await showSetupSwitcher(ctx, runRoute, undefined, sessionSignal);
         return result === "pull-attempted" || result === "closed" ? { kind: "close" } : { kind: "stay" };
@@ -231,7 +254,25 @@ export async function showSyncManager(
       },
     },
   });
-  await runMenu(ctx, menu, {
+  const menuContext: ExtensionCommandContext = {
+    ...ctx,
+    ui: {
+      ...ctx.ui,
+      custom: (factory, customOptions) =>
+        ctx.ui.custom((...args) => {
+          const bound = (component: Component & { dispose?(): void }) => {
+            const render = component.render.bind(component);
+            // Kit menus use a one-cell layout floor; suppress it at a zero-column display boundary.
+            component.render = (width) => (width <= 0 ? [] : render(width));
+            return component;
+          };
+          const component = factory(...args);
+          // Keep synchronous factories synchronous, including adapters that inspect their returned component.
+          return component instanceof Promise ? component.then(bound) : bound(component);
+        }, customOptions),
+    },
+  };
+  await runMenu(menuContext, menu, {
     getState: async () => {
       const pendingAttention = options.getAttention?.();
       const observation = options.getObservation?.();
@@ -261,6 +302,7 @@ function syncMainMenuItem(
 ): ActionMenuItem<
   "main",
   | "sync"
+  | "retry-refusal"
   | "pull"
   | "push"
   | "diff"
@@ -279,6 +321,7 @@ function syncMainMenuItem(
 > {
   const actions = {
     "Sync now": "sync",
+    "Retry refused model result…": "retry-refusal",
     "Pull from remote…": "pull",
     "Push to remote…": "push",
     "View differences": "diff",
@@ -303,18 +346,20 @@ function syncMainMenuItem(
     label,
     action,
     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,
+      action === "retry-refusal"
+        ? "Transfer: confirm one fresh model request for a current cached refusal; may incur costs."
+        : 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,
   };
 }