@oar-sh/oar 0.9.7 → 0.9.9

package/server/public/app/back-guard.mjs

@@ -0,0 +1,58 @@
+// In the installed app, the system back button with nothing left to go back
+// to closes the app. There is no way for a page to send itself to the
+// background instead, but it can make sure that moment never comes: one
+// entry marked as the floor is kept beneath the app's own entry, and when
+// back lands on the floor the app's entry is pushed again at once. Back
+// still closes the file viewer (which pushes its own entry above); only the
+// last step out is swallowed. A browser tab keeps its back button: this is
+// for the installed app alone.
+
+export const BACK_GUARD_FLOOR = 'oarBackGuardFloor';
+export const BACK_GUARD_APP = 'oarApp';
+const FIRST_INTERACTION_EVENTS = ['pointerdown', 'keydown', 'touchstart'];
+
+/**
+ * Lay the floor at the first touch or key, not at start-up: an entry a page
+ * leaves through pushState before the user has done anything is one the
+ * browser skips on back (its guard against pages that hijack the button),
+ * so a floor laid at start-up would be stepped over. Before the first
+ * interaction nothing a page does keeps back from leaving; from then on
+ * the floor holds.
+ */
+export function armBackGuardOnFirstInteraction({ history, enabled = true, target, onFloor = null } = {}) {
+  if (!enabled || !history || !target) return null;
+  const state = { guard: null };
+  const arm = () => {
+    for (const eventName of FIRST_INTERACTION_EVENTS) target.removeEventListener(eventName, arm, true);
+    if (state.guard) return;
+    state.guard = installBackGuard({ history, enabled: true, onFloor });
+    target.addEventListener('popstate', () => state.guard.onPopState());
+  };
+  for (const eventName of FIRST_INTERACTION_EVENTS) target.addEventListener(eventName, arm, true);
+  return { get armed() { return Boolean(state.guard); } };
+}
+
+/**
+ * `onFloor` is told each time back lands on the floor and is swallowed.
+ * The entry pushed again then is pushed without a touch, so the browser
+ * lets the next back leave unless the user touches the app in between:
+ * one swallowed press, then the app closes — the pattern phones use, and
+ * the moment to say "press back again to close".
+ */
+export function installBackGuard({ history, enabled = true, onFloor = null } = {}) {
+  if (!enabled || !history) return null;
+  const current = history.state && typeof history.state === 'object' ? history.state : {};
+  // After a reload on the app's entry the floor already lies beneath it.
+  if (!current[BACK_GUARD_FLOOR] && !current[BACK_GUARD_APP]) {
+    history.replaceState({ ...current, [BACK_GUARD_FLOOR]: true }, '');
+    history.pushState({ [BACK_GUARD_APP]: true }, '');
+  }
+  return {
+    /** Feed every popstate here. */
+    onPopState() {
+      if (!history.state?.[BACK_GUARD_FLOOR]) return;
+      history.pushState({ [BACK_GUARD_APP]: true }, '');
+      onFloor?.();
+    },
+  };
+}

package/server/public/app/bootstrap.js

@@ -32,6 +32,7 @@ import {
   openSummaryModal,
   closeSummaryModal,
   refreshSummaryModal,
+  setSummaryModalLeaveHandler,
   syncViewportMetrics,
   isMobileComposerViewport,
   releaseComposerFocusAfterSend,
@@ -120,7 +121,13 @@ import {
   clearImageEditTarget,
   jumpToImageParent,
   flushDeferredMessageRender,
+  conversationHasActiveTurn,
+  focusConversationMessageById,
+  syncRenderedPinState,
+  isConversationWindowAtTail,
+  getTranscriptJumpEpoch,
 } from './conversation-view.js';
+import { initPinnedMessagesView, setPinsConversation } from './pinned-messages-view.mjs';
 import { bindChatSelectionGuard, chatSelectionGuard, isChatInteractionHeld } from './selection-guard.mjs';
 import { loadRepoBrowserTree, openRepoBrowser, closeRepoBrowser, setRepoBrowserSessionInfo, resetWorkspaceRepoBrowserForRootChange } from './attachments-view.js';
 import { handleAttachmentInput, retryAttachmentUpload, openAnnotateEditorForPending, openAnnotateEditorForPreview, handleComposerPaste, handleComposerDrop, refreshComposerAttachmentWarning, removeAttachment, clearAttachments, openUploadedAttachmentViewer, setFilePreviewMode, toggleFilePreviewHtml, copyFilePreviewImage, closeFilePreview, goBackFilePreview, openWorkspaceFilePreview, openWorkspaceFilePreviewFromRepo, setRepoBrowserRoot, setRepoBrowserViewMode, toggleRepoBrowserHidden, toggleRepoBrowserHeavy, refreshRepoBrowser, focusRepoTree, setRepoCurrentPath, confirmRepoBrowserCwdPick } from './attachments-view.js';
@@ -196,9 +203,14 @@ import {
   adoptLegacyPwaAppName,
   registerPwaShell,
   updatePwaAppName,
+  isInstalledAppMode,
 } from './pwa-install.js';
+import { armBackGuardOnFirstInteraction } from './back-guard.mjs';
+import { initScrollbarHover } from './scrollbar-hover.mjs';
 import {
+  autoCompactWindowNotes,
   renderAutoCompactControlHtml,
+  renderAutoCompactNotesHtml,
   renderContextUsageHtml,
   renderThinkingControlHtml,
   thinkingEnabledFromKey,
@@ -207,7 +219,6 @@ import {
 import { renderAttributionControlHtml } from './attribution-control.mjs';
 import {
   autoCompactWindowFromIndex,
-  autoCompactWindowToIndex,
   formatAutoCompactWindowLabel,
 } from './auto-compact-window-options.mjs';
 import { renderPlanUsageHtml, planUsageSubtitle, normalizeUsageProvider } from './plan-usage-view.mjs';
@@ -826,7 +837,11 @@ function initNetworkLifecycleHandling() {
   window.addEventListener('pageshow', () => {
     handleForegroundTransition('pageshow', { immediate: true });
   });
-  window.addEventListener('pagehide', () => {
+  window.addEventListener('pagehide', (event) => {
+    // A page unloaded with the context modal still open (tab closed, app
+    // swiped away, reload) saves the window slider's draft like a modal
+    // close. A page only put aside (`persisted`) keeps its draft.
+    if (!event.persisted) commitAutoCompactDraft({ pageClosing: true });
     // The page is going away; no grace period, suspend immediately.
     cancelBackgroundSuspend();
     setForegroundNetworkWorkEnabled(false);
@@ -3094,18 +3109,37 @@ async function loadUsageSummaryAndRender() {
 // The context modal is rendered from scratch on every refresh, so the slider's
 // conversation binding lives here rather than on the element.
 let autoCompactControlConversationId = '';
-let autoCompactWindowUpdateInFlight = false;
-// The server's last known window for the rendered control. Kept so a rejected
-// PATCH can put the slider back instead of leaving the rejected value on
-// screen until the next refresh.
+// The save in flight, if any: saves run one after another, never side by side.
+let autoCompactWindowUpdateInFlight = null;
+// The server's last known window for the rendered control: what a draft is
+// compared against.
 let autoCompactControlStoredWindow = null;
+// What the last payload said about the running session, for the notes.
+let autoCompactControlSession = { activeWindow: null, deferred: null, usedTokens: null };
+// The slider is a draft while the modal is open: moving it only updates the
+// label and the notes, and the value is saved when the modal is left
+// (setSummaryModalLeaveHandler). `window` undefined = untouched. Kept outside
+// the DOM so a refresh of the open modal keeps the position.
+let autoCompactDraft = { conversationId: '', window: undefined };
+
+function autoCompactNotesOptions(draftWindow, storedWindow = autoCompactControlStoredWindow) {
+  return {
+    draftWindow,
+    storedWindow,
+    activeWindow: autoCompactControlSession.activeWindow,
+    deferred: autoCompactControlSession.deferred,
+    turnRunning: !!autoCompactControlConversationId && conversationHasActiveTurn(autoCompactControlConversationId),
+    usedTokens: autoCompactControlSession.usedTokens,
+  };
+}
 
-// Snaps both the range input and its label back to `window`.
-function setAutoCompactControlValue(window) {
-  const slider = document.getElementById('ctx-autocompact-slider');
-  if (slider) slider.value = String(autoCompactWindowToIndex(window));
+function trackAutoCompactDraft(slider) {
+  const window = autoCompactWindowFromIndex(slider.value);
+  autoCompactDraft = { conversationId: autoCompactControlConversationId, window };
   const label = document.getElementById('ctx-autocompact-value');
   if (label) label.textContent = formatAutoCompactWindowLabel(window);
+  const notes = document.getElementById('ctx-autocompact-notes');
+  if (notes) notes.innerHTML = renderAutoCompactNotesHtml(autoCompactNotesOptions(window));
 }
 
 /**
@@ -3121,18 +3155,37 @@ function initAutoCompactWindowControl() {
     const target = event?.target;
     return target && target.id === 'ctx-autocompact-slider' ? target : null;
   };
-  // Dragging only previews the label; nothing is persisted until the value
-  // settles, matching the settings-modal sliders.
-  body.addEventListener('input', (event) => {
-    const slider = sliderFrom(event);
-    if (!slider) return;
-    const label = document.getElementById('ctx-autocompact-value');
-    if (label) label.textContent = formatAutoCompactWindowLabel(autoCompactWindowFromIndex(slider.value));
-  });
-  body.addEventListener('change', (event) => {
-    const slider = sliderFrom(event);
-    if (!slider) return;
-    void applyAutoCompactWindowSelection(autoCompactWindowFromIndex(slider.value));
+  // Nothing is written while the modal is open; see commitAutoCompactDraft.
+  for (const type of ['input', 'change']) {
+    body.addEventListener(type, (event) => {
+      const slider = sliderFrom(event);
+      if (slider) trackAutoCompactDraft(slider);
+    });
+  }
+}
+
+// Runs when the context modal is left (or re-bound to another conversation):
+// a draft that differs from the stored value is saved; one set back to the
+// stored value sends nothing.
+function commitAutoCompactDraft({ pageClosing = false } = {}) {
+  const { conversationId, window } = autoCompactDraft;
+  autoCompactDraft = { conversationId: '', window: undefined };
+  if (!conversationId || window === undefined) return;
+  if (conversationId === autoCompactControlConversationId && window === autoCompactControlStoredWindow) return;
+  if (pageClosing) {
+    // Sent at once, not queued behind an earlier save: the request has to
+    // leave before the page does.
+    void saveAutoCompactWindow(conversationId, window, '', { pageClosing: true });
+    return;
+  }
+  const notes = autoCompactWindowNotes(autoCompactNotesOptions(window, window));
+  const previous = autoCompactWindowUpdateInFlight || Promise.resolve();
+  const run = previous
+    .catch(() => {})
+    .then(() => saveAutoCompactWindow(conversationId, window, notes.pending));
+  autoCompactWindowUpdateInFlight = run;
+  void run.finally(() => {
+    if (autoCompactWindowUpdateInFlight === run) autoCompactWindowUpdateInFlight = null;
   });
 }
 
@@ -3239,41 +3292,32 @@ async function applyThinkingSelection(axis, key) {
   }
 }
 
-async function applyAutoCompactWindowSelection(autoCompactWindow) {
-  const convId = String(autoCompactControlConversationId || '').trim();
-  const slider = document.getElementById('ctx-autocompact-slider');
-  if (!convId || autoCompactWindowUpdateInFlight) {
-    // Nothing will be written, so leave the control showing what is stored
-    // rather than a position the server never heard about.
-    setAutoCompactControlValue(autoCompactControlStoredWindow);
-    return;
-  }
-  autoCompactWindowUpdateInFlight = true;
-  if (slider) slider.disabled = true;
+async function saveAutoCompactWindow(convId, autoCompactWindow, pendingNote = '', { pageClosing = false } = {}) {
   try {
     // Only the window is sent: the route keeps every unmentioned preference as
     // stored, so this cannot clobber the composer's model/effort choice.
     const response = await updateConversationPreferences(convId, {
       clientId: CLIENT_ID,
       autoCompactWindow,
-    });
+    }, { keepalive: pageClosing });
+    // Nobody is left to tell on a page that is going away.
+    if (pageClosing) return;
     if (!response) throw new Error('Failed to update the auto-compact window');
     // The server, not the slider, decides what got stored (values snap to a
-    // stop), so the control follows the response.
+    // stop).
     const stored = response.autoCompactWindow ?? null;
-    autoCompactControlStoredWindow = stored;
-    setAutoCompactControlValue(stored);
+    if (convId === autoCompactControlConversationId) autoCompactControlStoredWindow = stored;
+    // No note when the running session already uses this value.
+    const when = pendingNote ? ` ${pendingNote}` : '';
     showTransientRelayNotice(stored === null
-      ? 'Auto-compact window back to the model default; applies to the next message.'
-      : `Auto-compact window set to ${formatAutoCompactWindowLabel(stored)} tokens; applies to the next message.`);
+      ? `Auto-compact window back to the model default.${when}`
+      : `Auto-compact window set to ${formatAutoCompactWindowLabel(stored)} tokens.${when}`);
+    // A modal reopened on this conversation meanwhile shows the new value.
+    if (summaryModalState.kind === 'context' && convId === autoCompactControlConversationId) {
+      await refreshSummaryModal();
+    }
   } catch (error) {
-    // The write was refused, so the rejected position is a lie: put the
-    // control back on the last value the server confirmed.
-    setAutoCompactControlValue(autoCompactControlStoredWindow);
     alert(error?.message || 'Failed to update the auto-compact window.');
-  } finally {
-    autoCompactWindowUpdateInFlight = false;
-    if (slider) slider.disabled = false;
   }
 }
 
@@ -3294,7 +3338,33 @@ async function loadContextSummaryAndRender(convId) {
     ? `${providerLabel} session ${sessionId.slice(0, 8)}`
     : (trimmedConvId ? `Conversation ${trimmedConvId.slice(0, 8)}` : 'No conversation selected');
 
-  const usageHtml = renderContextUsageHtml(payload.contextUsage);
+  // The session fields come with the payload when the relay knows them
+  // (older relays send neither, and the notes fall back to draft vs stored).
+  const sessionField = (key) => payload[key] ?? payload.contextUsage?.[key] ?? null;
+  const modelContextLimit = sessionField('modelContextLimit');
+  const usageHtml = renderContextUsageHtml(payload.contextUsage, {
+    compactionWindow: payload.providerType === 'claude',
+    modelContextLimit,
+  });
+  // The slider's writes need the conversation id even when the modal was
+  // opened through an sdk_session_id.
+  const boundConversationId = String(
+    payload.resolvedConversationId || (payload.providerType === 'claude' ? trimmedConvId : '') || '',
+  ).trim();
+  // A draft for another conversation is saved before this one takes over.
+  if (autoCompactDraft.conversationId && autoCompactDraft.conversationId !== boundConversationId) {
+    commitAutoCompactDraft();
+  }
+  autoCompactControlConversationId = boundConversationId;
+  // What the server says is stored right now, refreshed every time the
+  // control is re-rendered: the draft is compared against it.
+  autoCompactControlStoredWindow = payload.autoCompactWindow ?? null;
+  autoCompactControlSession = {
+    activeWindow: sessionField('activeAutoCompactWindow'),
+    deferred: sessionField('autoCompactWindowDeferred'),
+    usedTokens: payload.contextUsage?.totalTokens ?? null,
+  };
+  const draftWindow = autoCompactDraft.conversationId === boundConversationId ? autoCompactDraft.window : undefined;
   // Claude-only: no other provider exposes a compaction window (or any
   // session-settings surface) to steer.
   const autoCompactHtml = payload.providerType === 'claude'
@@ -3310,6 +3380,11 @@ async function loadContextSummaryAndRender(convId) {
         ? (payload.contextUsage.isAutoCompactEnabled ?? null)
         : null,
       maxTokens: payload.contextUsage?.maxTokens ?? null,
+      draftWindow,
+      activeAutoCompactWindow: autoCompactControlSession.activeWindow,
+      autoCompactWindowDeferred: autoCompactControlSession.deferred,
+      turnRunning: autoCompactNotesOptions(draftWindow).turnRunning,
+      usedTokens: autoCompactControlSession.usedTokens,
     })
     : '';
   const thinkingHtml = payload.providerType === 'claude'
@@ -3323,14 +3398,6 @@ async function loadContextSummaryAndRender(convId) {
   const attributionHtml = payload.providerType === 'claude' || payload.providerType === 'claude-cloud'
     ? renderAttributionControlHtml(payload.attribution || null)
     : '';
-  // The slider's writes need the conversation id even when the modal was
-  // opened through an sdk_session_id.
-  autoCompactControlConversationId = String(
-    payload.resolvedConversationId || (payload.providerType === 'claude' ? trimmedConvId : '') || '',
-  ).trim();
-  // Baseline for the failure path below: what the server says is stored right
-  // now, refreshed every time the control is re-rendered.
-  autoCompactControlStoredWindow = payload.autoCompactWindow ?? null;
   thinkingControlStored = {
     enabled: payload.thinkingEnabled !== false,
     display: payload.thinkingDisplay || 'summarized',
@@ -3351,6 +3418,7 @@ async function loadContextSummaryAndRender(convId) {
     refresh: () => loadContextSummaryAndRender(refreshLookupId),
     kind: 'context',
   });
+  setSummaryModalLeaveHandler('context', () => commitAutoCompactDraft());
 }
 
 async function showUsage() {
@@ -3531,6 +3599,15 @@ function startSessionWorkerStatusPolling() {
   }, 4000);
 }
 
+// The live poll and refreshCurrentView both reload the END of the
+// conversation. After a jump into the history (a search result, a pinned
+// message) that would put the end back over the window the user asked for,
+// until they have scrolled down to the newest message again. A message sent
+// from that window brings the present back at once: its bubble needs the poll.
+function transcriptIsInHistory(conversationId) {
+  return !isConversationWindowAtTail() && !hasPendingUserMessageForConversation(conversationId);
+}
+
 async function pollAuthenticatedCurrentConversationLive() {
   if (liveConversationPollInFlight) return;
   if (isSharedReaderMode()) return;
@@ -3548,6 +3625,7 @@ async function pollAuthenticatedCurrentConversationLive() {
   // Refreshing while the user selects or drags in the chat would rebuild the
   // DOM under the selection; the guard's release callback re-polls right away.
   if (isChatInteractionHeld()) return;
+  if (transcriptIsInHistory(currentId)) return;
 
   liveConversationPollInFlight = true;
   try {
@@ -3556,9 +3634,14 @@ async function pollAuthenticatedCurrentConversationLive() {
     const savedScrollTop = messagesEl?.scrollTop || 0;
     const savedLoadedCount = loadConversationLoadedMessageCount(currentId);
     const requestLimit = Math.max(20, getConversationLoadedMessageCount() || 0, savedLoadedCount || 0);
+    const jumpEpoch = getTranscriptJumpEpoch();
     const response = await loadConversation(currentId, { limit: requestLimit });
     if (!response) return;
     if (String(currentConvId || '').trim() !== currentId) return;
+    // The user jumped into the history while this request was on its way: the
+    // answer is the end of the conversation as it was asked for before that,
+    // and would overwrite the window they jumped to. The next round asks again.
+    if (getTranscriptJumpEpoch() !== jumpEpoch) return;
     const stableSavedScrollTop = resolveStableScrollTopForLiveRefresh(messagesEl, savedScrollTop);
     applyLoadedConversationState(currentId, response, {
       restoreScroll: !preserveBottom,
@@ -3766,6 +3849,7 @@ let refreshViewVersion = 0;
 
 async function refreshCurrentView() {
   const capturedVersion = ++refreshViewVersion;
+  const jumpEpoch = getTranscriptJumpEpoch();
   const messagesEl = document.getElementById('messages');
   const preserveBottom = isMessagesAtBottom();
   const scrollTop = messagesEl?.scrollTop || 0;
@@ -3788,11 +3872,16 @@ async function refreshCurrentView() {
   const r = await loadConversation(currentId, { limit: requestLimit });
   if (capturedVersion < refreshViewVersion) return;
   if (String(currentConvId || '').trim() !== currentId) return;
+  // The user jumped into the history, before this refresh or while it was on
+  // its way: title, tasks, pins and the rest are refreshed, the transcript
+  // and its scroll position are left as they are.
+  const keepTranscript = getTranscriptJumpEpoch() !== jumpEpoch || transcriptIsInHistory(currentId);
   if (r) {
     applyLoadedConversationState(currentId, r, {
       restoreScroll: !preserveBottom,
       savedScrollTop: preserveBottom ? null : stableSavedScrollTop,
-      followLiveUpdates: preserveBottom,
+      followLiveUpdates: preserveBottom && !keepTranscript,
+      keepTranscript,
     });
   } else {
     setRepoBrowserSessionInfo('', '');
@@ -3801,7 +3890,7 @@ async function refreshCurrentView() {
   await loadRelayQuestions(currentId);
   await loadRelayBoards();
   scheduleContextUsageRefresh(currentId, 0);
-  if (messagesEl && String(currentConvId || '').trim() === currentId) {
+  if (messagesEl && !keepTranscript && String(currentConvId || '').trim() === currentId) {
     if (!preserveBottom && Number.isFinite(stableSavedScrollTop) && stableSavedScrollTop >= 0) {
       messagesEl.scrollTop = stableSavedScrollTop;
     }
@@ -3963,6 +4052,8 @@ function lockChatActionsMenuShield(ms = 300) {
 function syncChatTitleControls() {
   const { title, editBtn, editor, input } = getChatTitleElements();
   const convId = String(currentConvId || '').trim();
+  // No conversation open (deleted, new chat): its 📍 button goes with it.
+  if (!convId) setPinsConversation(null);
   const killBtn = document.getElementById('chat-menu-kill-session');
   const sharedMode = isSharedReaderMode();
   const conversation = convId ? (conversations[convId] || null) : null;
@@ -4194,11 +4285,15 @@ function refreshClaudeCloudComposerModels() {
 }
 
 function showAuthGate(error = '') {
-  document.getElementById('startup-loading')?.remove();
   document.getElementById('auth-gate').style.display = 'flex';
   document.getElementById('app').classList.remove('visible');
   showAuthError(error);
-  document.getElementById('token-input')?.focus();
+  // The start screen hands its logo over to the box first (installed app);
+  // focusing earlier would open the keyboard and move the box under it.
+  const focusToken = () => document.getElementById('token-input')?.focus();
+  const handover = window.__startupSplash?.toAuth?.();
+  if (handover && window.__startupSplash.animated) void handover.then(focusToken);
+  else focusToken();
 }
 
 // Runs before anything reads MODEL_STORAGE_KEY so the first load after an
@@ -4224,6 +4319,7 @@ async function initApp() {
   setForegroundNetworkWorkEnabled(document.visibilityState === 'visible');
   const sharedThemeBtn = document.getElementById('chat-menu-shared-theme-toggle');
   initTheme();
+  initScrollbarHover();
   initThemeMenuToggle();
   if (sharedThemeBtn && sharedMode) sharedThemeBtn.hidden = false;
   initFontScaling();
@@ -4256,7 +4352,8 @@ async function initApp() {
     void flushConversationDraft(currentConvId);
     closeTmuxInspectorView();
   });
-  document.getElementById('startup-loading')?.remove();
+  // The start screen lies over the app and leaves once its animation is done.
+  void window.__startupSplash?.finish?.();
   document.getElementById('auth-gate').style.display = 'none';
   document.getElementById('app').classList.add('visible');
   initSidebarLayout();
@@ -4504,6 +4601,11 @@ async function initApp() {
   initMessageScrollPersistence();
   initComposerAttachmentInput();
   initMessageSearchView({ openConversation });
+  initPinnedMessagesView({
+    openConversation,
+    focusMessage: focusConversationMessageById,
+    syncRenderedPinState,
+  });
   initGitChangesView();
   syncChatTitleControls();
   connectSocket();
@@ -4560,6 +4662,15 @@ async function bootstrap() {
   }
   const urlToken = getTokenFromUrl();
   if (urlToken) stripTokenFromUrl();
+  // In the installed app the system back button must never close the app;
+  // a tab keeps its own back button. After the token is gone from the
+  // address, so the entries the guard lays down carry the clean one.
+  armBackGuardOnFirstInteraction({
+    history: window.history,
+    enabled: isInstalledAppMode(),
+    target: window,
+    onFloor: () => showTransientRelayNotice('Press back again to close the app', 2500),
+  });
   const persistedToken = consumeLegacyPersistedAuthToken();
   const bootstrapToken = String(urlToken || persistedToken || '').trim();
   const existingSession = await verifyExistingSession(bootstrapToken);

package/server/public/app/context-usage-view.mjs

@@ -134,6 +134,73 @@ function autocompactSourceLabel(source) {
   return AUTOCOMPACT_SOURCE_LABELS[key.toLowerCase()] || key;
 }
 
+// The slider's notes. The window is read by the CLI only when it starts, so
+// a new value takes effect through one session restart before a message, as
+// soon as nothing is running.
+export const AUTO_COMPACT_NOTE_TEXT = Object.freeze({
+  compactNext: 'The conversation will be compacted on the next message.',
+  afterTurn: 'Applies after the current turn.',
+  afterBackground: 'Applies when background work has finished.',
+  nextMessage: 'Applies on the next message (the session restarts once).',
+});
+
+function normalizeDeferred(value) {
+  const key = String(value || '').trim().toLowerCase();
+  return key === 'turn' || key === 'background' || key === 'next-message' ? key : null;
+}
+
+/**
+ * Which notes sit under the slider.
+ *
+ * - `warning`: the draft is a fixed window below the tokens already in use, so
+ *   the next message starts with a compaction.
+ * - `pending`: what is on the slider is not what the running session uses
+ *   yet — an unsaved draft, a stored value the session was not started with
+ *   (`activeWindow`, known only as a number), or a change the relay reports
+ *   as held back (`deferred`). Worded by what it waits for. Payloads without
+ *   the session fields only ever compare draft and stored.
+ *
+ * @returns {{ warning: string, pending: string }}
+ */
+export function autoCompactWindowNotes({
+  draftWindow,
+  storedWindow = null,
+  activeWindow = null,
+  deferred = null,
+  turnRunning = false,
+  usedTokens = null,
+} = {}) {
+  const stored = parseAutoCompactWindow(storedWindow);
+  const draft = draftWindow === undefined ? stored : parseAutoCompactWindow(draftWindow);
+  const active = toNullableNumber(activeWindow);
+  const held = normalizeDeferred(deferred);
+  const used = toNullableNumber(usedTokens);
+  const warning = draft !== null && used !== null && draft < used ? AUTO_COMPACT_NOTE_TEXT.compactNext : '';
+  const differs = draft !== stored
+    || (active !== null && parseAutoCompactWindow(active) !== stored)
+    || held !== null;
+  let pending = '';
+  if (differs) {
+    if (held === 'turn' || turnRunning) pending = AUTO_COMPACT_NOTE_TEXT.afterTurn;
+    else if (held === 'background') pending = AUTO_COMPACT_NOTE_TEXT.afterBackground;
+    else pending = AUTO_COMPACT_NOTE_TEXT.nextMessage;
+  }
+  return { warning, pending };
+}
+
+/** The notes block's inner HTML (re-rendered live while the slider moves). */
+export function renderAutoCompactNotesHtml(options = {}) {
+  const { warning, pending } = autoCompactWindowNotes(options);
+  return [
+    warning
+      ? `<div class="ctx-autocompact-note ctx-autocompact-warning" data-autocompact-note="compact-next">${escapeHtml(warning)}</div>`
+      : '',
+    pending
+      ? `<div class="ctx-autocompact-note" data-autocompact-note="pending">${escapeHtml(pending)}</div>`
+      : '',
+  ].join('');
+}
+
 /**
  * The Claude-only auto-compact window control: a snap-stop slider over
  * AUTO_COMPACT_WINDOW_STOPS plus the measured effective threshold.
@@ -142,8 +209,10 @@ function autocompactSourceLabel(source) {
  * trustworthy model-limit field. `rawMaxTokens` tracks the ACTIVE setting, not
  * the model's own window (probed on claude-opus-5[1m]: no setting → 1000000,
  * setting 100000 → 100000), so annotating from it told a user who had just
- * pinned 100k that every larger stop was pointless. Applied on the next
- * message delivery, which is why there is no live preview of the effect.
+ * pinned 100k that every larger stop was pointless.
+ *
+ * The slider is a draft while the modal is open (`draftWindow`, defaulting to
+ * the stored window); the caller saves it when the modal closes.
  *
  * `isAutoCompactEnabled` is tri-state on purpose: `null`/`undefined` means the
  * runtime has not reported yet (no context-usage snapshot exists before the
@@ -158,9 +227,23 @@ export function renderAutoCompactControlHtml({
   autocompactSource = null,
   isAutoCompactEnabled = null,
   maxTokens = null,
+  draftWindow = undefined,
+  activeAutoCompactWindow = null,
+  autoCompactWindowDeferred = null,
+  turnRunning = false,
+  usedTokens = null,
 } = {}) {
-  const window = parseAutoCompactWindow(autoCompactWindow);
+  const stored = parseAutoCompactWindow(autoCompactWindow);
+  const window = draftWindow === undefined ? stored : parseAutoCompactWindow(draftWindow);
   const index = autoCompactWindowToIndex(window);
+  const notesHtml = renderAutoCompactNotesHtml({
+    draftWindow: window,
+    storedWindow: stored,
+    activeWindow: activeAutoCompactWindow,
+    deferred: autoCompactWindowDeferred,
+    turnRunning,
+    usedTokens,
+  });
 
   const threshold = toNullableNumber(autoCompactThreshold);
   const sourceLabel = autocompactSourceLabel(autocompactSource);
@@ -195,7 +278,7 @@ export function renderAutoCompactControlHtml({
       >
       <div class="ctx-autocompact-effective">Effective: ${effective}</div>
       ${disabledNote}
-      <div class="ctx-autocompact-note">Applied on the next message in this conversation.</div>
+      <div id="ctx-autocompact-notes" class="ctx-autocompact-notes">${notesHtml}</div>
     </div>
   `;
 }
@@ -267,20 +350,56 @@ ${renderThinkingButtons('display', THINKING_DISPLAY_CHOICES, displayKey)}
   `;
 }
 
+// A model limit is a round figure: 1M rather than 1.0M.
+function formatModelLimit(value) {
+  const n = toNullableNumber(value);
+  if (n === null) return '—';
+  if (Math.abs(n) >= 1_000_000) return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
+  return formatCompactTokens(n);
+}
+
+/**
+ * The headline of a Claude session, whose snapshot max is the compaction
+ * window rather than the model's limit:
+ * `60.9k used · compaction window 100.0k · model limit 1M` (the limit only
+ * when known).
+ */
+export function formatCompactionWindowHeadline({ totalTokens, maxTokens, modelContextLimit = null } = {}) {
+  if (toNullableNumber(totalTokens) === null || toNullableNumber(maxTokens) === null) return '';
+  const parts = [
+    `${formatCompactTokens(totalTokens)} used`,
+    `compaction window ${formatCompactTokens(maxTokens)}`,
+  ];
+  if (toNullableNumber(modelContextLimit) !== null && Number(modelContextLimit) > 0) {
+    parts.push(`model limit ${formatModelLimit(modelContextLimit)}`);
+  }
+  return parts.join(' · ');
+}
+
 /**
  * @param {object|null} usage the `contextUsage` field of an /api/context response
+ * @param {object} [options]
+ * @param {boolean} [options.compactionWindow] the max is a compaction window
+ *   (Claude): the headline names it, plus `modelContextLimit` when known
  * @returns {string} modal body HTML, or '' when there is nothing to render
  */
-export function renderContextUsageHtml(usage) {
+export function renderContextUsageHtml(usage, { compactionWindow = false, modelContextLimit = null } = {}) {
   if (!usage || typeof usage !== 'object') return '';
   const categories = Array.isArray(usage.categories) ? usage.categories : [];
   const hasTotals = toNullableNumber(usage.totalTokens) !== null
     && toNullableNumber(usage.maxTokens) !== null;
   if (!categories.length && !hasTotals) return '';
 
-  const headline = hasTotals
-    ? `${formatCompactTokens(usage.totalTokens)} / ${formatCompactTokens(usage.maxTokens)} tokens (${formatUsagePercent(usage.percentage, { digits: 0 })})`
-    : '';
+  let headline = '';
+  if (hasTotals) {
+    headline = compactionWindow
+      ? formatCompactionWindowHeadline({
+        totalTokens: usage.totalTokens,
+        maxTokens: usage.maxTokens,
+        modelContextLimit,
+      })
+      : `${formatCompactTokens(usage.totalTokens)} / ${formatCompactTokens(usage.maxTokens)} tokens (${formatUsagePercent(usage.percentage, { digits: 0 })})`;
+  }
 
   const rows = categories.map((category) => renderRow(category)).join('');
   const freeRow = toNullableNumber(usage.freeTokens) !== null