From 417ddc01aeecd1bf5c720b7b60ed356c380dc74d Mon Sep 17 00:00:00 2001
From: cyue <cyue@local>
Date: Tue, 11 Aug 2026 18:01:25 +0800
Subject: [PATCH] feat(desktop): over-threshold resume guard and
 compaction_done live refresh

Keeps the review-endorsed parts of the original four-threshold PR #8256,
rescaled to the single compact_ratio architecture of #8244:
- over-threshold resume guard, asked BEFORE the mutating
  ResumeSessionPageForTab / OpenChannelSessionPageForTab calls via a
  read-only PreviewSession estimate, so cancelling leaves the session
  untouched
- immediate context + balance refresh on compaction_done (the coalesced
  BalanceForTab query is invalidated first so the refresh reads fresh data)

Drops everything tied to the multi-threshold model removed by #8244
(soft/snip/force ratios, the four-thumb slider, thresholdLayout,
SetCompactionThresholds, CLI snip-ratio, the widened compact-ratio range)
and does not reintroduce the ContextPanel maintenance block removed by
#8265. The live capacity visualization already aligns with the single
Compact threshold on current main-v2 (#8329/#8307), so the gauge is
unchanged.
---
 desktop/frontend/src/App.tsx                  |   2 +
 .../__tests__/new-session-load-race.test.tsx  |   1 +
 .../src/__tests__/resume-guard.test.tsx       | 312 ++++++++++++++++++
 .../use-controller-live-context.test.tsx      |  33 ++
 desktop/frontend/src/lib/useController.ts     |  41 ++-
 desktop/frontend/src/lib/useResumeGuard.ts    |  49 +++
 desktop/frontend/src/locales/en.ts            |   4 +
 desktop/frontend/src/locales/zh-TW.ts         |   4 +
 desktop/frontend/src/locales/zh.ts            |   4 +
 docs/SPEC.md                                  |   5 +
 docs/SPEC.zh-CN.md                            |   3 +
 tools/repolint/baseline.json                  |   6 +-
 12 files changed, 459 insertions(+), 5 deletions(-)
 create mode 100644 desktop/frontend/src/__tests__/resume-guard.test.tsx
 create mode 100644 desktop/frontend/src/lib/useResumeGuard.ts

diff --git a/desktop/frontend/src/App.tsx b/desktop/frontend/src/App.tsx
index a4edf9f482..a50f9c9c88 100644
--- a/desktop/frontend/src/App.tsx
+++ b/desktop/frontend/src/App.tsx
@@ -1135,6 +1135,7 @@ export default function App() {
     syncActiveTab,
     ensureBlankTab,
     ensureBlankSurface,
+    resumeGuardDialog,
   } = useController();
   const { locale, setPref: setLocalePref } = useI18n();
   const t = useT();
@@ -4906,6 +4907,7 @@ export default function App() {
             )}
           </main>
 
+          {resumeGuardDialog}
           {!sidebarImDetailConnection && (
           <footer className={["footer", terminalPanelOpen && !sidebarCreation ? "footer--compact" : "", decisionSurface ? "footer--decision" : ""].filter(Boolean).join(" ")} ref={footerRef}>
             {showTodos && (
diff --git a/desktop/frontend/src/__tests__/new-session-load-race.test.tsx b/desktop/frontend/src/__tests__/new-session-load-race.test.tsx
index 0fbaf2bba1..bba3239109 100644
--- a/desktop/frontend/src/__tests__/new-session-load-race.test.tsx
+++ b/desktop/frontend/src/__tests__/new-session-load-race.test.tsx
@@ -194,6 +194,7 @@ window.go = {
         newSessionCalls += 1;
         backendCanonicalTodos = [];
       },
+      PreviewSession: async () => [],
       ResumeSessionPageForTab: async () => {
         backendCanonicalTodos = [{ content: "Restored task", status: "completed" }];
         return {
diff --git a/desktop/frontend/src/__tests__/resume-guard.test.tsx b/desktop/frontend/src/__tests__/resume-guard.test.tsx
new file mode 100644
index 0000000000..b254dcd1de
--- /dev/null
+++ b/desktop/frontend/src/__tests__/resume-guard.test.tsx
@@ -0,0 +1,312 @@
+// Run: tsx src/__tests__/resume-guard.test.tsx
+// The resume guard estimates a session from the read-only PreviewSession and
+// asks before the mutating ResumeSessionPageForTab call: confirming continues
+// the hydrate, cancelling leaves the tab untouched (the resume call never
+// happens) and surfaces a cancelled hydrate error.
+
+import { JSDOM } from "jsdom";
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { useController } from "../lib/useController";
+import type { AppBindings } from "../lib/bridge";
+import type { BalanceInfo, CheckpointMeta, ContextInfo, EffortInfo, HistoryMessage, JobView, Meta, TabMeta } from "../lib/types";
+
+let passed = 0;
+let failed = 0;
+
+function ok(value: boolean, label: string) {
+  if (value) {
+    process.stdout.write(`  PASS  ${label}\n`);
+    passed += 1;
+  } else {
+    process.stdout.write(`  FAIL  ${label}\n`);
+    failed += 1;
+  }
+}
+
+function flushPromises(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+async function waitFor(label: string, predicate: () => boolean) {
+  for (let attempt = 0; attempt < 40; attempt += 1) {
+    await act(async () => {
+      await flushPromises();
+    });
+    if (predicate()) return;
+  }
+  throw new Error(`timed out waiting for ${label}`);
+}
+
+function tabMeta(): TabMeta {
+  return {
+    id: "tab-a",
+    scope: "project",
+    workspaceRoot: "/repo",
+    workspaceName: "repo",
+    workspacePath: "/repo",
+    gitBranch: "main",
+    topicId: "topic-a",
+    topicTitle: "General",
+    label: "model",
+    ready: true,
+    running: false,
+    mode: "normal",
+    toolApprovalMode: "ask",
+    tokenMode: "full",
+    active: true,
+    cwd: "/repo",
+  };
+}
+
+function meta(): Meta {
+  return { label: "model", ready: true, cwd: "/repo", workspaceRoot: "/repo", topicId: "topic-a" };
+}
+
+const context: ContextInfo = { used: 10, window: 1_000_000, sessionTokens: 0, compactRatio: 0.2 };
+const balance: BalanceInfo = { available: false, display: "" };
+const jobs: JobView[] = [];
+const checkpoints: CheckpointMeta[] = [];
+const effort: EffortInfo = { supported: true, current: "auto", default: "auto", levels: ["auto"] };
+
+class TestResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function installDom() {
+  const dom = new JSDOM("<!doctype html><html><body><div id='root'></div></body></html>", {
+    pretendToBeVisual: true,
+    url: "http://localhost/",
+  });
+  (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+  globalThis.window = dom.window as unknown as Window & typeof globalThis;
+  globalThis.document = dom.window.document;
+  globalThis.Node = dom.window.Node;
+  globalThis.HTMLElement = dom.window.HTMLElement;
+  globalThis.Event = dom.window.Event;
+  globalThis.KeyboardEvent = dom.window.KeyboardEvent;
+  globalThis.MouseEvent = dom.window.MouseEvent;
+  globalThis.requestAnimationFrame = dom.window.requestAnimationFrame.bind(dom.window);
+  globalThis.cancelAnimationFrame = dom.window.cancelAnimationFrame.bind(dom.window);
+  globalThis.ResizeObserver = TestResizeObserver;
+  Object.defineProperty(window, "matchMedia", {
+    configurable: true,
+    value: () => ({
+      matches: true,
+      media: "(prefers-reduced-motion: reduce)",
+      onchange: null,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      addListener: () => {},
+      removeListener: () => {},
+      dispatchEvent: () => false,
+    }),
+  });
+  return dom;
+}
+
+type Controller = ReturnType<typeof useController>;
+let controller: Controller | undefined;
+let resumeCalls = 0;
+let channelCalls = 0;
+
+// estimatedTokens ≈ content length × 0.25; 820_000 chars → ~205_000, above
+// the 200_000 threshold (window 1_000_000 × compactRatio 0.2).
+const bigPreview: HistoryMessage[] = [{ role: "user", content: "x".repeat(820_000), level: "user" }];
+const smallPreview: HistoryMessage[] = [{ role: "user", content: "small", level: "user" }];
+
+async function setup(preview: HistoryMessage[]) {
+  resumeCalls = 0;
+  channelCalls = 0;
+  const dom = installDom();
+  window.runtime = {
+    EventsOn: () => () => {},
+    BrowserOpenURL: () => {},
+  };
+  window.go = {
+    main: {
+      App: {
+        ListTabs: async () => [tabMeta()],
+        MetaForTab: async () => meta(),
+        ContextUsageForTab: async () => context,
+        EffortForTab: async () => effort,
+        BalanceForTab: async () => balance,
+        JobsForTab: async () => jobs,
+        CheckpointsForTab: async () => checkpoints,
+        HistoryForTab: async () => [],
+        HistoryPageForTab: async () => ({ messages: [], startTurn: 0, endTurn: 0, totalTurns: 0, hasOlder: false }),
+        HistoryCheckpointTurnsForTab: async () => [],
+        ReplayPendingPrompts: async () => {},
+        PreviewSession: async () => preview,
+        ResumeSessionPageForTab: async () => {
+          resumeCalls += 1;
+          return {
+            messages: [
+              { role: "user", content: "restore", level: "user" } as HistoryMessage,
+              { role: "assistant", content: "done", level: "assistant" } as HistoryMessage,
+            ],
+            startTurn: 0,
+            endTurn: 1,
+            totalTurns: 1,
+            hasOlder: false,
+          };
+        },
+        ResumeSessionForTab: async () => [],
+        OpenChannelSessionPageForTab: async () => {
+          channelCalls += 1;
+          return { messages: [], startTurn: 0, endTurn: 0, totalTurns: 0, hasOlder: false };
+        },
+      } as Partial<AppBindings> as AppBindings,
+    },
+  };
+
+  function Probe() {
+    controller = useController();
+    return <>{controller?.resumeGuardDialog}</>;
+  }
+
+  const rootEl = document.getElementById("root");
+  if (!rootEl) throw new Error("missing root");
+  const root = createRoot(rootEl);
+  await act(async () => {
+    root.render(<Probe />);
+    await flushPromises();
+  });
+  await waitFor("active tab", () => controller?.activeTabId === "tab-a");
+  return { dom, root };
+}
+
+console.log("\nresume guard");
+
+{
+  // Over-threshold resume asks first; confirming continues the hydrate.
+  const { dom, root } = await setup(bigPreview);
+
+  let resume: Promise<void>;
+  await act(async () => {
+    resume = controller?.resumeSession("/repo/session.jsonl", "tab-a") ?? Promise.resolve();
+    await flushPromises();
+  });
+  void resume;
+
+  const dialog = document.querySelector(".reasonix-confirm-dialog");
+  ok(dialog !== null, "over-threshold resume opens the confirm dialog");
+  const message = document.querySelector(".reasonix-confirm-dialog__message")?.textContent ?? "";
+  ok(
+    message.includes("205,000") && message.includes("200,000"),
+    `dialog names the estimated size and threshold, got ${message}`,
+  );
+  ok(resumeCalls === 0, "the mutating resume call has not happened while the dialog is open");
+
+  const confirmButton = [...document.querySelectorAll(".reasonix-confirm-dialog button")]
+    .find((b) => b.textContent?.includes("Resume"));
+  ok(confirmButton !== undefined, "confirm button labelled for resuming");
+  await act(async () => {
+    (confirmButton as HTMLButtonElement).click();
+    await flushPromises();
+  });
+
+  await waitFor("hydrate completes after confirm", () => document.querySelector(".reasonix-confirm-dialog") === null);
+  await waitFor("hydrate history loaded", () => (controller?.state.items?.length ?? 0) > 0);
+  ok(
+    !controller?.state.hydrateError && (controller?.state.items?.length ?? 0) > 0,
+    "confirmed resume hydrates the restored conversation",
+  );
+  ok(resumeCalls === 1, "confirmed resume performs exactly one mutating call");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
+{
+  // Cancelling never performs the mutating resume call and surfaces a notice.
+  const { dom, root } = await setup(bigPreview);
+
+  let resume: Promise<void>;
+  await act(async () => {
+    resume = controller?.resumeSession("/repo/session.jsonl", "tab-a") ?? Promise.resolve();
+    await flushPromises();
+  });
+  void resume;
+  const dialog = document.querySelector(".reasonix-confirm-dialog");
+  ok(dialog !== null, "over-threshold resume re-opens the confirm dialog");
+
+  const cancelButton = [...document.querySelectorAll(".reasonix-confirm-dialog button")]
+    .find((b) => b.textContent === "Cancel");
+  await act(async () => {
+    (cancelButton as HTMLButtonElement).click();
+    await flushPromises();
+  });
+  await waitFor("dialog closes on cancel", () => document.querySelector(".reasonix-confirm-dialog") === null);
+  ok(
+    controller?.state.hydrateError != null && controller?.state.hydrateError.includes("unchanged"),
+    `cancelled resume surfaces a hydrate error, got ${controller?.state.hydrateError}`,
+  );
+  ok(resumeCalls === 0, "cancelled resume never performs the mutating call");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
+{
+  // A session below the threshold resumes without any confirmation.
+  const { dom, root } = await setup(smallPreview);
+
+  let resume: Promise<void>;
+  await act(async () => {
+    resume = controller?.resumeSession("/repo/session.jsonl", "tab-a") ?? Promise.resolve();
+    await flushPromises();
+  });
+  void resume;
+  await waitFor("below-threshold hydrate completes", () => (controller?.state.items?.length ?? 0) > 0);
+  ok(
+    document.querySelector(".reasonix-confirm-dialog") === null,
+    "below-threshold resume skips the confirm dialog",
+  );
+  ok(resumeCalls === 1, "below-threshold resume performs the mutating call once");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
+{
+  // The channel-open path gets the same guard: cancelling never performs the
+  // mutating OpenChannelSessionPageForTab call.
+  const { dom, root } = await setup(bigPreview);
+
+  let channel: Promise<void>;
+  await act(async () => {
+    channel = controller?.openChannelSession("/repo/session.jsonl", "tab-a") ?? Promise.resolve();
+    await flushPromises();
+  });
+  void channel;
+  ok(
+    document.querySelector(".reasonix-confirm-dialog") !== null,
+    "over-threshold channel open asks for confirmation",
+  );
+  ok(channelCalls === 0, "the mutating channel call has not happened while the dialog is open");
+  const cancelButton = [...document.querySelectorAll(".reasonix-confirm-dialog button")]
+    .find((b) => b.textContent === "Cancel");
+  await act(async () => {
+    (cancelButton as HTMLButtonElement).click();
+    await flushPromises();
+  });
+  await waitFor("dialog closes on cancel", () => document.querySelector(".reasonix-confirm-dialog") === null);
+  ok(channelCalls === 0, "cancelled channel open never performs the mutating call");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);
diff --git a/desktop/frontend/src/__tests__/use-controller-live-context.test.tsx b/desktop/frontend/src/__tests__/use-controller-live-context.test.tsx
index 89928726f5..96689d1b07 100644
--- a/desktop/frontend/src/__tests__/use-controller-live-context.test.tsx
+++ b/desktop/frontend/src/__tests__/use-controller-live-context.test.tsx
@@ -624,6 +624,39 @@ ok(
   "failed close preserves model balance reconciliation",
 );
 
+{
+  // Compaction rewrites the session: the gauge must follow the collapsed
+  // usage immediately, even when no turn_done snapshot follows. The refresh
+  // itself invalidates the coalesced balance query, so no manual share drop
+  // is needed here.
+  const beforeCalls = contextCalls;
+  const beforeBalanceCalls = balanceCalls;
+  backendContext = {
+    used: 120,
+    window: 1_000,
+    sessionTokens: 130,
+    cacheHitTokens: 0,
+    cacheMissTokens: 120,
+  };
+  backendBalance = { available: true, display: "¥80.00" };
+  await act(async () => {
+    for (const handler of eventHandlers) {
+      handler({
+        kind: "compaction_done",
+        tabId: "tab-live-context",
+        compaction: { trigger: "auto", messages: 5, summary: "collapsed" },
+      });
+    }
+    await flushPromises();
+  });
+  ok(
+    await settleUntil(() => controller?.state.context.used === 120),
+    "compaction_done refreshes context usage immediately",
+  );
+  ok(contextCalls > beforeCalls, "compaction_done triggers a new ContextUsageForTab snapshot");
+  ok(balanceCalls > beforeBalanceCalls, "compaction_done also refreshes balance");
+}
+
 await act(async () => {
   root.unmount();
 });
diff --git a/desktop/frontend/src/lib/useController.ts b/desktop/frontend/src/lib/useController.ts
index 05cb6a8570..064b4a551c 100644
--- a/desktop/frontend/src/lib/useController.ts
+++ b/desktop/frontend/src/lib/useController.ts
@@ -17,6 +17,7 @@ import { applyLiveSegments, coalesceStreamDeltas, completeLiveReasoning, type St
 import { getTranscriptStore } from "./transcriptStore";
 import { uiPerfTracker } from "./uiPerf";
 import { getLocale, t, type DictKey } from "./i18n";
+import { estimateHistoryTokens, useResumeGuard } from "./useResumeGuard";
 import { sameTodoList } from "./todoVisibility";
 import { fileDiffFromWire, summarize, summarizeFileDiff, type ToolFileDiff } from "./tools";
 import { modeHasAutoApproveTools, normalizeMode, normalizeToolApprovalMode } from "./types";
@@ -2564,6 +2565,7 @@ export function replayPendingPromptsForActiveTab(activeTabId: string | undefined
 }
 
 export function useController() {
+  const { confirmOverThresholdResume, resumeGuardDialog } = useResumeGuard();
   const statesRef = useRef<TabStates>(new Map());
   const liveListenersByTabRef = useRef(new Map<string, Set<() => void>>());
   const balanceRefreshSeqByTab = useRef(new Map<string, number>());
@@ -3385,6 +3387,19 @@ export function useController() {
       if (e.kind === "turn_done" || e.kind === "context_maintenance") {
         void app.ContextUsageForTab(targetTabId).then((context) => dispatchTo(targetTabId, { type: "context", context })).catch(() => {});
       }
+      if (e.kind === "compaction_done") {
+        // Compaction rewrites the session behind the scenes (turn-end or
+        // resume-time); the gauge must follow the collapsed usage immediately
+        // instead of waiting for the next turn_done snapshot.
+        app
+          .ContextUsageForTab(targetTabId)
+          .then((context) => dispatchTo(targetTabId, { type: "context", context }))
+          .catch(() => {});
+        // BalanceForTab is coalesced for 200 ms; drop the shared burst answer
+        // so the refresh reads the post-compaction balance, not a stale one.
+        invalidateSharedQuery("BalanceForTab", [targetTabId]);
+        void refreshBalanceForTab(targetTabId);
+      }
       if (e.kind === "turn_done") {
         invalidateSharedQuery("BalanceForTab", [targetTabId]);
         void refreshBalanceForTab(targetTabId);
@@ -4053,6 +4068,17 @@ export function useController() {
     if (!navigationCompletionCurrent(navigationSeq, "session.resume", targetTabId)) return;
     const seq = bumpSessionLoadSeq(targetTabId);
     dispatchTo(targetTabId, { type: "hydrate_start", reason: "resume-session" });
+    // Preview is read-only, so the guard can ask before the mutating
+    // ResumeSessionPageForTab call rebinds the tab; cancelling leaves the
+    // session untouched.
+    const estimatedTokens = estimateHistoryTokens(asArray<HistoryMessage>(await app.PreviewSession(path).catch(() => [])));
+    if (!(await confirmOverThresholdResume(estimatedTokens, targetTabId))) {
+      if (isNavigationIntentCurrent(navigationSeq) && sessionLoadCurrent(targetTabId, seq)) {
+        dispatchTo(targetTabId, { type: "hydrate_error", reason: "resume-session", error: t("history.overThresholdResumeCancelled") });
+      }
+      return;
+    }
+    if (!navigationCompletionCurrent(navigationSeq, "session.resume", targetTabId) || !sessionLoadCurrent(targetTabId, seq)) return;
     let page: HistoryPage;
     try {
       page = tabId
@@ -4073,7 +4099,7 @@ export function useController() {
     if (!isNavigationIntentCurrent(navigationSeq) || !sessionLoadCurrent(targetTabId, seq)) return;
     app.ContextUsageForTab(targetTabId).then((context) => dispatchTo(targetTabId, { type: "context", context })).catch(() => {});
     void refreshCheckpoints(targetTabId);
-  }, [activeTabId, beginActiveNavigation, bumpSessionLoadSeq, dispatchTo, isNavigationIntentCurrent, navigationCompletionCurrent, refreshCheckpoints, refreshMetaOnlyForTab, sessionLoadCurrent, waitForBackendActiveTab, waitForTabReady]);
+  }, [activeTabId, beginActiveNavigation, bumpSessionLoadSeq, confirmOverThresholdResume, dispatchTo, isNavigationIntentCurrent, navigationCompletionCurrent, refreshCheckpoints, refreshMetaOnlyForTab, sessionLoadCurrent, waitForBackendActiveTab, waitForTabReady]);
 
   const openChannelSession = useCallback(async (path: string, tabId: string, navigationIntentSeq?: number) => {
     if (!tabId) return;
@@ -4082,6 +4108,16 @@ export function useController() {
     if (!navigationCompletionCurrent(navigationSeq, "session.channel", tabId)) return;
     const seq = bumpSessionLoadSeq(tabId);
     dispatchTo(tabId, { type: "hydrate_start", reason: "resume-session" });
+    // Same read-only preview guard as resumeSession: ask before the mutating
+    // OpenChannelSessionPageForTab call switches the tab's session binding.
+    const estimatedTokens = estimateHistoryTokens(asArray<HistoryMessage>(await app.PreviewSession(path).catch(() => [])));
+    if (!(await confirmOverThresholdResume(estimatedTokens, tabId))) {
+      if (isNavigationIntentCurrent(navigationSeq) && sessionLoadCurrent(tabId, seq)) {
+        dispatchTo(tabId, { type: "hydrate_error", reason: "resume-session", error: t("history.overThresholdResumeCancelled") });
+      }
+      return;
+    }
+    if (!navigationCompletionCurrent(navigationSeq, "session.channel", tabId) || !sessionLoadCurrent(tabId, seq)) return;
     let page: HistoryPage;
     try {
       page = await app.OpenChannelSessionPageForTab(tabId, path, HISTORY_PAGE_TURNS);
@@ -4100,7 +4136,7 @@ export function useController() {
     if (!isNavigationIntentCurrent(navigationSeq) || !sessionLoadCurrent(tabId, seq)) return;
     app.ContextUsageForTab(tabId).then((context) => dispatchTo(tabId, { type: "context", context })).catch(() => {});
     void refreshCheckpoints(tabId);
-  }, [beginActiveNavigation, bumpSessionLoadSeq, dispatchTo, isNavigationIntentCurrent, navigationCompletionCurrent, refreshCheckpoints, refreshMetaOnlyForTab, sessionLoadCurrent, waitForTabReady]);
+  }, [beginActiveNavigation, bumpSessionLoadSeq, confirmOverThresholdResume, dispatchTo, isNavigationIntentCurrent, navigationCompletionCurrent, refreshCheckpoints, refreshMetaOnlyForTab, sessionLoadCurrent, waitForTabReady]);
 
   const previewSession = useCallback(async (path: string): Promise<HistoryMessage[]> => asArray<HistoryMessage>(await app.PreviewSession(path).catch(() => [])), []);
   const deleteSession = useCallback((path: string) => app.DeleteSession(path).finally(() => invalidateCache()), []);
@@ -4718,6 +4754,7 @@ export function useController() {
     dismissExtensionForm, drainExtensionNotifications,
     setCollaborationMode, setCollaborationModeForTab, setToolApprovalMode, setToolApprovalModeForTab, setComposerProfileForTab, setGoal, setGoalForTab, clearGoal, clearGoalForTab, resumeGoal, resumeGoalForTab, pauseGoal, pauseGoalForTab,
     newSession, clearSession, listSessions, listTrashedSessions, resumeSession, openChannelSession, previewSession, deleteSession, restoreSession, purgeTrashedSession, renameSession,
+    resumeGuardDialog,
     loadOlderHistory,
     requestHistoryFullContent,
     refreshMeta, pickWorkspace, switchWorkspace, compact, rewind, rewindForTab, rewindForTabDetailed, undoRewindForTab, setModel, setEffort, setTokenMode, cancelJob,
diff --git a/desktop/frontend/src/lib/useResumeGuard.ts b/desktop/frontend/src/lib/useResumeGuard.ts
new file mode 100644
index 0000000000..dc845e7020
--- /dev/null
+++ b/desktop/frontend/src/lib/useResumeGuard.ts
@@ -0,0 +1,49 @@
+import { useCallback } from "react";
+import { useConfirmDialog } from "../components/ConfirmDialog";
+import { app } from "./bridge";
+import { t } from "./i18n";
+import type { HistoryMessage } from "./types";
+
+// estimateHistoryTokens approximates prompt tokens for a display-message list
+// (chars × 0.25, matching the agent's fallback calibration). It is not a
+// provider usage figure; the resume guard only uses it to decide whether a
+// restore needs confirmation.
+export function estimateHistoryTokens(messages: readonly HistoryMessage[]): number {
+  let chars = 0;
+  for (const m of messages) {
+    chars += m.content.length + (m.detail?.length ?? 0) + (m.reasoning?.length ?? 0) + (m.summary?.length ?? 0);
+    for (const tc of m.toolCalls ?? []) {
+      chars += tc.name.length + tc.arguments.length;
+    }
+  }
+  return Math.round(chars * 0.25);
+}
+
+// useResumeGuard backs the resume-flow confirmation: restoring a session whose
+// estimated prompt size already exceeds the compact threshold would trigger an
+// immediate cleanup pass, so ask first. The caller estimates from the read-only
+// preview and must invoke this before the mutating resume call, so cancelling
+// leaves the session untouched.
+export function useResumeGuard() {
+  const { confirm: confirmDialog, dialog: resumeGuardDialog } = useConfirmDialog();
+  const confirmOverThresholdResume = useCallback(async (estimatedTokens: number, tabId: string): Promise<boolean> => {
+    if (!estimatedTokens || estimatedTokens <= 0) return true;
+    const context = await app.ContextUsageForTab(tabId).catch(() => undefined);
+    const compactRatio = context?.compactRatio ?? 0;
+    const compactTokens = context && context.window > 0 && compactRatio > 0
+      ? Math.round(context.window * compactRatio)
+      : 0;
+    if (compactTokens <= 0 || estimatedTokens < compactTokens) return true;
+    return confirmDialog({
+      title: t("history.overThresholdResumeTitle"),
+      message: t("history.overThresholdResumeMessage", {
+        used: estimatedTokens.toLocaleString(),
+        threshold: compactTokens.toLocaleString(),
+      }),
+      confirmLabel: t("history.overThresholdResumeConfirm"),
+      cancelLabel: t("common.cancel"),
+      tone: "danger",
+    });
+  }, [confirmDialog]);
+  return { confirmOverThresholdResume, resumeGuardDialog };
+}
diff --git a/desktop/frontend/src/locales/en.ts b/desktop/frontend/src/locales/en.ts
index 1b7d03f980..d7d38a966e 100644
--- a/desktop/frontend/src/locales/en.ts
+++ b/desktop/frontend/src/locales/en.ts
@@ -1229,6 +1229,10 @@ export const en = {
   "history.channel": "Channel",
   "history.channelReadOnly": "Read-only channel",
   "history.failedOpenProject": "Cannot open session, \"{name}\" does not exist: {path}",
+  "history.overThresholdResumeTitle": "Resume large conversation?",
+  "history.overThresholdResumeMessage": "This conversation is about {used} tokens — already above the compaction threshold ({threshold} tokens). Continuing will immediately clean up and summarize earlier history.",
+  "history.overThresholdResumeConfirm": "Resume anyway",
+  "history.overThresholdResumeCancelled": "Resume cancelled — the conversation is unchanged.",
   "history.failedOpenSession": "Cannot open session",
   "history.failedOpenGlobal": "Cannot open global session",
   "history.missingWorkspaceRoot": "Cannot open session because its workspace path is missing.",
diff --git a/desktop/frontend/src/locales/zh-TW.ts b/desktop/frontend/src/locales/zh-TW.ts
index ba8baefb28..275ca34913 100644
--- a/desktop/frontend/src/locales/zh-TW.ts
+++ b/desktop/frontend/src/locales/zh-TW.ts
@@ -973,6 +973,10 @@ export const zhTW: Record<DictKey, string> = {
   "history.channel": "渠道",
   "history.channelReadOnly": "唯讀渠道",
   "history.failedOpenProject": "無法開啟會話，{name}不存在：{path}",
+  "history.overThresholdResumeTitle": "恢復超長會話？",
+  "history.overThresholdResumeMessage": "該會話上下文約 {used} tokens，已超過壓縮閾值（{threshold} tokens）。繼續將立即清理並摘要化較早歷史。",
+  "history.overThresholdResumeConfirm": "仍要恢復",
+  "history.overThresholdResumeCancelled": "已取消恢復——會話未被更改。",
   "history.failedOpenSession": "無法開啟會話",
   "history.failedOpenGlobal": "無法開啟全域會話",
   "history.missingWorkspaceRoot": "無法開啟會話：缺少工作區路徑。",
diff --git a/desktop/frontend/src/locales/zh.ts b/desktop/frontend/src/locales/zh.ts
index 9872a70455..2298271cc0 100644
--- a/desktop/frontend/src/locales/zh.ts
+++ b/desktop/frontend/src/locales/zh.ts
@@ -1230,6 +1230,10 @@ export const zh: Record<DictKey, string> = {
   "history.channel": "渠道",
   "history.channelReadOnly": "只读渠道",
   "history.failedOpenProject": "无法打开会话，{name}不存在：{path}",
+  "history.overThresholdResumeTitle": "恢复超长会话？",
+  "history.overThresholdResumeMessage": "该会话上下文约 {used} tokens，已超过压缩阈值（{threshold} tokens）。继续将立即清理并摘要化较早历史。",
+  "history.overThresholdResumeConfirm": "仍要恢复",
+  "history.overThresholdResumeCancelled": "已取消恢复——会话未被更改。",
   "history.failedOpenSession": "无法打开会话",
   "history.failedOpenGlobal": "无法打开全局会话",
   "history.missingWorkspaceRoot": "无法打开会话：缺少工作区路径。",
diff --git a/docs/SPEC.md b/docs/SPEC.md
index f22ce7c2c3..20adac79c2 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -272,6 +272,11 @@ when the sole automatic threshold is crossed.
   `reasonix config compact-ratio [--local] [VALUE]`. Project config overrides the
   user-global value used by desktop and new CLI sessions. UI always shows the
   **effective** ratio.
+- Resuming a session whose estimated prompt already exceeds `triggerTokens`
+  would run the cleanup pass on the first turn after restore. The desktop
+  history UI estimates the session from a read-only preview and asks for
+  confirmation **before** the restore, so cancelling leaves the session
+  untouched.
 - `max_output_tokens` is an independent **per-turn** completion ceiling.
   Recommended: `0` (**automatic**, not unlimited; DeepSeek default high → ~64K).
   User presets: `32768` ordinary coding / cost control, `65536` heavy reasoning /
diff --git a/docs/SPEC.zh-CN.md b/docs/SPEC.zh-CN.md
index 3a7301662a..93fdc721ea 100644
--- a/docs/SPEC.zh-CN.md
+++ b/docs/SPEC.zh-CN.md
@@ -158,6 +158,9 @@ transcript，仅在唯一自动阈值被跨越时安装 provider 可见的短 **
   `recentTailBudget = clamp(window×10%, 32K, 96K)`，摘要输出上限 **16K**。
 - 用户可用 `reasonix config compact-ratio [--local] [VALUE]` 查看或修改阈值。
   项目配置优先于桌面与新 CLI 会话共用的用户全局配置。UI 始终展示**实际生效**值。
+- 恢复一个估算 prompt 已超过 `triggerTokens` 的会话，会在恢复后的第一轮立即触发清理。
+  桌面端历史界面先从**只读预览**估算会话大小，并在恢复**之前**请求用户确认，
+  取消不会改动会话。
 - `max_output_tokens` 是独立的**本轮**输出上限。
   推荐 `0`（**自动**，不是无限；DeepSeek 默认 high → 约 64K）。
   用户侧常用值：`32768` 普通编码/控费，`65536` 重推理/长工具链，`131072` 仅在反复
diff --git a/tools/repolint/baseline.json b/tools/repolint/baseline.json
index 0b112d91e5..d17a2ba6df 100644
--- a/tools/repolint/baseline.json
+++ b/tools/repolint/baseline.json
@@ -4,7 +4,7 @@
     "commented-code": 0,
     "complexity": 2103,
     "essay": 4071,
-    "file-size": 109568,
+    "file-size": 109577,
     "function-size": 9153,
     "layering": 1,
     "marker": 0,
@@ -84,7 +84,7 @@
       "essay": 2
     },
     "desktop/frontend/src/App.tsx": {
-      "file-size": 4724
+      "file-size": 4696
     },
     "desktop/frontend/src/__tests__/app-chrome-tabs.test.ts": {
       "test-file-size": 19
@@ -177,7 +177,7 @@
       "file-size": 1511
     },
     "desktop/frontend/src/lib/useController.ts": {
-      "file-size": 3936
+      "file-size": 3973
     },
     "desktop/heartbeat.go": {
       "essay": 20,