@lincoln504/pi-research 1.2.0 → 1.3.0

package/src/sdk.ts

@@ -28,6 +28,9 @@ import type {
   ResearchOptions
 } from './core/interfaces/orchestration-interfaces.ts';
 import type { IPlanningService } from './core/interfaces/planning-interfaces.ts';
+import type { ResearchObserver, HeadlessObserverOptions } from './core/interfaces/observer-interfaces.ts';
+import type { ResearchPlan } from './core/interfaces/research-plan-types.ts';
+import { HeadlessObserver } from './orchestration/headless-observer.ts';
 import type { Model } from '@earendil-works/pi-ai';
 import { type ExtensionContext, ModelRegistry } from '@earendil-works/pi-coding-agent';
 import { logger, createLogger, setLogger } from './logger.ts';
@@ -94,6 +97,13 @@ export interface ResearcherOutcome {
   failureReasons: Record<string, string>;
 }
 let _lastResearcherOutcome: ResearcherOutcome | null = null;
+// Monotonic SDK-lifetime counter, bumped by _doShutdown. A run left in flight across
+// shutdownResearchSDK() settles AFTER the shutdown wiped the `_last*` accessors and
+// cleared session metrics; its catch/finally would then repopulate them, so a
+// re-initialized SDK reported a phantom run from the previous lifetime. Each run
+// captures the generation at start and every post-run telemetry write is gated on it
+// still matching.
+let _sdkGeneration = 0;
 
 // Signal handler state — registered once, removed on clean shutdown.
 let _onSignal: ((signal: string) => void) | null = null;
@@ -489,6 +499,18 @@ export async function runDeepResearch(
   // here instead of vanishing into the never-read global tracker.
   const runTracker = new ErrorTracker();
 
+  // Stamp the run with the current shutdown generation: if shutdownResearchSDK()
+  // completes while this run is still in flight, _doShutdown bumps the generation
+  // and every telemetry write below is skipped — the shutdown wipe must win over
+  // an older-generation run settling late (see _sdkGeneration).
+  const runGeneration = _sdkGeneration;
+
+  // Planned-researcher count, captured DURING the run via the observer wrapper —
+  // it is unreadable from the planning service once runResearch() settles (the deep
+  // orchestrator clears that per-run state in its own finally first).
+  let plannedResearchers = 0;
+  const observer = wrapObserverForOutcomeCapture(options.observer, (count) => { plannedResearchers += count; });
+
   try {
     // Resolve the orchestrator INSIDE the try: getService() can throw (container
     // disposal race with shutdown, or an unregistered service), and if that throw
@@ -506,6 +528,9 @@ export async function runDeepResearch(
       depth: depth as ResearchDepth,
       complexity: complexity as 1 | 2 | 3,
       initialLinks: options.initialLinks,
+      // The caller's observer, wrapped so the SDK captures the planned-researcher
+      // events for getLastResearcherOutcome() (must land AFTER the options spread).
+      observer,
       // Forward the SDK's resolved config so initResearchSDK({ config }) overrides
       // actually reach the orchestrator and every downstream service. A per-call
       // options.config (if provided) takes precedence over the SDK-global config.
@@ -522,27 +547,40 @@ export async function runDeepResearch(
     // unbounded across calls (a long-lived SDK/benchmark process). runRegistry.observe() lands
     // it in this run's snapshot, matching the tool path's run-scoped emission.
     runRegistry.observe('research_manager_latency_ms', completedAt - researchStart, { depth: depthLabel, status: 'success', source: 'sdk' });
-    _lastRunSummary = {
-      runId: researchId, startedAt: researchStart, completedAt,
-      durationMs: completedAt - researchStart, status: 'success', snapshot: runRegistry.getSnapshot(),
-    };
-    metrics.recordRunSummary(_lastRunSummary);
-    _lastErrorReport = runTracker.getReport();
-    logRunErrorSummary(_lastErrorReport, depthLabel, 'success');
-    _lastResearcherOutcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot);
+    // Generation guard: skip every module-level telemetry write if a shutdown
+    // completed mid-run — the wipe must not be resurrected by a stale run.
+    if (runGeneration === _sdkGeneration) {
+      _lastRunSummary = {
+        runId: researchId, startedAt: researchStart, completedAt,
+        durationMs: completedAt - researchStart, status: 'success', snapshot: runRegistry.getSnapshot(),
+      };
+      metrics.recordRunSummary(_lastRunSummary);
+      _lastErrorReport = runTracker.getReport();
+      logRunErrorSummary(_lastErrorReport, depthLabel, 'success');
+      // Re-check the generation AFTER the await: the gate above was evaluated
+      // before it, so a shutdown completing during the capture would otherwise
+      // land this assignment after the wipe — a phantom outcome from a dead run.
+      const outcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot, plannedResearchers);
+      if (runGeneration === _sdkGeneration) _lastResearcherOutcome = outcome;
+    }
     return result;
   } catch (err) {
     const completedAt = Date.now();
     // Per-run scope (see the success path above) — avoids unbounded session-scope accumulation.
     runRegistry.observe('research_manager_latency_ms', completedAt - researchStart, { depth: depthLabel, status: 'error', source: 'sdk' });
-    _lastRunSummary = {
-      runId: researchId, startedAt: researchStart, completedAt,
-      durationMs: completedAt - researchStart, status: 'error', snapshot: runRegistry.getSnapshot(),
-    };
-    metrics.recordRunSummary(_lastRunSummary);
-    _lastErrorReport = runTracker.getReport();
-    logRunErrorSummary(_lastErrorReport, depthLabel, 'error');
-    _lastResearcherOutcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot);
+    // Generation guard — see the success path above.
+    if (runGeneration === _sdkGeneration) {
+      _lastRunSummary = {
+        runId: researchId, startedAt: researchStart, completedAt,
+        durationMs: completedAt - researchStart, status: 'error', snapshot: runRegistry.getSnapshot(),
+      };
+      metrics.recordRunSummary(_lastRunSummary);
+      _lastErrorReport = runTracker.getReport();
+      logRunErrorSummary(_lastErrorReport, depthLabel, 'error');
+      // Re-check after the await — see the success path above.
+      const outcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot, plannedResearchers);
+      if (runGeneration === _sdkGeneration) _lastResearcherOutcome = outcome;
+    }
     throw err;
   } finally {
     // Free the per-run PiSessionState that shouldStopResearch()/getFailedResearchers()
@@ -603,16 +641,73 @@ function logRunErrorSummary(report: ErrorReport | null, depthLabel: string, stat
   logger.warn(`[SDK] run ${status} with ${report.totalErrors} tracked error(s) across ${report.uniquePatterns} pattern(s) [${depthLabel}]${top ? ` — top: ${top}` : ''}`);
 }
 
+/**
+ * Wrap the caller's observer so the SDK sees the planned-researcher events the deep
+ * orchestrator emits DURING the run. The count cannot be read back afterwards: the
+ * orchestrator's own finally runs cleanupResearchServices → clearPlanningState(researchId)
+ * BEFORE runResearch() resolves for the SDK, so a post-run getTotalResearchersPlanned()
+ * always sees 0. onPlanningSuccess (round 1) and onEvaluationDecision('delegate', …)
+ * (later rounds) fire at exactly the points the orchestrator increments that counter —
+ * it suppresses the delegate decision for a round-cap delegation it discards, so the
+ * captured total only counts researchers that were actually going to run.
+ *
+ * An { onProgress } options bag is normalized into a HeadlessObserver HERE rather than
+ * left to the orchestrator (which uses the same shape check): if the orchestrator wrapped
+ * the bag itself, the planning events would dispatch on ITS HeadlessObserver instance and
+ * never reach this capture layer. Mirrors makeSafeObserver's empty-target Proxy so a
+ * frozen caller observer can never trip the Proxy own-property invariant.
+ */
+function wrapObserverForOutcomeCapture(
+  observer: ResearchObserver | HeadlessObserverOptions | undefined,
+  onPlanned: (count: number) => void,
+): ResearchObserver {
+  const base: ResearchObserver | undefined =
+    observer && typeof (observer as HeadlessObserverOptions).onProgress === 'function' && !(observer instanceof HeadlessObserver)
+      ? new HeadlessObserver(observer as HeadlessObserverOptions)
+      : (observer as ResearchObserver | undefined);
+
+  return new Proxy({} as ResearchObserver, {
+    get(_target, prop) {
+      if (prop === 'onPlanningSuccess') {
+        return (plan: ResearchPlan) => {
+          onPlanned(plan?.researchers?.length ?? 0);
+          base?.onPlanningSuccess?.(plan);
+        };
+      }
+      if (prop === 'onEvaluationDecision') {
+        return (action: 'synthesize' | 'delegate', plan?: ResearchPlan, round?: number) => {
+          if (action === 'delegate') onPlanned(plan?.researchers?.length ?? 0);
+          base?.onEvaluationDecision?.(action, plan, round);
+        };
+      }
+      if (!base) return undefined;
+      const value = Reflect.get(base, prop, base);
+      return typeof value === 'function' ? (value as (...args: unknown[]) => unknown).bind(base) : value;
+    },
+    has(_target, prop) {
+      if (prop === 'onPlanningSuccess' || prop === 'onEvaluationDecision') return true;
+      return base ? Reflect.has(base, prop) : false;
+    },
+  });
+}
+
 /**
  * Capture how many researchers were planned/launched/failed for this run, BEFORE
  * the caller's `finally` block frees the PiSessionState (endResearchSession) that
  * getFailedResearchers()/getResearcherFailureReasons() read from. Best-effort:
  * this is instrumentation only and must never affect the run's own result.
  */
-async function captureResearcherOutcome(sessionId: string, researchId: string, snapshot: IMetricsSnapshot): Promise<ResearcherOutcome | null> {
+async function captureResearcherOutcome(sessionId: string, researchId: string, snapshot: IMetricsSnapshot, plannedFromObserver: number): Promise<ResearcherOutcome | null> {
   try {
-    const planningService = await getService<IPlanningService>(ServiceNames.PLANNING, undefined, globalContainer!);
-    const planned = planningService.getTotalResearchersPlanned(researchId);
+    // Deep runs: the observer-captured count is authoritative — the orchestrator's
+    // finally already cleared the planning service's per-run entry by the time the SDK
+    // regains control (see wrapObserverForOutcomeCapture). The service read stays as a
+    // fallback for any path that never emits the planning events.
+    let planned = plannedFromObserver;
+    if (planned === 0) {
+      const planningService = await getService<IPlanningService>(ServiceNames.PLANNING, undefined, globalContainer!);
+      planned = planningService.getTotalResearchersPlanned(researchId);
+    }
     const launched = extractRunStats(snapshot)?.researchersLaunched ?? 0;
     const failed = getFailedResearchers(sessionId, researchId);
     return {
@@ -825,6 +920,14 @@ export async function shutdownResearchSDK(): Promise<void> {
 async function _doShutdown(): Promise<void> {
   logger.log('[SDK] Shutting down Research SDK...');
 
+  // Invalidate the pending telemetry writes of any run still in flight FIRST —
+  // before runCleanup and the other long awaits below. The invariant: a run
+  // settling at ANY point after shutdown begins fails the generation gate. Bumping
+  // at the end instead left the whole teardown (cleanup, clearSession, service
+  // disposal) as a window in which a settling run passed the gate and wrote a
+  // phantom run-summary into the just-cleared session metrics.
+  _sdkGeneration++;
+
   const errors: Error[] = [];
 
   try {
@@ -886,6 +989,9 @@ async function _doShutdown(): Promise<void> {
   _lastRunSummary = null;
   _lastErrorReport = null;
   _lastResearcherOutcome = null;
+  // (No generation bump here — it happened at the TOP of this function, so any
+  // run settling during the teardown above already failed the gate and could not
+  // repopulate the `_last*` accessors or session metrics being wiped.)
   // The module-level config cache survives the globals above. Without this, a
   // shutdown → env/config-file change → re-init cycle in one process silently
   // reuses the first init's config. (The CLI/skill are unaffected — they pass

package/src/security/index.ts

@@ -22,12 +22,11 @@ import type {
   GitHubResult,
   OSVResult,
 } from './types.ts';
-import { REQUEST_DELAY_MS_NVD, REQUEST_DELAY_MS_OTHER } from '../constants.ts';
 import { searchNVD } from './nvd-client.ts';
 import { searchCisaKev } from './cisa-kev.ts';
 import { searchGitHubAdvisories } from './github-advisories.ts';
 import { searchOSV } from './osv-client.ts';
-import { safeUnref } from '../utils/safe-unref.ts';
+import { logger } from '../logger.ts';
 
 // ============================================================================
 // Type Definitions
@@ -35,6 +34,9 @@ import { safeUnref } from '../utils/safe-unref.ts';
 
 type Severity = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
 
+type KnownDatabase = 'nvd' | 'cisa_kev' | 'github' | 'osv';
+const KNOWN_DATABASES: readonly KnownDatabase[] = ['nvd', 'cisa_kev', 'github', 'osv'];
+
 interface DatabaseInfo {
   readonly databases: readonly DatabaseInfoEntry[];
 }
@@ -58,9 +60,22 @@ function isValidSeverity(value: unknown): value is Severity {
   );
 }
 
+// Called ONCE per search(), before dispatch, and the result is shared by every
+// requested backend (NVD, GitHub, OSV) — see the call site in search(). Do not
+// call this per-leg: that previously let NVD normalize while GitHub/OSV read
+// params.severity raw, so the same unrecognized value ran NVD unfiltered while
+// silently zeroing GitHub/OSV's strict filters.
 function getSeverityParam(params: SecuritySearchParams): Severity | undefined {
   if (params.severity === undefined) return undefined;
-  return isValidSeverity(params.severity) ? params.severity : undefined;
+  // NVD requires the exact uppercase enum. GitHub/OSV normalize case and the
+  // MODERATE↔MEDIUM synonym in their own clients (github-advisories.ts,
+  // osv-client.ts) as well, so applying the same normalization here keeps all
+  // three backends in agreement on what severity:"high" or "Moderate" means.
+  const upper = params.severity.trim().toUpperCase();
+  const normalized = upper === 'MODERATE' ? 'MEDIUM' : upper;
+  if (isValidSeverity(normalized)) return normalized;
+  logger.warn(`[security] Unknown severity filter "${params.severity}" (valid: LOW, MEDIUM, HIGH, CRITICAL) — no database will be severity-filtered`);
+  return undefined;
 }
 
 function getErrorMessage(error: unknown): string {
@@ -77,7 +92,6 @@ export interface SecuritySearcherConfig {
   readonly cisaKevClient?: ICisaKevClient;
   readonly githubAdvisoriesClient?: IGitHubAdvisoriesClient;
   readonly osvClient?: IOSVClient;
-  readonly requestDelay?: number; // Override for testing
 }
 
 const DEFAULT_CONFIG: SecuritySearcherConfig = {
@@ -85,7 +99,6 @@ const DEFAULT_CONFIG: SecuritySearcherConfig = {
   cisaKevClient: undefined,
   githubAdvisoriesClient: undefined,
   osvClient: undefined,
-  requestDelay: -1, // Use database-specific logic by default
 };
 
 export class SecuritySearcher {
@@ -101,13 +114,35 @@ export class SecuritySearcher {
     const errors: string[] = [];
     let totalVulnerabilities = 0;
 
+    // Normalize severity ONCE, before dispatch, so every backend that receives a
+    // severity filter sees the exact same value. Previously this call sat inline
+    // in the NVD branch only; GitHub and OSV read the raw, unvalidated
+    // params.severity directly, so an unrecognized value ran NVD unfiltered while
+    // silently zeroing GitHub/OSV (or vice versa depending on each client's own
+    // parsing) — the single-chokepoint fix has to normalize before the fan-out,
+    // not duplicate the call at each leg.
+    const severity = getSeverityParam(params);
+
+    // Normalize database names before dispatch: callers (agents, SDK users) write
+    // "NVD" / " osv " etc. An unrecognized name must surface in `errors` rather than
+    // silently contributing an authoritative-looking "0 vulnerabilities" for a
+    // database that was never queried.
+    const databases: string[] = [];
+    for (const raw of params.databases) {
+      const db = String(raw).trim().toLowerCase();
+      databases.push(db);
+      if (!(KNOWN_DATABASES as readonly string[]).includes(db)) {
+        errors.push(`Unknown database "${raw}" — valid databases: ${KNOWN_DATABASES.join(', ')}`);
+      }
+    }
+
     const searchPromises: Promise<void>[] = [];
 
-    if (params.databases.includes('nvd')) {
+    if (databases.includes('nvd')) {
       searchPromises.push((async () => {
         try {
           const nvdResult = await this.searchNVD(params.terms, {
-              severity: getSeverityParam(params),
+              severity,
               maxResults: params.maxResults,
               includeExploited: params.includeExploited,
               signal,
@@ -120,7 +155,7 @@ export class SecuritySearcher {
       })());
     }
 
-    if (params.databases.includes('cisa_kev')) {
+    if (databases.includes('cisa_kev')) {
       searchPromises.push((async () => {
         try {
           const cisaResult = await this.searchCisaKev(params.terms, { maxResults: params.maxResults, signal });
@@ -132,12 +167,12 @@ export class SecuritySearcher {
       })());
     }
 
-    if (params.databases.includes('github')) {
+    if (databases.includes('github')) {
       searchPromises.push((async () => {
         try {
           const githubResult = await this.searchGitHub(params.terms, {
             ecosystem: params.ecosystem,
-            severity: params.severity,
+            severity,
             maxResults: params.maxResults,
             repo: params.githubRepo,
             signal,
@@ -150,12 +185,12 @@ export class SecuritySearcher {
       })());
     }
 
-    if (params.databases.includes('osv')) {
+    if (databases.includes('osv')) {
       searchPromises.push((async () => {
         try {
           const osvResult = await this.searchOSV(params.terms, {
             ecosystem: params.ecosystem,
-            severity: params.severity,
+            severity,
             maxResults: params.maxResults,
             signal,
           });
@@ -169,24 +204,10 @@ export class SecuritySearcher {
 
     await Promise.all(searchPromises);
 
-    // Apply delay
-    let delay = this.config.requestDelay ?? -1;
-    if (delay === -1) {
-        delay = params.databases.includes('nvd') ? REQUEST_DELAY_MS_NVD : REQUEST_DELAY_MS_OTHER;
-    }
-
-    if (delay > 0) {
-      // Abortable: a caller cancel must not sit through the post-sweep delay.
-      await new Promise<void>((resolve) => {
-        const timeoutId = setTimeout(() => {
-          signal?.removeEventListener('abort', onAbort);
-          resolve();
-        }, delay);
-        safeUnref(timeoutId);
-        const onAbort = () => { clearTimeout(timeoutId); resolve(); };
-        if (signal) signal.addEventListener('abort', onAbort, { once: true });
-      });
-    }
+    // No post-sweep delay: NVD inter-request spacing is enforced by the module-level
+    // NVDRateLimiter in nvd-client.ts, whose state persists across searches and tool
+    // calls, so sleeping here after results were already in hand only added dead
+    // researcher time.
 
     return {
       results,

package/src/security/nvd-client.ts

@@ -353,6 +353,11 @@ function fetchWithRetry(url: string, signal?: AbortSignal): Promise<Response> {
 
   return nvdCircuitBreaker.execute(async () => {
     return retryWithBackoff(async () => {
+      // Every attempt — the first AND each 2s/4s retry — must hold a rate-limiter
+      // slot: the limiter's spacing is the ONLY mechanism enforcing NVD's ~6s
+      // inter-request interval (the post-sweep sleep was removed), and an acquire
+      // outside this closure let 429/5xx retries re-hit the API faster than it.
+      await nvdRateLimiter.acquire(signal);
       let response: Response;
       try {
         response = await fetch(url, createFetchOptions(signal));
@@ -392,8 +397,8 @@ async function fetchPaginated(
     if (signal?.aborted) break; // stop paginating promptly on cancel
     const url = buildURL(term, options, pageSize, startIndex, severityVersion);
 
-    await nvdRateLimiter.acquire(signal);
-
+    // No acquire here: fetchWithRetry acquires a rate-limiter slot per ATTEMPT,
+    // so retries are spaced too — a second acquire would double-charge the page.
     const response = await fetchWithRetry(url, signal);
     let data: unknown;
     try {

package/src/skill-install/skill-installer.ts

@@ -217,12 +217,28 @@ export function readManifest(opts?: { home?: string }): Manifest {
   return { version: 1, package: PACKAGE_NAME, entries: [] };
 }
 
+/** Monotonic per-process suffix for manifest tmp files (see writeManifest). */
+let manifestTmpSeq = 0;
+
 function writeManifest(manifest: Manifest, opts?: { home?: string }): void {
   const p = getManifestPath(opts);
   fs.mkdirSync(path.dirname(p), { recursive: true });
-  const tmp = `${p}.tmp`;
+  // Unique tmp name (pid + timestamp + counter, mirroring config.ts's registry
+  // writer): a FIXED `${p}.tmp` was a shared collision surface — concurrent
+  // runs' reconciles (the run cap allows 3 live runs) staged through the same
+  // path, the winner renamed it away, and the loser's renameSync threw ENOENT,
+  // surfacing as a spurious skill-install error. The read-modify-write around
+  // this stays deliberately UNLOCKED: a lost update is self-healing churn (the
+  // next reconcile re-derives the same state from disk), unlike the hard
+  // failure a tmp-name collision caused.
+  const tmp = `${p}.tmp.${process.pid}.${Date.now()}.${manifestTmpSeq++}`;
   fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tmp, p);
+  try {
+    fs.renameSync(tmp, p);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* best effort */ }
+    throw err;
+  }
 }
 
 function upsertEntry(manifest: Manifest, entry: ManifestEntry): void {

package/src/stackexchange/index.ts

@@ -45,6 +45,24 @@ function loadConfig(): StackExchangeConfig {
   };
 }
 
+// The client instance carries the resilience state the SE API requires callers to
+// honor across requests: the `backoff` directive (rest-client lastBackoff), quota
+// tracking, and the 5-failure circuit breaker. A per-call instance resets all of
+// that on every tool call — the exact throttle-violation pattern SE punishes with
+// IP bans — so the client is process-wide, rebuilt only when the API key changes
+// (the sole constructor input that can vary between calls; requestTimeout is a
+// constant in loadConfig).
+let sharedClient: StackExchangeClient | null = null;
+let sharedClientApiKey: string | null = null;
+
+function getClient(config: StackExchangeConfig): StackExchangeClient {
+  if (sharedClient === null || sharedClientApiKey !== config.apiKey) {
+    sharedClient = new StackExchangeClient(config.apiKey, config.requestTimeout);
+    sharedClientApiKey = config.apiKey;
+  }
+  return sharedClient;
+}
+
 /**
  * Main command handler for Stack Exchange operations
  */
@@ -60,11 +78,8 @@ export async function stackexchangeCommand(options: {
   // Load config
   const config = loadConfig();
 
-  // Initialize client
-  const client = new StackExchangeClient(
-    config.apiKey,
-    config.requestTimeout,
-  );
+  // Shared client — resilience state (backoff, quota, breaker) persists across calls
+  const client = getClient(config);
 
   try {
     // Check quota before making requests

package/src/stackexchange/output/table.ts

@@ -56,8 +56,13 @@ export function formatAnswersTable(answers: Answer[]): string {
     output += `- **Question ID:** ${a.question_id}\n`;
     output += `- **Created:** ${new Date(a.creation_date * 1000).toLocaleString()}\n`;
 
-    if (a.body && a.body.length < 2000) {
-      output += `\n### Answer Body\n\n${a.body}\n`;
+    if (a.body) {
+      // Truncate long bodies to a preview rather than dropping them entirely — the
+      // previous `length < 2000` guard omitted the body for exactly the longest
+      // answers (same class as the question-body fix above; answers get a more
+      // generous bound since the body is the whole point of an answer).
+      const body = a.body.length > 2000 ? `${a.body.substring(0, 2000)}...` : a.body;
+      output += `\n### Answer Body\n\n${body}\n`;
     }
 
     output += '\n---\n\n';

package/src/stackexchange/rest-client.ts

@@ -11,6 +11,16 @@ 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;
@@ -22,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;
@@ -122,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(),
@@ -136,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);
@@ -197,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-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');