codex-overleaf-link 2.4.1 → 2.5.1

package/extension/styles/popup.css

@@ -0,0 +1,110 @@
+:root {
+  color-scheme: dark;
+  --popup-bg: light-dark(#ffffff, #1b201d);
+  --popup-text: light-dark(#28312b, #e5eae6);
+  --popup-muted: light-dark(#717b74, #a3aea6);
+  --popup-border: light-dark(#e8ece9, #333c36);
+  --popup-surface: light-dark(#f6f8f6, #242c27);
+  --popup-green: light-dark(#35734a, #9ccdab);
+  --popup-on-green: light-dark(#ffffff, #182b1f);
+  --popup-danger: light-dark(#aa443d, #df928c);
+  --popup-warn: light-dark(#99702a, #d6b671);
+}
+:root[data-popup-theme="light"] { color-scheme: light; }
+:root[data-popup-theme="auto"] { color-scheme: light dark; }
+/* Give Chrome an intrinsic popup width; viewport-relative caps can shrink it
+   back to the initial narrow viewport during popup sizing. */
+html.popup-minimal-root {
+  box-sizing: border-box;
+  width: 340px;
+  min-width: 340px;
+  margin: 0;
+  overflow-x: hidden;
+  overflow-y: auto;
+  background: var(--popup-bg);
+}
+.popup-minimal * { box-sizing: border-box; }
+body.popup-minimal {
+  width: 340px;
+  min-width: 340px;
+  max-width: none;
+  min-height: 0;
+  margin: 0;
+  padding: 0;
+  color: var(--popup-text);
+  background: var(--popup-bg);
+  font: 13px/1.5 "Avenir Next", "Segoe UI", sans-serif;
+  animation: none;
+}
+.popup-minimal #popup-shell { display: block; width: 100%; min-width: 0; }
+.popup-minimal .popup-header { display: flex; align-items: center; gap: 12px; padding: 17px 18px 16px; }
+.popup-minimal .popup-icon { display: block; width: 32px; height: 32px; object-fit: contain; flex: 0 0 auto; }
+.popup-minimal .popup-brand { flex: 1; min-width: 0; }
+.popup-minimal .popup-brand h1 { margin: 0; font-size: 14px; font-weight: 500; letter-spacing: -.02em; line-height: 1.45; white-space: nowrap; overflow-wrap: normal; }
+.popup-minimal .connection-toggle {
+  appearance: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  width: auto;
+  min-height: 24px;
+  margin: 1px 0 -2px -4px;
+  padding: 2px 4px;
+  border: 1px solid transparent;
+  border-radius: 5px;
+  box-shadow: none;
+  background: transparent;
+  color: var(--popup-muted);
+  font: inherit;
+  font-size: 11px;
+  font-weight: 400;
+  line-height: 1.45;
+  white-space: nowrap;
+  cursor: pointer;
+}
+.popup-minimal .connection-toggle:hover { border-color: var(--popup-border); background: var(--popup-surface); color: var(--popup-text); transform: none; }
+.popup-minimal .connection-chevron { width: 5px; height: 5px; flex: 0 0 auto; margin: -2px 2px 0; border: solid currentColor; border-width: 0 1px 1px 0; transform: rotate(45deg); }
+.popup-minimal .connection-toggle[aria-expanded="true"] .connection-chevron { margin-top: 2px; transform: rotate(225deg); }
+.popup-minimal .status-icon { display: block; width: 5px; height: 5px; min-width: 5px; min-height: 5px; flex: 0 0 auto; border-radius: 50%; background: var(--popup-muted); font-size: 0; box-shadow: none; }
+.popup-minimal .status-icon.compatible { background: var(--popup-green); }
+.popup-minimal .status-icon.update-available { background: var(--popup-warn); }
+.popup-minimal .status-icon.incompatible { background: var(--popup-danger); }
+.popup-minimal .connection-details { padding: 12px 18px; border-top: 1px solid var(--popup-border); background: var(--popup-surface); }
+.popup-minimal #version-pair { display: grid; gap: 8px; margin: 0; font-size: 11px; line-height: 1.45; }
+.popup-minimal #version-pair > div { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+.popup-minimal #version-pair dt { color: var(--popup-muted); }
+.popup-minimal #version-pair dd { margin: 0; color: var(--popup-text); font-variant-numeric: tabular-nums; white-space: nowrap; }
+.popup-minimal .launcher-setting { display: grid; grid-template-columns: minmax(0, 1fr) 31px; align-items: center; gap: 16px; padding: 15px 18px 17px; border-top: 1px solid var(--popup-border); cursor: pointer; }
+.popup-minimal .launcher-copy { min-width: 0; }
+.popup-minimal .launcher-copy strong { display: block; font-size: 12px; font-weight: 500; line-height: 1.5; }
+.popup-minimal .launcher-copy small { display: block; margin-top: 3px; color: var(--popup-muted); font-size: 11px; line-height: 1.5; }
+.popup-minimal .launcher-toggle {
+  appearance: none;
+  -webkit-appearance: none;
+  position: relative;
+  width: 31px;
+  height: 19px;
+  margin: 0;
+  padding: 0;
+  flex: 0 0 auto;
+  border: 1px solid var(--popup-border);
+  border-radius: 20px;
+  background: var(--popup-surface);
+  cursor: pointer;
+}
+.popup-minimal .launcher-toggle::after { content: ""; position: absolute; top: 2px; left: 2px; width: 13px; height: 13px; border-radius: 50%; background: var(--popup-muted); transition: transform 130ms ease; }
+.popup-minimal .launcher-toggle:checked { border-color: var(--popup-green); background: var(--popup-green); }
+.popup-minimal .launcher-toggle:checked::after { background: var(--popup-on-green); transform: translateX(12px); }
+.popup-minimal .launcher-toggle:disabled { cursor: default; opacity: .5; }
+.popup-minimal .popup-note { margin: 0; padding: 11px 18px; border-top: 1px solid var(--popup-border); color: var(--popup-muted); font-size: 11px; line-height: 1.6; overflow-wrap: anywhere; }
+.popup-minimal .popup-note[role="alert"] { color: var(--popup-danger); }
+.popup-minimal .install { margin: 0; padding: 14px 18px 16px; border: 0; border-top: 1px solid var(--popup-border); border-radius: 0; background: var(--popup-surface); }
+.popup-minimal .install > strong { font-size: 12px; font-weight: 500; }
+.popup-minimal .install p { margin: 6px 0 0; color: var(--popup-muted); font-size: 11px; line-height: 1.6; }
+.popup-minimal .install code { display: block; margin: 10px 0; padding: 9px; max-height: 120px; overflow: auto; border: 1px solid var(--popup-border); border-radius: 6px; color: var(--popup-text); background: var(--popup-bg); white-space: pre-wrap; overflow-wrap: anywhere; font: 11px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+.popup-minimal .copy-command { appearance: none; width: auto; min-height: 29px; margin: 0; padding: 5px 8px; border: 1px solid var(--popup-border); border-radius: 6px; background: var(--popup-bg); color: var(--popup-text); font: inherit; font-size: 11px; font-weight: 500; cursor: pointer; }
+.popup-minimal .copy-command:hover { background: var(--popup-surface); border-color: var(--popup-muted); transform: none; }
+.popup-minimal .copy-command:disabled { opacity: .55; cursor: default; }
+.popup-minimal button:focus-visible, .popup-minimal input:focus-visible { outline: 2px solid var(--popup-green); outline-offset: 3px; }
+.popup-minimal [hidden] { display: none !important; }
+@media (prefers-reduced-motion: reduce) { .popup-minimal .launcher-toggle::after { transition: none; } }

package/native-host/src/anthropicBridgeRequest.js

@@ -34,7 +34,7 @@ function buildAnthropicRequest({ requestBody = {}, launch = {}, historyMessages
     model,
     max_tokens: maxTokens,
     messages,
-    stream: requestBody.stream !== false
+    stream: requestBody.stream !== false && launch.upstreamResponseMode !== 'buffered'
   };
   if (systemParts.length) {
     body.system = launch.anthropicPromptCaching
@@ -175,7 +175,8 @@ function convertToolChoice(value, context, launch) {
 }
 
 function applyAnthropicThinking(body, requestBody, launch, maxTokens) {
-  const effort = text(requestBody?.reasoning?.effort || launch.reasoningEffort).toLowerCase();
+  // The captured panel choice wins over a model-generated request default.
+  const effort = text(launch.reasoningEffort || requestBody?.reasoning?.effort).toLowerCase();
   if (!effort || ['none', 'off', 'disabled'].includes(effort) || launch.anthropicThinkingMode === 'none') {
     return false;
   }
@@ -217,8 +218,10 @@ function rectifyAnthropicRequestForRetry(body, errorText) {
     return changed;
   }
   if (/budget_tokens|thinking budget|must be less than max_tokens|at least 1024/i.test(message)) {
+    // Keep this existing compatibility retry only when its budget fits the
+    // caller's maximum. Otherwise expose the original upstream rejection.
+    if (!Number.isFinite(Number(body.max_tokens)) || Number(body.max_tokens) < 64000) return false;
     body.thinking = { type: 'enabled', budget_tokens: 32000 };
-    body.max_tokens = Math.max(Number(body.max_tokens) || 0, 64000);
     delete body.output_config;
     return true;
   }

package/native-host/src/anthropicBridgeResponse.js

@@ -216,6 +216,7 @@ function appendBlockDelta(state, res, index, delta) {
 function closeBlock(state, res, index) {
   const entry = state.blocks.get(index);
   if (!entry || entry.closed) return;
+  const args = entry.type === 'tool_use' ? canonicalArguments(entry.arguments) : '';
   entry.closed = true;
   if (entry.type === 'text') {
     const part = { type: 'output_text', text: entry.text, annotations: [] };
@@ -236,7 +237,6 @@ function closeBlock(state, res, index) {
     state.assistantBlocks[index] = block;
   } else {
     entry.item.status = 'completed';
-    const args = canonicalArguments(entry.arguments);
     if (entry.kind === 'custom') {
       entry.item.input = unwrapCustomInput(args);
       emit(state, res, 'response.custom_tool_call_input.done', { item_id: entry.item.id, output_index: entry.outputIndex, input: entry.item.input });
@@ -401,7 +401,11 @@ function reserve(state, item) {
 }
 
 function canonicalArguments(value) {
-  try { return JSON.stringify(JSON.parse(value || '{}')); } catch (_error) { return '{}'; }
+  try {
+    return JSON.stringify(JSON.parse(value || '{}'));
+  } catch (_error) {
+    throw responseError('The provider returned incomplete or invalid JSON tool arguments.');
+  }
 }
 
 function unwrapCustomInput(value) {

package/native-host/src/anthropicMessagesBridge.js

@@ -13,6 +13,7 @@ const {
 const { writeConvertedResponseAsSse } = require('./chatBridgeResponse');
 const { classifyResponsesRoute } = require('./providerBridgeRoutes');
 const { providerError } = require('./providerProfile');
+const { fetchProvider, readProviderText, readProviderJson } = require('./providerHttp');
 const { sanitizeProviderMessage } = require('./providerRedaction');
 const { logDebug } = require('./debugLog');
 const {
@@ -92,9 +93,13 @@ async function handleRequest({ req, res, launch, clientToken, activeRequests, hi
   const requestBody = await readJsonBody(req);
   const previousResponseId = String(requestBody.previous_response_id || '');
   const previous = history.get(previousResponseId);
-  const fallbackAnchor = previous ? [] : continuationState.anchorMessages;
+  const fallbackAllowed = !previousResponseId || previousResponseId === continuationState.responseId;
+  const fallbackAnchor = previous || !fallbackAllowed ? [] : continuationState.anchorMessages;
+  const continuationAttempts = previous
+    ? Number(previous.continuationAttempts) || 0
+    : fallbackAllowed ? continuationState.attempts : 0;
   const continuing = Boolean(previous?.continuation || fallbackAnchor.length);
-  if (continuing && continuationState.attempts >= MAX_REASONING_CONTINUATIONS) {
+  if (continuing && continuationAttempts >= MAX_REASONING_CONTINUATIONS) {
     throw providerError(
       'provider_reasoning_continuation_exhausted',
       'The provider repeatedly interrupted the same reasoning stream. Retry the task or use a different model endpoint.'
@@ -107,12 +112,12 @@ async function handleRequest({ req, res, launch, clientToken, activeRequests, hi
   });
   logDebug('provider.anthropic.request', {
     model: translated.body.model,
-    stream: requestBody.stream !== false,
+    stream: translated.body.stream,
     maxTokens: translated.body.max_tokens,
     thinkingType: translated.body.thinking?.type || 'disabled',
     hasPreviousResponse: Boolean(previousResponseId),
     continuing,
-    continuationAttempt: continuationState.attempts
+    continuationAttempt: continuationAttempts
   });
   const controller = new AbortController();
   activeRequests.add(controller);
@@ -130,7 +135,7 @@ async function handleRequest({ req, res, launch, clientToken, activeRequests, hi
   res.on('close', onClientClose);
   lifecycle.start();
   try {
-    const upstream = await fetchWithRectification(launch, translated.body, controller.signal);
+    const upstream = await fetchWithRectification(launch, translated.body, controller.signal, lifecycle.touch);
     lifecycle.touch();
     if (!upstream.response.ok) {
       forwardUpstreamError(upstream.response, upstream.errorText, res, launch.apiKey);
@@ -152,14 +157,15 @@ async function handleRequest({ req, res, launch, clientToken, activeRequests, hi
       const messages = [...baseMessages, ...assistantMessages];
       if (anchored) {
         continuationState.anchorMessages = messages;
-        continuationState.attempts += 1;
+        continuationState.attempts = continuationAttempts + 1;
         continuationState.responseId = converted.response.id;
       } else {
         continuationState.anchorMessages = [];
         continuationState.attempts = 0;
         continuationState.responseId = '';
       }
-      rememberHistory(history, converted.response.id, messages, { continuation: anchored });
+      rememberHistory(history, converted.response.id, messages, { continuation: anchored,
+        continuationAttempts: anchored ? continuationAttempts + 1 : 0 });
       const blocks = Array.isArray(converted.assistantBlocks) ? converted.assistantBlocks : [];
       logDebug('provider.anthropic.response', {
         responseId: converted.response.id,
@@ -185,7 +191,7 @@ async function handleRequest({ req, res, launch, clientToken, activeRequests, hi
           recoverInterrupted: lifecycle.recoverInterrupted
         });
       } else {
-        const converted = convertAnthropicResponse(await upstream.response.json(), context);
+        const converted = convertAnthropicResponse(await readProviderJson(upstream.response, lifecycle.touch), context);
         writeConvertedResponseAsSse(res, converted, context, remember);
       }
     } else if (contentType.includes('text/event-stream')) {
@@ -202,7 +208,7 @@ async function handleRequest({ req, res, launch, clientToken, activeRequests, hi
       remember(converted);
       sendJson(res, 200, converted.response);
     } else {
-      const converted = convertAnthropicResponse(await upstream.response.json(), context);
+      const converted = convertAnthropicResponse(await readProviderJson(upstream.response, lifecycle.touch), context);
       remember(converted);
       sendJson(res, 200, converted.response);
     }
@@ -224,27 +230,29 @@ async function handleRequest({ req, res, launch, clientToken, activeRequests, hi
   }
 }
 
-async function fetchWithRectification(launch, body, signal) {
+async function fetchWithRectification(launch, body, signal, onActivity) {
   let requestBody = body;
-  let response = await fetch(buildAnthropicMessagesUrl(launch.baseUrl, launch), {
+  let response = await fetchProvider(buildAnthropicMessagesUrl(launch.baseUrl, launch), {
     method: 'POST',
     headers: buildAnthropicHeaders(launch),
     body: JSON.stringify(body),
     signal
-  });
+  }, launch);
+  onActivity();
   if (response.ok) return { response, errorText: '', requestBody };
-  let errorText = (await response.text()).slice(0, MAX_ERROR_BYTES);
+  let errorText = (await readProviderText(response, onActivity)).slice(0, MAX_ERROR_BYTES);
   if (response.status === 400) {
     const retryBody = JSON.parse(JSON.stringify(body));
     if (rectifyAnthropicRequestForRetry(retryBody, errorText)) {
       requestBody = retryBody;
-      response = await fetch(buildAnthropicMessagesUrl(launch.baseUrl, launch), {
+      response = await fetchProvider(buildAnthropicMessagesUrl(launch.baseUrl, launch), {
         method: 'POST',
         headers: buildAnthropicHeaders(launch),
         body: JSON.stringify(retryBody),
         signal
-      });
-      errorText = response.ok ? '' : (await response.text()).slice(0, MAX_ERROR_BYTES);
+      }, launch);
+      onActivity();
+      errorText = response.ok ? '' : (await readProviderText(response, onActivity)).slice(0, MAX_ERROR_BYTES);
     }
   }
   return { response, errorText, requestBody };

package/native-host/src/bootstrapMigration.js

@@ -0,0 +1,296 @@
+'use strict';
+
+// This module owns only files and their recovery record. The caller must verify
+// the signed release, bind its authorization and hold the update mutation lock.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { validateBootstrapMigrationDescriptor } = require('./bootstrapMigrationContract');
+
+const RECORD_SCHEMA = 1;
+const TRANSACTION_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+
+function prepareBootstrapMigration(options, hooks = {}) {
+  const descriptor = clone(options.descriptor);
+  validateBootstrapMigrationDescriptor(descriptor, { targetVersion: options.targetVersion });
+  if (!descriptor.sourceVersions.includes(options.sourceVersion)) fail('source_version_mismatch');
+  const transactionId = validTransaction(options.transactionId);
+  const backupRoot = absoluteRoot(options.backupRoot);
+  const extensionRoot = absoluteRoot(options.extensionRoot);
+  const payloadRoot = absoluteRoot(options.payloadRoot);
+  if (overlaps(backupRoot, extensionRoot) || overlaps(backupRoot, payloadRoot)
+      || overlaps(extensionRoot, payloadRoot)) fail('roots_overlap');
+  ensureDirectory(backupRoot);
+  const recordRoot = path.join(backupRoot, transactionId);
+  ensureChildDirectory(backupRoot, transactionId);
+  const journalPath = path.join(recordRoot, 'state.json');
+  const identity = { transactionId, sourceVersion: options.sourceVersion,
+    targetVersion: options.targetVersion, extensionRoot, payloadRoot,
+    descriptorSha256: hash(JSON.stringify(descriptor)) };
+  if (readFileInfo(journalPath)) {
+    const saved = loadBootstrapMigration({ backupRoot, transactionId });
+    if (Object.entries(identity).some(([key, value]) => saved[key] !== value)) fail('transaction_mismatch');
+    return saved;
+  }
+
+  // Verify the entire source and target before writing any recovery material.
+  const files = descriptor.files.map(file => {
+    const source = readRootFile(extensionRoot, file.path);
+    if (source?.sha256 !== file.sourceSha256 && !(source === null && file.sourceSha256 === null)) fail('source_mismatch', file.path);
+    const target = readRootFile(payloadRoot, file.path);
+    if (!target || target.sha256 !== file.targetSha256) fail('payload_mismatch', file.path);
+    return { ...file, sourceMode: source?.mode ?? null, targetMode: source?.mode ?? target.mode };
+  });
+  ensureChildDirectory(recordRoot, 'files');
+  for (const file of files) {
+    if (file.sourceSha256 === null) continue;
+    const source = readRootFile(extensionRoot, file.path);
+    if (!source || source.sha256 !== file.sourceSha256 || source.mode !== file.sourceMode) fail('source_mismatch', file.path);
+    const target = childFile(recordRoot, 'files/' + file.path, true);
+    atomicWrite(target, source.bytes, 0o600, hooks, 'backup');
+  }
+  const record = { schemaVersion: RECORD_SCHEMA, ...identity, descriptor,
+    migrationId: descriptor.id, backupRoot, recordRoot, journalPath, files,
+    sourceDigest: digest(files, 'sourceSha256'), targetDigest: digest(files, 'targetSha256'),
+    state: 'prepared', pending: null, completed: [], createdAt: new Date().toISOString() };
+  writeRecord(record, hooks);
+  return publicPlan(record);
+}
+
+function loadBootstrapMigration({ backupRoot, transactionId }) {
+  backupRoot = absoluteRoot(backupRoot);
+  transactionId = validTransaction(transactionId);
+  const recordRoot = childFile(backupRoot, transactionId);
+  const journalPath = childFile(recordRoot, 'state.json');
+  const info = readFileInfo(journalPath);
+  if (!info) fail('record_missing');
+  let record;
+  try { record = JSON.parse(info.bytes.toString('utf8')); } catch (_) { fail('record_invalid'); }
+  if (!record || record.schemaVersion !== RECORD_SCHEMA || record.transactionId !== transactionId
+      || record.backupRoot !== backupRoot || record.recordRoot !== recordRoot || record.journalPath !== journalPath) fail('record_invalid');
+  validateBootstrapMigrationDescriptor(record.descriptor, { targetVersion: record.targetVersion });
+  if (!record.descriptor.sourceVersions.includes(record.sourceVersion)
+      || record.migrationId !== record.descriptor.id
+      || record.descriptorSha256 !== hash(JSON.stringify(record.descriptor))
+      || !Array.isArray(record.files) || record.files.length !== record.descriptor.files.length
+      || !['prepared', 'applying', 'applied', 'restoring', 'restored'].includes(record.state)
+      || !Array.isArray(record.completed)) fail('record_invalid');
+  const extensionRoot = absoluteRoot(record.extensionRoot);
+  const payloadRoot = absoluteRoot(record.payloadRoot);
+  if (overlaps(backupRoot, extensionRoot) || overlaps(backupRoot, payloadRoot)
+      || overlaps(extensionRoot, payloadRoot)) fail('roots_overlap');
+  for (let index = 0; index < record.files.length; index++) {
+    const file = record.files[index];
+    const expected = record.descriptor.files[index];
+    if (['path', 'sourceSha256', 'targetSha256'].some(key => file[key] !== expected[key])
+        || !validMode(file.targetMode) || (file.sourceSha256 === null ? file.sourceMode !== null : !validMode(file.sourceMode))) fail('record_invalid');
+  }
+  if (record.sourceDigest !== digest(record.files, 'sourceSha256')
+      || record.targetDigest !== digest(record.files, 'targetSha256')) fail('record_invalid');
+  return publicPlan(record);
+}
+
+function applyBootstrapMigration(plan, hooks = {}) {
+  const record = reloadPlan(plan);
+  if (record.state === 'restoring' || record.state === 'restored') fail('already_restoring');
+  verifyKnownFiles(record);
+  verifyBackups(record);
+  for (const file of record.files) {
+    const target = readRootFile(record.payloadRoot, file.path);
+    if (!target || target.sha256 !== file.targetSha256) fail('payload_mismatch', file.path);
+  }
+  if (record.state === 'applied') return verifyBootstrapMigration(record, { expected: 'target' });
+  record.state = 'applying';
+  writeRecord(record, hooks);
+  for (const file of writeOrder(record.files)) {
+    record.pending = file.path;
+    writeRecord(record, hooks);
+    const current = readRootFile(record.extensionRoot, file.path);
+    if (!matchesKnown(current, file)) fail('source_mismatch', file.path);
+    if (current?.sha256 !== file.targetSha256 || current.mode !== file.targetMode) {
+      const target = readRootFile(record.payloadRoot, file.path);
+      if (!target || target.sha256 !== file.targetSha256) fail('payload_mismatch', file.path);
+      atomicWrite(childFile(record.extensionRoot, file.path, true), target.bytes, file.targetMode, hooks, 'apply');
+    }
+    verifyFile(record.extensionRoot, file, 'target');
+    if (!record.completed.includes(file.path)) record.completed.push(file.path);
+    record.pending = null;
+    writeRecord(record, hooks);
+  }
+  record.state = 'applied';
+  writeRecord(record, hooks);
+  return verifyBootstrapMigration(record, { expected: 'target' });
+}
+
+function restoreBootstrapMigration(plan, hooks = {}) {
+  const record = reloadPlan(plan);
+  verifyKnownFiles(record);
+  verifyBackups(record);
+  if (record.state === 'restored') return verifyBootstrapMigration(record, { expected: 'source' });
+  record.state = 'restoring';
+  writeRecord(record, hooks);
+  // Reverse dependencies: restore HTML/entry users before removing new files.
+  for (const file of writeOrder(record.files).reverse()) {
+    record.pending = file.path;
+    writeRecord(record, hooks);
+    const current = readRootFile(record.extensionRoot, file.path);
+    if (!matchesKnown(current, file)) fail('source_mismatch', file.path);
+    const target = childFile(record.extensionRoot, file.path);
+    if (file.sourceSha256 === null) {
+      if (current) {
+        fs.unlinkSync(target);
+        syncDirectory(path.dirname(target));
+        step(hooks, 'restore:removed', target);
+      }
+    } else if (current?.sha256 !== file.sourceSha256 || current.mode !== file.sourceMode) {
+      const backup = readRootFile(record.recordRoot, 'files/' + file.path);
+      if (!backup || backup.sha256 !== file.sourceSha256) fail('backup_mismatch', file.path);
+      atomicWrite(target, backup.bytes, file.sourceMode, hooks, 'restore');
+    }
+    verifyFile(record.extensionRoot, file, 'source');
+    record.completed = record.completed.filter(value => value !== file.path);
+    record.pending = null;
+    writeRecord(record, hooks);
+  }
+  record.state = 'restored';
+  writeRecord(record, hooks);
+  return verifyBootstrapMigration(record, { expected: 'source' });
+}
+
+function verifyBootstrapMigration(plan, { expected = 'target' } = {}) {
+  if (!['source', 'target'].includes(expected)) fail('expectation_invalid');
+  const record = reloadPlan(plan);
+  for (const file of record.files) verifyFile(record.extensionRoot, file, expected);
+  return { transactionId: record.transactionId, migrationId: record.migrationId,
+    state: record.state, digest: expected === 'target' ? record.targetDigest : record.sourceDigest,
+    targetRevision: record.descriptor.targetRevision, expected };
+}
+
+function readBootstrapMigrationState(plan) { return reloadPlan(plan); }
+
+function reloadPlan(plan) {
+  if (!plan || typeof plan !== 'object') fail('record_invalid');
+  const saved = loadBootstrapMigration(plan);
+  for (const key of ['descriptorSha256', 'extensionRoot', 'payloadRoot', 'sourceVersion', 'targetVersion']) {
+    if (plan[key] !== saved[key]) fail('transaction_mismatch');
+  }
+  return saved;
+}
+
+function verifyKnownFiles(record) {
+  for (const file of record.files) {
+    if (!matchesKnown(readRootFile(record.extensionRoot, file.path), file)) fail('source_mismatch', file.path);
+  }
+}
+
+function matchesKnown(current, file) {
+  if (current === null) return file.sourceSha256 === null;
+  return (current.sha256 === file.sourceSha256 && current.mode === file.sourceMode)
+    || (current.sha256 === file.targetSha256 && current.mode === file.targetMode);
+}
+
+function verifyBackups(record) {
+  for (const file of record.files) {
+    if (file.sourceSha256 === null) continue;
+    const backup = readRootFile(record.recordRoot, 'files/' + file.path);
+    if (!backup || backup.sha256 !== file.sourceSha256) fail('backup_mismatch', file.path);
+  }
+}
+
+function verifyFile(root, file, expected) {
+  const current = readRootFile(root, file.path);
+  const expectedHash = file[expected + 'Sha256'];
+  if (expectedHash === null ? current !== null : !current || current.sha256 !== expectedHash
+      || current.mode !== file[expected + 'Mode']) fail(expected + '_mismatch', file.path);
+}
+
+function writeOrder(files) {
+  const rank = file => file.sourceSha256 === null ? 0 : file.path === 'bootstrap/background.js' ? 3
+    : file.path.endsWith('.html') ? 2 : 1;
+  return [...files].sort((a, b) => rank(a) - rank(b) || a.path.localeCompare(b.path));
+}
+
+function writeRecord(record, hooks) {
+  record.updatedAt = new Date().toISOString();
+  atomicWrite(record.journalPath, JSON.stringify(record, null, 2) + '\n', 0o600, hooks, 'journal');
+}
+
+function atomicWrite(target, bytes, mode, hooks, phase) {
+  try { if (!fs.lstatSync(target).isFile()) fail('path_unsafe'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const temporary = target + '.migration-' + crypto.randomBytes(8).toString('hex') + '.tmp';
+  const fd = fs.openSync(temporary, 'wx', mode);
+  try { fs.writeFileSync(fd, bytes); fs.fchmodSync(fd, mode); fs.fsyncSync(fd); }
+  finally { fs.closeSync(fd); }
+  step(hooks, phase + ':temporary', target);
+  fs.renameSync(temporary, target);
+  syncDirectory(path.dirname(target));
+  step(hooks, phase + ':replaced', target);
+}
+
+function syncDirectory(directory) {
+  let fd;
+  try { fd = fs.openSync(directory, 'r'); fs.fsyncSync(fd); }
+  catch (error) {
+    // Windows does not expose POSIX directory fsync through Node. File contents
+    // are flushed before rename on all platforms; directory durability is OS-dependent.
+    if (process.platform !== 'win32' || !['EPERM', 'EISDIR', 'EINVAL', 'EBADF', 'EACCES'].includes(error.code)) throw error;
+  } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+function childFile(root, relative, createParents = false) {
+  if (typeof relative !== 'string' || relative.includes('\\') || relative.split('/').some(part => !part || part === '.' || part === '..')
+      || path.isAbsolute(relative)) fail('path_unsafe');
+  assertDirectory(root);
+  const parts = relative.split('/');
+  let parent = root;
+  for (const part of parts.slice(0, -1)) {
+    parent = path.join(parent, part);
+    if (createParents && !fs.existsSync(parent)) { fs.mkdirSync(parent, { mode: 0o700 }); syncDirectory(path.dirname(parent)); }
+    assertDirectory(parent);
+  }
+  const target = path.join(root, ...parts);
+  try { if (fs.lstatSync(target).isSymbolicLink()) fail('path_unsafe'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  return target;
+}
+
+function readRootFile(root, relative) { return readFileInfo(childFile(root, relative)); }
+
+function readFileInfo(target) {
+  let stat;
+  try { stat = fs.lstatSync(target); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_FILE_BYTES) fail('path_unsafe', target);
+  const bytes = fs.readFileSync(target);
+  return { bytes, sha256: hash(bytes), mode: stat.mode & 0o777 };
+}
+
+function ensureDirectory(root) {
+  if (!fs.existsSync(root)) {
+    ensureDirectory(path.dirname(root));
+    fs.mkdirSync(root, { mode: 0o700 });
+    syncDirectory(path.dirname(root));
+  }
+  assertDirectory(root);
+}
+function ensureChildDirectory(root, relative) {
+  const directory = childFile(root, relative, true);
+  if (!fs.existsSync(directory)) { fs.mkdirSync(directory, { mode: 0o700 }); syncDirectory(path.dirname(directory)); }
+  assertDirectory(directory);
+  return directory;
+}
+function assertDirectory(value) { if (!fs.lstatSync(value).isDirectory() || fs.lstatSync(value).isSymbolicLink()) fail('path_unsafe'); }
+function absoluteRoot(value) { if (typeof value !== 'string' || !path.isAbsolute(value) || path.normalize(value) !== value) fail('path_unsafe'); return value; }
+function validTransaction(value) { if (typeof value !== 'string' || !TRANSACTION_ID.test(value) || value === '.' || value === '..') fail('transaction_invalid'); return value; }
+function overlaps(a, b) { return a === b || a.startsWith(b + path.sep) || b.startsWith(a + path.sep); }
+function validMode(value) { return Number.isInteger(value) && value >= 0 && value <= 0o777; }
+function digest(files, key) { return hash(JSON.stringify([...files].sort((a, b) => a.path.localeCompare(b.path)).map(file => [file.path, file[key]]))); }
+function hash(value) { return crypto.createHash('sha256').update(value).digest('hex'); }
+function clone(value) { return JSON.parse(JSON.stringify(value)); }
+function publicPlan(record) { return clone(record); }
+function step(hooks, phase, target) { if (typeof hooks.onStep === 'function') hooks.onStep({ phase, path: target }); }
+function fail(reason, file) { const error = new Error('Bootstrap migration ' + reason.replaceAll('_', ' ') + (file ? ': ' + file : '.')); error.code = 'update_bootstrap_' + reason; throw error; }
+
+module.exports = { prepareBootstrapMigration, loadBootstrapMigration, applyBootstrapMigration,
+  restoreBootstrapMigration, verifyBootstrapMigration, readBootstrapMigrationState };