codex-overleaf-link 2.5.0 → 2.5.1

package/native-host/src/managedInstallRecovery.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { updateError } = require('./updateTrust');
+const { MUTATION_LOCK_STALE_MS, removeStaleUpdateFileLock } = require('./updateManager');
+
+// A full install changes one Native version and a small fixed set of files.
+// Retain just those destinations until registration and journal settlement
+// succeed; this is in-process compensation, not crash recovery for the disk.
+function createInstallRestorePoint({ nativeRoot, version, files }) {
+  const rootWasAbsent = !fs.existsSync(nativeRoot);
+  let existed = false;
+  const backup = path.join(path.dirname(nativeRoot), '.native.rollback-' + crypto.randomUUID());
+  const target = path.join(nativeRoot, 'versions', version);
+  let targetExisted = false;
+  let snapshots = [];
+  let lock = null;
+  let restored = false;
+  try {
+    lock = acquireInstallLock(nativeRoot);
+    existed = fs.existsSync(path.join(nativeRoot, '.codex-overleaf-managed-native.json'));
+    if (!existed && (fs.readdirSync(nativeRoot).some(name => name !== 'updates')
+      || fs.readdirSync(path.join(nativeRoot, 'updates')).some(name => name !== 'mutation.lock'))) {
+      throw new Error('Refusing to replace an unmarked managed native root: ' + nativeRoot);
+    }
+    targetExisted = fs.existsSync(target);
+    snapshots = files.map(filename => {
+      try {
+        const stat = fs.statSync(filename);
+        return { filename, bytes: fs.readFileSync(filename), mode: stat.mode & 0o777 };
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+        return { filename, bytes: null };
+      }
+    });
+    if (targetExisted) fs.cpSync(target, backup, { recursive: true });
+  } catch (error) {
+    if (lock) releaseInstallLock(lock);
+    fs.rmSync(backup, { recursive: true, force: true });
+    if (rootWasAbsent) {
+      // Only remove directories still empty after our failed initialization;
+      // never remove another creator's lock, marker or runtime files.
+      try { fs.rmdirSync(path.join(nativeRoot, 'updates')); fs.rmdirSync(nativeRoot); } catch (_) { /* retained */ }
+    }
+    throw error;
+  }
+  return {
+    nativeExisted: existed,
+    restore() {
+      assertInstallLock(lock);
+      const errors = [];
+      const attempt = action => { try { action(); } catch (error) { errors.push(error); } };
+      attempt(() => {
+        fs.rmSync(target, { recursive: true, force: true });
+        if (targetExisted) fs.renameSync(backup, target);
+      });
+      for (const snapshot of snapshots) attempt(() => {
+        if (snapshot.bytes === null) fs.rmSync(snapshot.filename, { force: true });
+        else {
+          fs.mkdirSync(path.dirname(snapshot.filename), { recursive: true });
+          fs.writeFileSync(snapshot.filename, snapshot.bytes, { mode: snapshot.mode });
+          fs.chmodSync(snapshot.filename, snapshot.mode);
+        }
+      });
+      if (errors.length) throw updateError('managed_install_restore_failed',
+        'Managed installation failed and the previous installation could not be fully restored.', { cause: errors[0] });
+      restored = true;
+    },
+    finish() {
+      let removeEmptyRoot = false;
+      try {
+        fs.rmSync(backup, { recursive: true, force: true });
+        if (restored && !existed) {
+          assertInstallLock(lock);
+          // The root was created by this install. Keep its mutation lock while
+          // removing our remaining staging/directories, including after all
+          // filesystem and browser-registration compensation has completed.
+          for (const name of fs.readdirSync(nativeRoot)) {
+            if (name !== 'updates') fs.rmSync(path.join(nativeRoot, name), { recursive: true, force: true });
+          }
+          for (const name of fs.readdirSync(path.join(nativeRoot, 'updates'))) {
+            if (name !== 'mutation.lock') fs.rmSync(path.join(nativeRoot, 'updates', name), { recursive: true, force: true });
+          }
+          removeEmptyRoot = true;
+        }
+      }
+      finally { if (lock) releaseInstallLock(lock); }
+      if (removeEmptyRoot) {
+        // After release another installer may own these paths. Empty-only
+        // removal cannot delete its new lock, metadata, runtime or bridge.
+        for (const directory of [path.join(nativeRoot, 'updates'), nativeRoot]) {
+          try { fs.rmdirSync(directory); }
+          catch (error) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; }
+        }
+      }
+    },
+    release() { if (lock) releaseInstallLock(lock); }
+  };
+}
+
+function assertInstallLock(lock) {
+  let owner;
+  try { owner = JSON.parse(fs.readFileSync(lock.filename, 'utf8')); } catch (_) { /* unknown */ }
+  if (owner?.token !== lock?.token) {
+    throw updateError('managed_install_restore_failed', 'The installation no longer owns its recovery lock.');
+  }
+}
+
+function acquireInstallLock(nativeRoot) {
+  const filename = path.join(nativeRoot, 'updates', 'mutation.lock');
+  fs.mkdirSync(path.dirname(filename), { recursive: true });
+  const token = crypto.randomUUID();
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    let descriptor;
+    try {
+      descriptor = fs.openSync(filename, 'wx', 0o600);
+      fs.writeFileSync(descriptor, JSON.stringify({ token, pid: process.pid, operationId: '',
+        createdAt: Date.now(), expiresAt: Date.now() + MUTATION_LOCK_STALE_MS }));
+      fs.closeSync(descriptor);
+      return { filename, token };
+    } catch (error) {
+      if (descriptor !== undefined) { fs.closeSync(descriptor); fs.rmSync(filename, { force: true }); throw error; }
+      if (error.code !== 'EEXIST') throw error;
+      if (!removeStaleUpdateFileLock(filename)) {
+        throw updateError('update_busy', 'A managed update is in progress. Retry installation after it settles.');
+      }
+    }
+  }
+  throw updateError('update_busy', 'A managed update is in progress. Retry installation after it settles.');
+}
+
+function releaseInstallLock(lock) {
+  try {
+    if (JSON.parse(fs.readFileSync(lock.filename, 'utf8')).token === lock.token) fs.rmSync(lock.filename);
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+}
+
+module.exports = { createInstallRestorePoint };

package/native-host/src/managedRuntimeEvidence.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { parseSemver, updateError } = require('./updateTrust');
+
+function readManagedRuntimeEvidence(context, version, runtimeRoot = path.join(context.extensionRoot, 'runtime')) {
+  try {
+    if (!parseSemver(version)) throw new Error('Invalid source version');
+    const compatibility = fs.readFileSync(path.join(runtimeRoot, 'src/shared/compatibility.js'), 'utf8');
+    const declared = compatibility.match(/BUILD_TARGET_VERSION\s*=\s*['"]([^'"]+)['"]/)?.[1];
+    if (declared !== version) throw new Error('Extension source version mismatch');
+    const manifest = JSON.parse(fs.readFileSync(path.join(runtimeRoot, 'runtime-manifest.json'), 'utf8'));
+    const assets = [...(Array.isArray(manifest.js) ? manifest.js : []), ...(Array.isArray(manifest.css) ? manifest.css : [])];
+    if (!assets.length) throw new Error('Missing runtime assets');
+    for (const asset of assets) {
+      if (typeof asset !== 'string' || asset.startsWith('/') || asset.includes('\\')
+        || asset.split('/').some(part => !part || part === '.' || part === '..')
+        || !fs.statSync(path.join(runtimeRoot, asset)).isFile()) throw new Error('Invalid runtime asset');
+    }
+    const nativeRoot = path.join(context.nativeRoot, 'versions', version);
+    if (JSON.parse(fs.readFileSync(path.join(nativeRoot, 'package.json'), 'utf8')).version !== version
+      || !fs.statSync(path.join(nativeRoot, 'native-host/src/index.js')).isFile()) throw new Error('Native source unavailable');
+    return { extensionVersion: declared, nativeVersion: version,
+      extensionSha256: hashTree(runtimeRoot), nativeSha256: hashTree(nativeRoot) };
+  } catch (cause) {
+    throw updateError('update_rollback_source_unavailable',
+      'The source runtime files could not be verified. Run install-managed to restore the matched installation.', { cause });
+  }
+}
+
+function hashTree(root) {
+  const hash = crypto.createHash('sha256');
+  function visit(directory, prefix) {
+    // Native processes can start under different LANG/ICU defaults. Evidence
+    // ordering must be a fixed code-unit order, never locale collation.
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })
+      .sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+      const filename = path.join(directory, entry.name), relative = prefix + entry.name;
+      if (entry.isDirectory()) visit(filename, relative + '/');
+      else if (entry.isFile()) {
+        const bytes = fs.readFileSync(filename);
+        hash.update(JSON.stringify([relative, bytes.length])); hash.update(bytes);
+      } else throw new Error('Runtime entry is not a regular file or directory');
+    }
+  }
+  visit(root, '');
+  return hash.digest('hex');
+}
+
+function sameRuntimeEvidence(left, right) {
+  return Boolean(left && right && ['extensionVersion', 'nativeVersion', 'extensionSha256', 'nativeSha256']
+    .every(key => left[key] && left[key] === right[key]));
+}
+
+module.exports = { readManagedRuntimeEvidence, sameRuntimeEvidence };

package/native-host/src/mirrorWorkspace.js

@@ -4,6 +4,7 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const { getHomeDir } = require('./nativeHostPlatform');
+const { assertProjectPathsForPlatform } = require('./projectPathPlatform');
 
 const BASELINE_FILE = 'baseline.json';
 const MAX_BINARY_FILE_BYTES = 10 * 1024 * 1024;
@@ -37,10 +38,14 @@ async function syncOverleafToMirror({ projectId, project, rootDir }) {
   const mirror = getProjectMirror(projectId, { rootDir });
   const normalized = normalizeProjectFilesDetailed(project?.files || []);
   const files = normalized.files;
-  const skippedFiles = normalized.skippedFiles;
-  const nextPaths = new Set(files.map(file => file.path));
   const previous = readBaseline(mirror.baselinePath);
   const fullProjectSnapshot = project?.capabilities?.fullProjectSnapshot !== false;
+  const skippedFiles = resolveUnreadSnapshotFiles(project, normalized, previous, fullProjectSnapshot);
+  // Runtime platform is authoritative; request fields cannot opt out of this check.
+  assertProjectPathsForPlatform([...files, ...skippedFiles].map(file => file.path), process.platform);
+  const unreadPaths = new Set(skippedFiles.map(file => file.path));
+  const nextPaths = new Set([...files.map(file => file.path), ...unreadPaths]);
+  const completeContents = fullProjectSnapshot && !unreadPaths.size;
 
   const mirrorRoot = path.dirname(mirror.projectRoot);
   assertSafeMirrorPathBeforeCreate(mirror.workspacePath, mirrorRoot);
@@ -82,20 +87,21 @@ async function syncOverleafToMirror({ projectId, project, rootDir }) {
 
   const now = new Date().toISOString();
   const nextBaselineFiles = fullProjectSnapshot
-    ? files.map(file => buildBaselineFile(file))
+    ? [...files.map(file => buildBaselineFile(file)), ...(previous.files || []).filter(file => unreadPaths.has(file.path))]
     : mergePartialBaselineFiles(previous.files || [], files);
 
   writeBaseline(mirror.baselinePath, {
     ...previous,
     projectKey: mirror.projectKey,
-    capturedAt: fullProjectSnapshot ? now : (previous.capturedAt || ''),
-    lastFullSyncAt: fullProjectSnapshot ? now : previous.lastFullSyncAt,
-    lastPartialSyncAt: fullProjectSnapshot ? previous.lastPartialSyncAt : now,
+    capturedAt: completeContents ? now : (previous.capturedAt || ''),
+    lastFullSyncAt: completeContents ? now : previous.lastFullSyncAt,
+    lastPartialSyncAt: completeContents ? previous.lastPartialSyncAt : now,
     lastSyncSource: fullProjectSnapshot ? (project?.capabilities?.method || 'snapshot') : previous.lastSyncSource,
     lastFileCount: files.length,
-    dirty: fullProjectSnapshot ? false : previous.dirty === true,
-    dirtyReason: fullProjectSnapshot ? '' : previous.dirtyReason || '',
-    dirtyAt: fullProjectSnapshot ? '' : previous.dirtyAt || '',
+    dirty: unreadPaths.size > 0 || (!completeContents && previous.dirty === true),
+    dirtyReason: unreadPaths.size ? 'snapshot_content_unavailable' : completeContents ? '' : previous.dirtyReason || '',
+    dirtyAt: unreadPaths.size ? now : completeContents ? '' : previous.dirtyAt || '',
+    unreadFiles: skippedFiles,
     files: nextBaselineFiles
   });
 
@@ -104,10 +110,30 @@ async function syncOverleafToMirror({ projectId, project, rootDir }) {
     fileCount: files.length,
     writtenCount,
     skippedFiles,
+    contentComplete: completeContents,
     partialSnapshot: !fullProjectSnapshot
   };
 }
 
+// A ZIP skip establishes that a path exists, without establishing its current
+// bytes. Keep its last known bytes/baseline, but never promote them to fresh.
+function resolveUnreadSnapshotFiles(project, normalized, previous, fullProjectSnapshot) {
+  const filesByPath = new Map();
+  const candidates = [
+    ...(fullProjectSnapshot ? [] : previous.unreadFiles || []),
+    ...(Array.isArray(project?.capabilities?.skipped) ? project.capabilities.skipped : []),
+    ...normalized.skippedFiles
+  ];
+  for (const file of candidates) {
+    if (!['binary_file_too_large', 'binary_project_too_large'].includes(file?.reason) || typeof file.path !== 'string') continue;
+    const filePath = normalizeRelativePath(file.path);
+    filesByPath.set(filePath, { path: filePath, kind: 'binary', reason: file.reason,
+      ...(Number.isFinite(Number(file.size)) && Number(file.size) >= 0 ? { size: Number(file.size) } : {}) });
+  }
+  for (const file of normalized.files) filesByPath.delete(file.path);
+  return Array.from(filesByPath.values());
+}
+
 async function collectMirrorChanges({ projectId, rootDir }) {
   return (await collectMirrorChangesDetailed({ projectId, rootDir })).changes;
 }
@@ -116,6 +142,7 @@ async function collectMirrorChangesDetailed({ projectId, rootDir }) {
   const mirror = getProjectMirror(projectId, { rootDir });
   const baseline = readBaseline(mirror.baselinePath);
   const baselineByPath = new Map((baseline.files || []).map(file => [file.path, file]));
+  const unreadPaths = new Set((baseline.unreadFiles || []).map(file => file.path));
   const currentPaths = listWorkspaceFiles(mirror.workspacePath);
   const currentByPath = new Map();
   const unsupportedChanges = [];
@@ -124,6 +151,14 @@ async function collectMirrorChangesDetailed({ projectId, rootDir }) {
     const previous = baselineByPath.get(filePath);
     const target = resolveWorkspacePath(mirror.workspacePath, filePath);
     const stat = fs.statSync(target);
+    if (unreadPaths.has(filePath)) {
+      if (!previous || !workspaceFileMatchesBaseline(target, previous)) {
+        unsupportedChanges.push({ type: 'unsupported-local-file', path: filePath,
+          reason: 'snapshot_content_unavailable', size: stat.size, previousExists: true,
+          previousKind: previous?.kind || 'binary' });
+      }
+      continue;
+    }
     if (isGeneratedArtifactPath(filePath, baselineByPath)) {
       if (!previous || !workspaceFileMatchesBaseline(target, previous)) {
         unsupportedChanges.push({
@@ -208,6 +243,7 @@ async function collectMirrorChangesDetailed({ projectId, rootDir }) {
         previousExists: Boolean(previous),
         previousKind: previous?.kind || '',
         previousSize: previous?.size,
+        previousSha256: previous?.kind === 'binary' ? previous.hash : undefined,
         size: contentOrBinary.size
       });
       continue;
@@ -225,6 +261,13 @@ async function collectMirrorChangesDetailed({ projectId, rootDir }) {
   }
 
   for (const [filePath, previous] of baselineByPath) {
+    if (unreadPaths.has(filePath)) {
+      if (!currentPaths.includes(filePath)) {
+        unsupportedChanges.push({ type: 'unsupported-local-file', path: filePath,
+          reason: 'snapshot_content_unavailable', previousExists: true, previousKind: previous.kind });
+      }
+      continue;
+    }
     if (previous.kind === 'binary') {
       if (!currentByPath.has(filePath) && !currentPaths.includes(filePath)) {
         unsupportedChanges.push({
@@ -622,6 +665,7 @@ function hashBytes(bytes) {
 function getMirrorStatus(projectId, options = {}) {
   const mirror = getProjectMirror(projectId, options);
   const baseline = readBaseline(mirror.baselinePath);
+  const unreadContents = (baseline.unreadFiles || []).length > 0;
   if (!baseline.lastFullSyncAt) {
     return {
       exists: false,
@@ -633,13 +677,13 @@ function getMirrorStatus(projectId, options = {}) {
       lastPartialSyncAt: baseline.lastPartialSyncAt || '',
       lastSyncSource: baseline.lastSyncSource || '',
       lastFileCount: Number.isFinite(Number(baseline.lastFileCount)) ? Number(baseline.lastFileCount) : (baseline.files || []).length,
-      dirty: baseline.dirty === true,
-      dirtyReason: baseline.dirtyReason || '',
+      dirty: unreadContents || baseline.dirty === true,
+      dirtyReason: unreadContents ? 'snapshot_content_unavailable' : baseline.dirtyReason || '',
       workspacePath: mirror.workspacePath,
       ...buildOtStatusFields(baseline, false)
     };
   }
-  if (baseline.dirty === true) {
+  if (unreadContents || baseline.dirty === true) {
     return {
       exists: false,
       projectKey: mirror.projectKey,
@@ -651,7 +695,7 @@ function getMirrorStatus(projectId, options = {}) {
       lastSyncSource: baseline.lastSyncSource || '',
       lastFileCount: Number.isFinite(Number(baseline.lastFileCount)) ? Number(baseline.lastFileCount) : (baseline.files || []).length,
       dirty: true,
-      dirtyReason: baseline.dirtyReason || 'dirty_mirror',
+      dirtyReason: unreadContents ? 'snapshot_content_unavailable' : baseline.dirtyReason || 'dirty_mirror',
       workspacePath: mirror.workspacePath,
       ...buildOtStatusFields(baseline, false)
     };
@@ -747,6 +791,7 @@ function buildOtStatusFields(baseline = {}, trusted) {
       && isFreshOtObservation(file.freshness))
     .map(file => ({
       path: file.path,
+      sha256: file.hash,
       source: file.freshness.source,
       state: file.freshness.state,
       lastFullSyncAt: file.freshness.lastFullSyncAt || '',
@@ -767,12 +812,14 @@ async function applyFileOverlays({ projectId, overlays, rootDir }) {
   const mirror = getProjectMirror(projectId, { rootDir });
   const baseline = readBaseline(mirror.baselinePath);
   const filesByPath = new Map((baseline.files || []).map(f => [f.path, f]));
+  const unreadPaths = new Set((baseline.unreadFiles || []).map(file => file.path));
 
   for (const overlay of overlays || []) {
     if (!overlay?.path || typeof overlay.content !== 'string') {
       continue;
     }
     const normalizedPath = normalizeRelativePath(overlay.path);
+    if (unreadPaths.has(normalizedPath)) continue;
     const target = resolveWorkspacePath(mirror.workspacePath, normalizedPath);
     assertSafeWorkspaceTarget(mirror.workspacePath, target, normalizedPath);
     fs.mkdirSync(path.dirname(target), { recursive: true });
@@ -794,14 +841,15 @@ async function applyFileOverlays({ projectId, overlays, rootDir }) {
 }
 
 // v1.8.0: after a VERIFIED writeback, the workspace already holds the exact
-// content that landed in Overleaf (the writeback reads from this workspace).
-// Instead of re-downloading the whole project only to rewrite what we just
-// uploaded, re-hash the written workspace files in place and refresh the
-// baseline freshness metadata. Any doubt -> ok:false, and the caller falls
-// back to a full syncOverleafToMirror.
-async function confirmWritebackFiles({ projectId, paths, rootDir }) {
+// content that landed in Overleaf only while its hashes match the page's
+// verified post-images. Check every target before updating any baseline.
+// Missing or mismatched evidence falls back to a full syncOverleafToMirror.
+async function confirmWritebackFiles({ projectId, paths, expectedFiles, rootDir }) {
   const mirror = getProjectMirror(projectId, { rootDir });
   const baseline = readBaseline(mirror.baselinePath);
+  if ((baseline.unreadFiles || []).length) {
+    return { ok: false, reason: 'snapshot_content_unavailable' };
+  }
   if (!baseline.lastFullSyncAt) {
     return { ok: false, reason: 'no_baseline' };
   }
@@ -810,8 +858,23 @@ async function confirmWritebackFiles({ projectId, paths, rootDir }) {
   }
   const filesByPath = new Map((baseline.files || []).map(file => [file.path, file]));
   const confirmed = [];
-  for (const rawPath of Array.isArray(paths) ? paths : []) {
+  const requestedPaths = Array.isArray(paths) ? paths : [];
+  const seenPaths = new Set();
+  const expectedByPath = new Map();
+  if (Array.isArray(expectedFiles) && expectedFiles.length === requestedPaths.length) {
+    for (const file of expectedFiles) {
+      if (typeof file?.path !== 'string' || !/^[a-f0-9]{64}$/i.test(file?.sha256 || '')) {
+        return { ok: false, reason: 'postimage_proof_invalid' };
+      }
+      const normalizedPath = normalizeRelativePath(file.path);
+      if (expectedByPath.has(normalizedPath)) return { ok: false, reason: 'postimage_proof_invalid' };
+      expectedByPath.set(normalizedPath, file.sha256.toLowerCase());
+    }
+  }
+  for (const rawPath of requestedPaths) {
     const normalizedPath = normalizeRelativePath(rawPath);
+    if (seenPaths.has(normalizedPath)) return { ok: false, reason: 'postimage_proof_invalid' };
+    seenPaths.add(normalizedPath);
     const baselineFile = filesByPath.get(normalizedPath);
     if (!baselineFile) {
       return { ok: false, reason: 'missing_baseline_file', path: normalizedPath };
@@ -819,6 +882,9 @@ async function confirmWritebackFiles({ projectId, paths, rootDir }) {
     if (baselineFile.kind !== 'text') {
       return { ok: false, reason: 'not_text', path: normalizedPath };
     }
+    if (!expectedByPath.has(normalizedPath)) {
+      return { ok: false, reason: 'postimage_proof_required', path: normalizedPath };
+    }
     let target;
     try {
       target = resolveWorkspacePath(mirror.workspacePath, normalizedPath);
@@ -835,6 +901,9 @@ async function confirmWritebackFiles({ projectId, paths, rootDir }) {
       return { ok: false, reason: 'workspace_read_failed', path: normalizedPath };
     }
     const hash = hashText(content);
+    if (hash !== expectedByPath.get(normalizedPath)) {
+      return { ok: false, reason: 'postimage_mismatch', path: normalizedPath };
+    }
     filesByPath.set(normalizedPath, { ...baselineFile, hash, content });
     confirmed.push({ path: normalizedPath, hash });
   }
@@ -854,6 +923,7 @@ async function confirmWritebackFiles({ projectId, paths, rootDir }) {
 async function patchMirrorFiles({ projectId, files, rootDir, source = 'ot' }) {
   const mirror = getProjectMirror(projectId, { rootDir });
   const baseline = readBaseline(mirror.baselinePath);
+  const unreadContents = (baseline.unreadFiles || []).length > 0;
   const baselineByPath = new Map((baseline.files || []).map(file => [file.path, file]));
   const patchedFilesByPath = new Map();
   const appliedFiles = [];
@@ -895,7 +965,7 @@ async function patchMirrorFiles({ projectId, files, rootDir, source = 'ot' }) {
     const nextHash = hashText(patch.nextContent);
     if (patch.baseHash !== baselineFile.hash) {
       if (nextHash === baselineFile.hash) {
-        if (baseline.dirty === true) {
+        if (unreadContents || baseline.dirty === true) {
           skippedFiles.push({ path: normalized.path, reason: 'dirty_mirror' });
           lastOtErrorCode = 'dirty_mirror';
           continue;
@@ -922,7 +992,7 @@ async function patchMirrorFiles({ projectId, files, rootDir, source = 'ot' }) {
       lastOtErrorCode = 'base_hash_mismatch';
       continue;
     }
-    if (baseline.dirty === true) {
+    if (unreadContents || baseline.dirty === true) {
       skippedFiles.push({ path: normalized.path, reason: 'dirty_mirror' });
       lastOtErrorCode = 'dirty_mirror';
       continue;

package/native-host/src/nativeDoctor.js

@@ -10,6 +10,7 @@ const {
   getNativeHostPlatform,
   getNativeHostRegistrationTarget
 } = require('./nativeHostPlatform');
+const { queryWindowsNativeHostRegistration } = require('./nativeHostRegistration');
 const { decodeFrames, encodeMessage } = require('./nativeMessaging');
 const {
   buildBridgePingParams,
@@ -68,6 +69,12 @@ async function runDoctor(options = {}) {
     }
   };
 
+  if (registrationTarget.kind === 'registry') {
+    const observed = queryWindowsNativeHostRegistration(registrationTarget, { env, spawnSync: options.spawnSync });
+    body.registration = { ...body.registration, ...observed,
+      ...(observed.registeredManifestPath ? { registeredManifestPath: normalizeDiagnosticPath(observed.registeredManifestPath, pathOptions) } : {}) };
+  }
+
   if (runtimeRoot) {
     body.runtimeRoot = runtimeRoot;
     body.diagnostics.runtimeRoot = runtimeRoot;
@@ -160,6 +167,10 @@ function classifyDoctorResult(body = {}) {
     };
   }
 
+  if (body.registration?.kind === 'registry' && body.registration.verified !== true) {
+    return { exitCode: 2, ok: false, status: 'registration_unverified' };
+  }
+
   if (body.compatibility?.classification === 'compatible') {
     return {
       exitCode: 0,
@@ -198,6 +209,10 @@ function formatDoctorHuman(body = {}) {
   if (body.registration?.registryKey) {
     lines.push(`Registry key: ${body.registration.registryKey}`);
   }
+  if (body.registration?.kind === 'registry') {
+    lines.push(`Registry discovery: ${body.registration.status || 'unverified'}`);
+    if (body.registration.registeredManifestPath) lines.push(`Registered manifest: ${body.registration.registeredManifestPath}`);
+  }
   if (body.bridge?.path) {
     lines.push(`Bridge: ${body.bridge.path}`);
   }

package/native-host/src/nativeHelperLifecycle.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const { register } = require('./nativeRunLifecycle');
+
+// Helpers own no project mirror lock, but their preparation and process-stop
+// promises must finish before the Host's transport shutdown can finish.
+async function runOwnedNativeHelper(execute, signal) {
+  const controller = new AbortController();
+  const lifetime = register({ controller });
+  const onAbort = () => controller.abort(signal.reason);
+  signal?.addEventListener('abort', onAbort, { once: true });
+  if (signal?.aborted) onAbort();
+  try {
+    return await execute(controller.signal);
+  } finally {
+    signal?.removeEventListener('abort', onAbort);
+    lifetime.complete();
+  }
+}
+
+module.exports = { runOwnedNativeHelper };

package/native-host/src/nativeHostRegistration.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const path = require('node:path');
+
+// Query only the selected browser's current-user default registration value.
+// An unreadable/missing value is unknown discovery evidence, never healthy.
+function queryWindowsNativeHostRegistration(target, options = {}) {
+  const env = options.env || process.env;
+  const run = options.spawnSync || require('node:child_process').spawnSync;
+  let result;
+  try { result = run(env.CODEX_OVERLEAF_REG_EXE || 'reg.exe', [
+    ...parseStringArrayEnv(env.CODEX_OVERLEAF_REG_EXE_ARGS_JSON), 'query', target.registryKey, '/ve'
+  ], {
+    env, encoding: 'utf8', windowsHide: true, timeout: 3000, maxBuffer: 64 * 1024
+  }); } catch (_) { return { verified: false, status: 'unavailable' }; }
+  if (result.error || result.status !== 0) return { verified: false, status: 'unavailable' };
+  const values = [...String(result.stdout || '').matchAll(/^\s*.+?\s+REG_SZ\s+(.+?)\s*$/gm)].map(match => match[1]);
+  if (values.length !== 1 || !path.win32.isAbsolute(values[0])) return { verified: false, status: 'unavailable' };
+  const matches = path.win32.normalize(values[0]).toLowerCase() === path.win32.normalize(target.manifestPath).toLowerCase();
+  return { verified: matches, status: matches ? 'verified' : 'mismatch', registeredManifestPath: values[0] };
+}
+
+// Match the existing install/uninstall registry command prefix contract.
+function parseStringArrayEnv(value) {
+  if (!value) return [];
+  const parsed = JSON.parse(value);
+  if (!Array.isArray(parsed) || !parsed.every(item => typeof item === 'string')) {
+    throw new Error('CODEX_OVERLEAF_REG_EXE_ARGS_JSON must be a JSON array of strings');
+  }
+  return parsed;
+}
+
+module.exports = { queryWindowsNativeHostRegistration };

package/native-host/src/nativeRunLifecycle.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const processStopBarrier = require('./processStopBarrier');
+const { logDebug } = require('./debugLog');
+const active = new Set();
+let closingError;
+
+// Shutdown ownership is independent of RPC ids: absent/reused ids must not
+// hide a live run from transport shutdown or its durable quarantine.
+function register({ controller, projectKey, rootDir }) {
+  let resolveDone;
+  const entry = { controller, projectKey, rootDir, processes: [], done: new Promise(resolve => { resolveDone = resolve; }) };
+  active.add(entry);
+  if (closingError) controller.abort(closingError);
+  return {
+    trackProcess(identity) {
+      if (!Number.isInteger(identity?.processId) || identity.processId <= 0) return;
+      entry.processes.push(identity);
+      if (closingError) quarantine(entry, identity);
+    },
+    complete() {
+      active.delete(entry);
+      try {
+        if (entry.processes.some(identity => identity.quarantined)) processStopBarrier.isBlocked(projectKey, rootDir);
+      } catch (error) { logDebug('native_transport.quarantine_cleanup_failed', { projectKey, message: error.message }); }
+      finally { resolveDone(); }
+    }
+  };
+}
+
+function abortAllActiveOperations(reason = 'Native messaging transport disconnected.') {
+  closingError = new Error(String(reason || 'Native messaging transport disconnected.'));
+  closingError.code = 'native_transport_closed';
+  const entries = Array.from(active);
+  for (const entry of entries) {
+    if (!entry.controller.signal.aborted) entry.controller.abort(closingError);
+  }
+  return Promise.all(entries.map(entry => entry.done));
+}
+
+function quarantineActiveOperations() {
+  const failures = [];
+  for (const entry of active) {
+    // A preparing run has no process to quarantine. Its aborted signal is
+    // checked again after provider preparation and immediately before spawn.
+    for (const identity of entry.processes) {
+      const failure = quarantine(entry, identity);
+      if (failure) failures.push(failure);
+    }
+  }
+  return failures;
+}
+
+function quarantine(entry, identity) {
+  if (identity.quarantined) return null;
+  const error = Object.assign(new Error('Native transport closed before run settlement.'), identity, {
+    code: 'codex_process_stop_unconfirmed'
+  });
+  try {
+    processStopBarrier.record(entry.projectKey, entry.rootDir, error);
+    if (error.stopBarrierPersistenceError) throw new Error(error.stopBarrierPersistenceError);
+    identity.quarantined = true;
+    return null;
+  } catch (failure) {
+    const detail = { projectKey: entry.projectKey, message: failure.message };
+    logDebug('native_transport.quarantine_failed', detail);
+    return detail;
+  }
+}
+
+module.exports = { register, abortAllActiveOperations, quarantineActiveOperations };