@lincoln504/pi-research 1.3.11 → 1.4.1

package/src/prompts/system-lead-router.md

@@ -0,0 +1,122 @@
+# Research Lead — Routing
+
+You decide whether this research run continues or ends.
+
+You are given the message in two parts.
+
+**NEW SINCE YOUR LAST DECISION** holds the **full reports** from the researchers that have just finished. This is the evidence your decision turns on — read it. Each report is preceded by the **coverage digest** its own researcher wrote for it: treat that as a *claim*, and check it against the report underneath. A digest saying `Gaps: none` above a thin or hedged report is the single most important thing you can catch, because nobody else will.
+
+**REVIEWED IN EARLIER ROUNDS** holds only the coverage digests of reports you already read in full on a previous round and already judged. They are not repeated in full — you have seen them.
+
+Everything specific to this run — the root query, the current round and round budget, the agenda so far, the queries already executed, any additional user guidance, and the phase guidance for this particular round — is supplied in a **RUN CONTEXT** block at the END of the message you are given, after the reports. Read that block before deciding; the instructions below tell you how to decide, the RUN CONTEXT tells you what you are deciding about.
+
+You never write the report. When you decide the research is complete, a separate synthesis step reads every full report and writes it. Your output is a decision, not prose.
+
+## CRITICAL: Steering Compliance Checkpoint
+- **STRICT STEERING**: If the RUN CONTEXT block carries an "ADDITIONAL USER GUIDANCE" section, you MUST treat every point in it as a **mandatory rule and instruction** for your decisions, next round goals, and queries. Do not ignore them. They are directional requirements.
+- **STEERING SATISFACTION**: Before deciding to FINISH, you MUST explicitly verify that ALL user steering requirements are actually covered by the findings — not merely claimed by a digest. If ANY steering requirement is unaddressed, or only superficially covered, you MUST DELEGATE — do NOT finish. The user's guidance takes priority over round budget or feeling that research is "complete enough."
+
+{{disabled_tools_section}}
+
+---
+
+## Complexity-Aware Decision Thresholds
+
+**Complexity Level**: {{complexity_label}}
+
+{{complexity_guidance}}
+
+The phase guidance for the current round appears in the RUN CONTEXT block; it refines these thresholds for where this run currently sits in its round budget.
+
+---
+
+## Reading the evidence
+
+For **earlier rounds** you have only the digest, and you already judged that work when it arrived. For **new reports** you have the prose; the digest beside it is a claim to verify.
+
+Read a digest as follows:
+
+- **`Covered`** tells you what is established. Treat a specific, concrete `Covered` line as reliable; treat a vague one ("general background on the topic") as weak coverage that may need a follow-up.
+- **`Gaps`** is a researcher telling you directly what it could not reach. A non-"none" `Gaps` line on a topic the root query asks about is the strongest possible signal to delegate.
+- **`Unsubstantiated`** flags claims that were looked for and not grounded. Delegating a targeted follow-up on those is usually higher value than opening a new angle.
+- **`Sources: 0` or a very low count** means that researcher produced little usable material regardless of what its other lines claim. Re-cover that goal.
+- **A digest that says coverage is unknown** was derived mechanically because that researcher emitted no digest of its own. For a new report that costs you nothing — read the report. For an earlier round it means coverage there is unverified, so weigh it accordingly.
+
+**Verify the new reports rather than trusting their digests.** For each new report, read the prose and ask whether it actually establishes what its `Covered` line claims. Specific, sourced prose backs the claim up. Hedged prose, "not found in sources", a handful of thin paragraphs, or a report that never reaches its stated topic does not — in that case the goal is still open however confidently the digest is worded, and you should delegate it again.
+
+Then compare everything covered — earlier digests plus what the new reports actually establish — against the root query and the initial agenda. What the root query asks for and nothing covers is a gap.
+
+---
+
+## Decision Framework
+
+**FINISH if:** Coverage across the new reports and the earlier digests meets the complexity-specific synthesis criteria above. ("Finish" is the decision; the literal value you emit for it is `"action": "synthesize"`.)
+**DELEGATE if:** Coverage meets the complexity-specific delegation criteria above.
+**Note on Guidance**: If the user provides additional guidance mid-research (via Alt+Enter or direct follow-up), those messages will be provided to you. You MUST incorporate them into your next round's delegation goals and queries.
+
+**STAY IN SCOPE (every delegation):**
+- Going deeper on in-scope material is always welcome. Widening to new areas (breadth) is the drift to avoid — only do it when genuinely appropriate and helpful for the topic.
+- A gap is missing depth on what was asked — not a broader topic next to it. Don't add anything the query didn't ask for, even if it came up in the findings.
+- Match the query's scope-bounding constraints exactly — don't broaden them, don't narrow them.
+
+**COMMON MISTAKES TO AVOID:**
+- Do NOT finish early just because you've done "enough" rounds. Finish only when the evidence shows comprehensive coverage across all major topics the query asks about.
+- Do NOT finish with gaps remaining, hoping they can be "filled in later". Complete the research first.
+- Do NOT invent a gap outside the query's scope just to keep going or fill the budget. Finish what was asked; don't add what wasn't.
+- Do NOT write findings, prose, or a report. You have read findings, but writing the report is a separate step's job. A `reason` is one sentence.
+
+Use unique, targeted queries for any new researchers.
+
+**Decision**: Return valid JSON in a code block:
+
+**If the research is complete**:
+```json
+{
+  "action": "synthesize",
+  "reason": "<one sentence naming the coverage that makes this complete>"
+}
+```
+
+**If delegating**:
+```json
+{
+  "action": "delegate",
+  "researchers": [
+    {
+      "id": "<CURRENT_ROUND>.1",
+      "name": "<Researcher Specialty>",
+      "goal": "<Focused gap or new angle to investigate>",
+      "queries": ["<query_1>", "<query_2>", "<query_3>", "..."]
+    }
+  ],
+  "allQueries": ["<flat_list_of_all_queries_from_all_new_researchers>"]
+}
+```
+
+**DELEGATION REQUIREMENTS**:
+- **CRITICAL — Queries are mandatory**: Every researcher MUST have at least one query. Never plan a researcher without queries. Researchers receive ONLY the search results you delegate to them.
+- **Maximize queries**: For EACH researcher, generate the maximum number of targeted, specific queries within the budget. Do not plan fewer than needed — fill the budget. Queries should target primary sources and authoritative evidence.
+- **YouTube discovery**: For roughly one in {{youtube_query_every_n}} queries, append the word `youtube` to the query text (e.g. `"<topic> analysis youtube"`). DuckDuckGo rarely surfaces YouTube on its own, and YouTube links let researchers read video transcripts. Skip only when the gap is clearly unsuited to video.
+- **Temporal anchoring**: Anchor every new time-sensitive query to the current month and year shown at the top of this prompt. Use that exact year (and month where relevant); never default to an older year than the one shown there unless the user explicitly asks about the past.
+- **Flexible coverage**: Use up to {{max_team_size}} researchers to cover distinct angles in parallel. Scale based on research gaps — a single well-targeted researcher is often sufficient for focused gaps.
+- **Source diversity**: Encourage researchers to find multiple authoritative sources per topic area to enable comprehensive citations in the final synthesis.
+
+---
+
+## Quality Standards for Delegation
+
+When delegating, ensure:
+- **Query Specificity**: Each new query targets distinct, unexplored territory
+- **No Redundancy**: Do not repeat queries from previous rounds
+- **Specialized Focus**: Each new researcher has a clear, distinct angle
+- **Gap-Driven**: Only delegate when the evidence shows a gap that existing coverage cannot resolve
+- **Progressive Depth**: New queries go deeper, or to a new angle still inside the query's scope — never outside it, and never repeating surface-level coverage
+
+---
+
+## Output Requirements
+
+- **Researcher IDs**: Use Round.Index format — the current round number from the RUN CONTEXT block, then the researcher index. In round 3 that is **3.1**, **3.2**, and so on.
+- **Query Budget**: Use the complexity-specific budget ({{query_budget}} per researcher). Fill each researcher's query budget completely.
+- **Team Size**: Scale researcher count to match the gaps. Use up to {{max_team_size}} researchers when delegating, but a single well-targeted researcher is often sufficient for focused gaps. Don't pad the team when fewer researchers will cover the remaining gaps efficiently.
+- **Format**: ONLY return valid JSON in a code block. Never return report prose.

package/src/prompts/system-lead-synthesizer.md

@@ -0,0 +1,46 @@
+# Research Lead — Synthesis
+
+You write the final report for this research run.
+
+The research is finished. Every researcher report collected during the run is supplied to you in full, followed by a **Global Source List**, followed by a **RUN CONTEXT** block carrying the root query and any additional user guidance. Read the RUN CONTEXT block before writing: the instructions below tell you how to write, it tells you what the report is about.
+
+You do not decide anything and you do not plan further research. Your only output is the report.
+
+## CRITICAL: Steering Compliance
+If the RUN CONTEXT block carries an "ADDITIONAL USER GUIDANCE" section, treat every point in it as a **mandatory rule** governing the report's content, structure, and emphasis. The user's guidance overrides your own judgment about what to include or how to organize.
+
+{{disabled_tools_section}}
+
+---
+
+## Synthesis Protocol
+
+1. **Organization**: Organize the report logically **BY TOPIC**. Do NOT structure it by researcher or round.
+2. **Anonymity**: Do NOT reference "researchers", "agents", "reports", or the research process. Present the findings as a direct, unified knowledge base.
+3. **Master Links List**: A **Global Source List** has been provided to you, after the findings. Use these sequential numbers [1], [2], [3], etc., for all inline citations. The researcher reports provided to you have already been normalized to these global numbers. This list includes all URLs found during live research and any relevant entries from the **Local and Global Knowledge Stores**.
+4. **Exhaustive Synthesis**: Use ALL findings from ALL reports. Include every fact, date, name, and statistic verbatim. Longer is better.
+5. **Strict Grounding**: Every sentence must come from a report. Use [N] inline citations. No prior knowledge.
+6. **CRITICAL — Links at Bottom Only**:
+   - Write all topic sections first with inline citations [1], [2], etc., using the numbers from the **Global Source List**.
+   - Place exactly ONE `CITED LINKS` section at the VERY END of the entire synthesis.
+   - This section must contain the complete master list of all unique URLs exactly as provided in the **Global Source List**.
+   - Do NOT include any links within topic sections or subsections.
+   - Format: `[1] https://url.com [Source: ...] — brief description` on each line.
+
+> **MANDATORY TERMINATION RULE**: Your synthesis is not complete until it ends with `CITED LINKS`. Do NOT close the JSON object or stop generating until this section is written in full. A synthesis without `CITED LINKS` is a failed output.
+
+---
+
+## Output Requirements
+
+- **Synthesis Quality**: Logical topic-based structure in plain prose, maximal detail, NO mention of researchers, NO markdown headings or bullets.
+- **Format**: ONLY return valid JSON in a code block:
+
+```json
+{
+  "action": "synthesize",
+  "content": "<Plain prose report with [N] citations, organized by topic. No markdown headings, bullets, or bold text. Followed by the mandatory CITED LINKS section.>"
+}
+```
+
+{{partial_synthesis_section}}

package/src/sdk.ts

@@ -44,7 +44,7 @@ import { runHealthCheck } from './healthcheck/index.ts';
 import { buildModelRegistry as sharedBuildModelRegistry, resolveModel } from './core/llm/model-registry-factory.ts';
 import { scrapeSingle } from './web-research/web-scraper.ts';
 import { validateInitialLinks } from './utils/url-utils.ts';
-import { validateUrlForSSRF } from './web-research/scraper-utils.ts';
+import { validateUrlForSSRF, disposeSsrfSafeFetcher } from './web-research/scraper-utils.ts';
 import type { ScrapeResult } from './core/interfaces/scheduler-interfaces.ts';
 import { randomUUID } from 'node:crypto';
 import type { ResearchDepth } from './types/index.ts';
@@ -954,6 +954,15 @@ async function _doShutdown(): Promise<void> {
     errors.push(err instanceof Error ? err : new Error(String(err)));
   }
 
+  // Release the module-level undici Agent's keep-alive sockets. Nothing else
+  // owns it, so a long-lived host would otherwise hold them past teardown.
+  try {
+    await disposeSsrfSafeFetcher();
+  } catch (err) {
+    logger.error('[SDK] Error disposing SSRF fetcher:', err);
+    errors.push(err instanceof Error ? err : new Error(String(err)));
+  }
+
   if (globalContainer) {
     // Dispose all services in one DAG-ordered teardown. disposeCoreServices first
     // clears the embedding-server state while the StateManager is still alive, then

package/src/security/nvd-client.ts

@@ -22,7 +22,6 @@ import type {
 } from './nvd-types.ts';
 import { createTimeoutSignal, retryWithBackoff, isTransientError } from '../web-research/retry-utils.ts';
 import { CircuitBreaker } from '../utils/circuit-breaker.ts';
-import { safeUnref } from '../utils/safe-unref.ts';
 import { metrics } from '../utils/metrics.ts';
 import { readJsonCapped, BodyTooLargeError, MAX_BULK_JSON_BODY_BYTES } from '../utils/http-body.ts';
 import {
@@ -77,7 +76,15 @@ class NVDRateLimiter {
           signal?.removeEventListener('abort', onAbort);
           resolve();
         }, waitTime);
-        safeUnref(timeoutId);
+        // NOT unref'd. This timer IS the operation, not a watchdog racing one:
+        // nothing else will ever settle this promise, so unref'ing it let Node
+        // consider the process idle while an NVD search was mid-spacing. With no
+        // other ref'd handle the search simply never resumed — the awaited
+        // promise stayed unsettled and the caller got no result and no error.
+        // Every other unref in this codebase guards a timeout against real I/O
+        // that holds the loop open by itself; this one had nothing behind it.
+        // Bounded (≤6s, or ≤600ms with NVD_API_KEY) and abortable below, so
+        // keeping it ref'd cannot delay shutdown beyond one spacing interval.
         const onAbort = () => {
           clearTimeout(timeoutId as unknown as ReturnType<typeof setTimeout>);
           reject(Object.assign(new Error('NVD search aborted'), { name: 'AbortError' }));
@@ -392,6 +399,8 @@ async function fetchPaginated(
   const signal = options?.signal;
   let startIndex = 0;
   let totalPagesFetched = 0;
+  // Whether the one-time jump to the newest window (below) has been performed.
+  let seekedToNewest = false;
 
   while (totalPagesFetched < maxPages && allVulnerabilities.length < maxResults) {
     if (signal?.aborted) break; // stop paginating promptly on cancel
@@ -433,10 +442,40 @@ async function fetchPaginated(
     }
     metrics.increment('nvd_cache_hits_total', 1);
 
+    const responseData = data as Record<string, unknown> | undefined;
+    const reportedTotal = typeof responseData?.['totalResults'] === 'number'
+      ? responseData['totalResults'] as number
+      : undefined;
+
+    // NVD 2.0 returns keyword matches OLDEST FIRST and offers no sort parameter
+    // (`sortBy` is a 404), so paging from index 0 and stopping at maxResults kept
+    // precisely the least useful window: a `security_search` for "openssl"
+    // returned CVE-1999-0428 through 2004 out of 566 matches and could never
+    // reach the ones published this month. Seek once to the tail instead, so the
+    // rows we keep are the most recent. Only fires when the match set is larger
+    // than what we return — a query whose results all fit is already complete, so
+    // the common (and every mocked) case still costs exactly one request.
+    //
+    // Interaction with the `v2` supplemental pass (searchSingleTerm), deliberate:
+    // that pass admits only entries carrying NO v3/v4 metric, and NVD scores
+    // essentially every modern CVE with v3 — so v2-only rows live at the OLD end.
+    // Seeking to the tail therefore makes the supplement return little or nothing
+    // once a match set is large. That is the intended trade, not an oversight: the
+    // supplement was the channel feeding 1999-era advisories into results that are
+    // supposed to describe the current picture. A genuinely legacy product still
+    // works, because its own v2 match set is small enough that no seek fires.
+
+    if (!seekedToNewest && startIndex === 0 && reportedTotal !== undefined && reportedTotal > maxResults) {
+      seekedToNewest = true;
+      startIndex = reportedTotal - maxResults;
+      allVulnerabilities.length = 0; // the oldest window we just read is not what we want
+      totalPagesFetched++;
+      continue;
+    }
+
     allVulnerabilities.push(...admitted);
 
-    const responseData = data as Record<string, unknown> | undefined;
-    if (responseData?.['totalResults'] !== undefined && typeof responseData['totalResults'] === 'number' && startIndex + pageSize >= responseData['totalResults']) {
+    if (reportedTotal !== undefined && startIndex + pageSize >= reportedTotal) {
       break;
     }
 
@@ -447,6 +486,18 @@ async function fetchPaginated(
   metrics.increment('nvd_pagination_requests_total', totalPagesFetched);
   metrics.observe('nvd_pagination_pages_fetched', totalPagesFetched);
 
+  // Newest first within the window. NVD's own order is ascending, so without
+  // this the caller's slice() would again favour the older end of whatever we
+  // gathered. Undated entries sort last rather than jumping to the front.
+  allVulnerabilities.sort((a, b) => {
+    const ta = a.published ? Date.parse(a.published) : NaN;
+    const tb = b.published ? Date.parse(b.published) : NaN;
+    if (Number.isNaN(ta) && Number.isNaN(tb)) return 0;
+    if (Number.isNaN(ta)) return 1;
+    if (Number.isNaN(tb)) return -1;
+    return tb - ta;
+  });
+
   return allVulnerabilities.slice(0, maxResults);
 }
 

package/src/security/osv-client.ts

@@ -230,7 +230,19 @@ export async function searchOSV(
       }
     }
 
-    vulnerabilities.push(...Array.from(uniqueVulns.values()));
+    // Newest first, so the slice(0, maxResults) below keeps the advisories most
+    // likely to matter. OSV returns a package's vulnerabilities in ID order,
+    // which is effectively alphabetical — truncating that dropped whichever
+    // advisories happened to sort late, recency playing no part. Undated entries
+    // sort last rather than displacing dated ones.
+    vulnerabilities.push(...Array.from(uniqueVulns.values()).sort((a, b) => {
+      const ta = a.published ? Date.parse(a.published) : NaN;
+      const tb = b.published ? Date.parse(b.published) : NaN;
+      if (Number.isNaN(ta) && Number.isNaN(tb)) return 0;
+      if (Number.isNaN(ta)) return 1;
+      if (Number.isNaN(tb)) return -1;
+      return tb - ta;
+    }));
 
     if (failures.length > 0 && failures.length === terms.length) {
       throw new Error(`All OSV lookups failed: ${failures.join('; ')}`);

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

@@ -54,6 +54,7 @@ import { loadPrompt } from '../core/llm/prompts.ts';
 import { formatParentContext } from '../orchestration/session-context.ts';
 import { getConfig, type ConfigInterface, type Config } from '../config.ts';
 import { createKnowledgeSearchPanel } from '../tui/knowledge-search-panel.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 // ---------------------------------------------------------------------------
 // Phase 1: Tool Parameters
@@ -114,6 +115,17 @@ export function formatQueriesBlock(queries: string[]): string {
 /** Widget ID for the knowledge search TUI panel */
 const KNOWLEDGE_WIDGET_ID = 'pi-research-knowledge-search';
 
+/**
+ * How many knowledge searches are currently showing the widget.
+ *
+ * The widget ID is a single global slot and `setWidget` replaces rather than
+ * stacks, but this tool is `executionMode: 'parallel'` and can also be driven
+ * concurrently by the `/knowledge-store` slash command. Without a refcount the
+ * first call to finish tears the widget down while a sibling is still running,
+ * leaving an in-flight search with no indicator. Only the last one out removes it.
+ */
+let knowledgeWidgetRefCount = 0;
+
 /**
  * System string returned when the answer is NOT found in the research
  * knowledge store. The exact phrasing is critical — the main pi agent
@@ -140,6 +152,7 @@ export const RESEARCH_KNOWLEDGE_MAYBE_STRING =
  */
 function showKnowledgeSearchWidget(ctx: ExtensionContext): void {
   if (ctx.mode !== 'tui' || !ctx.hasUI) return;
+  knowledgeWidgetRefCount++;
   try {
     const panelFactory = createKnowledgeSearchPanel();
     ctx.ui.setWidget(KNOWLEDGE_WIDGET_ID, panelFactory as any, { placement: 'aboveEditor' });
@@ -149,10 +162,15 @@ function showKnowledgeSearchWidget(ctx: ExtensionContext): void {
 }
 
 /**
- * Remove the knowledge search TUI widget.
+ * Remove the knowledge search TUI widget once the last concurrent search is done.
  */
 function hideKnowledgeSearchWidget(ctx: ExtensionContext): void {
   if (ctx.mode !== 'tui' || !ctx.hasUI) return;
+  // show() incremented under the identical guard, so the counter stays balanced.
+  // Clamp anyway: a stray hide must never drive it negative and wedge the
+  // widget on-screen for the rest of the session.
+  knowledgeWidgetRefCount = Math.max(0, knowledgeWidgetRefCount - 1);
+  if (knowledgeWidgetRefCount > 0) return;
   try {
     ctx.ui.setWidget(KNOWLEDGE_WIDGET_ID, undefined as any, { placement: 'aboveEditor' });
   } catch (err) {
@@ -422,6 +440,7 @@ export async function runBackgroundExtraction(
   maxTokens: number,
   thinkingLevel: Config['LLM_THINKING_LEVEL'],
   signal?: AbortSignal,
+  sessionId?: string,
 ): Promise<ResearchKnowledgeSynthesisResponse> {
   const promptTemplate = loadPrompt('research-knowledge-search-extractor');
   if (!promptTemplate) {
@@ -462,7 +481,8 @@ export async function runBackgroundExtraction(
         }, buildSafeOptions(model, {
           apiKey: auth.apiKey,
           headers: auth.headers,
-          signal
+          signal,
+          sessionId,
         }, maxTokens, thinkingLevel)),
         llmTimeout,
         'knowledge-search-extraction',
@@ -520,6 +540,7 @@ export async function runBackgroundExtraction(
       context: 'Knowledge search extraction — synthesizing answer from reference documents',
       serviceName: 'ResearchKnowledgeSearch',
       signal,
+      sessionId,
       // Match the budget of the call being repaired so a large synthesis is not re-truncated
       // at repairJsonWithLlm's smaller default (16384). Mirrors the planning-service repairs.
       maxTokens,
@@ -955,6 +976,11 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
           config.SYNTHESIS_MAX_TOKENS,
           config.LLM_THINKING_LEVEL,
           signal,
+          // Cache/session-affinity hint only (keeps repeated calls on the same warmed
+          // replica) — same resolution research-config.ts uses, since this tool has no
+          // researchId of its own to key on. ctx.sessionId is read defensively: it is
+          // not on every host's ExtensionContext shape, hence the `as any`.
+          (ctx as any).sessionId || ctx.sessionManager?.getSessionId(),
         );
 
         const durationMs = Date.now() - startTime;
@@ -966,7 +992,6 @@ 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
@@ -974,7 +999,7 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
         // 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)) {
+        if (isCancellation(error, signal)) {
           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.');

package/src/tools/scrape.ts

@@ -31,6 +31,7 @@ import { ServiceNames } from '../core/service-interfaces.ts';
 import type { IKnowledgeStoreService } from '../core/service-interfaces.ts';
 import { logger } from '../logger.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 export function createScrapeTool(options: {
   ctx: ExtensionContext;
@@ -267,6 +268,11 @@ export function createScrapeTool(options: {
         }, container);
         freshResults = Array.isArray(results) ? results : [];
       } catch (error) {
+          // A cancelled scrape is not a failed scrape — see isCancellation.
+          if (isCancellation(error, signal)) {
+            metrics.increment('tool_scrape_calls_total', 1, { status: 'cancelled' });
+            throw error;
+          }
           const message = error instanceof Error ? error.message : String(error);
           logger.error(`[scrape tool] Scrape failed: ${message}`);
           metrics.increment('tool_scrape_calls_total', 1, { status: 'error' });

package/src/tools/search.ts

@@ -13,6 +13,7 @@ import type { SystemResearchState } from '../orchestration/deep-research-types.t
 import { logger } from '../logger.ts';
 import { type Config, getConfig } from '../config.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 import { tryGetServiceContainerFromCtx } from '../core/service-registry.ts';
 
 export function createSearchTool(options: {
@@ -134,6 +135,12 @@ export function createSearchTool(options: {
         };
       } catch (error) {
         const elapsed = Date.now() - startTime;
+        // A cancelled search is not a failed search — see isCancellation.
+        if (isCancellation(error, signal)) {
+          metrics.observe('tool_search_duration_ms', elapsed, { status: 'cancelled' });
+          metrics.increment('tool_search_calls_total', 1, { status: 'cancelled' });
+          throw error;
+        }
         metrics.observe('tool_search_duration_ms', elapsed, { status: 'error' });
         metrics.increment('tool_search_calls_total', 1, { status: 'error' });
         const msg = error instanceof Error ? error.message : String(error);

package/src/tools/security.ts

@@ -11,6 +11,7 @@ import { searchSecurityDatabases } from '../security/index.ts';
 import type { ToolUsageTracker } from '../utils/tool-usage-tracker.ts';
 import { getMaxGatheringCalls } from '../constants.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 import type { SecuritySearchParams } from '../security/types.ts';
 
 const MAX_DESCRIPTION_CHARS = 300;
@@ -78,7 +79,24 @@ export function createSecuritySearchTool(options: {
       _extensionCtx,
     ): Promise<AgentToolResult<unknown>> {
       const startTime = Date.now();
-      metrics.increment('tool_security_search_calls_total', 1);
+
+      // Every exit path below increments `tool_security_search_calls_total` itself
+      // (labeled with its own status) — there is no separate unconditional increment
+      // here. There used to be one, which double-counted every single call: sumCounter
+      // matches both the bare key and every labeled variant of the same base name, so
+      // the Session Metrics / Research Summary view reported exactly 2x the real count.
+
+      // Validate BEFORE spending the budget: a rejected call did no work, and charging
+      // it against the shared MAX_GATHERING_CALLS allowance turns a malformed call into
+      // a permanently lost one. See youtube-transcript for the sharpest case (a single
+      // allowed call, forfeited by a schema violation).
+      if (!Value.Check(SecuritySearchParamsSchema, params)) {
+          metrics.increment('tool_security_search_calls_total', 1, { status: 'invalid_params' });
+          return {
+            content: [{ type: 'text', text: 'Invalid parameters for security_search tool.' }],
+            details: { error: 'invalid_parameters' },
+          };
+      }
 
       // Record call in tracker - returns false if limit reached
       const allowed = options.tracker.recordCall('security_search');
@@ -90,14 +108,6 @@ export function createSecuritySearchTool(options: {
           };
       }
 
-      if (!Value.Check(SecuritySearchParamsSchema, params)) {
-          metrics.increment('tool_security_search_calls_total', 1, { status: 'invalid_params' });
-          return {
-            content: [{ type: 'text', text: 'Invalid parameters for security_search tool.' }],
-            details: { error: 'invalid_parameters' },
-          };
-      }
-
       const p = params as SecuritySearchParamsType;
 
       const terms = p.terms;
@@ -167,6 +177,14 @@ export function createSecuritySearchTool(options: {
         results = await searchSecurityDatabases(searchParams, signal);
       } catch (error) {
         const duration = Date.now() - startTime;
+        // A cancelled search is not a database outage — see isCancellation. The
+        // "temporary issue - try again later" text below invites exactly the retry
+        // the user just interrupted.
+        if (isCancellation(error, signal)) {
+          metrics.observe('tool_security_search_duration_ms', duration, { status: 'cancelled' });
+          metrics.increment('tool_security_search_calls_total', 1, { status: 'cancelled' });
+          throw error;
+        }
         metrics.observe('tool_security_search_duration_ms', duration, { status: 'error' });
         metrics.increment('tool_security_search_calls_total', 1, { status: 'error' });
         const errorMsg = error instanceof Error ? error.message : String(error);

package/src/tools/stackexchange.ts

@@ -10,6 +10,7 @@ import { Value } from 'typebox/value';
 import { stackexchangeCommand } from '../stackexchange/index.ts';
 import type { ToolUsageTracker } from '../utils/tool-usage-tracker.ts';
 import { getMaxGatheringCalls } from '../constants.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 export function createStackexchangeTool(options: {
   ctx: ExtensionContext;
@@ -74,6 +75,15 @@ export function createStackexchangeTool(options: {
       _onUpdate,
       extensionCtx,
     ): Promise<AgentToolResult<unknown>> {
+      // Validate BEFORE spending the budget — see security.ts. A rejected call did no
+      // work and must not consume one of MAX_GATHERING_CALLS.
+      if (!Value.Check(StackExchangeParamsSchema, params)) {
+          return {
+            content: [{ type: 'text', text: 'Invalid parameters for stackexchange tool.' }],
+            details: { error: 'invalid_parameters' },
+          };
+      }
+
       // Record call in tracker - returns false if limit reached
       const allowed = tracker.recordCall('stackexchange');
       if (!allowed) {
@@ -83,13 +93,6 @@ export function createStackexchangeTool(options: {
           };
       }
 
-      if (!Value.Check(StackExchangeParamsSchema, params)) {
-          return {
-            content: [{ type: 'text', text: 'Invalid parameters for stackexchange tool.' }],
-            details: { error: 'invalid_parameters' },
-          };
-      }
-
       const p = params as StackExchangeParams;
       const command = p.command;
 
@@ -105,6 +108,9 @@ export function createStackexchangeTool(options: {
           signal,
         });
       } catch (error) {
+        // A cancelled query was never rate-limited — see isCancellation. Naming a
+        // quota the run never hit is a cause the agent can carry into its report.
+        if (isCancellation(error, signal)) throw error;
         const errorMsg = error instanceof Error ? error.message : String(error);
         return {
           content: [

package/src/tools/youtube-transcript.ts

@@ -24,6 +24,7 @@ import { cacheScrapedContent, registerScrapedLinks, registerTranscribedLinks, re
 import { type Config, getConfig } from '../config.ts';
 import { logger } from '../logger.ts';
 import { metrics } from '../utils/metrics.ts';
+import { isCancellation } from '../utils/cancellation.ts';
 
 export function createYoutubeTranscriptTool(options: {
   ctx: ExtensionContext;
@@ -75,18 +76,12 @@ export function createYoutubeTranscriptTool(options: {
       _onUpdate: AgentToolUpdateCallback<unknown>,
       extensionCtx: ExtensionContext,
     ): Promise<AgentToolResult<unknown>> {
-      // Rate-limit enforcement (one call per researcher).
-      if (tracker) {
-        const allowed = tracker.recordCall('youtube_transcript');
-        if (!allowed) {
-          metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'rate_limited' });
-          return {
-            content: [{ type: 'text', text: tracker.getLimitMessage('youtube_transcript') }],
-            details: { blocked: true, reason: 'limit_reached' },
-          };
-        }
-      }
-
+      // Validate BEFORE spending the budget. Charging a rejected call is not a rate
+      // limit, it is a forfeit: this tool's schema caps `urls` at maxVideos while the
+      // per-researcher allowance is a single call, so a researcher passing one URL too
+      // many got a validation error AND lost its only call — and the retry was then told
+      // "You have already used your one youtube_transcript call", which is false. The
+      // round loses transcripts entirely. grep and search already validate first.
       if (!Value.Check(YoutubeParamsSchema, params)) {
         metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'invalid_params' });
         return {
@@ -105,6 +100,19 @@ export function createYoutubeTranscriptTool(options: {
         };
       }
 
+      // Rate-limit enforcement (one call per researcher), now that the call is one that
+      // would actually do work.
+      if (tracker) {
+        const allowed = tracker.recordCall('youtube_transcript');
+        if (!allowed) {
+          metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'rate_limited' });
+          return {
+            content: [{ type: 'text', text: tracker.getLimitMessage('youtube_transcript') }],
+            details: { blocked: true, reason: 'limit_reached' },
+          };
+        }
+      }
+
       // Resolve config against the live cwd for timeout/lang. The video cap stays
       // `maxVideos` (the factory value the schema's maxItems was built from) so the
       // schema gate and the command-level cap can never disagree. The PoToken
@@ -151,6 +159,12 @@ export function createYoutubeTranscriptTool(options: {
 
         return result;
       } catch (error) {
+        // A cancelled batch is not bot-protection — see isCancellation. "Continue
+        // with the rest of your research" is the opposite of what a Ctrl-C means.
+        if (isCancellation(error, signal)) {
+          metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'cancelled' });
+          throw error;
+        }
         const errorMsg = error instanceof Error ? error.message : String(error);
         logger.error(`[youtube_transcript tool] Failed: ${errorMsg}`);
         metrics.increment('tool_youtube_transcript_calls_total', 1, { status: 'error' });