codex-overleaf-link 2.4.0 → 2.5.0

package/native-host/src/managedInstall.js

@@ -19,7 +19,7 @@ const {
   getNativeHostRegistrationTarget
 } = require('./nativeHostPlatform');
 const { buildRuntimeFileManifest } = require('./runtimeInstaller');
-const { parseSemver, updateError } = require('./updateTrust');
+const { BOOTSTRAP_PROTOCOL, parseSemver, updateError } = require('./updateTrust');
 
 const MANAGED_BY = 'codex-overleaf-link';
 const EXTENSION_MARKER = '.codex-overleaf-managed-extension.json';
@@ -154,7 +154,7 @@ function buildManagedExtensionTree(options = {}) {
   fs.writeFileSync(path.join(targetRoot, EXTENSION_MARKER), JSON.stringify({
     managedBy: MANAGED_BY,
     kind: 'extension',
-    bootstrapProtocol: 2,
+    bootstrapProtocol: BOOTSTRAP_PROTOCOL,
     version,
     releaseRef,
     releaseChannel,
@@ -199,7 +199,7 @@ function installManagedNativeVersion({ packageRoot, nativeRoot, version, release
   fs.writeFileSync(path.join(nativeRoot, NATIVE_MARKER), JSON.stringify({
     managedBy: MANAGED_BY,
     kind: 'native',
-    bootstrapProtocol: 2,
+    bootstrapProtocol: BOOTSTRAP_PROTOCOL,
     version,
     installedAt: new Date().toISOString()
   }, null, 2) + '\n', 'utf8');
@@ -388,7 +388,8 @@ function readManagedMarker(root, markerName) {
 function isManagedMarker(marker, kind) {
   return marker?.managedBy === MANAGED_BY &&
     marker?.kind === kind &&
-    (marker?.bootstrapProtocol === 1 || marker?.bootstrapProtocol === 2);
+    Number.isInteger(marker?.bootstrapProtocol) &&
+    marker.bootstrapProtocol >= 1 && marker.bootstrapProtocol <= BOOTSTRAP_PROTOCOL;
 }
 
 function readVersionPointer(nativeRoot, name) {

package/native-host/src/nativeEnvironment.js

@@ -4,8 +4,10 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
+const { logDebug } = require('./debugLog');
 const {
   buildCodexRuntimeIdentity,
+  discoverCodexCandidates,
   getCodexRuntimeIdentityFromEnv,
   serializeCodexRuntimeIdentity
 } = require('./codexRuntimeIdentity');
@@ -54,6 +56,69 @@ function buildNativeRuntimeEnv(baseEnv = process.env, options = {}) {
   return env;
 }
 
+const codexRuntimeRefreshCache = new Map();
+
+function refreshCodexRuntimeEnv(baseEnv = process.env, options = {}) {
+  const runtimeOptions = { ...options, platform: getNativeRuntimePlatform({ ...options, env: baseEnv }) };
+  const previous = getCodexRuntimeIdentityFromEnv(baseEnv);
+  const selectedPath = previous.selected?.path || String(baseEnv.CODEX_OVERLEAF_CODEX_PATH || '');
+  const pinned = previous.selectedBy === 'explicit-path'
+    || (previous.selectedBy === 'legacy-path' && Boolean(selectedPath));
+  const pathValue = mergePathSegments([
+    ...getPathValues(baseEnv, runtimeOptions),
+    ...getDefaultPathSegments(baseEnv, runtimeOptions)
+  ], runtimeOptions);
+  const candidates = discoverCodexCandidates(pathValue, { ...runtimeOptions, env: baseEnv });
+  const paths = [...new Set([selectedPath, ...candidates].filter(Boolean))];
+  const signatures = paths.map(candidate => {
+    try {
+      const resolved = fs.realpathSync(candidate);
+      const stat = fs.statSync(resolved);
+      return [candidate, resolved, stat.size, stat.mtimeMs, stat.ctimeMs];
+    } catch (_) { return [candidate, 'missing']; }
+  });
+  const key = JSON.stringify([runtimeOptions.platform, pinned ? selectedPath : '', pathValue, signatures]);
+  const cached = codexRuntimeRefreshCache.get(key);
+  let identity = cached?.identity;
+  if (options.force || !cached || Date.now() - cached.createdAt > 30000) {
+    identity = buildCodexRuntimeIdentity({
+      selectedPath,
+      selectionPolicy: pinned ? 'explicit-path' : 'newest-version',
+      pathValue,
+      delimiter: runtimeOptions.delimiter,
+      env: { ...baseEnv, PATH: pathValue },
+      platform: runtimeOptions.platform
+    });
+    codexRuntimeRefreshCache.set(key, { identity, createdAt: Date.now() });
+    while (codexRuntimeRefreshCache.size > 4) {
+      codexRuntimeRefreshCache.delete(codexRuntimeRefreshCache.keys().next().value);
+    }
+    if (identity.selected?.path !== previous.selected?.path
+      || identity.selected?.version !== previous.selected?.version) {
+      logDebug('codex.runtime.refreshed', {
+        previousVersion: previous.selected?.version || '',
+        selectedVersion: identity.selected?.version || '',
+        selectedPath: identity.selected?.displayPath || '',
+        selectedBy: identity.selectedBy,
+        reason: options.force ? 'model_version_rejection' : 'before_request'
+      });
+    }
+  }
+  // Keep each in-flight run on its own environment snapshot.
+  const env = {
+    ...baseEnv,
+    CODEX_OVERLEAF_ENV_READY: '1',
+    CODEX_OVERLEAF_PLATFORM: runtimeOptions.platform,
+    CODEX_OVERLEAF_CODEX_PATH: identity.selected?.path || '',
+    CODEX_OVERLEAF_CODEX_RUNTIME_JSON: serializeCodexRuntimeIdentity(identity),
+    CODEX_OVERLEAF_CODEX_VERSION: identity.selected?.version || '',
+    CODEX_OVERLEAF_CODEX_SOURCE: identity.selected?.source || ''
+  };
+  normalizePathKeys(env, pathValue, runtimeOptions);
+  env.PATH = pathValue;
+  return env;
+}
+
 function readLoginShellEnv(baseEnv = process.env, options = {}) {
   if (getNativeRuntimePlatform(options) === 'win32') {
     return null;
@@ -169,6 +234,10 @@ function getDefaultPathSegments(env = process.env, options = {}) {
 
   return [
     ...commonSegments.slice(0, 4),
+    platformPath.join(home, 'Applications/ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS'),
+    platformPath.join(home, 'Applications/Codex.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS'),
+    '/Applications/ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS',
+    '/Applications/Codex.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS',
     platformPath.join(home, 'Applications/ChatGPT.app/Contents/Resources'),
     platformPath.join(home, 'Applications/Codex.app/Contents/Resources'),
     '/Applications/ChatGPT.app/Contents/Resources',
@@ -344,6 +413,7 @@ module.exports = {
   mergePathSegments,
   parseMarkedShellEnv,
   readLoginShellEnv,
+  refreshCodexRuntimeEnv,
   resolveExecutable,
   summarizeNativeEnvironment
 };

package/native-host/src/nativeQuotas.js

@@ -1,5 +1,12 @@
 'use strict';
 
+const { REFERENCE_LIMITS } = require('../../extension/src/shared/writingStyle');
+const WRITING_STYLE_ATTACHMENT_QUOTAS = Object.freeze({
+  maxAttachmentCount: REFERENCE_LIMITS.maxSources,
+  maxAttachmentBytes: REFERENCE_LIMITS.maxPdfBytes,
+  maxAttachmentTotalBytes: REFERENCE_LIMITS.maxAttachmentTotalBytes
+});
+
 const NATIVE_REQUEST_QUOTAS = Object.freeze({
   maxProjectFiles: 1000,
   maxProjectTextBytes: 32 * 1024 * 1024,
@@ -21,7 +28,7 @@ function validateNativeRequestQuotas(request = {}) {
         validateOperationListQuota(params.fileOverlays, 'fileOverlays'),
         validateFilePayloadQuota(params.fileOverlays, 'fileOverlays'),
         validateCompileLogQuota(params),
-        validateAttachmentQuota(params.attachments),
+        validateAttachmentQuota(params.attachments, params.writingStyleBuild ? WRITING_STYLE_ATTACHMENT_QUOTAS : NATIVE_REQUEST_QUOTAS),
         validateSkillContentQuota(params.skillContent)
       ]);
     case 'mirror.sync':
@@ -211,27 +218,27 @@ function validateCompileLogQuota(params = {}) {
     : null;
 }
 
-function validateAttachmentQuota(attachments) {
+function validateAttachmentQuota(attachments, quotas = NATIVE_REQUEST_QUOTAS) {
   const items = Array.isArray(attachments) ? attachments : [];
-  if (items.length > NATIVE_REQUEST_QUOTAS.maxAttachmentCount) {
-    return quotaViolation('attachments', NATIVE_REQUEST_QUOTAS.maxAttachmentCount, items.length, 'too many attachments');
+  if (items.length > quotas.maxAttachmentCount) {
+    return quotaViolation('attachments', quotas.maxAttachmentCount, items.length, 'too many attachments');
   }
 
   let totalBytes = 0;
   for (const item of items) {
     const bytes = getDeclaredOrEstimatedBinaryBytes(item);
-    if (bytes > NATIVE_REQUEST_QUOTAS.maxAttachmentBytes) {
+    if (bytes > quotas.maxAttachmentBytes) {
       return quotaViolation(
         'attachments.contentBase64',
-        NATIVE_REQUEST_QUOTAS.maxAttachmentBytes,
+        quotas.maxAttachmentBytes,
         bytes,
         'attachment payload is too large'
       );
     }
     totalBytes += bytes;
   }
-  return totalBytes > NATIVE_REQUEST_QUOTAS.maxAttachmentTotalBytes
-    ? quotaViolation('attachments', NATIVE_REQUEST_QUOTAS.maxAttachmentTotalBytes, totalBytes, 'attachment payload is too large')
+  return totalBytes > quotas.maxAttachmentTotalBytes
+    ? quotaViolation('attachments', quotas.maxAttachmentTotalBytes, totalBytes, 'attachment payload is too large')
     : null;
 }
 

package/native-host/src/overleafWorkspaceRules.js

@@ -0,0 +1,16 @@
+'use strict';
+
+// Shared by project turns and broker workers. Skill-install turns run outside
+// the project mirror and retain their existing installer command policy.
+function formatOverleafWorkspaceRules() {
+  return [
+    'Overleaf workspace rules (also apply to delegated subagents):',
+    '- This directory is a synchronized Overleaf project mirror without .git metadata.',
+    '- Do not run Git commands in this mirror, including git status, git diff, git rev-parse, or git init. Do not create .git metadata or search parent directories for a repository.',
+    '- Verify changes through direct file reads and searches. Run compilation checks only when needed and permitted by the current task and mode; never compile solely to replace an unavailable Git check.',
+    '- The plugin compares the workspace against its synchronized baseline, collects file changes, and handles writeback to Overleaf. No Git-based diff, staging, or commit is required.',
+    '- Include these workspace rules in every delegated subagent task so workers follow the same constraints.'
+  ].join('\n');
+}
+
+module.exports = { formatOverleafWorkspaceRules };

package/native-host/src/processStopBarrier.js

@@ -0,0 +1,80 @@
+'use strict';
+
+// A stop acknowledgement is not proof of process exit. This quarantine survives
+// Native Host restarts and only permits work after positive exit evidence.
+const fs = require('node:fs');
+const path = require('node:path');
+const { getProjectMirror } = require('./mirrorWorkspace');
+const pending = new Map();
+
+function location(projectId, rootDir) {
+  const mirror = getProjectMirror(projectId, { rootDir });
+  return path.join(path.dirname(mirror.workspacePath), '.codex-stop-barrier.json');
+}
+
+function load(file) {
+  if (pending.has(file)) return pending.get(file);
+  let records = [];
+  try {
+    if (fs.statSync(file).size > 65536) throw new Error('Oversized stop barrier');
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!Array.isArray(value) || value.length > 64) throw new Error('Invalid stop barrier');
+    records = value;
+  } catch (error) {
+    if (error.code !== 'ENOENT') records = [{ unknown: true }];
+  }
+  pending.set(file, records);
+  return records;
+}
+
+function persist(file, records) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = file + '.' + process.pid + '.tmp';
+  const fd = fs.openSync(temp, 'w', 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(records.map(({ isStopped, ...record }) => record)));
+    fs.fsyncSync(fd);
+  } finally { fs.closeSync(fd); }
+  fs.renameSync(temp, file);
+}
+
+function stopped(record) {
+  if (typeof record.isStopped === 'function') {
+    try { return record.isStopped() === true; } catch (_) { return false; }
+  }
+  // Recovered POSIX process-group identities can be checked without signalling
+  // or killing anything. Unknown/Windows trees remain quarantined.
+  if (record.processGroup !== true || record.platform !== process.platform
+    || !Number.isInteger(record.processId) || record.processId <= 0) return false;
+  try { process.kill(-record.processId, 0); return false; }
+  catch (error) { return error.code === 'ESRCH'; }
+}
+
+function record(projectId, rootDir, error) {
+  const file = location(projectId, rootDir);
+  const records = load(file);
+  records.push({
+    processId: error.processId, processGroup: error.processGroup === true,
+    platform: process.platform, createdAt: new Date().toISOString(),
+    isStopped: error.isStopped
+  });
+  try { persist(file, records); }
+  catch (failure) { error.stopBarrierPersistenceError = failure.message; }
+}
+
+function isBlocked(projectId, rootDir) {
+  const file = location(projectId, rootDir);
+  const records = load(file);
+  if (!records.length) return false;
+  const remaining = records.filter(value => !stopped(value));
+  if (remaining.length !== records.length) {
+    try {
+      persist(file, remaining);
+      pending.set(file, remaining);
+    } catch (_) { return true; }
+  }
+  return remaining.length > 0;
+}
+
+module.exports = { record, isBlocked };
+

package/native-host/src/providerModelCatalog.js

@@ -79,9 +79,10 @@ function buildModelEntry(model, launch, index) {
 }
 
 function normalizeEfforts(...values) {
-  const allowed = new Set(['none', 'minimal', 'low', 'medium', 'high', 'xhigh']);
-  const normalized = values
-    .flatMap(value => Array.isArray(value) ? value : [])
+  const allowed = new Set(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+  // Explicit model capabilities must not inherit the selected model's levels.
+  const configured = values.find(value => Array.isArray(value) && value.length) || [];
+  const normalized = configured
     .map(value => String(value || '').trim().toLowerCase())
     .filter(value => allowed.has(value));
   return Array.from(new Set(normalized.length ? normalized : ['none']));

package/native-host/src/providerProfile.js

@@ -7,7 +7,7 @@ const {
 } = require('./providerReasoning');
 
 const ALLOWED_WIRE_APIS = new Set(['auto', 'responses', 'chat', 'anthropic']);
-const ALLOWED_REASONING_EFFORTS = new Set(['none', 'minimal', 'low', 'medium', 'high', 'xhigh']);
+const ALLOWED_REASONING_EFFORTS = new Set(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
 const ALLOWED_UPSTREAM_RESPONSE_MODES = new Set(['auto', 'streaming', 'buffered']);
 const ALLOWED_AUTH_MODES = new Set(['bearer', 'x-api-key', 'api-key', 'custom', 'none']);
 const ALLOWED_INPUT_MODALITIES = new Set(['text', 'image']);
@@ -93,6 +93,9 @@ function normalizeModels(values) {
       upstreamResponseMode: normalizeUpstreamResponseMode(value?.upstreamResponseMode, true),
       resolvedUpstreamResponseMode: normalizeUpstreamResponseMode(value?.resolvedUpstreamResponseMode, false),
       contextWindow: normalizeContextWindow(value?.contextWindow),
+      maxOutputTokens: normalizeModelOutputTokens(value?.maxOutputTokens),
+      reasoningAdapter: value?.reasoningAdapter ? normalizeReasoningAdapter(value.reasoningAdapter) : '',
+      reasoningCapability: value?.reasoningCapability ? normalizeReasoningCapability(value.reasoningCapability) : '',
       supportsParallelToolCalls: value?.supportsParallelToolCalls === true,
       inputModalities: normalizeInputModalities(value?.inputModalities),
       baseInstructions: normalizeOptionalText(value?.baseInstructions, 8000)
@@ -101,6 +104,15 @@ function normalizeModels(values) {
   return result;
 }
 
+function normalizeModelOutputTokens(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < 256 || number > 65536) {
+    throw providerError('provider_configuration_invalid', 'Model output limit must be an integer between 256 and 65536.');
+  }
+  return number;
+}
+
 function normalizeBaseUrl(value) {
   const text = normalizeRequiredText(value, 'provider_base_url_invalid', 'Base URL is required.', 2048);
   let parsed;

package/native-host/src/providerReasoning.js

@@ -12,7 +12,7 @@ const REASONING_ADAPTERS = new Set([
   'reasoning_split'
 ]);
 const REASONING_CAPABILITIES = new Set(['auto', 'none', 'toggle', 'effort']);
-const REASONING_EFFORTS = new Set(['none', 'minimal', 'low', 'medium', 'high', 'xhigh']);
+const REASONING_EFFORTS = new Set(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
 const DEEPSEEK_MAX_REASONING_OUTPUT_TOKENS = 65536;
 
 function normalizeReasoningAdapter(value) {
@@ -67,6 +67,10 @@ function getSupportedReasoningEfforts(profile = {}, model = {}) {
 }
 
 function getReasoningControl(profile = {}, model = {}) {
+  profile = { ...profile,
+    reasoningAdapter: model.reasoningAdapter || profile.reasoningAdapter,
+    reasoningCapability: model.reasoningCapability || profile.reasoningCapability
+  };
   const explicit = Array.isArray(model.reasoningEfforts)
     ? model.reasoningEfforts.map(normalizeEffort).filter(Boolean)
     : [];
@@ -85,7 +89,7 @@ function getReasoningControl(profile = {}, model = {}) {
   }
   if (adapter === 'deepseek') {
     return {
-      efforts: ['none', 'high', 'xhigh'],
+      efforts: ['none', 'high', 'max'],
       defaultEffort: 'high',
       presentation: 'deepseek'
     };
@@ -134,11 +138,11 @@ function applyReasoningControl(chatBody, responsesRequest = {}, launch = {}) {
   if (adapter === 'deepseek') {
     chatBody.thinking = { type: enabled ? 'enabled' : 'disabled' };
     if (enabled) {
-      chatBody.reasoning_effort = requested === 'xhigh' ? 'max' : 'high';
+      chatBody.reasoning_effort = ['xhigh', 'max'].includes(requested) ? 'max' : 'high';
     }
   } else if (adapter === 'reasoning_effort') {
     if (enabled) {
-      chatBody.reasoning_effort = clampEffort(requested, false);
+      chatBody.reasoning_effort = clampEffort(requested, true);
     }
   } else if (adapter === 'openrouter') {
     chatBody.reasoning = { effort: clampEffort(requested, true) };
@@ -164,7 +168,7 @@ function resolveReasoningMaxOutputTokens(value, responsesRequest = {}, launch =
   const normalized = Math.max(1, Math.floor(number));
   const effort = resolveRequestedReasoningEffort(responsesRequest, launch);
   const adapter = resolveReasoningAdapter(launch, modelId || launch.modelId);
-  return adapter === 'deepseek' && effort === 'xhigh'
+  return adapter === 'deepseek' && ['xhigh', 'max'].includes(effort)
     ? Math.max(normalized, DEEPSEEK_MAX_REASONING_OUTPUT_TOKENS)
     : normalized;
 }

package/native-host/src/providerStore.js

@@ -261,6 +261,10 @@ function recordProviderDiagnosticUnlocked(params = {}, env = process.env) {
     return { recorded: false };
   }
   const modelId = String(params.modelId || '').trim();
+  // Draft tests may cover models that are not saved yet; only saved models carry diagnostics.
+  if (!profile.models.some(model => model.id === modelId)) {
+    return { recorded: false };
+  }
   const secret = state.secrets.secrets[providerId] || '';
   const connectionFingerprint = computeConnectionFingerprint(profile, secret, modelId);
   if (connectionFingerprint !== String(params.connectionFingerprint || '') || !isResolvedWireApi(params.wireApi)) {

package/native-host/src/readProgressGuard.js

@@ -19,6 +19,36 @@ function buildReadProgressRules() {
   ].join('\n');
 }
 
+function createRunEventScope(getTurn = () => ({})) {
+  const owners = new Map();
+  const identity = params => ({
+    threadId: String(params?.threadId || params?.thread?.id || ''),
+    turnId: String(params?.turnId || params?.turn?.id || '')
+  });
+  const itemId = params => String(params?.itemId || params?.item?.id || '');
+  const matches = owner => {
+    const active = getTurn() || {};
+    return (!owner.threadId || owner.threadId === active.threadId)
+      && (!owner.turnId || !active.turnId || owner.turnId === active.turnId);
+  };
+  return {
+    accepts(params = {}) {
+      const owner = identity(params);
+      const id = itemId(params);
+      if (owner.threadId || owner.turnId) {
+        if (id) owners.set(id, owner);
+        return matches(owner);
+      }
+      return !owners.has(id) || matches(owners.get(id));
+    },
+    owns(params = {}) {
+      const explicit = identity(params);
+      const owner = explicit.threadId || explicit.turnId ? explicit : owners.get(itemId(params));
+      return Boolean((getTurn() || {}).turnId && owner?.threadId && matches(owner));
+    }
+  };
+}
+
 function createReadProgressGuard(options = {}) {
   const settings = {
     minReadCommands: positiveInteger(options.minReadCommands, DEFAULT_MIN_READ_COMMANDS),
@@ -37,11 +67,19 @@ function createReadProgressGuard(options = {}) {
   let redundantStreak = 0;
   let postSteerRedundantStreak = 0;
   let steerIssued = false;
+  let steerAcknowledged = false;
   let abortIssued = false;
 
   return {
     observe(item) {
       if (abortIssued) return noAction();
+      if (item?.type === 'fileChange') {
+        coverageByFile.clear();
+        commandCounts.clear();
+        readCount = redundantStreak = postSteerRedundantStreak = 0;
+        steerIssued = steerAcknowledged = false;
+        return noAction();
+      }
       const inspection = extractReadInspection(item, settings.workspacePath);
       if (!inspection) {
         if (item?.type === 'commandExecution') {
@@ -52,8 +90,9 @@ function createReadProgressGuard(options = {}) {
       }
 
       readCount += 1;
-      const signatureCount = (commandCounts.get(inspection.signature) || 0) + 1;
-      commandCounts.set(inspection.signature, signatureCount);
+      const signatureKey = inspection.fileKey + '\0' + inspection.signature;
+      const signatureCount = (commandCounts.get(signatureKey) || 0) + 1;
+      commandCounts.set(signatureKey, signatureCount);
       let overlapRatio = 0;
       let redundant = signatureCount > 1;
 
@@ -85,6 +124,7 @@ function createReadProgressGuard(options = {}) {
       });
 
       if (steerIssued) {
+        if (!steerAcknowledged) return noAction(evidence);
         postSteerRedundantStreak = redundant ? postSteerRedundantStreak + 1 : 0;
         if (postSteerRedundantStreak >= settings.postSteerRedundantStreak) {
           abortIssued = true;
@@ -101,12 +141,20 @@ function createReadProgressGuard(options = {}) {
       return noAction(evidence);
     },
 
+    acknowledgeSteer() {
+      if (steerIssued && !abortIssued) {
+        steerAcknowledged = true;
+        postSteerRedundantStreak = 0;
+      }
+    },
+
     snapshot() {
       return {
         readCount,
         redundantStreak,
         postSteerRedundantStreak,
         steerIssued,
+        steerAcknowledged,
         abortIssued
       };
     }
@@ -120,9 +168,15 @@ function createReadProgressController({ input = {}, request, fail, getTurn, emit
   });
   let pendingSteer = null;
   let steerInFlight = false;
+  let generation = 0;
 
   return {
     observe(item) {
+      if (item?.type === 'fileChange') {
+        generation += 1;
+        pendingSteer = null;
+        steerInFlight = false;
+      }
       const decision = guard.observe(item);
       if (decision.action === 'steer') {
         steer(decision);
@@ -153,6 +207,7 @@ function createReadProgressController({ input = {}, request, fail, getTurn, emit
       return;
     }
     steerInFlight = true;
+    const steerGeneration = generation;
     emitEvent('codex.no_progress.steered', 'Repeated file reads detected; asking Codex to synthesize', {
       ...decision.evidence,
       guardAction: 'steer'
@@ -165,7 +220,10 @@ function createReadProgressController({ input = {}, request, fail, getTurn, emit
         text: buildReadProgressSteerText(decision.evidence, input.mode),
         text_elements: []
       }]
+    }).then(() => {
+      if (steerGeneration === generation) guard.acknowledgeSteer();
     }).catch(error => {
+      if (steerGeneration !== generation) return;
       const progressError = createNoProgressError(decision.evidence);
       progressError.message += ` Automatic steering failed: ${String(error?.message || error).slice(0, 500)}`;
       fail(progressError);
@@ -175,30 +233,35 @@ function createReadProgressController({ input = {}, request, fail, getTurn, emit
 
 function extractReadInspection(item = {}, workspacePath = '') {
   if (item.type !== 'commandExecution') return null;
+  if (item.status && item.status !== 'completed') return null;
+  if (Number.isInteger(item.exitCode) && item.exitCode !== 0) return null;
   const command = String(item.command || '').trim();
   if (!command) return null;
+  const cwd = typeof item.cwd === 'string' && item.cwd ? path.resolve(workspacePath || '.', item.cwd) : workspacePath;
   const actions = Array.isArray(item.commandActions) ? item.commandActions : [];
-  const readAction = actions.find(action => action?.type === 'read');
-  if (!readAction && !looksLikeReadCommand(command)) return null;
-
+  const readActions = actions.filter(action => action?.type === 'read');
+  if (!readActions.length && !looksLikeReadCommand(command)) return null;
+  const paths = [...new Set(readActions.map(action => normalizeFileKey(action.path, cwd)).filter(Boolean))];
+  if (paths.length > 1) return null;
   const bounded = extractBoundedRange(command);
-  const rawPath = bounded?.path || readAction?.path || '';
-  const fileKey = normalizeFileKey(rawPath, workspacePath);
-  const displayPath = safeDisplayPath(fileKey, workspacePath) || path.basename(fileKey) || 'project file';
-  const range = bounded
-    ? { startLine: bounded.startLine, endLine: bounded.endLine }
-    : null;
+  const boundedKey = normalizeFileKey(bounded?.path, cwd);
+  if (boundedKey && paths[0] && boundedKey !== paths[0]) return null;
+  const fileKey = paths[0] || boundedKey;
+  if (!fileKey) return null;
   return {
-    fileKey: fileKey || displayPath,
-    displayPath,
-    range,
+    fileKey,
+    displayPath: safeDisplayPath(fileKey, workspacePath) || path.basename(fileKey),
+    range: bounded && boundedKey === fileKey
+      ? { startLine: bounded.startLine, endLine: bounded.endLine } : null,
     signature: normalizeCommandSignature(command, workspacePath)
   };
 }
 
 function extractBoundedRange(command) {
   const source = String(command || '');
-  const sedMatch = source.match(/\bsed\s+(?:-[A-Za-z]+\s+)*["']?(\d+)\s*,\s*(\d+)p["']?(?:\s+((?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s;&|]+)))?/i);
+  // Stream pagination and compound commands do not prove source-file ranges.
+  if (/[|;&<>\x60]/.test(source)) return null;
+  const sedMatch = source.match(/\bsed\s+(?:-[A-Za-z]+\s+)*["']?(\d+)\s*,\s*(\d+)p["']?\s+((?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s;&|]+))/i);
   if (sedMatch) {
     return normalizeRangeMatch(sedMatch[1], sedMatch[2], sedMatch[3]);
   }
@@ -212,13 +275,15 @@ function extractBoundedRange(command) {
 function normalizeRangeMatch(startValue, endValue, pathValue) {
   const startLine = Number(startValue);
   const endLine = Number(endValue);
+  const filePath = unquoteShellWord(pathValue);
+  if (!filePath || filePath === '-') return null;
   if (!Number.isSafeInteger(startLine) || !Number.isSafeInteger(endLine) || startLine < 1 || endLine < startLine) {
     return null;
   }
   return {
     startLine,
     endLine,
-    path: unquoteShellWord(pathValue)
+    path: filePath
   };
 }
 
@@ -228,8 +293,9 @@ function looksLikeReadCommand(command) {
 }
 
 function normalizeFileKey(value, workspacePath) {
+  if (typeof value !== 'string') return '';
   const source = unquoteShellWord(value);
-  if (!source) return '';
+  if (!source || source === '-' || source.startsWith('~') || /[$\x60*?\[\]{}]/.test(source)) return '';
   if (path.isAbsolute(source)) return path.normalize(source);
   return path.resolve(workspacePath || '.', source);
 }
@@ -355,6 +421,7 @@ module.exports = {
   createNoProgressError,
   createReadProgressController,
   createReadProgressGuard,
+  createRunEventScope,
   extractBoundedRange,
   extractReadInspection
 };