codex-overleaf-link 2.4.1 → 2.5.0

package/extension/src/shared/storageDb.js

@@ -1,18 +1,23 @@
 (function initStorageDb(root, factory) {
   if (typeof module === 'object' && module.exports) {
     module.exports = factory(require('./storageRunActions'), require('./runInputQueue'),
-      require('./settlementFacts'), require('./storageSessionClaims'), require('./sessionState'));
+      require('./settlementFacts'), require('./storageSessionClaims'), require('./sessionState'), require('./runActivityModel'), require('./sharedSessionBridge'), require('./subagentActivityModel'), require('./storageValuePruning'));
   } else {
     root.CodexOverleafModuleRegistry.define('StorageDb', [
       'StorageRunActions',
       'RunInputQueue',
       'SettlementFacts',
       'StorageSessionClaims',
-      'SessionState'
+      'SessionState',
+      'RunActivityModel',
+      'SharedSessionBridge',
+      'SubagentActivityModel',
+      'StorageValuePruning'
     ], factory);
   }
-})(typeof globalThis !== 'undefined' ? globalThis : window, function storageDbFactory(StorageRunActions, RunInputQueue, SettlementFacts, StorageSessionClaims, SessionState) {
+})(typeof globalThis !== 'undefined' ? globalThis : window, function storageDbFactory(StorageRunActions, RunInputQueue, SettlementFacts, StorageSessionClaims, SessionState, RunActivityModel, SharedSessionBridge, SubagentActivityModel, StorageValuePruning) {
   'use strict';
+  const { removeEmptySummaryFields, removeEmptyFields } = StorageValuePruning;
   if (!StorageRunActions?.compactRunsForStorage || !StorageRunActions?.compactRunActionPayload || !StorageRunActions?.compactProviderSnapshot || !StorageRunActions?.compactRunExecutionSnapshot || !StorageRunActions?.compactStructuredEventValue || !StorageRunActions?.hashString || !RunInputQueue?.compactForStorage || !SettlementFacts?.compactSettlementFacts || !StorageSessionClaims?.createSessionClaimer) {
     throw new Error('Codex Overleaf storage run-action helpers are unavailable.');
   }
@@ -280,6 +285,7 @@
       codexThreadId: typeof input.codexThreadId === 'string' ? input.codexThreadId : '',
       status: typeof input.status === 'string' && input.status ? input.status : 'active',
       focusFiles: normalizePathList(input.focusFiles),
+      selectionContext: SessionState.normalizeSelectionContext(input.selectionContext),
       projectReferenceFiles: SessionState.normalizeProjectReferenceFiles(input.projectReferenceFiles),
       pendingInputs: RunInputQueue.compactForStorage(input.pendingInputs, {
         normalizeField: normalizeTextField,
@@ -655,8 +661,10 @@
     return StorageRunActions.compactRunsForStorage(runs, options, SESSION_STORAGE_LIMITS.maxRunsPerSession, compactRunForStorage);
   }
   function compactRunForStorage(run, keepActionPayload) {
+    run = SessionState.recoverRecordedRunFailure(run);
     var actionPayload = StorageRunActions.compactRunActionPayload(run, keepActionPayload);
     var compact = {
+      ...SessionState.pickWritebackRecovery(run),
       id: run.id,
       task: normalizeDisplayTextForStorage(run.task || 'untitled task', SESSION_STORAGE_LIMITS.taskChars),
       mode: typeof run.mode === 'string' ? redactSecretLikeText(run.mode) : '', ...StorageRunActions.compactProviderSnapshot(run),
@@ -664,12 +672,13 @@
       model: normalizeTextField(run.model, 80),
       reasoningEffort: typeof run.reasoningEffort === 'string' ? redactSecretLikeText(run.reasoningEffort) : '',
       speedTier: typeof run.speedTier === 'string' ? redactSecretLikeText(run.speedTier) : '',
-      status: normalizeRunStatus(run.status),
+      status: SessionState.normalizeRunStatus(run.status, run),
       statusText: normalizeDisplayTextForStorage(run.statusText, SESSION_STORAGE_LIMITS.statusTextChars),
       runProjectId: normalizeProjectPrefKey(run.runProjectId),
       startedAt: typeof run.startedAt === 'string' ? redactSecretLikeText(run.startedAt) : '',
       finishedAt: typeof run.finishedAt === 'string' ? redactSecretLikeText(run.finishedAt) : '',
       events: compactRunEventsForStorage(run.events),
+      ...(run.subagents?.length ? { subagents: SubagentActivityModel.normalize(run.subagents, sanitizeAssistantVisibleText) } : {}),
       attachments: compactRunAttachmentsForStorage(run.attachments),
       appliedOperations: actionPayload.appliedOperations,
       undoOperations: actionPayload.undoOperations,
@@ -719,6 +728,13 @@
           streamKey: typeof event.streamKey === 'string' ? redactSecretLikeText(event.streamKey) : '',
           streamRole: typeof event.streamRole === 'string' ? redactSecretLikeText(event.streamRole) : ''
         };
+        // Persist the bounded display projection, never the raw tool payload.
+        // Hydration uses the same model; dropping this metadata demotes tools
+        // to hidden diagnostics after an otherwise successful history reload.
+        var activity = RunActivityModel.capture(event, sanitizeAssistantVisibleText);
+        if (activity) compact.activity = activity;
+        var streamPhase = RunActivityModel.normalizePhase(event.streamPhase);
+        if (streamPhase) compact.streamPhase = streamPhase;
         if (event.subagent === true) {
           compact.subagent = true;
         }
@@ -914,25 +930,6 @@
       .trim(), maxChars || SESSION_STORAGE_LIMITS.pathChars);
   }
 
-  function normalizeRunStatus(status) {
-    // Welcome-panel + write-guard: the run-status
-    // enum gained three post-navigation values. The storage normalizer must
-    // accept them so a settled run round-trips intact through `buildSessionRecord`.
-    // Unknown legacy values fall through to `completed` (the historical default).
-    return [
-      'pending',
-      'running',
-      'completed',
-      'failed',
-      'background_completed',
-      'needs_review_after_navigation',
-      'abandoned_after_navigation',
-      // v1.8.1: reload-orphaned runs settle to 'interrupted' (v1.7.6); the
-      // storage round-trip must not rewrite them to a false 'completed'.
-      'interrupted'
-    ].indexOf(status) !== -1 ? status : 'completed';
-  }
-
   function normalizeEventStatus(status) {
     return VALID_EVENT_STATUSES[status] ? status : 'info';
   }
@@ -1106,37 +1103,7 @@
     return 'error';
   }
 
-  function removeEmptySummaryFields(value) {
-    var result = {};
-    var keys = Object.keys(value || {});
-    for (var i = 0; i < keys.length; i++) {
-      var key = keys[i];
-      var item = value[key];
-      if (item === undefined || item === '' || item === null) {
-        continue;
-      }
-      if (Array.isArray(item) && item.length === 0) {
-        continue;
-      }
-      if (item && typeof item === 'object' && !Array.isArray(item) && Object.keys(item).length === 0) {
-        continue;
-      }
-      result[key] = item;
-    }
-    return result;
-  }
 
-  function removeEmptyFields(value) {
-    var result = {};
-    var keys = Object.keys(value);
-    for (var i = 0; i < keys.length; i++) {
-      var key = keys[i];
-      if (value[key] !== undefined && value[key] !== '') {
-        result[key] = value[key];
-      }
-    }
-    return result;
-  }
 
   // Welcome-panel + write-guard: the Recent-projects
   // dashboard variant calls `listRecentProjectsAcrossAccount` to get the
@@ -1328,7 +1295,7 @@
   }
   var hashString = StorageRunActions.hashString;
 
-  return {
+  return SharedSessionBridge.decorate({
     TARGET_SCHEMA_VERSION: TARGET_SCHEMA_VERSION,
     DB_NAME: DB_NAME,
     STORES: STORES,
@@ -1355,5 +1322,5 @@
     filterRecentProjectsAcrossAccount: filterRecentProjectsAcrossAccount,
     derivePrimaryStatusBadge: derivePrimaryStatusBadge,
     getAllSessions: getAllSessions
-  };
+  });
 });

package/extension/src/shared/storageMigration.js

@@ -50,6 +50,9 @@
   }
 
   function withProjectPreferenceLock(projectId, work) {
+    if (StorageDb.sharedSessionsEnabled?.()) {
+      return StorageDb.withSharedLock('preferences', { projectId: projectId }, work);
+    }
     var lockName = 'codex-overleaf-project-prefs:' + compactScopePart(projectId);
     var lockManager = typeof navigator !== 'undefined' && navigator && navigator.locks;
     if (lockManager && typeof lockManager.request === 'function') {

package/extension/src/shared/storageRunActions.js

@@ -1,14 +1,18 @@
 (function initStorageRunActions(root, factory) {
   if (typeof module === 'object' && module.exports) {
-    module.exports = factory();
+    module.exports = factory(require('./selectionContext'), require('./writebackIntent'), require('./writingStyle'));
   } else {
-    root.CodexOverleafStorageRunActions = factory();
+    root.CodexOverleafModuleRegistry.define('StorageRunActions', ['SelectionContext', 'WritebackIntent', 'WritingStyle'], factory);
   }
-})(typeof globalThis !== 'undefined' ? globalThis : window, function storageRunActionsFactory() {
+})(typeof globalThis !== 'undefined' ? globalThis : window, function storageRunActionsFactory(SelectionContext, WritebackIntent, WritingStyle) {
   'use strict';
 
   var MAX_PERSISTED_ACTION_RUNS_PER_SESSION = 2;
-  var MAX_PERSISTED_ACTION_BYTES_PER_RUN = 320 * 1024;
+  // Undo/Accept need whole pre- and post-images of every written file, so one
+  // run that edits a 120 KB roadmap and creates a 100 KB chapter already needs
+  // ~560 KB. The old 320 KB cap silently dropped the whole payload and the
+  // buttons vanished after a reload. Two runs per session keep this bounded.
+  var MAX_PERSISTED_ACTION_BYTES_PER_RUN = 2 * 1024 * 1024;
 
   function compactRunsForStorage(runs, options, maxRuns, compactRun) {
     if (typeof compactRun !== 'function') {
@@ -126,6 +130,8 @@
       compact.focusFiles = snapshot.focusFiles.slice(0, 100)
         .filter(function (value) { return typeof value === 'string'; }).map(normalize);
     }
+    compact.selectionContext = SelectionContext.normalize(snapshot.selectionContext);
+    compact.writingStyle = WritingStyle.normalizeSnapshot(snapshot.writingStyle);
     return { executionSnapshot: compact };
   }
 

package/extension/src/shared/storageValuePruning.js

@@ -0,0 +1,40 @@
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CodexOverleafModuleRegistry.define('StorageValuePruning', [], factory);
+})(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  'use strict';
+
+  function removeEmptySummaryFields(value) {
+    var result = {};
+    var keys = Object.keys(value || {});
+    for (var i = 0; i < keys.length; i++) {
+      var key = keys[i];
+      var item = value[key];
+      if (item === undefined || item === '' || item === null) {
+        continue;
+      }
+      if (Array.isArray(item) && item.length === 0) {
+        continue;
+      }
+      if (item && typeof item === 'object' && !Array.isArray(item) && Object.keys(item).length === 0) {
+        continue;
+      }
+      result[key] = item;
+    }
+    return result;
+  }
+
+  function removeEmptyFields(value) {
+    var result = {};
+    var keys = Object.keys(value);
+    for (var i = 0; i < keys.length; i++) {
+      var key = keys[i];
+      if (value[key] !== undefined && value[key] !== '') {
+        result[key] = value[key];
+      }
+    }
+    return result;
+  }
+
+  return { removeEmptySummaryFields, removeEmptyFields };
+});

package/extension/src/shared/subagentActivityModel.js

@@ -0,0 +1,174 @@
+(function initSubagentActivityModel(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory(require('./agentTranscript'), require('./runActivityModel'));
+  } else root.CodexOverleafModuleRegistry.define('SubagentActivityModel', ['AgentTranscript', 'RunActivityModel'], factory);
+})(typeof globalThis !== 'undefined' ? globalThis : window, function subagentActivityModelFactory(Transcript, Activity) {
+  'use strict';
+  const MAX_AGENTS = 16, MAX_EVENTS = 100, MAX_CHARS = 48000;
+  const STATES = new Set(['pending', 'running', 'completed', 'failed', 'cancelled', 'unknown']);
+  const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+  const string = value => typeof value === 'string' ? value : '';
+  function clean(value, sanitize = string, limit = 24000) {
+    return string(sanitize(string(value))).slice(0, limit);
+  }
+  function trim(agent) {
+    if (agent.events.length > MAX_EVENTS) { agent.events = agent.events.slice(-MAX_EVENTS); agent.clipped = true; }
+    while (agent.events.length > 1 && JSON.stringify(agent.events).length > MAX_CHARS) {
+      agent.events.shift(); agent.clipped = true;
+    }
+    return agent;
+  }
+  function normalize(agents, sanitize = string) {
+    const seen = new Set();
+    return (Array.isArray(agents) ? agents : []).slice(0, MAX_AGENTS).filter(agent => {
+      if (!agent || !['broker', 'codex'].includes(agent.source)) return false;
+      const id = agent.source === 'broker' ? agent.jobId : agent.threadId;
+      if (typeof id !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,159}$/.test(id)) return false;
+      const key = agent.source + ':' + id;
+      if (seen.has(key)) return false;
+      seen.add(key); return true;
+    }).map(agent => trim({
+      v: 1, source: agent.source, key: agent.source + ':' + (agent.source === 'broker' ? agent.jobId : agent.threadId),
+      jobId: clean(agent.jobId, sanitize, 160), threadId: clean(agent.threadId, sanitize, 160),
+      parentThreadId: clean(agent.parentThreadId, sanitize, 160),
+      title: clean(agent.title, sanitize, 160), task: clean(agent.task, sanitize, 4096),
+      model: clean(agent.model, sanitize, 160), reasoningEffort: clean(agent.reasoningEffort, sanitize, 32),
+      status: STATES.has(agent.status) ? agent.status : 'unknown',
+      startedAt: clean(agent.startedAt, sanitize, 64), updatedAt: clean(agent.updatedAt, sanitize, 64),
+      finishedAt: clean(agent.finishedAt, sanitize, 64),
+      lastSequence: Number.isSafeInteger(agent.lastSequence) ? agent.lastSequence : 0,
+      nativeEventSeq: Number.isSafeInteger(agent.nativeEventSeq) ? agent.nativeEventSeq : 0,
+      clipped: agent.clipped === true, historyUnavailable: agent.historyUnavailable === true,
+      events: (Array.isArray(agent.events) ? agent.events : []).filter(event => event && typeof event.title === 'string')
+        .slice(-MAX_EVENTS).map(event => ({
+          title: clean(event.title, sanitize), status: clean(event.status, sanitize, 32),
+          timestamp: clean(event.timestamp, sanitize, 64),
+          kind: event.kind === 'stream' ? 'stream' : 'activity',
+          streamKey: clean(event.streamKey, sanitize, 600), streamRole: event.streamRole === 'assistant' ? 'assistant' : '',
+          streamPhase: Activity.normalizePhase(event.streamPhase),
+          activity: Activity.normalize(event.activity, sanitize)
+        }))
+    }));
+  }
+  function effectiveStatus(agent, run) {
+    if (TERMINAL.has(agent.status) || agent.status === 'unknown' || run.status === 'running') return agent.status;
+    return ['cancelled', 'rejected'].includes(run.status) ? 'cancelled' : 'unknown';
+  }
+  function terminalTime(agent, run) {
+    const terminal = [agent.finishedAt, run.status === 'running' ? '' : run.finishedAt]
+      .map(value => Date.parse(value || '')).find(Number.isFinite);
+    const evidence = [agent.startedAt, agent.updatedAt, ...(agent.events || []).map(event => event.timestamp)];
+    if (run.status !== 'running') evidence.push(run.startedAt, run.updatedAt, ...(run.events || []).map(event => event.timestamp));
+    return terminal ?? Math.max(...evidence.map(value => Date.parse(value || '')).filter(Number.isFinite));
+  }
+  function elapsedMs(agent, run, now = Date.now()) {
+    const start = Date.parse(agent.startedAt || '');
+    const live = run.status === 'running' && ['pending', 'running'].includes(effectiveStatus(agent, run));
+    return Number.isFinite(start) ? Math.max(0, (live ? now : terminalTime(agent, run)) - start) : null;
+  }
+  function append(agent, input, sanitize) {
+    const event = {
+      title: clean(input.title, sanitize), status: input.status || 'running',
+      timestamp: input.timestamp || new Date().toISOString(),
+      kind: input.kind === 'stream' ? 'stream' : 'activity',
+      streamKey: input.streamKey || '', streamRole: input.streamRole || '',
+      streamPhase: Activity.normalizePhase(input.streamPhase),
+      activity: Activity.normalize(input.activity, sanitize)
+    };
+    if (!event.title) return;
+    const key = event.kind === 'stream' ? 'stream:' + event.streamKey : event.activity?.id;
+    const previous = key && agent.events.find(old => (old.kind === 'stream' ? 'stream:' + old.streamKey : old.activity?.id) === key);
+    if (previous) {
+      if (previous.status === 'completed' && event.status === 'running' && input.appendText) return;
+      const fullText = input.appendText ? previous.title + event.title : event.title;
+      if (fullText.length > 24000) agent.clipped = true;
+      const activity = previous.activity && event.activity ? { ...previous.activity, ...event.activity,
+        command: event.activity.command || previous.activity.command,
+        output: event.activity.output || previous.activity.output,
+        paths: event.activity.paths?.length ? event.activity.paths : previous.activity.paths,
+        files: event.activity.files?.length ? event.activity.files : previous.activity.files } : event.activity || previous.activity;
+      Object.assign(previous, event, { title: fullText.slice(0, 24000), activity });
+    } else agent.events.push(event);
+    trim(agent);
+  }
+  function addAnswer(agent, answer, timestamp, sanitize) {
+    if (!answer) return;
+    const last = agent.events.filter(event => event.kind === 'stream' && event.streamRole === 'assistant').at(-1);
+    const safe = clean(answer, sanitize);
+    if (last?.title.trim() === safe.trim()) { last.status = 'completed'; return; }
+    append(agent, { kind: 'stream', streamRole: 'assistant', streamPhase: 'final_answer',
+      streamKey: last?.streamPhase === 'final_answer' ? last.streamKey : 'answer:' + agent.key,
+      title: safe, status: 'completed', timestamp }, sanitize);
+  }
+  function ingest(run, raw, options = {}) {
+    const type = string(raw?.type), detail = raw?.detail || {};
+    if (type === 'codex.subagent.drained') return true;
+    if (!['codex.subagent.queued', 'codex.subagent.started', 'codex.subagent.completed',
+      'codex.subagent.failed', 'codex.subagent.rejected', 'codex.subagent.event', 'codex.subagent.observed'].includes(type)) return false;
+    const source = detail.source === 'codex' ? 'codex' : 'broker';
+    const id = source === 'broker' ? string(detail.jobId || detail.id) : string(detail.threadId);
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,159}$/.test(id)) return true;
+    const sanitize = options.sanitize || string, key = source + ':' + id;
+    const agents = run.subagents || (run.subagents = []);
+    let agent = agents.find(item => item.key === key);
+    if (!agent) {
+      if (agents.length >= MAX_AGENTS) return true;
+      agent = { v: 1, source, key, jobId: source === 'broker' ? id : '', threadId: source === 'codex' ? id : '',
+        title: id, task: '', status: 'pending', events: [], nativeEventSeq: 0, lastSequence: 0 };
+      agents.push(agent);
+    }
+    const seq = Number(options.nativeEventSeq) || 0;
+    if (seq > 0 && seq <= (agent.nativeEventSeq || 0)) return true;
+    const sequence = Number(detail.sequence) || 0;
+    if (sequence > 0 && sequence <= (agent.lastSequence || 0)) return true;
+    agent.nativeEventSeq = Math.max(agent.nativeEventSeq || 0, seq);
+    agent.lastSequence = Math.max(agent.lastSequence || 0, sequence);
+    const timestamp = string(raw.timestamp) || new Date().toISOString(), at = Date.parse(string(raw.timestamp));
+    const wasTerminal = TERMINAL.has(agent.status), previousEnd = terminalTime(agent, run);
+    if (Number.isFinite(at) && at < Date.parse(agent.startedAt || '')) return true;
+    agent.updatedAt = timestamp;
+    for (const field of ['title', 'task', 'threadId', 'parentThreadId', 'model', 'reasoningEffort']) {
+      const value = detail[field] || (field === 'title' ? raw.title : '');
+      if (typeof value === 'string' && value) agent[field] = clean(value, sanitize, field === 'task' ? 4096 : 160);
+    }
+    agent.clipped ||= detail.historyClipped === true;
+    agent.historyUnavailable ||= detail.historyUnavailable === true;
+    let next = type.endsWith('.queued') ? 'pending' : type.endsWith('.started') ? 'running'
+      : type.endsWith('.completed') ? 'completed' : type.endsWith('.rejected') ? 'failed'
+        : type.endsWith('.failed') ? (detail.status === 'cancelled' ? 'cancelled' : 'failed') : detail.status;
+    const inner = type === 'codex.subagent.event' ? detail.event : null;
+    const method = inner?.detail?.method, params = inner?.detail?.params || {};
+    if (method === 'turn/started') next = 'running';
+    if (method === 'turn/completed' && source === 'codex') next = params.turn?.status === 'interrupted' ? 'cancelled' : params.turn?.status;
+    const reopening = wasTerminal && method === 'turn/started';
+    if (STATES.has(next) && (!wasTerminal || TERMINAL.has(next) || reopening)) agent.status = next;
+    if (reopening) { agent.startedAt = timestamp; agent.finishedAt = ''; }
+    if (agent.status === 'running' && !agent.startedAt) agent.startedAt = timestamp;
+    if (TERMINAL.has(agent.status) || run.status !== 'running') {
+      // Late snapshots describe the same stopped interval; only a new turn resets it.
+      const end = wasTerminal || run.status !== 'running' || !Number.isFinite(at) ? previousEnd : at;
+      if (Number.isFinite(end)) agent.finishedAt = new Date(end).toISOString();
+    }
+    if (inner) {
+      const boundThread = inner.detail?.threadId || params.threadId || params.thread?.id;
+      if (boundThread) agent.threadId = clean(boundThread, sanitize, 160);
+      if (params.thread?.model) agent.model = clean(params.thread.model, sanitize, 160);
+      const mapped = Transcript.mapAgentEventToActivity(inner, { locale: options.locale });
+      const activity = Activity.capture({ ...mapped, technicalDetail: mapped?.technicalDetail || inner }, sanitize);
+      if (mapped?.visible && mapped.kind !== 'technical' && (!mapped.streamRole || mapped.streamRole === 'assistant')) {
+        const itemId = params.item?.id || params.itemId || inner.detail?.itemId;
+        const turnId = params.turnId || inner.detail?.turnId || '';
+        append(agent, { ...mapped, timestamp, activity,
+          streamKey: mapped.kind === 'stream' ? turnId + ':' + (itemId || mapped.streamKey || 'assistant') : '' }, sanitize);
+      }
+    }
+    if (TERMINAL.has(agent.status)) {
+      for (const event of agent.events) if (event.kind === 'stream' && event.status === 'running') event.status = 'completed';
+      addAnswer(agent, detail.summary, timestamp, sanitize);
+      if (detail.reason) append(agent, { title: clean(detail.reason, sanitize, 1200), status: 'warning', timestamp,
+        activity: { kind: 'notice', id: key + ':failure', state: agent.status === 'failed' ? 'failed' : 'warning' } }, sanitize);
+    }
+    return true;
+  }
+  return { normalize, ingest, effectiveStatus, elapsedMs };
+});

package/extension/src/shared/undoOperations.js

@@ -130,6 +130,91 @@
     };
   }
 
+  // File creation has its own inverse even when text edits use Reviewing.
+  // Store post-images, never infer an empty pre-image for a missing file.
+  function buildCreatedFileUndoCheckpoint(project, appliedOperations, previous = {}) {
+    const originalPaths = new Set((project?.files || []).map(file => file?.path));
+    const priorFiles = filesListToMap(previous.undoBaseFiles);
+    const created = new Map();
+    for (const operation of previous.undoOperations || []) {
+      const proof = operation?.undoCreatedFile;
+      if (operation?.type !== 'delete' || proof?.v !== 1) continue;
+      if (proof.kind === 'text' && priorFiles.has(operation.path)) {
+        created.set(operation.path, { kind: 'text', content: priorFiles.get(operation.path) });
+      } else if (proof.kind === 'binary' && /^[a-f0-9]{64}$/i.test(proof.sha256 || '')) {
+        created.set(operation.path, { kind: 'binary', sha256: proof.sha256.toLowerCase() });
+      }
+    }
+    for (const operation of appliedOperations || []) {
+      if (!operation?.path) continue;
+      const path = operation.path;
+      if (operation.type === 'create' || operation.type === 'binary-create') {
+        if (originalPaths.has(path) && !created.has(path)) continue;
+        if (operation.type === 'create' && typeof operation.content === 'string') {
+          created.set(path, { kind: 'text', content: typeof operation.verifiedContent === 'string'
+            ? operation.verifiedContent : operation.content });
+        } else {
+          const hash = operation.sha256 || operation.assetRef?.sha256;
+          if (operation.previousExists !== true && /^[a-f0-9]{64}$/i.test(hash || '')) {
+            created.set(path, { kind: 'binary', sha256: hash.toLowerCase() });
+          }
+        }
+      } else if (operation.type === 'edit' && created.get(path)?.kind === 'text') {
+        const files = new Map([[path, created.get(path).content]]);
+        applyOperationToFiles(files, operation);
+        created.set(path, { kind: 'text', content: files.get(path) });
+      } else if (['delete', 'rename', 'move', 'overwrite-binary'].includes(operation.type)) {
+        // Existing rename/overwrite recovery retains ownership of these cases.
+        created.delete(path);
+        if (operation.to) created.delete(operation.to);
+      }
+    }
+    const undoBaseFiles = [], undoOperations = [];
+    for (const [path, proof] of Array.from(created).reverse()) {
+      const undoCreatedFile = proof.kind === 'binary'
+        ? { v: 1, kind: 'binary', sha256: proof.sha256 } : { v: 1, kind: 'text' };
+      undoOperations.push({ ...normalizeUndoOperation({ type: 'delete', path, reason: 'Undo create' }), undoCreatedFile });
+      if (proof.kind === 'text') undoBaseFiles.push({ path, content: proof.content });
+    }
+    return { undoOperations, undoBaseFiles };
+  }
+
+  // Consume only independently verified rollback receipts. Forward writes
+  // remain audit evidence; recovery arrays describe only unfinished work.
+  function advanceUndoCheckpoint(run = {}, result = {}, verifyText = () => false) {
+    const operations = Array.isArray(run?.undoOperations) ? run.undoOperations : [];
+    if (!operations.some(operation => operation?.undoCreatedFile?.v === 1)) return run;
+    const applied = Array.isArray(result.applied) ? result.applied : [];
+    const skipped = Array.isArray(result.skipped) ? result.skipped : [];
+    const failed = path => skipped.some(entry => {
+      const target = entry?.operation?.path || entry?.trackedChange?.path || entry?.result?.failure?.file;
+      return !target || target === path;
+    });
+    if (result.failure || result.error) return run;
+    const textPaths = new Set((run.undoExpectedFiles || [])
+      .filter(file => file?.path && typeof file.content === 'string' && !failed(file.path)
+        && typeof verifyText === 'function' && verifyText(file) === true)
+      .map(file => file.path));
+    const deletedPaths = new Set(operations.filter(operation => operation?.type === 'delete'
+      && operation.undoCreatedFile?.v === 1 && !failed(operation.path)
+      && applied.some(entry => entry?.operation?.type === 'delete' && entry.operation.path === operation.path
+        && JSON.stringify(entry.operation.undoCreatedFile) === JSON.stringify(operation.undoCreatedFile)
+        && entry.result?.ok === true && entry.result.verified === true
+        && entry.result.verification === 'overleaf-zip')).map(operation => operation.path));
+    if (!textPaths.size && !deletedPaths.size) return run;
+    const pending = operations.filter(operation => !(operation?.type === 'edit' && textPaths.has(operation.path))
+      && !(operation?.type === 'delete' && operation.undoCreatedFile?.v === 1 && deletedPaths.has(operation.path)));
+    const needed = new Set(pending.flatMap(operation => [operation?.path, operation?.to]).filter(Boolean));
+    return { ...run,
+      undoOperations: pending,
+      undoBaseFiles: (run.undoBaseFiles || []).filter(file => needed.has(file?.path)
+        || (!textPaths.has(file?.path) && !deletedPaths.has(file?.path))),
+      undoExpectedFiles: (run.undoExpectedFiles || []).filter(file => !textPaths.has(file?.path)),
+      undoTrackedChanges: (run.undoTrackedChanges || []).filter(ref => !textPaths.has(ref?.path)),
+      trackedChangeCaptures: (run.trackedChangeCaptures || []).filter(capture => !textPaths.has(capture?.path))
+    };
+  }
+
   function buildSnapshotRestoreUndo(run = {}) {
     const undoOperations = Array.isArray(run.undoOperations) ? run.undoOperations : [];
     const originalByPath = buildOriginalFilesForSnapshotUndo(run, undoOperations);
@@ -370,6 +455,8 @@
 
   return {
     buildUndoCheckpoint,
+    buildCreatedFileUndoCheckpoint,
+    advanceUndoCheckpoint,
     buildExpectedFilesAfterOperations,
     buildUndoOperations,
     buildSnapshotRestoreUndo

package/extension/src/shared/updateConsent.js

@@ -13,6 +13,7 @@
     'idle',
     'checking',
     'update_available',
+    'manual_install_required',
     'downloading',
     'staged',
     'waiting_for_idle',
@@ -41,6 +42,7 @@
     idle: { value: 0, determinate: true, phase: 'idle' },
     checking: { value: 0, determinate: false, phase: 'checking' },
     update_available: { value: 0, determinate: true, phase: 'available' },
+    manual_install_required: { value: 0, determinate: true, phase: 'manual' },
     downloading: { value: 35, determinate: false, phase: 'downloading' },
     staged: { value: 65, determinate: true, phase: 'staged' },
     waiting_for_idle: { value: 65, determinate: true, phase: 'waiting' },
@@ -66,6 +68,9 @@
       blocker: blockers[0] || '',
       blockers,
       transactionId: safeId(value.transactionId),
+      operationId: safeId(value.operationId),
+      cancelRequested: value.cancelRequested === true,
+      recoveryPending: value.recoveryPending === true,
       initiatedBy: ['automatic', 'manual'].includes(value.initiatedBy) ? value.initiatedBy : '',
       lastCheckedAt: finiteNumber(value.lastCheckedAt),
       stagedAt: finiteNumber(value.stagedAt),
@@ -74,10 +79,22 @@
       heartbeatAt: finiteNumber(value.heartbeatAt),
       postponeUntil: finiteNumber(value.postponeUntil),
       code: safeToken(value.code),
-      message: String(value.message || '').replace(/\s+/g, ' ').trim().slice(0, 300)
+      message: String(value.message || '').replace(/\s+/g, ' ').trim().slice(0, 300),
+      manualReason: normalizeManualReason(value.manualReason)
     };
   }
 
+  // Signed per-locale reason a release needs a one-time reinstall.
+  function normalizeManualReason(value) {
+    if (!value || typeof value !== 'object') return {};
+    const out = {};
+    for (const locale of ['en', 'zh']) {
+      const text = String(value[locale] || '').replace(/\s+/g, ' ').trim().slice(0, 400);
+      if (text) out[locale] = text;
+    }
+    return out;
+  }
+
   function normalizeConsentState(value = {}) {
     return {
       schemaVersion: 1,
@@ -106,6 +123,13 @@
       consent.snoozedUntil > now;
     const execution = EXECUTION_STATES.has(state.state);
     const available = state.state === 'update_available' && newer;
+    // A newer release that only a reinstall can apply. It is shown even after
+    // an automatic check, because no Update now button can ever resolve it.
+    // Compare with the running version: after the reinstall the stored state
+    // still names the old one, and the notice must clear by itself.
+    const runningVersion = safeVersion(options.currentVersion) || state.currentVersion;
+    const manualInstall = state.state === 'manual_install_required'
+      && compareStableVersions(state.latestVersion, runningVersion) > 0;
     const progress = getProgressModel(state);
     const quietFailure = state.state === 'failed' &&
       state.initiatedBy !== 'manual' &&
@@ -124,16 +148,21 @@
       },
       progress,
       available,
+      manualInstall,
       snoozed,
       execution,
-      showPanel: (available && !snoozed) || execution || state.state === 'rolled_back' ||
-        visibleFailure,
-      badge: getBadge(state, { available, snoozed }),
+      showPanel: state.cancelRequested || state.recoveryPending
+        || (state.state === 'checking' && state.initiatedBy === 'manual')
+        || ((available || manualInstall) && !snoozed) || execution || state.state === 'rolled_back' || visibleFailure,
+      badge: getBadge(state, { available: available || manualInstall, snoozed }),
       actions: {
-        check: ['idle', 'committed', 'rolled_back', 'failed'].includes(state.state),
-        install: available,
-        later: available || ['staged', 'waiting_for_idle'].includes(state.state),
-        retry: ['failed', 'rolled_back'].includes(state.state)
+        check: !state.cancelRequested && !state.recoveryPending && ['idle', 'committed', 'rolled_back', 'failed', 'manual_install_required'].includes(state.state),
+        copyInstall: manualInstall,
+        install: available && !state.cancelRequested && !state.recoveryPending,
+        later: !state.recoveryPending && (available || manualInstall || ['staged', 'waiting_for_idle'].includes(state.state)),
+        cancel: !state.recoveryPending && (state.cancelRequested || ['checking', 'downloading', 'staged', 'waiting_for_idle'].includes(state.state)),
+        recover: state.recoveryPending,
+        retry: !state.cancelRequested && !state.recoveryPending && ['failed', 'rolled_back'].includes(state.state)
       }
     };
   }