codex-overleaf-link 2.4.1 → 2.5.1

package/native-host/src/subagentBroker.js

@@ -19,6 +19,10 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { SUBAGENT_QUEUE_DIR } = require('./mirrorWorkspace');
+const { safeWorkspaceRelativePath } = require('./subagentWorkspacePath');
+const { estimateWorkerWaves } = require('./subagentAdmission');
+const { compactEvent, publicText } = require('./subagentTelemetry');
+const { createSubagentWorkspace } = require('./subagentWorkspace');
 
 const PROTOCOL_VERSION = 1;
 const JOB_ID_PATTERN = /^[a-z0-9-]{1,32}$/;
@@ -28,8 +32,8 @@ const SUMMARY_LIMIT_CHARS = 2048;
 const DEFAULT_LIMITS = Object.freeze({
   maxWorkers: 3,
   maxJobsPerRun: 8,
-  perWorkerTimeoutMs: 300000,
-  brokerBudgetMs: 900000,
+  perWorkerTimeoutMs: 600000,
+  brokerBudgetMs: 1800000,
   pollIntervalMs: 500,
   drainGraceMs: 30000
 });
@@ -43,15 +47,31 @@ function createSubagentBroker(options = {}) {
   if (typeof runWorkerTask !== 'function') {
     throw new Error('subagent broker requires a runWorkerTask function');
   }
-  const emit = typeof options.emit === 'function' ? options.emit : () => {};
+  const emit = (...args) => {
+    try { if (typeof options.emit === 'function') options.emit(...args); }
+    catch (_error) { /* Observability cannot prevent worker cleanup. */ }
+  };
   const onMirrorDirty = typeof options.onMirrorDirty === 'function' ? options.onMirrorDirty : () => {};
   const parentSignal = options.signal || null;
-  const limits = { ...DEFAULT_LIMITS, ...(options.limits || {}) };
+  const env = options.env || process.env;
+  const boundedMs = (value, fallback, max) => Number.isFinite(Number(value)) && Number(value) > 0
+    ? Math.min(max, Math.max(60000, Number(value))) : fallback;
+  const limits = { ...DEFAULT_LIMITS,
+    perWorkerTimeoutMs: boundedMs(env.CODEX_OVERLEAF_SUBAGENT_TIMEOUT_MS, DEFAULT_LIMITS.perWorkerTimeoutMs, 900000),
+    brokerBudgetMs: boundedMs(env.CODEX_OVERLEAF_SUBAGENT_BUDGET_MS, DEFAULT_LIMITS.brokerBudgetMs, 3600000),
+    ...(options.limits || {}) };
 
   const queueRoot = path.join(workspacePath, SUBAGENT_QUEUE_DIR);
   const jobsDir = path.join(queueRoot, 'jobs');
   const resultsDir = path.join(queueRoot, 'results');
   const logsDir = path.join(queueRoot, 'logs');
+  const { atomicWrite, appendLog, adoptionHash, hashWorkspace, hashPaths, buildWorkerPrompt } =
+    createSubagentWorkspace({ workspacePath, logsDir });
+  const adoptionsDir = path.join(queueRoot, 'adoptions');
+  const adoptionResultsDir = path.join(queueRoot, 'adoption-results');
+  const quarantined = new Map();
+  const seenAdoptions = new Set();
+  let adoptionToken = '';
 
   const jobs = new Map(); // id -> { job, status, startedAt, ownedBefore }
   const seenFiles = new Set();
@@ -68,6 +88,8 @@ function createSubagentBroker(options = {}) {
   let anyWorkerStarted = false;
   let cancelled = false;
   let closed = false;
+  let brokerError = null;
+  let stopping = null;
 
   function start() {
     // Stale queue dirs from a previous run carry old results/logs — clear
@@ -76,6 +98,8 @@ function createSubagentBroker(options = {}) {
     fs.mkdirSync(jobsDir, { recursive: true });
     fs.mkdirSync(resultsDir, { recursive: true });
     fs.mkdirSync(logsDir, { recursive: true });
+    fs.mkdirSync(adoptionsDir, { recursive: true });
+    fs.mkdirSync(adoptionResultsDir, { recursive: true });
     fs.mkdirSync(path.join(queueRoot, 'work'), { recursive: true });
     startedAt = Date.now();
     accepting = true;
@@ -94,16 +118,14 @@ function createSubagentBroker(options = {}) {
       maxJobsPerRun: limits.maxJobsPerRun,
       perWorkerTimeoutMs: limits.perWorkerTimeoutMs,
       brokerBudgetMs: limits.brokerBudgetMs,
+      activeWorkers: running.size,
+      adoptionToken,
+      adoptionDirectory: 'adoptions',
       acceptedUntil: new Date(startedAt + limits.brokerBudgetMs - limits.perWorkerTimeoutMs).toISOString()
     };
     atomicWrite(path.join(queueRoot, 'broker.json'), JSON.stringify(payload, null, 2));
   }
 
-  function atomicWrite(target, text) {
-    const tmp = path.join(path.dirname(target), `.tmp-${crypto.randomUUID()}`);
-    fs.writeFileSync(tmp, text);
-    fs.renameSync(tmp, target);
-  }
 
   function pollOnce() {
     if (closed || cancelled) {
@@ -112,11 +134,23 @@ function createSubagentBroker(options = {}) {
     try {
       intakeJobs();
       fillSlots();
-    } catch (_error) {
-      // The queue is adversarial model output; the broker never throws on it.
+      processAdoptions();
+    } catch (error) {
+      recordFailure(error);
     }
   }
 
+  function recordFailure(error, jobId) {
+    accepting = false;
+    if (brokerError) return;
+    brokerError = Object.assign(new Error('Subagent broker results or cleanup could not be persisted.'), {
+      code: 'subagent_io_failed', cause: error
+    });
+    emit('codex.subagent.failed', 'Subagent result storage failed', {
+      jobId, status: 'failed', reason: brokerError.message, code: brokerError.code
+    }, 'warning');
+  }
+
   function intakeJobs() {
     if (!accepting || !fs.existsSync(jobsDir)) {
       return;
@@ -154,15 +188,18 @@ function createSubagentBroker(options = {}) {
     acceptedCount += 1;
     jobs.set(job.id, { job, status: 'queued' });
     queued.push(job.id);
-    emit('codex.subagent.queued', job.title || job.id, { jobId: job.id, files: job.files }, 'running');
+    emit('codex.subagent.queued', publicText(job.title || job.id, 160), {
+      jobId: job.id, files: job.files, task: publicText(job.task, 4096)
+    }, 'running');
   }
 
   function idFromFileName(name) {
-    return name.replace(/\.json$/, '').slice(0, 32) || 'unknown';
+    const id = name.replace(/\.json$/, '');
+    return JOB_ID_PATTERN.test(id) ? id : `rejected-${crypto.randomBytes(11).toString('hex')}`;
   }
 
   function jobIdOrFallback(job, name) {
-    return typeof job?.id === 'string' && job.id ? job.id.slice(0, 32) : idFromFileName(name);
+    return typeof job?.id === 'string' && JOB_ID_PATTERN.test(job.id) ? job.id : idFromFileName(name);
   }
 
   function validateJob(job) {
@@ -195,13 +232,11 @@ function createSubagentBroker(options = {}) {
       }
       owned.push(safe);
     }
-    // Overlapping ownership no longer rejects: same-file jobs are admitted
-    // and SERIALIZED by the scheduler (fillSlots never runs two jobs whose
-    // files intersect). Prompt-scoped same-file delegation is then safe —
-    // the physical lost-update race only exists under concurrency (v1.6.1).
-    // Wave-aware admission: the parent turn has no default absolute deadline,
-    // so the broker enforces its own wall-clock envelope across ALL waves.
-    const projectedWaves = Math.ceil((queued.length + running.size + 1) / limits.maxWorkers);
+    // Reserve serial waves for overlapping ownership, matching fillSlots.
+    // The budget covers worker admission; parent/OS cleanup has separate limits.
+    const projectedWaves = estimateWorkerWaves(
+      [...running.keys()].map(id => jobs.get(id).job.files),
+      [...queued.map(id => jobs.get(id).job.files), owned], limits.maxWorkers);
     if (Date.now() + projectedWaves * limits.perWorkerTimeoutMs > startedAt + limits.brokerBudgetMs) {
       return { reason: 'insufficient_time' };
     }
@@ -212,30 +247,6 @@ function createSubagentBroker(options = {}) {
     return null;
   }
 
-  function safeWorkspaceRelativePath(value) {
-    if (typeof value !== 'string' || !value.trim()) {
-      return null;
-    }
-    const normalized = value.trim().replace(/\\/g, '/').replace(/^\.\//, '');
-    if (!normalized || path.isAbsolute(normalized)) {
-      return null;
-    }
-    const segments = normalized.split('/');
-    if (segments.some(segment => segment === '..' || segment === '')) {
-      return null;
-    }
-    if (segments[0] === SUBAGENT_QUEUE_DIR) {
-      // The queue control plane (jobs/results/logs/broker.json) is never
-      // ownable — but the work/ scratch zone IS: single-file fan-out slices
-      // live there (v1.6.1 scatter-gather), excluded from writeback by the
-      // mirror-scan rule yet fully owned/hashed like any other job file.
-      if (segments[1] === 'work' && segments.length >= 3) {
-        return segments.join('/');
-      }
-      return null;
-    }
-    return segments.join('/');
-  }
 
   function writeRejection(input) {
     const result = {
@@ -250,6 +261,10 @@ function createSubagentBroker(options = {}) {
   }
 
   function writeResult(result) {
+    // Rejection receipts cross the same filesystem boundary as accepted jobs.
+    if (typeof result.id !== 'string' || !JOB_ID_PATTERN.test(result.id)) {
+      throw new Error('Invalid subagent result ID');
+    }
     atomicWrite(path.join(resultsDir, `${result.id}.json`), JSON.stringify(result, null, 2));
   }
 
@@ -270,6 +285,11 @@ function createSubagentBroker(options = {}) {
       }
       const [jobId] = queued.splice(index, 1);
       const entry = jobs.get(jobId);
+      if (Date.now() + limits.perWorkerTimeoutMs > startedAt + limits.brokerBudgetMs) {
+        entry.status = 'rejected';
+        writeRejection({ id: jobId, reason: 'insufficient_time' });
+        continue;
+      }
       try {
         startWorker(entry);
       } catch (error) {
@@ -283,6 +303,9 @@ function createSubagentBroker(options = {}) {
         try {
           writeResult({ id: jobId, status: 'failed', reason: error?.message || 'subagent failed to start' });
         } catch (_writeError) { /* result dir may be gone */ }
+        emit('codex.subagent.failed', publicText(entry?.job?.title || jobId, 160), {
+          jobId, status: 'failed', reason: publicText(error?.message || 'subagent failed to start', 1200)
+        }, 'warning');
       }
     }
   }
@@ -313,8 +336,9 @@ function createSubagentBroker(options = {}) {
       controller.abort(new Error('subagent timeout'));
     }, limits.perWorkerTimeoutMs);
 
-    emit('codex.subagent.started', job.title || job.id, {
+    emit('codex.subagent.started', publicText(job.title || job.id, 160), {
       jobId: job.id,
+      task: publicText(job.task, 4096),
       files: job.files,
       activeWorkers: running.size + 1,
       maxWorkers: limits.maxWorkers
@@ -323,8 +347,23 @@ function createSubagentBroker(options = {}) {
     const promise = runWorkerTask({
       jobId: job.id,
       prompt: buildWorkerPrompt(job),
-      signal: controller.signal
+      signal: controller.signal,
+      onEvent: event => {
+        if (closed || entry.status !== 'running') return;
+        try {
+          const bounded = compactEvent(event);
+          if (!bounded) return;
+          const params = bounded.detail?.params || {};
+          entry.threadId = bounded.detail?.threadId || params.threadId || params.thread?.id || entry.threadId || '';
+          entry.sequence = (entry.sequence || 0) + 1;
+          emit('codex.subagent.event', publicText(job.title || job.id, 160), {
+            source: 'broker', jobId: job.id, threadId: entry.threadId,
+            sequence: entry.sequence, event: bounded
+          }, 'running');
+        } catch (_error) { /* Observability must not fail or stop the worker. */ }
+      }
     }).then(workerResult => {
+      if (controller.signal.aborted) throw controller.signal.reason || new Error('Subagent aborted');
       finishWorker(entry, {
         status: 'completed',
         summary: String(workerResult?.assistantMessage || '').slice(0, SUMMARY_LIMIT_CHARS),
@@ -332,21 +371,22 @@ function createSubagentBroker(options = {}) {
       }, workerResult);
     }).catch(error => {
       // Any broker-initiated abort that is not the wall-clock deadline
-      // (parent cancel, drain) reads as 'cancelled'; only genuine worker
-      // errors read as 'failed'.
-      const status = timedOut ? 'timeout' : controller.signal.aborted ? 'cancelled' : 'failed';
+      // (parent cancel, drain), or an interrupted worker turn, is cancelled.
+      const status = timedOut ? 'timeout' : controller.signal.aborted || error?.code === 'codex_cancelled' ? 'cancelled' : 'failed';
       appendLog(job.id, `${status}: ${error?.stack || error?.message || String(error)}`);
       finishWorker(entry, { status, reason: error?.message || String(error) });
-    }).finally(() => {
+    }).catch(error => recordFailure(error, job.id)).finally(() => {
       clearTimeout(deadlineTimer);
       running.delete(job.id);
       if (running.size === 0) {
         endWave();
       }
+      writeBrokerFile(closed ? 'closed' : 'ready');
       fillSlots();
-    });
+    }).catch(error => recordFailure(error, job.id));
 
     running.set(job.id, { controller, deadlineTimer, promise });
+    try { writeBrokerFile('ready'); } catch (error) { recordFailure(error, job.id); }
   }
 
   function finishWorker(entry, resultFields, workerResult) {
@@ -362,12 +402,13 @@ function createSubagentBroker(options = {}) {
       // demotion reads getViolationPaths() and drops these from writeback
       // (spec S8 safety extension, v1.6.2).
       for (const file of changedFiles) {
-        violationPaths.add(file);
+        quarantined.set(file, { jobId: job.id, status: resultFields.status, adoptedHash: '' });
       }
     }
     const result = {
       id: job.id,
       ...resultFields,
+      threadId: workerResult?.threadId || entry.threadId || '',
       changedFiles,
       durationMs: Date.now() - entry.startedAt
     };
@@ -377,24 +418,23 @@ function createSubagentBroker(options = {}) {
       atomicWrite(path.join(resultsDir, `${job.id}.last-message.md`), String(workerResult.assistantMessage));
     }
     const eventType = resultFields.status === 'completed' ? 'codex.subagent.completed' : 'codex.subagent.failed';
-    emit(eventType, job.title || job.id, {
+    emit(eventType, publicText(job.title || job.id, 160), {
       jobId: job.id,
+      threadId: result.threadId,
       status: resultFields.status,
-      reason: resultFields.reason,
+      reason: publicText(resultFields.reason, 1200),
+      summary: publicText(workerResult?.assistantMessage || resultFields.summary, 24000),
       changedFiles,
       durationMs: result.durationMs
     }, resultFields.status === 'completed' ? 'completed' : 'warning');
   }
 
-  function appendLog(jobId, text) {
-    try {
-      fs.appendFileSync(path.join(logsDir, `${jobId}.log`), `${new Date().toISOString()} ${text}\n`);
-    } catch (_error) { /* logs are best-effort */ }
-  }
 
   // ---- wave tracking (spec S5): owned attribution is per worker; unowned
   // changes can only be attributed to the wave's set of suspects.
   function beginWave() {
+    adoptionToken = '';
+    writeBrokerFile('ready');
     waveIndex += 1;
     waveSnapshot = {
       hashes: hashWorkspace(),
@@ -434,68 +474,48 @@ function createSubagentBroker(options = {}) {
       emit('codex.subagent.violation', file, violation, 'warning');
     }
     waveSnapshot = null;
+    if (!closed && !cancelled && accepting && running.size === 0) {
+      // Workers have exited before this capability is published. A worker
+      // cannot pre-authorize its own incomplete output while still running.
+      adoptionToken = crypto.randomBytes(24).toString('hex');
+    }
   }
 
-  function hashWorkspace() {
-    const hashes = new Map();
-    walk(workspacePath, '');
-    return hashes;
 
-    function walk(dir, prefix) {
-      let entries;
+  function processAdoptions() {
+    if (closed || cancelled || running.size || !adoptionToken || !fs.existsSync(adoptionsDir)) return;
+    for (const name of fs.readdirSync(adoptionsDir).filter(name => /^[a-z0-9-]{1,32}\.json$/.test(name)).slice(0, 64)) {
+      if (seenAdoptions.has(name)) continue;
+      seenAdoptions.add(name);
+      let result = { ok: false, reason: 'invalid_adoption' };
       try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
-      } catch (_error) {
-        return;
-      }
-      for (const entry of entries) {
-        // The whole queue zone (incl. the work/ slice scratch) stays out of
-        // wave hashing: scratch can never reach Overleaf, same-wave slices
-        // are all in the owned union anyway, and a lead staggering slice
-        // creation mid-wave must not read as a violation (v1.6.1).
-        if (entry.name === '.DS_Store' || entry.name === SUBAGENT_QUEUE_DIR || entry.name === '.codex-overleaf-attachments') {
-          continue;
-        }
-        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
-        const absolute = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-          walk(absolute, relative);
-        } else if (entry.isFile()) {
-          hashes.set(relative, hashFile(absolute));
+        const requestPath = path.join(adoptionsDir, name), stat = fs.lstatSync(requestPath);
+        if (!stat.isFile() || stat.size > MAX_JOB_FILE_BYTES) throw new Error('invalid_adoption_file');
+        const request = JSON.parse(fs.readFileSync(requestPath, 'utf8'));
+        if (request.token !== adoptionToken || request.reviewed !== true || !Array.isArray(request.files)
+          || !request.files.length || request.files.length > 100) throw new Error('adoption_not_authorized');
+        const approved = [];
+        for (const item of request.files) {
+          const safe = safeWorkspaceRelativePath(item?.path), held = quarantined.get(safe);
+          const entry = held && jobs.get(held.jobId);
+          if (!safe || !held || held.jobId !== item.jobId || !entry?.job?.files.includes(safe)
+            || violationPaths.has(safe) || !/^[a-f0-9]{64}$/i.test(item.sha256 || '')
+            || adoptionHash(safe) !== item.sha256.toLowerCase()) throw new Error('adoption_content_or_owner_mismatch');
+          approved.push({ path: safe, sha256: item.sha256.toLowerCase(), held });
         }
-      }
-    }
-  }
-
-  function hashPaths(files) {
-    const hashes = new Map();
-    for (const file of files) {
-      hashes.set(file, hashFile(path.join(workspacePath, file)));
+        for (const item of approved) item.held.adoptedHash = item.sha256;
+        result = { ok: true, files: approved.map(item => ({ path: item.path, sha256: item.sha256 })) };
+      } catch (error) { result = { ok: false, reason: String(error?.message || error).slice(0, 200) }; }
+      atomicWrite(path.join(adoptionResultsDir, name), JSON.stringify(result, null, 2));
     }
-    return hashes;
   }
 
-  function hashFile(absolute) {
-    try {
-      return crypto.createHash('sha1').update(fs.readFileSync(absolute)).digest('hex');
-    } catch (_error) {
-      return 'missing';
+  function blockedPaths() {
+    const blocked = new Set(violationPaths);
+    for (const [file, held] of quarantined) {
+      if (!held.adoptedHash || adoptionHash(file) !== held.adoptedHash) blocked.add(file);
     }
-  }
-
-  function buildWorkerPrompt(job) {
-    const readOnly = job.readOnlyContext.length
-      ? `- You may read these for context but must not modify them: ${job.readOnlyContext.join(', ')}.\n`
-      : '';
-    return [
-      'You are a subagent working on one slice of a larger task.',
-      'HARD CONSTRAINTS:',
-      `- You may modify ONLY these files: ${job.files.join(', ')}.`,
-      readOnly + '- Do not modify, create, or delete any other file. Inside .codex-overleaf-subagents/ you may touch ONLY the slice files listed above (if any).',
-      '- Work fully autonomously; nobody can answer questions.',
-      '',
-      job.task
-    ].join('\n');
+    return blocked;
   }
 
   function onParentAbort() {
@@ -504,62 +524,56 @@ function createSubagentBroker(options = {}) {
     for (const { controller } of running.values()) {
       controller.abort(new Error('run cancelled'));
     }
-    for (const jobId of queued.splice(0)) {
-      const entry = jobs.get(jobId);
-      entry.status = 'cancelled';
-      writeResult({ id: jobId, status: 'cancelled', reason: 'run cancelled' });
-    }
     if (anyWorkerStarted) {
-      // Partial worker edits must be deterministically discarded: cancellation
-      // already skips writeback, and the dirty mark forces the next run's
-      // mirror sync to rebuild the workspace from Overleaf (spec P1-3 fix).
-      onMirrorDirty();
+      try { onMirrorDirty(); } catch (error) { recordFailure(error); }
     }
-    close();
+    // Event listeners cannot expose an async rejection. The same sticky stop
+    // promise is still awaited by the parent runner and reports any I/O error.
+    stop({ drain: false }).catch(() => {});
   }
 
-  async function stop({ drain = true } = {}) {
-    accepting = false;
-    // Queued-but-unstarted jobs would otherwise vanish with no result file,
-    // hanging a lead still polling for its job count. Settle them first
-    // (mirrors onParentAbort's queue handling).
+  function cancelQueued(reason) {
     for (const jobId of queued.splice(0)) {
       const entry = jobs.get(jobId);
-      if (entry) {
-        entry.status = 'cancelled';
-      }
-      writeResult({ id: jobId, status: 'cancelled', reason: 'The run ended before this subagent started.' });
-    }
-    if (drain && running.size) {
-      let graceTimer = null;
-      const grace = new Promise(resolve => {
-        graceTimer = setTimeout(resolve, limits.drainGraceMs);
-      });
-      await Promise.race([
-        Promise.allSettled([...running.values()].map(worker => worker.promise)),
-        grace
-      ]);
-      // The grace timer gates an awaited race; if the workers settled first it
-      // must be cleared or it keeps the event loop alive for drainGraceMs
-      // (the "keep timers gated, then clear" discipline from c3cd357).
-      if (graceTimer) {
-        clearTimeout(graceTimer);
-      }
+      if (entry) entry.status = 'cancelled';
+      try { writeResult({ id: jobId, status: 'cancelled', reason }); }
+      catch (error) { recordFailure(error, jobId); }
+      emit('codex.subagent.failed', publicText(entry?.job?.title || jobId, 160), {
+        jobId, status: 'cancelled', reason
+      }, 'warning');
     }
-    for (const { controller } of running.values()) {
-      controller.abort(new Error('broker drained'));
+  }
+
+  function stop({ drain = true } = {}) {
+    accepting = false;
+    if (!stopping) stopping = Promise.resolve().then(() => stopWorkers(drain));
+    return stopping.then(() => { if (brokerError) throw brokerError; });
+  }
+
+  async function stopWorkers(drain) {
+    accepting = false;
+    try {
+      try { processAdoptions(); } catch (error) { recordFailure(error); }
+      cancelQueued(cancelled ? 'run cancelled' : 'The run ended before this subagent started.');
+      if (drain && !cancelled && !brokerError) await settleRunningWithin(limits.drainGraceMs);
+    } finally {
+      for (const { controller } of running.values()) controller.abort(new Error('broker drained'));
+      // Keep bounded waiting for workers that ignore abort; their own deadline
+      // remains active until settlement. OS exit proof belongs to the runner.
+      try { await settleRunningWithin(limits.drainGraceMs); } finally {
+        for (const jobId of running.keys()) for (const file of jobs.get(jobId).job.files) {
+          quarantined.set(file, { jobId, status: 'cancelled', adoptedHash: '' });
+        }
+        close();
+      }
     }
-    // Bounded final settle: a worker that ignores its abort must not hang
-    // stop() forever — that strands codex.run and leaks the project lock (the
-    // very zombie-lock case handleCodexCancel exists to recover from).
-    await settleRunningWithin(limits.drainGraceMs);
     if (jobs.size) {
       emit('codex.subagent.drained', 'subagents drained', {
         jobs: jobs.size,
         violations: violations.length
-      }, 'completed');
+      }, brokerError ? 'warning' : 'completed');
     }
-    close();
+    if (brokerError) throw brokerError;
   }
 
   async function settleRunningWithin(timeoutMs) {
@@ -590,7 +604,7 @@ function createSubagentBroker(options = {}) {
     parentSignal?.removeEventListener?.('abort', onParentAbort);
     try {
       writeBrokerFile('closed');
-    } catch (_error) { /* workspace may already be gone */ }
+    } catch (error) { recordFailure(error); }
   }
 
   return {
@@ -599,7 +613,8 @@ function createSubagentBroker(options = {}) {
     pollOnce,
     hasActiveWorkers: () => running.size > 0,
     hasAcceptedJobs: () => jobs.size > 0,
-    getViolationPaths: () => new Set(violationPaths),
+    getViolationPaths: blockedPaths,
+    getBlockedReason: file => violationPaths.has(file) ? 'subagent_unauthorized_edit' : 'subagent_unfinished_output',
     getAuditSummary: () => ({
       jobs: [...jobs.values()].map(entry => ({
         id: entry.job?.id,
@@ -609,7 +624,9 @@ function createSubagentBroker(options = {}) {
         reason: entry.result?.reason,
         durationMs: entry.result?.durationMs
       })),
-      violations: violations.slice()
+      violations: violations.slice(),
+      quarantined: [...quarantined].map(([file, item]) => ({ path: file, jobId: item.jobId, status: item.status,
+        adopted: Boolean(item.adoptedHash && adoptionHash(file) === item.adoptedHash) }))
     })
   };
 }