@lincoln504/pi-research 1.1.2 → 1.3.0

package/src/stackexchange/rest-client.ts

@@ -7,9 +7,20 @@ import type { StackExchangeWrapper } from './types.ts';
 import { logger } from '../logger.ts';
 import { CircuitBreaker } from '../utils/circuit-breaker.ts';
 import { metrics } from '../utils/metrics.ts';
+import { readJsonCapped, BodyTooLargeError } from '../utils/http-body.ts';
 
 const API_BASE = 'https://api.stackexchange.com/2.3';
 
+// How long quota-exhaustion evidence keeps the request gate armed. quotaRemaining
+// is only refreshed from a successful response, and the tool-level gate
+// (stackexchange/index.ts) blocks every request while isQuotaExhausted() — so a
+// plain `quotaRemaining <= 0` check could never observe SE's real daily reset and
+// wedged the process-wide client until restart or an API-key change. After the
+// cooldown one probe request is allowed: it either refreshes the quota (clearing
+// the stamp) or shows 0 / throttles again, re-arming the gate — at most one
+// wasted request per cooldown.
+const QUOTA_PROBE_COOLDOWN_MS = 10 * 60 * 1000;
+
 export interface RequestOptions {
   method: string;
   endpoint: string;
@@ -21,6 +32,9 @@ export class StackExchangeClient {
   private readonly _timeout: number;
   private quotaRemaining = 300;
   private quotaMax = 300;
+  // Timestamp of the last quota-exhaustion evidence (a response reporting
+  // quota_remaining <= 0, or a throttle_violation API error). null = no evidence.
+  private quotaExhaustedAt: number | null = null;
   private requestCount = 0;
   private lastBackoff: number | null = null;
   private circuitBreaker: CircuitBreaker;
@@ -99,7 +113,7 @@ export class StackExchangeClient {
 
         // NB: the timeout is cleared in `finally`, not here. Clearing it now —
         // when only the headers have arrived — would leave the body read
-        // (response.json() below) with no timeout, so a stalled body could hang
+        // (readJsonCapped below) with no timeout, so a stalled body could hang
         // for the whole process lifetime.
 
         // The SE API returns a structured JSON wrapper (with error_id) even for
@@ -109,8 +123,11 @@ export class StackExchangeClient {
         // "Unexpected token <" SyntaxError that hides the real cause.
         let data: StackExchangeWrapper<T>;
         try {
-          data = await response.json() as StackExchangeWrapper<T>;
+          data = await readJsonCapped<StackExchangeWrapper<T>>(response);
         } catch (parseErr) {
+          // An over-cap body is a size failure, not a malformed-JSON one: rethrow
+          // it unwrapped so it can't be relabelled as an HTTP-status error below.
+          if (parseErr instanceof BodyTooLargeError) throw parseErr;
           if (!response.ok) throw new Error(`HTTP ${response.status} from Stack Exchange API`, { cause: parseErr });
           throw parseErr;
         }
@@ -118,6 +135,12 @@ export class StackExchangeClient {
         // Handle API errors
         if (data.error_id) {
           const errorName = data.error_name ?? 'unknown';
+          // A throttle_violation is quota-exhaustion evidence even though no
+          // quota_remaining arrives with it (this throw happens before the quota
+          // update below) — stamp it so the gate arms/re-arms.
+          if (errorName === 'throttle_violation') {
+            this.quotaExhaustedAt = Date.now();
+          }
           metrics.increment('stackexchange_errors_total', 1, { 
             endpoint: options.endpoint, 
             error_id: data.error_id.toString(),
@@ -132,6 +155,15 @@ export class StackExchangeClient {
         this.quotaRemaining = data.quota_remaining;
         this.quotaMax = data.quota_max;
         this.requestCount++;
+        // Stamp (or clear) exhaustion evidence: isQuotaExhausted() reads the
+        // stamp, not quotaRemaining — which can never refresh while the gate
+        // blocks requests — so a probe after the cooldown self-corrects once
+        // SE's daily reset has happened.
+        if (data.quota_remaining <= 0) {
+          this.quotaExhaustedAt = Date.now();
+        } else {
+          this.quotaExhaustedAt = null;
+        }
         
         // Track quota metrics
         metrics.setGauge('stackexchange_quota_remaining', this.quotaRemaining);
@@ -193,7 +225,13 @@ export class StackExchangeClient {
   }
 
   isQuotaExhausted(): boolean {
-    return this.quotaRemaining <= 0;
+    // True only within the probe cooldown of the last exhaustion evidence. After
+    // it elapses, one probe request is allowed through the tool-level gate; the
+    // probe's outcome refreshes or clears the stamp (see request()).
+    return (
+      this.quotaExhaustedAt !== null &&
+      Date.now() - this.quotaExhaustedAt < QUOTA_PROBE_COOLDOWN_MS
+    );
   }
 
   isQuotaLow(): boolean {

package/src/tools/research-knowledge-search.ts

@@ -962,6 +962,21 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
         return buildSteeringResult(result, urls);
       } catch (error) {
         const durationMs = Date.now() - startTime;
+        const msg = error instanceof Error ? error.message : String(error);
+
+        // A CANCELLED search is not an empty store. Reporting the miss string here
+        // told the calling agent, definitively, that the knowledge store has
+        // nothing on this topic — so it would go straight to full live research,
+        // the very work the user just interrupted. Propagate the abort instead;
+        // the run is ending either way. (Same misclassification as the search
+        // layer's "browser workers may be unavailable" on Ctrl-C.)
+        if (signal?.aborted || (error instanceof Error && error.name === 'AbortError') || /^(aborted|research (aborted|cancelled))$/i.test(msg)) {
+          metrics.observe('research_knowledge_search_duration_ms', durationMs, { status: 'cancelled' });
+          metrics.increment('research_knowledge_search_total', 1, { status: 'cancelled' });
+          logger.debug('[research-knowledge-search] Cancelled mid-search — propagating rather than reporting an empty store.');
+          throw error;
+        }
+
         metrics.observe('research_knowledge_search_duration_ms', durationMs, { status: 'error' });
         metrics.increment('research_knowledge_search_total', 1, { status: 'error' });
 

package/src/tools/research-tool-definition.ts

@@ -466,8 +466,14 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
 
         const errMsg = String(error).toLowerCase();
 
-        // Handle rate limits gracefully
-        if (errMsg.includes('429') || errMsg.includes('rate limit') || errMsg.includes('too many requests') || errMsg.includes('quota')) {
+        // Handle rate limits gracefully. "429" is matched on a word boundary
+        // (mirroring messageIsTransient in web-research/retry-utils.ts): a substring
+        // test also matched digits embedded in a larger number — e.g. a context-
+        // overflow error quoting "you requested 142935 tokens" — misreporting the
+        // run as rate-limited. 'quota' stays unanchored, same trade-off as
+        // retry-utils: provider quota errors ("insufficient_quota") carry no
+        // rate/limit wording to anchor on.
+        if (/\b429\b/.test(errMsg) || errMsg.includes('rate limit') || errMsg.includes('too many requests') || errMsg.includes('quota')) {
             logger.warn('[research] Run halted gracefully due to rate limit:', error);
             if (ctx.hasUI) {
                 ctx.ui.notify('Research halted: API rate limit reached', 'warning');

package/src/tools/scrape.ts

@@ -139,11 +139,38 @@ export function createScrapeTool(options: {
       // almost nothing and must not be blocked as if every URL were a full scrape.
       const { kept: dedupedUrls, duplicates } = deduplicateUrls(rawUrls, getGlobalState().researchId);
 
+      // Partition duplicates by whether their content still survives in the session
+      // cache. The content cache is FIFO-capped, so a pool member's content may have
+      // been evicted; those URLs re-enter the fetch list — otherwise they would be
+      // reported as "retrieved from session memory" while appearing nowhere in the
+      // output, and a re-request would just dedup them away again.
+      const duplicateResults: { url: string; markdown: string; success: true }[] = [];
+      const evictedDuplicates: string[] = [];
+      for (const url of duplicates) {
+        const cachedContent = getCachedScrapedContent(getGlobalState().researchId, url);
+        if (cachedContent) {
+          duplicateResults.push({ url, markdown: cachedContent, success: true });
+        } else {
+          evictedDuplicates.push(url);
+        }
+      }
+
+      // Only the first MAX_SCRAPE_URLS candidates are ever fetched. Slice BEFORE the
+      // context gate so the projection bills what will actually be scraped — billing
+      // the full list blocked an 8-URL first batch on a 128k model at zero tokens
+      // used, while the URLs actually fetchable would have passed. Over-cap URLs are
+      // reported explicitly below instead of silently vanishing (they appear neither
+      // in results nor in Failed-to-Scrape, and the session-pool footer excludes the
+      // current batch).
+      const fetchCandidates = [...dedupedUrls, ...evictedDuplicates];
+      const finalUrls = fetchCandidates.slice(0, MAX_SCRAPE_URLS);
+      const skippedUrls = fetchCandidates.slice(MAX_SCRAPE_URLS);
+
       // Context gate: block if projected token usage would exceed threshold
       if (options.getTokensUsed) {
         const ctxWindow = options.contextWindowSize ?? DEFAULT_MODEL_CONTEXT_WINDOW;
         const tokensUsed = options.getTokensUsed();
-        const projected = (tokensUsed + dedupedUrls.length * config.AVG_TOKENS_PER_SCRAPE) / ctxWindow;
+        const projected = (tokensUsed + finalUrls.length * config.AVG_TOKENS_PER_SCRAPE) / ctxWindow;
         if (projected >= config.MAX_SCRAPE_TOKEN_FRACTION_FOR_SCRAPING) {
           const pct = Math.round(config.MAX_SCRAPE_TOKEN_FRACTION_FOR_SCRAPING * 100);
           metrics.increment('tool_scrape_calls_total', 1, { status: 'context_limit' });
@@ -160,36 +187,22 @@ export function createScrapeTool(options: {
       }
 
       const callCount = options.tracker?.getToolCallCount('scrape') ?? 0;
-      const batchLabel = `Batch ${callCount + 1}`;
       options.tracker?.recordCall('scrape');
       const scrapeStartTime = Date.now();
-      const dedupNote = duplicates.length > 0
-        ? `**Global Cache Hit**: ${duplicates.length} URL(s) retrieved from session memory (already scraped).\n\n`
+      // Count only content actually re-served. Evicted pool members are in the fetch
+      // list instead, so they surface as fresh results (or in the not-fetched note),
+      // never as a "retrieved" claim with no content attached.
+      let dedupNote = duplicateResults.length > 0
+        ? `**Global Cache Hit**: ${duplicateResults.length} URL(s) retrieved from session memory (already scraped).\n\n`
         : '';
-      metrics.increment('tool_scrape_duplicates_total', duplicates.length);
-
-      // Even for duplicates, we want to return the content if we have it in the session cache
-      const duplicateResults: { url: string; markdown: string; success: true }[] = [];
-      for (const url of duplicates) {
-        const cachedContent = getCachedScrapedContent(getGlobalState().researchId, url);
-        if (cachedContent) {
-          duplicateResults.push({ url, markdown: cachedContent, success: true });
-          options.onUrlScrapeResult?.(url, true);
-        }
+      if (evictedDuplicates.length > 0) {
+        dedupNote += `**Session Cache Evicted**: ${evictedDuplicates.length} previously-scraped URL(s) no longer in session memory — queued for a fresh fetch:\n${evictedDuplicates.map(u => `- ${u}`).join('\n')}\n\n`;
       }
-
-      if (dedupedUrls.length === 0 && duplicateResults.length === 0) {
-        metrics.increment('tool_scrape_calls_total', 1, { status: 'all_duplicates_no_content' });
-        // Add footer with alternative URLs for discovery
-        const earlyFooter = buildSessionPoolFooter(getGlobalState().researchId, rawUrls, options.researcherId);
-        return {
-          content: [{ type: 'text', text: `# ${batchLabel} Skipped\n\nAll URLs were already in the global pool, but no cached content was available.${earlyFooter}` }],
-          details: { all_duplicates: true },
-        };
+      metrics.increment('tool_scrape_duplicates_total', duplicates.length);
+      for (const r of duplicateResults) {
+        options.onUrlScrapeResult?.(r.url, true);
       }
 
-      const finalUrls = dedupedUrls.slice(0, MAX_SCRAPE_URLS);
-
       // Batch 1 uses the configured scrape concurrency; batch 2+ may go wider
       // once the context budget allows — but never wider than the real browser
       // pool (WORKER_THREADS × WORKER_CONCURRENCY), or the extra requests just
@@ -331,6 +344,15 @@ export function createScrapeTool(options: {
         markdown += '\n';
       }
 
+      if (skippedUrls.length > 0) {
+        markdown += `## Not Fetched — Over Batch Cap (${skippedUrls.length})\n\n`;
+        markdown += `Only the first ${MAX_SCRAPE_URLS} URLs of a batch are fetched. The following URLs were NOT fetched — no content for them appears above. Request them in a later scrape batch if still needed:\n`;
+        for (const url of skippedUrls) {
+          markdown += `- ${url}\n`;
+        }
+        markdown += '\n';
+      }
+
       // Append Session URL Pool footer
       markdown += buildSessionPoolFooter(getGlobalState().researchId, rawUrls, options.researcherId);
 
@@ -342,6 +364,7 @@ export function createScrapeTool(options: {
           failed: failedFresh.length,
           cached: cachedResults.length,
           fresh: successfulFresh.length,
+          skipped: skippedUrls.length,
         },
       };
     },

package/src/tools/search.ts

@@ -9,6 +9,7 @@ import { Type, type Static } from 'typebox';
 import { Value } from 'typebox/value';
 import { search } from '../web-research/search.ts';
 import type { ToolUsageTracker } from '../utils/tool-usage-tracker.ts';
+import type { SystemResearchState } from '../orchestration/deep-research-types.ts';
 import { logger } from '../logger.ts';
 import { type Config, getConfig } from '../config.ts';
 import { metrics } from '../utils/metrics.ts';
@@ -18,6 +19,8 @@ export function createSearchTool(options: {
   ctx: ExtensionContext;
   tracker: ToolUsageTracker;
   onProgress?: (links: number) => void;
+  /** Research state accessor; its researchId keys the per-session circuit breaker (mirrors scrape). */
+  getGlobalState?: () => SystemResearchState;
   config?: Config;
 }): ToolDefinition {
   const youtubeEveryN = (options.config ?? getConfig(options.ctx.cwd)).YOUTUBE_QUERY_EVERY_N;
@@ -84,9 +87,15 @@ export function createSearchTool(options: {
 
       try {
         const container = tryGetServiceContainerFromCtx(ctx);
+        // Per-session circuit-breaker scoping: thread the researchId exactly as
+        // the scrape path does (tools/scrape.ts passes getGlobalState().researchId
+        // into scrape() → runBrowserTask). Search previously hard-coded
+        // sessionId=undefined at the runWorkerSearch hop, so its failures always
+        // hit the GLOBAL breaker while scrape's hit the per-run one.
+        const sessionId = options.getGlobalState?.().researchId;
         const results = await search(queries, options.config, signal, (links) => {
           if (options.onProgress) options.onProgress(links);
-        }, container);
+        }, container, sessionId);
         const elapsed = Date.now() - startTime;
         
         const totalResults = results.reduce((sum, r) => sum + r.results.length, 0);
@@ -106,7 +115,12 @@ export function createSearchTool(options: {
         results.forEach((r, i) => {
           markdown += `## Query ${i + 1}: ${r.query}\n`;
           if (r.results.length === 0) {
-            markdown += `*No results found.*\n\n`;
+            // Render the attributed failure, not a bare "no results": a timeout or
+            // dead worker says nothing about the query, and presenting it as an
+            // empty result sent the model off rewriting perfectly good queries —
+            // the misdirection QueryFailure exists to prevent. This is the only
+            // surface the researcher agent actually reads.
+            markdown += r.error ? `*${r.error.message}*\n\n` : `*No results found.*\n\n`;
           } else {
             r.results.forEach((item, j) => {
               markdown += `[${j + 1}] **${item.title}**\n${item.url}\n${item.content}\n\n`;

package/src/tools/security.ts

@@ -97,9 +97,48 @@ export function createSecuritySearchTool(options: {
         throw new Error('At least one search term is required');
       }
 
+      // Normalize database names (schema accepts free text): "NVD" must reach the
+      // dispatcher as "nvd". Unknown names are still passed through — the searcher
+      // reports each one in `errors`, which the note below surfaces — but when EVERY
+      // requested name is unknown the call must fail loudly here: running zero
+      // databases and reporting "0 vulnerabilities found" would read as an
+      // authoritative all-clear.
+      const VALID_DATABASES = ['nvd', 'cisa_kev', 'github', 'osv'] as const;
       const databases: readonly ('nvd' | 'cisa_kev' | 'github' | 'osv')[] = p.databases !== undefined && p.databases.length > 0
-        ? p.databases as readonly ('nvd' | 'cisa_kev' | 'github' | 'osv')[]
-        : ['nvd', 'cisa_kev', 'github', 'osv'];
+        ? p.databases.map(db => db.trim().toLowerCase()) as readonly ('nvd' | 'cisa_kev' | 'github' | 'osv')[]
+        : VALID_DATABASES;
+      if (!databases.some(db => (VALID_DATABASES as readonly string[]).includes(db))) {
+        metrics.increment('tool_security_search_calls_total', 1, { status: 'unknown_databases' });
+        return {
+          content: [{
+            type: 'text',
+            text: `# Security Vulnerability Search Failed\n\n**Error:** No recognized databases in request — nothing was searched.\n\n**Requested:** ${p.databases!.join(', ')}\n\n**Valid databases (case-insensitive):** ${VALID_DATABASES.join(', ')}`,
+          }],
+          details: { error: 'unknown_databases', requested: p.databases, validDatabases: VALID_DATABASES },
+        };
+      }
+      // Normalize the severity filter at the single dispatch chokepoint (schema
+      // accepts free text). Only NVD's path normalized (security/index.ts
+      // getSeverityParam): GitHub/OSV received the raw string, so "med" or
+      // "HIGH,CRITICAL" ran NVD unfiltered while their strict filters silently
+      // returned zero. An unrecognized value must fail loudly BEFORE any database
+      // is queried rather than let the databases silently diverge.
+      const VALID_SEVERITIES = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'] as const;
+      let severity: string | undefined;
+      if (p.severity !== undefined) {
+        const upper = p.severity.trim().toUpperCase();
+        severity = upper === 'MODERATE' ? 'MEDIUM' : upper;
+        if (!(VALID_SEVERITIES as readonly string[]).includes(severity)) {
+          metrics.increment('tool_security_search_calls_total', 1, { status: 'invalid_severity' });
+          return {
+            content: [{
+              type: 'text',
+              text: `[Error] Unknown severity "${p.severity}" — valid: LOW, MEDIUM, HIGH, CRITICAL (MODERATE accepted as MEDIUM). No databases were queried.`,
+            }],
+            details: { error: 'invalid_severity', requested: p.severity, validSeverities: VALID_SEVERITIES },
+          };
+        }
+      }
       const maxResults = p.maxResults ?? 20;
 
       metrics.increment('tool_security_search_terms_total', terms.length);
@@ -110,7 +149,7 @@ export function createSecuritySearchTool(options: {
         const searchParams: SecuritySearchParams = {
           terms,
           databases,
-          severity: p.severity,
+          severity,
           maxResults,
           includeExploited: p.includeExploited ?? false,
           ecosystem: p.ecosystem,
@@ -172,7 +211,13 @@ export function createSecuritySearchTool(options: {
         markdown += '## NIST NVD\n\n';
         if (results.results.nvd.error !== undefined) {
           markdown += `[Error] ${results.results.nvd.error}\n\n`;
-        } else {
+        }
+        // Partial failures: the clients deliberately return whatever they fetched
+        // PLUS an error annotation (e.g. "NVD lookup failed for 1/2 term(s)"), so
+        // the data must render alongside the [Error] line — the header's totals
+        // already count it. Only a total failure (error with zero rows) stays
+        // error-only, so it can't read as an authoritative "found nothing".
+        if (results.results.nvd.error === undefined || results.results.nvd.vulnerabilities.length > 0) {
           markdown += `Found: ${results.results.nvd.count} vulnerabilities\n\n`;
           for (const vuln of results.results.nvd.vulnerabilities.slice(0, 20)) {
             markdown += `### ${vuln.id}\n`;
@@ -212,7 +257,9 @@ export function createSecuritySearchTool(options: {
         markdown += '## CISA Known Exploited Vulnerabilities\n\n';
         if (results.results.cisa_kev.error !== undefined) {
           markdown += `[Error] ${results.results.cisa_kev.error}\n\n`;
-        } else {
+        }
+        // Partial failure: render the data alongside the error (see NVD section).
+        if (results.results.cisa_kev.error === undefined || results.results.cisa_kev.vulnerabilities.length > 0) {
           markdown += `Found: ${results.results.cisa_kev.count} actively exploited vulnerabilities\n\n`;
           for (const vuln of results.results.cisa_kev.vulnerabilities.slice(0, 20)) {
             markdown += `### ${vuln.id}\n`;
@@ -245,8 +292,16 @@ export function createSecuritySearchTool(options: {
         markdown += '## GitHub Security Advisories\n\n';
         if (results.results.github.error !== undefined) {
           markdown += `[Error] ${results.results.github.error}\n\n`;
-        } else {
+        }
+        // Partial failure: render the data alongside the error (see NVD section).
+        if (results.results.github.error === undefined || results.results.github.advisories.length > 0) {
           markdown += `Found: ${results.results.github.count} advisories\n\n`;
+          if (p.includeExploited === true) {
+            // includeExploited reaches only NVD (hasKev) and CISA KEV (inherently
+            // exploited-only); GitHub carries no exploitation signal, so these
+            // results are NOT filtered by it — say so rather than imply they were.
+            markdown += '*Note: GitHub Advisories are not filtered by known-exploitation — that signal exists only in NVD and CISA KEV.*\n\n';
+          }
           for (const adv of results.results.github.advisories.slice(0, 20)) {
             markdown += `### ${adv.id}\n`;
             markdown += `- **Severity:** ${adv.severity}\n`;
@@ -277,8 +332,14 @@ export function createSecuritySearchTool(options: {
         markdown += '## Open Source Vulnerabilities (OSV)\n\n';
         if (results.results.osv.error !== undefined) {
           markdown += `[Error] ${results.results.osv.error}\n\n`;
-        } else {
+        }
+        // Partial failure: render the data alongside the error (see NVD section).
+        if (results.results.osv.error === undefined || results.results.osv.vulnerabilities.length > 0) {
           markdown += `Found: ${results.results.osv.count} vulnerabilities\n\n`;
+          if (p.includeExploited === true) {
+            // Same caveat as GitHub: OSV carries no exploitation signal.
+            markdown += '*Note: OSV results are not filtered by known-exploitation — that signal exists only in NVD and CISA KEV.*\n\n';
+          }
           for (const vuln of results.results.osv.vulnerabilities.slice(0, 20)) {
             markdown += `### ${vuln.id}\n`;
             markdown += `- **Severity:** ${vuln.severity}\n`;

package/src/tui/research-health.ts

@@ -95,17 +95,33 @@ export interface HealthMonitor {
 
 export function createHealthMonitor(): HealthMonitor {
   let timer: NodeJS.Timeout | null = null;
+  // Critical components already warned this run, so a persistently failing check
+  // logs once rather than on every 30s tick.
+  const warnedCritical = new Set<string>();
 
   const start = () => {
     if (timer) return;
-    
+    warnedCritical.clear();
+
+    // Note: the registry API (runAll) only supports { force } — there is no surface
+    // for selecting/skipping individual checks, so each tick runs the full set
+    // (including the real BrowserRuntime page-load probe when the pool is active).
     timer = setInterval(async () => {
       try {
         const health = await healthRegistry.runAll();
-        const failedNonCritical = health.components.filter(c => !c.healthy && !healthRegistry.isCritical(c.component));
+        const failed = health.components.filter(c => !c.healthy);
+        const failedNonCritical = failed.filter(c => !healthRegistry.isCritical(c.component));
         if (failedNonCritical.length > 0) {
           logger.warn(`[research] Periodic health check: non-critical components degraded: ${failedNonCritical.map(c => c.component).join(', ')}`);
         }
+        // Critical failures are worth surfacing too — the run itself keeps going
+        // (per-task timeouts bound the real work), but silently burning probes while
+        // a critical component is down left the monitor with no output at all.
+        for (const c of failed.filter(f => healthRegistry.isCritical(f.component))) {
+          if (warnedCritical.has(c.component)) continue;
+          warnedCritical.add(c.component);
+          logger.warn(`[research] Periodic health check: critical component unhealthy mid-run: ${c.component}${c.error ? ` (${c.error})` : ''}`);
+        }
       } catch (error) {
         logger.debug('[research] Periodic health check failed (non-blocking):', error);
       }

package/src/utils/atomic-replace.ts

@@ -0,0 +1,101 @@
+/**
+ * Atomic file replacement, with the Windows caveat handled honestly.
+ *
+ * The temp-file + fsync + rename dance exists so a reader never observes a partial
+ * file and a crash never leaves one: rename is atomic, so the destination is either
+ * entirely the old content or entirely the new.
+ *
+ * On Windows that guarantee is easy to lose. The long-standing comment at these call
+ * sites — "fs.rename fails on Windows if target exists (NTFS)" — is not true: Node
+ * calls `MoveFileExW` with `MOVEFILE_REPLACE_EXISTING`, so replacing an existing file
+ * is fine. What actually fails is a rename whose TARGET is held open by another
+ * process without delete sharing (an AV scanner mid-scan, a backup agent), which
+ * surfaces as EPERM/EBUSY/EACCES.
+ *
+ * The old remedy — fall straight to `copyFile` — traded a transient, retryable error
+ * for a permanent hazard: `copyFile` truncates the destination and rewrites it in
+ * place, so a concurrent reader or a crash mid-copy sees a torn or zero-length file.
+ * For `state.json` (leader election, server auth secrets) and `config.env` (API keys)
+ * that is a much worse outcome than the error it was avoiding.
+ *
+ * So: retry the rename first. An AV lock clears in tens of milliseconds, and a retried
+ * rename stays atomic. Only a lock that outlives every retry falls back to copying,
+ * which is reported to the caller so it can be logged as the degraded path it is.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+
+/** Transient Windows sharing/locking failures — worth retrying, unlike ENOENT/ENOSPC. */
+const RETRYABLE_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+
+const MAX_RENAME_ATTEMPTS = 5;
+const RENAME_RETRY_DELAY_MS = 25;
+
+export type ReplaceOutcome = 'renamed' | 'copied';
+
+function isRetryable(err: unknown): boolean {
+  const code = (err as NodeJS.ErrnoException | undefined)?.code;
+  return code !== undefined && RETRYABLE_CODES.has(code);
+}
+
+/**
+ * Replace `destPath` with `tmpPath` atomically where the platform allows it.
+ *
+ * Returns `'renamed'` for the atomic path and `'copied'` for the degraded Windows
+ * fallback. Rethrows on every non-Windows failure, and on Windows failures that are
+ * not lock-related.
+ */
+export async function replaceFile(tmpPath: string, destPath: string): Promise<ReplaceOutcome> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_RENAME_ATTEMPTS; attempt++) {
+    try {
+      await fs.rename(tmpPath, destPath);
+      return 'renamed';
+    } catch (err) {
+      lastError = err;
+      // Only a Windows sharing conflict is worth another try; anything else (and any
+      // failure on a POSIX platform, where rename-over-existing always works) is real.
+      if (process.platform !== 'win32' || !isRetryable(err)) throw err;
+      if (attempt < MAX_RENAME_ATTEMPTS - 1) {
+        await new Promise((r) => setTimeout(r, RENAME_RETRY_DELAY_MS * (attempt + 1)));
+      }
+    }
+  }
+
+  // Every retry lost to the same lock. Copying is not atomic — a reader can catch the
+  // destination mid-write — but it is the only remaining way to persist the data.
+  try {
+    await fs.copyFile(tmpPath, destPath);
+    return 'copied';
+  } catch {
+    throw lastError;
+  }
+}
+
+/** Synchronous {@link replaceFile}, for the config writer, which is sync throughout. */
+export function replaceFileSync(tmpPath: string, destPath: string): ReplaceOutcome {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_RENAME_ATTEMPTS; attempt++) {
+    try {
+      fsSync.renameSync(tmpPath, destPath);
+      return 'renamed';
+    } catch (err) {
+      lastError = err;
+      if (process.platform !== 'win32' || !isRetryable(err)) throw err;
+      if (attempt < MAX_RENAME_ATTEMPTS - 1) {
+        // Sync busy-wait: this path is rare, bounded (~250ms worst case) and the
+        // caller is already blocking on a synchronous write.
+        const until = Date.now() + RENAME_RETRY_DELAY_MS * (attempt + 1);
+        while (Date.now() < until) { /* spin */ }
+      }
+    }
+  }
+
+  try {
+    fsSync.copyFileSync(tmpPath, destPath);
+    return 'copied';
+  } catch {
+    throw lastError;
+  }
+}

package/src/utils/circuit-breaker.ts

@@ -71,7 +71,7 @@ export class CircuitBreaker {
       const result = await action();
       const duration = Date.now() - startTime;
       metrics.observe('circuit_breaker_call_duration_ms', duration, { breaker: this.options.name, status: 'success' });
-      this.onSuccess();
+      this.onSuccess(admittedAsProbe);
       return result;
     } catch (error) {
       const duration = Date.now() - startTime;
@@ -105,9 +105,16 @@ export class CircuitBreaker {
     }
   }
 
-  private onSuccess() {
+  private onSuccess(admittedAsProbe: boolean) {
     metrics.increment('circuit_breaker_success_total', 1, { breaker: this.options.name, state: this.state });
     if (this.state === 'HALF_OPEN') {
+      // Only a call admitted through the HALF_OPEN gate is evidence of recovery.
+      // A call admitted while CLOSED that merely settles after the breaker tripped
+      // and re-half-opened carries PRE-outage evidence — counting it would close
+      // the circuit while the real probe is still in flight against a dependency
+      // that may still be down. Its success is simply not counted; the in-flight
+      // probe's own outcome decides the transition.
+      if (!admittedAsProbe) return;
       this.successCount++;
       if (this.successCount >= this.options.halfOpenMaxCalls) {
         this.transitionTo('CLOSED');

package/src/utils/citation-utils.ts

@@ -16,7 +16,9 @@ export interface GlobalCitation extends Citation {
  * @param reports - Map of researcher ID to report content
  * @returns Object containing normalized reports and the global citation list
  */
-export function normalizeCitations(reports: Map<string, string>): {
+// ReadonlyMap: this only reads `reports` (it returns a NEW normalizedReports map),
+// and callers now pass a read-only view to avoid create-on-read side effects.
+export function normalizeCitations(reports: ReadonlyMap<string, string>): {
   normalizedReports: Map<string, string>;
   globalCitations: GlobalCitation[];
 } {

package/src/utils/disk-space-checker.ts

@@ -36,12 +36,17 @@ export class DiskSpaceChecker {
       if (availableBytes < this.MIN_DISK_SPACE_BYTES) {
         this.hasDiskSpace = false;
         // Write directly to stderr — this check runs inside the logger itself,
-        // so using the logger here would create a circular dependency.
-        process.stderr.write(
-          `[pi-research] Insufficient disk space for logging: ` +
-          `${Math.round(availableBytes / 1024 / 1024)}MB available, ` +
-          `minimum ${this.MIN_DISK_SPACE_BYTES / 1024 / 1024}MB required\n`
-        );
+        // so using the logger here would create a circular dependency. Guarded:
+        // when the parent has already closed the pipe, a bare write throws
+        // EPIPE/ERR_STREAM_DESTROYED and (with no global uncaughtException
+        // handler in the main process) would crash the run over a diagnostic.
+        try {
+          process.stderr.write(
+            `[pi-research] Insufficient disk space for logging: ` +
+            `${Math.round(availableBytes / 1024 / 1024)}MB available, ` +
+            `minimum ${this.MIN_DISK_SPACE_BYTES / 1024 / 1024}MB required\n`
+          );
+        } catch { /* stderr gone — the flag above already halts log writes */ }
       } else {
         this.hasDiskSpace = true;
       }