codex-overleaf-link 2.5.0 → 2.6.0

package/native-host/src/responsesPassthroughBridge.js

@@ -4,6 +4,7 @@ const crypto = require('node:crypto');
 const http = require('node:http');
 const { classifyResponsesRoute } = require('./providerBridgeRoutes');
 const { providerError } = require('./providerProfile');
+const { fetchProvider, readProviderText } = require('./providerHttp');
 const { sanitizeProviderMessage } = require('./providerRedaction');
 const { logDebug } = require('./debugLog');
 const {
@@ -19,6 +20,7 @@ const MAX_HISTORY_ITEMS = 4096;
 const MAX_HISTORY_BYTES = 32 * 1024 * 1024;
 const MAX_DUPLICATE_CONTINUATIONS = 2;
 const MAX_STREAM_BUFFER_BYTES = 8 * 1024 * 1024;
+const MAX_COMPACT_RESPONSE_BYTES = 32 * 1024 * 1024;
 const DEFAULT_MAX_OUTPUT_TOKENS = 65536;
 const CONTINUATION_MARKER = '[codex-overleaf-provider-reasoning-continuation]';
 
@@ -102,7 +104,7 @@ async function handleRequest({ req, res, launch, clientToken, activeRequests, hi
   const prepared = route === 'responses'
     ? prepareResponsesRequest({ requestBody, launch, history, previous, originalPreviousResponseId })
     : {
-        body: { ...requestBody },
+        body: { ...(launch.bodyOverrides || {}), ...requestBody, previous_response_id: requestBody.previous_response_id },
         currentInput: normalizeInputItems(requestBody.input),
         replayed: false
       };
@@ -140,19 +142,19 @@ async function handleRequest({ req, res, launch, clientToken, activeRequests, hi
   res.on('close', onClientClose);
   lifecycle.start();
   try {
-    const upstream = await fetch(buildResponsesUrl(launch.baseUrl, launch, route), {
+    const upstream = await fetchProvider(buildResponsesUrl(launch.baseUrl, launch, route), {
       method: 'POST',
       headers: buildUpstreamHeaders(launch),
       body: JSON.stringify(prepared.body),
       signal: controller.signal
-    });
+    }, launch);
     lifecycle.touch();
     if (!upstream.ok) {
-      await forwardUpstreamError(upstream, res, launch.apiKey);
+      await forwardUpstreamError(upstream, res, launch.apiKey, lifecycle.touch);
       return;
     }
     if (route === 'compact') {
-      await forwardOpaqueResponse(upstream, res, lifecycle.touch);
+      await forwardCompactResponse(upstream, res, lifecycle.touch, launch.apiKey);
       return;
     }
 
@@ -165,11 +167,18 @@ async function handleRequest({ req, res, launch, clientToken, activeRequests, hi
           'The provider returned a non-streaming payload for a streaming Responses request.'
         );
       }
-      response = await forwardResponsesSse(upstream, res, lifecycle.touch);
+      response = await forwardResponsesSse(upstream, res, lifecycle.touch, launch.apiKey);
     } else {
-      response = await upstream.json();
+      const text = await readProviderText(upstream, lifecycle.touch);
+      try {
+        response = JSON.parse(text);
+      } catch (_error) {
+        throw providerError('provider_response_invalid', 'The provider returned an invalid Responses JSON response.');
+      }
       lifecycle.touch();
-      sendJson(res, 200, response);
+      sanitizeProtocolErrors(response, launch.apiKey, hasDuplicateJsonKeys(text));
+      if (requestBody.stream !== false) writeBufferedResponseAsSse(res, response);
+      else sendJson(res, 200, response);
     }
     if (response?.id) {
       rememberResponse(history, {
@@ -228,7 +237,10 @@ async function handleRequest({ req, res, launch, clientToken, activeRequests, hi
 function prepareResponsesRequest({ requestBody, launch, history, previous, originalPreviousResponseId }) {
   const currentInput = normalizeInputItems(requestBody.input);
   const body = {
+    ...(launch.bodyOverrides || {}),
     ...requestBody,
+    previous_response_id: requestBody.previous_response_id,
+    stream: requestBody.stream !== false && launch.upstreamResponseMode !== 'buffered',
     max_output_tokens: resolveMaxOutputTokens(launch.maxOutputTokens, requestBody.max_output_tokens)
   };
   if (!previous?.continuationRequired) {
@@ -405,7 +417,75 @@ function resolveMaxOutputTokens(configured, requested) {
   return Math.max(1, Math.floor(value));
 }
 
-async function forwardResponsesSse(upstream, res, onActivity) {
+function writeBufferedResponseAsSse(res, response) {
+  if (!response || typeof response !== 'object' || Array.isArray(response)) {
+    throw providerError('provider_response_invalid', 'The provider returned an invalid Responses JSON response.');
+  }
+  if (!response.error && !['completed', 'incomplete', 'failed'].includes(response.status)) {
+    throw providerError('provider_response_invalid', 'The buffered Responses request did not return a terminal response.');
+  }
+  res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache, no-store' });
+  let sequence = 0;
+  const emit = (type, detail) => {
+    const frame = `event: ${type}\ndata: ${JSON.stringify({ type, sequence_number: sequence++, ...detail })}\n\n`;
+    if (Buffer.byteLength(frame, 'utf8') > MAX_STREAM_BUFFER_BYTES) {
+      throw providerError('provider_stream_frame_too_large', 'Provider stream frame exceeded the local bridge limit.');
+    }
+    res.write(frame);
+  };
+  if (response.error && !Array.isArray(response.output)) {
+    emit('error', { ...response, type: 'error' });
+    res.end();
+    return;
+  }
+  const pending = { ...response, status: 'in_progress', output: [], usage: null, error: null, incomplete_details: null };
+  emit('response.created', { response: pending });
+  emit('response.in_progress', { response: pending });
+  for (const [output_index, item] of (response.output || []).entries()) {
+    const identity = { item_id: item.id, output_index };
+    const added = { ...item, status: 'in_progress' };
+    if (item.type === 'message') added.content = [];
+    if (item.type === 'reasoning') added.summary = [];
+    if (item.type === 'function_call') added.arguments = '';
+    if (item.type === 'custom_tool_call') added.input = '';
+    emit('response.output_item.added', { output_index, item: added });
+    for (const [content_index, part] of (item.content || []).entries()) {
+      const detail = { ...identity, content_index };
+      const emptyPart = part.type === 'refusal' ? { ...part, refusal: '' }
+        : { ...part, ...(typeof part.text === 'string' ? { text: '' } : {}) };
+      emit('response.content_part.added', { ...detail, part: emptyPart });
+      if (part.type === 'output_text') {
+        if (part.text) emit('response.output_text.delta', { ...detail, delta: part.text, logprobs: [] });
+        emit('response.output_text.done', { ...detail, text: part.text || '', logprobs: [] });
+      } else if (part.type === 'refusal') {
+        if (part.refusal) emit('response.refusal.delta', { ...detail, delta: part.refusal });
+        emit('response.refusal.done', { ...detail, refusal: part.refusal || '' });
+      }
+      emit('response.content_part.done', { ...detail, part });
+    }
+    for (const [summary_index, part] of (item.summary || []).entries()) {
+      const detail = { ...identity, summary_index };
+      emit('response.reasoning_summary_part.added', { ...detail, part: { ...part, text: '' } });
+      if (part.text) emit('response.reasoning_summary_text.delta', { ...detail, delta: part.text });
+      emit('response.reasoning_summary_text.done', { ...detail, text: part.text || '' });
+      emit('response.reasoning_summary_part.done', { ...detail, part });
+    }
+    if (item.type === 'function_call' || item.type === 'custom_tool_call') {
+      const custom = item.type === 'custom_tool_call';
+      const value = custom ? item.input : item.arguments;
+      const event = custom ? 'response.custom_tool_call_input' : 'response.function_call_arguments';
+      if (value) emit(event + '.delta', { ...identity, delta: value });
+      emit(event + '.done', { ...identity, [custom ? 'input' : 'arguments']: value || (custom ? '' : '{}') });
+    }
+    emit('response.output_item.done', { output_index, item });
+  }
+  const status = response.error || response.status === 'failed' ? 'failed'
+    : response.status === 'incomplete' ? 'incomplete' : 'completed';
+  emit('response.' + status, { response });
+  res.end();
+}
+
+async function forwardResponsesSse(upstream, res, onActivity, apiKey) {
   res.writeHead(200, {
     'content-type': 'text/event-stream; charset=utf-8',
     'cache-control': 'no-cache, no-store',
@@ -415,67 +495,199 @@ async function forwardResponsesSse(upstream, res, onActivity) {
     throw providerError('provider_response_invalid', 'The provider returned an empty Responses stream.');
   }
   const reader = upstream.body.getReader();
-  const decoder = new TextDecoder();
-  const observer = { buffer: '', terminalResponse: null };
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    onActivity();
-    observeSseText(observer, decoder.decode(value, { stream: true }));
-    if (!res.writableEnded) res.write(Buffer.from(value));
-  }
-  observeSseText(observer, decoder.decode(), true);
+  const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+  const observer = { buffer: '', position: 0, lineStart: 0, terminalResponse: null };
+  const forward = frame => {
+    const safeFrame = inspectSseFrame(observer, frame, apiKey);
+    if (!res.writableEnded) res.write(safeFrame);
+  };
+  let complete = false;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      onActivity();
+      forwardSseText(observer, decoder.decode(value, { stream: true }), forward);
+    }
+    forwardSseText(observer, decoder.decode(), forward, true);
+    complete = true;
+  } finally {
+    if (!complete) await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
   if (!res.writableEnded) res.end();
   return observer.terminalResponse;
 }
 
-function observeSseText(observer, text, flush = false) {
+function forwardSseText(observer, text, forward, flush = false) {
   observer.buffer += text;
+  // Hold each event until its diagnostics can be inspected. Line endings and
+  // successful frames remain intact, including CRLF split across HTTP chunks.
+  while (observer.position < observer.buffer.length) {
+    const position = observer.position;
+    const char = observer.buffer[position];
+    if (char !== '\r' && char !== '\n') { observer.position += 1; continue; }
+    if (char === '\r' && position + 1 === observer.buffer.length && !flush) break;
+    const end = position + (char === '\r' && observer.buffer[position + 1] === '\n' ? 2 : 1);
+    if (position === observer.lineStart) {
+      forward(observer.buffer.slice(0, end));
+      observer.buffer = observer.buffer.slice(end);
+      observer.position = observer.lineStart = 0;
+    } else {
+      observer.position = observer.lineStart = end;
+    }
+  }
   if (Buffer.byteLength(observer.buffer, 'utf8') > MAX_STREAM_BUFFER_BYTES) {
     throw providerError('provider_stream_frame_too_large', 'Provider stream frame exceeded the local bridge limit.');
   }
-  let match;
-  while ((match = /\r?\n\r?\n/.exec(observer.buffer))) {
-    const block = observer.buffer.slice(0, match.index);
-    observer.buffer = observer.buffer.slice(match.index + match[0].length);
-    observeSseBlock(observer, block);
-  }
   if (flush && observer.buffer.trim()) {
-    observeSseBlock(observer, observer.buffer);
+    forward(observer.buffer);
     observer.buffer = '';
   }
 }
 
-function observeSseBlock(observer, block) {
-  const data = String(block || '')
-    .split(/\r?\n/)
-    .filter(line => line.startsWith('data:'))
-    .map(line => line.slice(5).trimStart())
-    .join('\n');
-  if (!data || data === '[DONE]') return;
+function inspectSseFrame(observer, frame, apiKey) {
+  if (Buffer.byteLength(frame, 'utf8') > MAX_STREAM_BUFFER_BYTES) {
+    throw providerError('provider_stream_frame_too_large', 'Provider stream frame exceeded the local bridge limit.');
+  }
+  const parts = frame.split(/(\r\n|\r|\n)/);
+  const dataIndexes = [];
+  let event = '';
+  for (let index = 0; index < parts.length; index += 2) {
+    const line = parts[index].replace(/^\uFEFF/, '');
+    if (/^data(?::|$)/.test(line)) dataIndexes.push(index);
+    if (line.startsWith('event:')) event = line.slice(6).replace(/^ /, '');
+  }
+  const failedEvent = ['error', 'response.failed', 'response.error'].includes(event);
+  if (!dataIndexes.length && !failedEvent) return frame;
+  const data = dataIndexes.map(index => parts[index].replace(/^\uFEFF/, '').replace(/^data:? ?/, '')).join('\n');
+  if ((!data || data === '[DONE]') && !failedEvent) return frame;
+  let payload;
   try {
-    const payload = JSON.parse(data);
-    if (['response.completed', 'response.incomplete', 'response.failed'].includes(payload?.type) && payload.response) {
-      observer.terminalResponse = payload.response;
+    payload = JSON.parse(data);
+  } catch (_error) {
+    throw providerError('provider_response_invalid', 'The provider returned an invalid Responses stream event.');
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw providerError('provider_response_invalid', 'The provider returned an invalid Responses stream event.');
+  }
+  const changed = sanitizeProtocolErrors(payload, apiKey, failedEvent || hasDuplicateJsonKeys(data));
+  if (['response.completed', 'response.incomplete', 'response.failed'].includes(payload.type || event) && payload.response) {
+    observer.terminalResponse = payload.response;
+  }
+  if (!changed) return frame;
+  parts[dataIndexes[0]] = `data: ${JSON.stringify(payload)}`;
+  for (const index of dataIndexes.slice(1)) parts[index] = parts[index + 1] = '';
+  return parts.join('');
+}
+
+function sanitizeProtocolErrors(payload, apiKey, failedEvent = false) {
+  let changed = false;
+  const clean = value => {
+    if (typeof value === 'string' && value) {
+      const safe = sanitizeProviderMessage(value, [apiKey], MAX_ERROR_BYTES);
+      changed ||= safe !== value;
+      return safe;
     }
-  } catch (_error) {}
+    if (value && typeof value === 'object') {
+      for (const key of Object.keys(value)) value[key] = clean(value[key]);
+    }
+    return value;
+  };
+  const visit = (value, inheritedFailure) => {
+    if (!value || typeof value !== 'object') return;
+    if (value.error != null) { changed = true; value.error = clean(value.error); }
+    const failed = inheritedFailure || ['error', 'response.failed', 'response.error'].includes(value.type)
+      || ['failed', 'error'].includes(value.status);
+    if (failed) {
+      // Re-encode failures even when the surviving values need no replacement:
+      // duplicate JSON keys must not retain an earlier raw diagnostic value.
+      changed = true;
+      for (const key of ['message', 'code', 'param', 'detail', 'details', 'reason', 'description']) {
+        if (value[key] != null) value[key] = clean(value[key]);
+      }
+    }
+    // Response envelopes carry diagnostics; model output and tool arguments
+    // retain their original protocol semantics, even if they resemble secrets.
+    visit(value.response, failed);
+  };
+  visit(payload, failedEvent);
+  return changed;
 }
 
-async function forwardOpaqueResponse(upstream, res, onActivity) {
-  const contentType = upstream.headers.get('content-type') || 'application/json; charset=utf-8';
-  res.writeHead(upstream.status, { 'content-type': contentType, 'cache-control': 'no-store' });
+function hasDuplicateJsonKeys(text) {
+  // Called only after JSON.parse succeeds. Track keys per object and skip
+  // entire string values, including JSON-looking tool arguments. A duplicate
+  // can hide both an error value and an earlier failed status, so its protocol
+  // diagnostics require cleaning even when the surviving status is completed.
+  const stack = [];
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '{') stack.push({ keys: new Set(), expectsKey: true });
+    else if (char === '[') stack.push(null);
+    else if (char === '}' || char === ']') stack.pop();
+    else if (char === ',' && stack.at(-1)) stack.at(-1).expectsKey = true;
+    else if (char === '"') {
+      let end = index;
+      while (true) {
+        end = text.indexOf('"', end + 1);
+        let backslashes = 0;
+        for (let at = end - 1; text[at] === '\\'; at -= 1) backslashes += 1;
+        if (backslashes % 2 === 0) break;
+      }
+      const object = stack.at(-1);
+      if (object?.expectsKey) {
+        const key = JSON.parse(text.slice(index, end + 1));
+        if (object.keys.has(key)) return true;
+        object.keys.add(key);
+        object.expectsKey = false;
+      }
+      index = end;
+    }
+  }
+  return false;
+}
+
+async function forwardCompactResponse(upstream, res, onActivity, apiKey) {
   if (!upstream.body) {
-    res.end();
-    return;
+    throw providerError('provider_response_invalid', 'The provider returned an empty compact response.');
   }
   const reader = upstream.body.getReader();
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    onActivity();
-    if (!res.writableEnded) res.write(Buffer.from(value));
+  const chunks = [];
+  let bytes = 0;
+  let complete = false;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      onActivity();
+      bytes += value.byteLength;
+      if (bytes > MAX_COMPACT_RESPONSE_BYTES) {
+        throw providerError('provider_response_too_large', 'The compact response exceeded the 32 MiB local bridge limit.');
+      }
+      chunks.push(Buffer.from(value));
+    }
+    complete = true;
+  } finally {
+    if (!complete) await reader.cancel().catch(() => {});
+    reader.releaseLock();
   }
-  if (!res.writableEnded) res.end();
+  const body = Buffer.concat(chunks, bytes);
+  let text;
+  let payload;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(body);
+    payload = JSON.parse(text);
+  } catch (_error) {
+    throw providerError('provider_response_invalid', 'The provider returned an invalid compact JSON response.');
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw providerError('provider_response_invalid', 'The provider returned an invalid compact JSON response.');
+  }
+  const changed = sanitizeProtocolErrors(payload, apiKey, hasDuplicateJsonKeys(text));
+  const contentType = upstream.headers.get('content-type') || 'application/json; charset=utf-8';
+  res.writeHead(upstream.status, { 'content-type': contentType, 'cache-control': 'no-store' });
+  if (!res.writableEnded) res.end(changed ? JSON.stringify(payload) : body);
 }
 
 function buildResponsesUrl(baseUrl, launch = {}, route = 'responses') {
@@ -521,8 +733,8 @@ function buildUpstreamHeaders(launch = {}) {
   return headers;
 }
 
-async function forwardUpstreamError(upstream, res, apiKey) {
-  const text = (await upstream.text()).slice(0, MAX_ERROR_BYTES);
+async function forwardUpstreamError(upstream, res, apiKey, onActivity) {
+  const text = (await readProviderText(upstream, onActivity)).slice(0, MAX_ERROR_BYTES);
   let message = `Provider returned HTTP ${upstream.status}.`;
   try {
     const parsed = JSON.parse(text);
@@ -555,12 +767,14 @@ function normalizeBridgeErrorCode(value) {
   return [
     'provider_connection_timeout',
     'provider_response_invalid',
+    'provider_response_too_large',
     'provider_protocol_incompatible',
     'provider_request_invalid',
     'provider_request_too_large',
     'provider_responses_continuation_repeated',
     'provider_responses_continuation_unrecoverable',
-    'provider_continuation_history_limit'
+    'provider_continuation_history_limit',
+    'provider_upstream_error'
   ].includes(value) ? value : 'provider_bridge_failed';
 }
 

package/native-host/src/runtimeInstaller.js

@@ -18,16 +18,36 @@ function buildRuntimeFileManifest(options = {}) {
     fileEntry(packageRoot, 'package.json'),
     ...directoryEntries(packageRoot, 'native-host/src'),
     ...directoryEntries(packageRoot, 'extension/src/shared'),
+    ...bootstrapPayloadEntries(packageRoot),
     fileEntry(packageRoot, 'scripts/codex-json-agent.mjs'),
     fileEntry(packageRoot, 'scripts/install-native-host.mjs'),
     fileEntry(packageRoot, 'scripts/uninstall-native-host.mjs')
   ];
 
   return files
-    .filter((entry) => !allowedFiles || allowedFiles.has(entry.relativePath))
+    .filter((entry) => !allowedFiles || allowedFiles.has(entry.sourceRelativePath || entry.relativePath))
     .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
 }
 
+// Source packages hold one authoritative Bootstrap tree. Materialize its copy
+// under the native-host namespace accepted by the already-published updater.
+// Standalone Native tarballs already contain that mapped copy.
+function bootstrapPayloadEntries(packageRoot) {
+  const sourceDir = 'extension/bootstrap';
+  const payloadDir = 'native-host/bootstrap-payload';
+  if (!fs.existsSync(path.join(packageRoot, sourceDir))) {
+    return fs.existsSync(path.join(packageRoot, payloadDir)) ? directoryEntries(packageRoot, payloadDir) : [];
+  }
+  return directoryEntries(packageRoot, sourceDir).map(entry => {
+    const filename = path.posix.relative(sourceDir, entry.relativePath);
+    return {
+      ...entry,
+      sourceRelativePath: entry.relativePath,
+      relativePath: path.posix.join(payloadDir, filename === 'manifest.template.json' ? filename : 'bootstrap/' + filename)
+    };
+  });
+}
+
 function assertSafeManagedRuntimeRoot(runtimeRoot, options = {}) {
   if (!runtimeRoot || typeof runtimeRoot !== 'string') {
     throw new Error('Runtime root is required');

package/native-host/src/selectionScope.js

@@ -29,13 +29,40 @@ function prepareSelectionScope(value, workspacePath, projectId) {
     if (error.code === 'selected_context_unresolved') throw error;
     throw invalid('The selected file could not be read. Select it again after the project is synchronized.');
   }
-  const digest = crypto.createHash('sha256').update(before, 'utf8').digest('hex');
-  if (digest !== selection.documentHash || before.slice(selection.from, selection.to) !== selection.text) {
-    throw invalid('The document changed after the selection was captured. Select the passage again before editing.');
+  const digest = hash(before);
+  if (digest === selection.documentHash && before.slice(selection.from, selection.to) === selection.text) {
+    return { selection, before };
   }
-  return { selection, before };
+  const proof = selection.rebaseEvidence;
+  const candidates = new Map();
+  const add = (from, to) => {
+    if (Number.isSafeInteger(from) && from >= 0 && to <= before.length
+      && before.slice(from, to) === selection.text) candidates.set(from + ':' + to, { from, to });
+  };
+  if (proof) {
+    // Full flanks define positions; never search for a possibly repeated passage.
+    if (selection.from <= before.length && hash(before.slice(0, selection.from)) === proof.prefixHash) {
+      add(selection.from, selection.from + selection.text.length);
+    }
+    const suffixLength = proof.documentLength - selection.to;
+    const to = before.length - suffixLength;
+    if (to >= 0 && hash(before.slice(to)) === proof.suffixHash) add(to - selection.text.length, to);
+  }
+  if (candidates.size !== 1) {
+    throw invalid('The selected passage could not be safely mapped to the changed document. Select it again before editing.');
+  }
+  const { from, to } = [...candidates.values()][0];
+  const rebased = SelectionContext.normalize({ ...selection, from, to, documentHash: digest,
+    lineStart: before.slice(0, from).split('\n').length,
+    lineEnd: before.slice(0, Math.max(from, to - 1)).split('\n').length,
+    rebaseEvidence: { v: 1, documentLength: before.length,
+      prefixHash: hash(before.slice(0, from)), suffixHash: hash(before.slice(to)) } });
+  return { selection: rebased, before, rebased: true,
+    original: { from: selection.from, to: selection.to, documentHash: selection.documentHash } };
 }
 
+function hash(value) { return crypto.createHash('sha256').update(value, 'utf8').digest('hex'); }
+
 function filterSelectionChanges(changes, scope) {
   const items = Array.isArray(changes) ? changes : [];
   if (scope?.selection?.mode !== 'edit') return { changes: items, unsupportedChanges: [] };
@@ -46,11 +73,12 @@ function filterSelectionChanges(changes, scope) {
     && change.previousContent === before && typeof change.content === 'string'
     && change.content.length >= prefix.length + suffix.length
     && change.content.startsWith(prefix) && change.content.endsWith(suffix);
-  if (items.every(withinSelection)) return { changes: items, unsupportedChanges: [] };
+  const selectedPathCount = items.filter(change => change?.path === selection.path).length;
+  const allowed = change => selectedPathCount === 1 && withinSelection(change);
   return {
-    changes: [],
-    unsupportedChanges: items.map(change => ({
-      type: 'unsupported-local-file', path: change.path, reason: 'selection_scope_violation'
+    changes: items.filter(allowed),
+    unsupportedChanges: items.filter(change => !allowed(change)).map(change => ({
+      type: 'unsupported-local-file', path: change?.path || '', reason: 'selection_scope_violation'
     }))
   };
 }

package/native-host/src/subagentAdmission.js

@@ -0,0 +1,26 @@
+'use strict';
+
+// Project the broker's FIFO-with-skip scheduler in worker-budget-sized waves.
+// Running workers reserve their current wave; queued files are already canonical.
+// This is admission accounting, not a timer for the parent turn or OS cleanup.
+function estimateWorkerWaves(runningFiles, queuedFiles, maxWorkers) {
+  const pending = queuedFiles.slice();
+  let active = runningFiles.slice();
+  let waves = 0;
+  while (active.length || pending.length) {
+    const occupied = new Set(active.flat());
+    while (active.length < maxWorkers) {
+      const index = pending.findIndex(files => !files.some(file => occupied.has(file)));
+      if (index === -1) break;
+      const [files] = pending.splice(index, 1);
+      active.push(files);
+      for (const file of files) occupied.add(file);
+    }
+    if (!active.length) return Infinity;
+    waves += 1;
+    active = [];
+  }
+  return waves;
+}
+
+module.exports = { estimateWorkerWaves };