@lincoln504/pi-research 1.0.4 → 1.0.6

package/src/cli.ts

@@ -259,7 +259,7 @@ export interface CredentialDetection {
   apiKeyConfigured: boolean;
   provider?: string;
   model?: string;
-  modelFrom: 'PI_RESEARCH_MODEL' | 'config.env' | 'unset';
+  modelFrom: '--model' | 'PI_RESEARCH_MODEL' | 'config.env' | 'unset';
   piAuthPresent: boolean;
   piModelsPresent: boolean;
   /** A short, human-readable problem string, or undefined when ready. */
@@ -269,8 +269,17 @@ export interface CredentialDetection {
 /**
  * Detect how the SDK will authenticate WITHOUT initializing it. Used both for
  * the `status` command and for the fast-fail pre-flight before every run.
+ *
+ * `explicitModel` is a per-run `--model` flag. It must participate in the
+ * pre-flight: it outranks PI_RESEARCH_MODEL/config for the run, so (a) it
+ * satisfies the model-required check on its own, and (b) when no explicit
+ * PI_RESEARCH_PROVIDER is set, provider-aware key detection derives the
+ * provider from the FLAG's model — otherwise a configured model on provider X
+ * greenlights a `--model` run on keyless provider Y (or vice versa wrongly
+ * blocks a valid `--model` run). An explicit PI_RESEARCH_PROVIDER still wins:
+ * it names the provider the configured key belongs to.
  */
-function detectCredentials(): CredentialDetection {
+function detectCredentials(explicitModel?: string): CredentialDetection {
   const paths = resolvedConfigPaths();
   const piAuthPresent = fileExists(paths.piAuth);
   const piModelsPresent = fileExists(paths.piModels);
@@ -280,8 +289,8 @@ function detectCredentials(): CredentialDetection {
   const modelEnv = process.env['PI_RESEARCH_MODEL'];
   const modelConfig = getConfig(process.cwd(), 'cli').RESEARCH_MODEL;
 
-  const model = modelEnv ?? modelConfig;
-  const modelFrom = modelEnv ? 'PI_RESEARCH_MODEL' : modelConfig ? 'config.env' : 'unset';
+  const model = explicitModel ?? modelEnv ?? modelConfig;
+  const modelFrom = explicitModel ? '--model' : modelEnv ? 'PI_RESEARCH_MODEL' : modelConfig ? 'config.env' : 'unset';
   // Provider is either explicit, or inferred from a "provider/id" model string.
   const provider =
     providerEnv ?? (model && model.includes('/') ? model.slice(0, model.indexOf('/')) : undefined);
@@ -316,7 +325,7 @@ function detectCredentials(): CredentialDetection {
         piModelsPresent,
         problem:
           'PI_RESEARCH_API_KEY is set but no model is configured. Set PI_RESEARCH_MODEL to a ' +
-          '"provider/model-id" (e.g. openai/gpt-4o).',
+          '"provider/model-id" (e.g. openai/gpt-4o), or pass --model <provider/id> for a single run.',
       };
     }
     return {
@@ -350,7 +359,8 @@ function detectCredentials(): CredentialDetection {
           'pi credentials were found (in pi\'s configuration), but no research model is configured. ' +
           'The standalone CLI / agent skill run only on an explicitly configured model — they do not ' +
           'follow the model selected inside the pi extension. Set PI_RESEARCH_MODEL to a ' +
-          '"provider/model-id" (in the environment, or in config.env / cli.env below).',
+          '"provider/model-id" (in the environment, or in config.env / cli.env below), or pass ' +
+          '--model <provider/id> for a single run.',
       };
     }
     return {
@@ -401,8 +411,8 @@ function configBlock(det: CredentialDetection, extraNote?: string): string {
   lines.push(`  • api key configured: ${det.apiKeyConfigured}`);
   lines.push(`  • provider:           ${det.provider ?? '(unset — inferred from a provider/model-id model)'}`);
   lines.push(`  • model:              ${det.model ? `${det.model}  [from: ${det.modelFrom}]` : '(not set — set PI_RESEARCH_MODEL, required)'}`);
-  lines.push(`  • pi auth.json:       ${det.piAuthPresent ? 'present' : 'absent'}`);
-  lines.push(`  • pi models.json:     ${det.piModelsPresent ? 'present' : 'absent'}`);
+  lines.push(`  • pi config (auth.json):   ${det.piAuthPresent ? 'present' : 'absent'}`);
+  lines.push(`  • pi config (models.json): ${det.piModelsPresent ? 'present' : 'absent'}`);
   if (extraNote) lines.push(`  • note:               ${extraNote}`);
   return lines.join('\n');
 }
@@ -425,7 +435,9 @@ interface ResearchArgs {
  * markdown report to stdout, and always shuts down (even on failure).
  */
 async function cmdResearch(args: ResearchArgs): Promise<number> {
-  const det = detectCredentials();
+  // Pre-flight with the per-run --model flag folded in: it satisfies the
+  // model-required check and steers the provider-aware key detection.
+  const det = detectCredentials(args.model);
   if (det.problem) {
     if (args.json) toStdout(pretty({ ok: false, error: det.problem, exitCode: EXIT.CONFIG }));
     else toStderr(`\nError: ${det.problem}\n\n${configBlock(det)}\n`);
@@ -447,8 +459,8 @@ async function cmdResearch(args: ResearchArgs): Promise<number> {
 
   const depth: 0 | 1 | 2 | 3 =
     (args.depth ?? getConfig(process.cwd(), 'cli').DEFAULT_RESEARCH_DEPTH) as 0 | 1 | 2 | 3;
-  // An explicit --model wins over configured/PI_RESEARCH_MODEL for this run.
-  const runModel = args.model ?? det.model;
+  // det.model already reflects --model-first precedence (detectCredentials above).
+  const runModel = det.model;
   toStderr(`[pi-research] starting research (depth ${depth})${runModel ? ` with ${runModel}` : ''}…\n`);
 
   // Stream concise lifecycle progress to stderr so a long run is never silent.
@@ -877,7 +889,7 @@ USAGE
 COMMANDS
   research  "<query>"            Run multi-agent web research (default depth: 1).
     --depth <0-3>                0 = quick, 1 = normal (default), 2 = deep, 3 = ultra.
-    --model <provider/id>        Override the model for this run.
+    --model <provider/id>        Model for this run (outranks PI_RESEARCH_MODEL; satisfies the required-model check).
     --exclude-tools <a,b>        Disable internal tools (e.g. security_search,stackexchange).
     --initial-links <url ...>    Seed URLs to investigate first; requires a query (-- ends options).
     --config <path>              Use this config file instead of the base config.env.
@@ -914,9 +926,9 @@ CONFIGURE
     pi config (keys):    ${p.piAuth}
     pi config (models):  ${p.piModels}
 
-  A model is REQUIRED: set PI_RESEARCH_MODEL to a "provider/model-id". This CLI and
-  the agent skill run only on that configured model — they do not follow the model
-  selected inside the pi extension.
+  A model is REQUIRED: set PI_RESEARCH_MODEL to a "provider/model-id" (or pass
+  --model per run). This CLI and the agent skill run only on that configured
+  model — they do not follow the model selected inside the pi extension.
 
   The pi extension has its own optional overlay file:
     pi extension: ${p.piIfaceEnv}

package/src/knowledge/store.ts

@@ -267,10 +267,12 @@ export class KnowledgeStore implements IKnowledgeStore {
               if (strategy !== 'drop' && strategy !== 'backup') {
                 logger.warn('[store] Falling back to backup strategy after migration failure');
                 await this.handleModelChange(storedModel || 'unknown', this.options.modelName, 'backup');
-              } else if (strategy === 'backup') {
-                logger.warn('[store] Falling back to drop strategy after backup failure');
-                await this.handleModelChange(storedModel || 'unknown', this.options.modelName, 'drop');
               } else {
+                // 'backup' failure must ABORT, never escalate to 'drop': backup is the
+                // data-preserving strategy, and silently destroying every row after a
+                // (possibly transient) failure is the opposite of what the user asked
+                // for. The store stays on the old model; the next open() retries.
+                // 'drop' failure has nowhere further to fall.
                 throw new Error(errorMsg, { cause: err });
               }
             }
@@ -332,8 +334,16 @@ export class KnowledgeStore implements IKnowledgeStore {
       throw new Error('Table not connected');
     }
 
-    const count = await this.table.countRows();
-    
+    // Best-effort: the count is only used for logging and the result summary, so a
+    // transient countRows() failure must not abort the backup (previously it threw
+    // while the fallback ladder could still escalate to a data-destroying drop).
+    let count = -1;
+    try {
+      count = await this.table.countRows();
+    } catch (err) {
+      logger.warn(`[store] countRows failed before backup (continuing): ${err instanceof Error ? err.message : String(err)}`);
+    }
+
     // Close current table handle
     this.table = null;
     
@@ -355,9 +365,9 @@ export class KnowledgeStore implements IKnowledgeStore {
     this.table = await this.createTable();
     // Table name unchanged (still canonical 'knowledge'), but persist to be safe.
     await this.saveManifest();
-    logger.info(`[store] Migration complete: ${count} documents backed up, fresh table created with model ${newModel}`);
+    logger.info(`[store] Migration complete: ${count >= 0 ? count : 'unknown count of'} documents backed up, fresh table created with model ${newModel}`);
 
-    return { strategy: 'backup', success: true, documentsProcessed: count };
+    return { strategy: 'backup', success: true, documentsProcessed: Math.max(0, count) };
   }
 
   private async migrationDrop(_oldModel: string, newModel: string): Promise<MigrationResult> {

package/src/orchestration/deep-research-orchestrator.ts

@@ -17,7 +17,7 @@ import {
 import type {
   ResearchObserver,
 } from '../core/interfaces/observer-interfaces.ts';
-import { HeadlessObserver, type HeadlessObserverOptions } from './headless-observer.ts';
+import { HeadlessObserver, makeSafeObserver, type HeadlessObserverOptions } from './headless-observer.ts';
 import {
   ServiceNames,
   type IResearchOrchestration,
@@ -61,11 +61,12 @@ export class DeepResearchOrchestrator {
   constructor(private options: DeepResearchOrchestratorOptions) {
     this.config = options.config || getConfig(options.ctx.cwd);
     
-    // Resolve observer: if options were provided instead of an instance, create the instance
+    // Resolve observer: if options were provided instead of an instance, create the instance.
+    // Either way, wrap it so a throwing observer callback can never fail the run.
     if (options.observer && typeof (options.observer as any).onProgress === 'function' && !(options.observer instanceof HeadlessObserver)) {
-       this.observer = new HeadlessObserver(options.observer as HeadlessObserverOptions);
+       this.observer = makeSafeObserver(new HeadlessObserver(options.observer as HeadlessObserverOptions));
     } else {
-       this.observer = options.observer as ResearchObserver | undefined;
+       this.observer = options.observer ? makeSafeObserver(options.observer as ResearchObserver) : undefined;
     }
 
     if (options.orchestrationService) {
@@ -478,30 +479,40 @@ export class DeepResearchOrchestrator {
       }
 
       let result = finalReport.content || '';
-      
-      // If content is empty but we have reports, build a fallback synthesis
+
+      // ZERO reports collected AND researchers actually failed — the run attempted
+      // research and produced nothing groundable. This gate is deliberately
+      // independent of the synthesis text: with the default single-researcher plan
+      // the fast-stop threshold (MAX_FAILED_RESEARCHERS = 2) never trips, so a lone
+      // researcher that exhausts its retries (e.g. a provider rate limit) reaches
+      // synthesis with no source material. Whether the LLM then returns an empty
+      // string OR chatty refusal prose ("no information was found"), that is a
+      // FAILED run: throw, and surface the recorded root causes so the user sees
+      // the 429/model error, not a shrug (and never a source-free report shipped
+      // as success). The failed-researcher condition keeps the designed
+      // immediate-synthesis path intact: a coordinator that chose to answer
+      // directly (no delegation, no failures) is not a failed run.
+      const synthesisCheckService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
+      const hasReports = synthesisCheckService.hasReports(researchId);
+      const failedIds = getFailedResearchers(this.options.sessionId, researchId);
+      if (!hasReports && failedIds.length > 0) {
+          const reasons = getResearcherFailureReasons(this.options.sessionId, researchId);
+          const causes = failedIds
+            .map((id) => `researcher ${id}: ${reasons[id] ?? 'no usable report'}`)
+            .join('; ');
+          throw new Error(
+            `Research produced no report — no source material was collected. Causes: ${causes}`
+          );
+      }
+
       if (!result.trim()) {
-          const synthesisService = await getService<IResearchSynthesisService>(ServiceNames.RESEARCH_SYNTHESIS_SERVICE, ctx, container);
-          if (synthesisService.hasReports(researchId)) {
-              logger.warn(`[DeepOrchestrator] LLM returned empty synthesis for ${researchId}, building fallback from ${synthesisService.getReportCount(researchId)} reports`);
-              result = synthesisService.buildFallbackSynthesis(researchId, this.currentRound);
+          if (hasReports) {
+              // Content is empty but reports exist — build a fallback synthesis.
+              logger.warn(`[DeepOrchestrator] LLM returned empty synthesis for ${researchId}, building fallback from ${synthesisCheckService.getReportCount(researchId)} reports`);
+              result = synthesisCheckService.buildFallbackSynthesis(researchId, this.currentRound);
           } else {
-              // ZERO reports were collected — the run produced nothing groundable.
-              // With the default single-researcher plan the fast-stop threshold
-              // (MAX_FAILED_RESEARCHERS = 2) never trips, so a lone researcher that
-              // exhausts its retries (e.g. a provider rate limit) used to land here
-              // and return a hollow "no summary was generated" string on the SUCCESS
-              // path — exit 0. That is a FAILED run: throw, and surface the recorded
-              // root causes so the user sees the 429/model error, not a shrug.
-              const failedIds = getFailedResearchers(this.options.sessionId, researchId);
-              const reasons = getResearcherFailureReasons(this.options.sessionId, researchId);
-              const causes = failedIds
-                .map((id) => `researcher ${id}: ${reasons[id] ?? 'no usable report'}`)
-                .join('; ');
-              throw new Error(
-                'Research produced no report — no source material was collected' +
-                (causes ? `. Causes: ${causes}` : '.')
-              );
+              // No reports, no recorded failures, and nothing to ship either.
+              throw new Error('Research produced no report — no source material was collected.');
           }
       }
 

package/src/orchestration/headless-observer.ts

@@ -12,6 +12,69 @@ import type { ResearchPlan } from '../core/interfaces/research-plan-types.ts';
 
 export type { HeadlessObserverOptions };
 
+/**
+ * Wrap an observer so a throwing (or rejecting) callback can never corrupt a
+ * research run. Observer methods are fire-and-forget notifications, but the
+ * orchestrators invoke them inline at load-bearing points (researcher
+ * completion, evaluation decisions, synthesis start) — an exception from
+ * user-supplied SDK/TUI observer code would otherwise surface as a *research*
+ * failure. HeadlessObserver already isolates its own onProgress callback; this
+ * extends the same isolation to raw ResearchObserver implementations. Sync
+ * throws are logged and swallowed; returned promises get a .catch so
+ * rejections never become unhandled.
+ */
+export function makeSafeObserver<T extends object>(observer: T): T {
+  // Proxy a FRESH empty object and close over the real observer instead of
+  // proxying the observer directly: a `get` trap on the observer itself may
+  // not substitute a wrapper for a non-writable non-configurable own data
+  // property (Proxy invariant), so a frozen observer — a common defensive
+  // pattern for SDK callback bags — would make the engine throw TypeError at
+  // the property ACCESS, outside every try/catch. An empty target has no own
+  // properties, so no invariant can ever bind the trap.
+  return new Proxy({} as T, {
+    get(_target, prop) {
+      // Guard the ACCESS too, and resolve getters against the observer (not
+      // the proxy): an observer exposing a method via an accessor that touches
+      // a private field would otherwise throw at `observer?.onX?.(...)`
+      // property access — outside the call-site try/catch below — which is
+      // exactly the failure this wrapper exists to absorb.
+      let value: unknown;
+      try {
+        value = Reflect.get(observer, prop, observer);
+      } catch (err) {
+        logger.warn(`[observer] Ignored error reading observer.${String(prop)}:`, err);
+        return undefined;
+      }
+      if (typeof value !== 'function') return value;
+      return (...args: unknown[]) => {
+        try {
+          const out = value.apply(observer, args);
+          if (out && typeof (out as Promise<unknown>).then === 'function') {
+            return (out as Promise<unknown>).catch((err: unknown) => {
+              logger.warn(`[observer] Ignored rejection from observer.${String(prop)}:`, err);
+            });
+          }
+          return out;
+        } catch (err) {
+          logger.warn(`[observer] Ignored error from observer.${String(prop)}:`, err);
+          return undefined;
+        }
+      };
+    },
+    has(_target, prop) {
+      try {
+        return Reflect.has(observer, prop);
+      } catch {
+        return false;
+      }
+    },
+    // Keep `instanceof` transparent (legal on an extensible target).
+    getPrototypeOf() {
+      return Reflect.getPrototypeOf(observer);
+    },
+  }) as T;
+}
+
 export class HeadlessObserver implements ResearchObserver {
   constructor(private options: HeadlessObserverOptions = {}) {}
 

package/src/orchestration/quick-research-orchestrator.ts

@@ -20,7 +20,7 @@ import { createResearcherSession } from './researcher.ts';
 import { ensureAssistantResponse, parseCitations } from '../utils/text-utils.ts';
 import { getMaxScrapeBatches } from '../constants.ts';
 import type { ResearchObserver } from '../core/interfaces/observer-interfaces.ts';
-import { HeadlessObserver, type HeadlessObserverOptions } from './headless-observer.ts';
+import { HeadlessObserver, makeSafeObserver, type HeadlessObserverOptions } from './headless-observer.ts';
 import { getService, tryGetServiceContainerFromCtx } from '../core/service-registry.ts';
 import { ServiceNames, type IWriterQueue, type IKnowledgeStoreService, type IResearchSynthesisService, type IResearchOrchestration } from '../core/service-interfaces.ts';
 import type { ResearchSessionService } from './research-session-service.ts';
@@ -51,11 +51,12 @@ export class QuickResearchOrchestrator {
   constructor(private options: QuickResearchOrchestratorOptions) {
     this.config = options.config || getConfig(options.ctx.cwd);
 
-    // Resolve observer: if options were provided instead of an instance, create the instance
+    // Resolve observer: if options were provided instead of an instance, create the instance.
+    // Either way, wrap it so a throwing observer callback can never fail the run.
     if (options.observer && typeof (options.observer as any).onProgress === 'function' && !(options.observer instanceof HeadlessObserver)) {
-       this.observer = new HeadlessObserver(options.observer as HeadlessObserverOptions);
+       this.observer = makeSafeObserver(new HeadlessObserver(options.observer as HeadlessObserverOptions));
     } else {
-       this.observer = options.observer as ResearchObserver | undefined;
+       this.observer = options.observer ? makeSafeObserver(options.observer as ResearchObserver) : undefined;
     }
   }
 

package/src/orchestration/research-synthesis-service.ts

@@ -12,7 +12,7 @@
 import { parseCitations } from '../utils/text-utils.ts';
 import { normalizeCitations, formatCitedLinks, type GlobalCitation } from '../utils/citation-utils.ts';
 import { lastCitedLinksHeaderIndex } from '../utils/text-utils.ts';
-import { getScrapedLinks, normalizeUrl } from '../utils/shared-links.ts';
+import { getScrapedLinks, isTranscribedLink, normalizeUrl } from '../utils/shared-links.ts';
 import { logger } from '../logger.ts';
 import { ServiceLifecycle, type IService } from '../core/service-registry.ts';
 import { ServiceNames } from '../core/interfaces/service-names.ts';
@@ -188,9 +188,17 @@ export class ResearchSynthesisService implements IService {
     if (globalCitations.length === 0) {
       const scraped = getScrapedLinks(sessionId);
       if (scraped.length > 0) {
-        globalCitations = scraped.map((url, i) => ({ id: i + 1, url, description: '', source: 'Scrape' }));
+        // Label per actual provenance: the pool also contains transcript watch
+        // URLs the youtube_transcript tool registered — calling those "Scrape"
+        // misattributes the report's real source material.
+        globalCitations = scraped.map((url, i) => ({
+          id: i + 1,
+          url,
+          description: '',
+          source: isTranscribedLink(sessionId, url) ? 'YouTube Transcript' : 'Scrape',
+        }));
         logger.warn(
-          `[ResearchSynthesisService] No citations parsed from reports; rebuilt ${scraped.length} source(s) from scrape provenance.`,
+          `[ResearchSynthesisService] No citations parsed from reports; rebuilt ${scraped.length} source(s) from scrape/transcript provenance.`,
         );
       }
     }

package/src/prompts/researcher.md

@@ -58,7 +58,7 @@ Write your report immediately after scraping is complete, or as soon as a tool r
 ## Guidelines
 
 - **Available Tools**:
-  - `scrape`: Fetch and read web pages (primary tool). Focus your energy here.
+  - `scrape`: Fetch and read web pages (primary tool). Focus your energy here. Do NOT scrape YouTube video links (watch / youtu.be / shorts) — a watch page returns YouTube's app shell, not the video's content; read videos with `youtube_transcript`. Scraping a YouTube channel or playlist page to DISCOVER video links is fine.
   - `youtube_transcript`: Read the captions/transcript of YouTube videos from your source list — it is the `scrape` for video. ONE call only, batching up to a few of the most relevant YouTube links. Cite these as `Source: YouTube Transcript`.
   - `stackexchange`: Use ONLY for Stack Overflow or Stack Exchange URLs.
   - `security_search`: Query NVD, CVE, OSV, CISA databases.

package/src/sdk.ts

@@ -30,7 +30,7 @@ import type {
 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';
-import { getConfig, createConfig, validateConfig, type Config } from './config.ts';
+import { getConfig, createConfig, validateConfig, resetConfig, type Config } from './config.ts';
 import { metrics, MetricsRegistry, runWithRunRegistry } from './utils/metrics.ts';
 import type { IMetricsSnapshot, RunSummary } from './utils/metrics.ts';
 import { extractRunStats, type ResearchStats } from './utils/metrics-summary.ts';
@@ -833,6 +833,12 @@ async function _doShutdown(): Promise<void> {
   _lastResearchId = null;
   _lastRunSummary = null;
   _lastErrorReport = null;
+  // 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
+  // ignoreGlobalConfig and their own config — but the SDK contract is that a
+  // fresh init reads fresh config.)
+  resetConfig();
 
   // Remove signal handlers — caller is shutting down cooperatively.
   _removeSignalHandlers();

package/src/security/cisa-kev.ts

@@ -122,6 +122,9 @@ async function fetchWithRetryImpl(url: string, options: RequestInit, signal?: Ab
       async () => {
         const response = await fetch(url, options);
         if (!response.ok) {
+          // Drain before throwing: an unconsumed error body pins its socket until
+          // GC, and this path runs on every retry of a failed sweep.
+          void response.body?.cancel()?.catch(() => { /* best-effort */ });
           const error = new Error(`HTTP ${response.status}: ${response.statusText}`) as Error & { status?: number };
           error.status = response.status;
           metrics.increment('cisa_kev_errors_total', 1, { endpoint, status_code: response.status.toString() });

package/src/security/github-advisories.ts

@@ -116,6 +116,9 @@ export async function searchGitHubAdvisories(
         });
 
         if (!resp.ok) {
+          // Drain before throwing: an unconsumed error body pins its socket until
+          // GC, and the 403/5xx branches below are retried with backoff.
+          void resp.body?.cancel()?.catch(() => { /* best-effort */ });
           if (resp.status === 404) {
             throw new Error(`Repository "${owner}/${name}" not found or no access to security advisories.`);
           }
@@ -206,6 +209,8 @@ export async function searchGitHubAdvisories(
           });
 
           if (!resp.ok) {
+            // Same drain-before-throw as the repo-advisories fetch above.
+            void resp.body?.cancel()?.catch(() => { /* best-effort */ });
             if (resp.status === 404) {
               throw new Error('Advisory not found (HTTP 404)');
             }

package/src/security/nvd-client.ts

@@ -327,6 +327,9 @@ function handleFetchError(error: unknown): never {
 
 function handleResponseStatus(response: Response): void {
   if (!response.ok) {
+    // Drain before throwing: an unconsumed error body pins its socket until GC,
+    // and this path runs on every retry of a rate-limited/5xx sweep.
+    void response.body?.cancel()?.catch(() => { /* best-effort */ });
     if (response.status === 429) {
       throw new Error('NVD API rate limit exceeded (HTTP 429). Retrying with backoff...');
     }

package/src/security/osv-client.ts

@@ -44,6 +44,9 @@ async function fetchWithRetry(
       async () => {
         const response = await fetch(url, options);
         if (!response.ok) {
+          // Drain before throwing: an unconsumed error body pins its socket until
+          // GC, and this path runs on every retry of a rate-limited/5xx sweep.
+          void response.body?.cancel()?.catch(() => { /* best-effort */ });
           const error = new Error(`HTTP ${response.status}: ${response.statusText}`) as Error & { status?: number };
           error.status = response.status;
           metrics.increment('osv_errors_total', 1, { endpoint, status_code: response.status.toString() });

package/src/tools/youtube-transcript.ts

@@ -20,7 +20,7 @@ import { Value } from 'typebox/value';
 import { youtubeTranscriptCommand } from '../youtube/index.ts';
 import type { ToolUsageTracker } from '../utils/tool-usage-tracker.ts';
 import type { SystemResearchState } from '../orchestration/deep-research-types.ts';
-import { cacheScrapedContent, registerScrapedLinks, registerResearcherScrapes } from '../utils/shared-links.ts';
+import { cacheScrapedContent, registerScrapedLinks, registerTranscribedLinks, registerResearcherScrapes } from '../utils/shared-links.ts';
 import { type Config, getConfig } from '../config.ts';
 import { logger } from '../logger.ts';
 import { metrics } from '../utils/metrics.ts';
@@ -64,7 +64,7 @@ export function createYoutubeTranscriptTool(options: {
       'You may call this tool only ONCE, so choose the videos carefully before calling.',
       'Pass full watch URLs, youtu.be links, or shorts/embed/live links. Non-YouTube links are ignored.',
       'Videos without captions, or that are private/age-restricted, are reported as unavailable — the rest still succeed.',
-      "When you cite a YouTube source in CITED LINKS, use the video's ACTUAL title and channel (both shown in this tool's output) as the description — e.g. \"'<exact title>' by <channel>\". Do NOT paraphrase or invent a title; the watch URL alone is not human-identifiable.",
+      "When you cite a YouTube source in CITED LINKS, the entry's link MUST be the video's watch URL (shown in this tool's output) — a title-only entry loses the source from the final report. Put the video's ACTUAL title and channel in the Description — e.g. \"'<exact title>' by <channel>\". Do NOT paraphrase or invent a title.",
     ],
     parameters: YoutubeParamsSchema,
     executionMode: 'parallel',
@@ -139,6 +139,10 @@ export function createYoutubeTranscriptTool(options: {
 
         if (researchId && cachedUrls.length > 0) {
           registerScrapedLinks(researchId, cachedUrls);
+          // Record the provenance subset: if the researcher's CITED LINKS block is
+          // unparseable, the synthesis fallback rebuilds sources from the link pool
+          // and must label these "YouTube Transcript", not "Scrape".
+          registerTranscribedLinks(researchId, cachedUrls);
           options.updateGlobalLinks?.(cachedUrls);
           if (options.researcherId) {
             registerResearcherScrapes(researchId, options.researcherId, cachedUrls);

package/src/utils/shared-links.ts

@@ -17,6 +17,11 @@ const sessionLinks = new Map<string, Set<string>>();
 const sessionScrapedContent = new Map<string, Map<string, string>>();
 // Per-researcher scrape tracking: researchId → researcherId → Set<normalizedUrl>
 const researcherScrapes = new Map<string, Map<string, Set<string>>>();
+// URLs whose content came from a YouTube TRANSCRIPT (not a page scrape). The
+// transcript tool registers its watch URLs in the same sessionLinks pool so the
+// post-round writer and citation fallback see them; this subset lets the
+// fallback label them "YouTube Transcript" instead of "Scrape".
+const transcribedUrls = new Map<string, Set<string>>();
 
 // FIX (Issue 12): Track creation timestamps for orphaned-entry cleanup.
 const sessionTimestamps = new Map<string, number>();
@@ -38,6 +43,7 @@ function startCleanupTimer(): void {
         sessionScrapedContent.delete(researchId);
         sessionTimestamps.delete(researchId);
         researcherScrapes.delete(researchId);
+        transcribedUrls.delete(researchId);
         cleaned++;
       }
     }
@@ -111,6 +117,24 @@ export function getScrapedLinks(researchId: string): string[] {
     return Array.from(sessionLinks.get(researchId) || []);
 }
 
+/**
+ * Mark links as sourced from a YouTube transcript (call IN ADDITION to
+ * registerScrapedLinks — this only records the provenance subset).
+ */
+export function registerTranscribedLinks(researchId: string, links: string[]) {
+    if (!transcribedUrls.has(researchId)) {
+        transcribedUrls.set(researchId, new Set());
+    }
+    sessionTimestamps.set(researchId, Date.now()); // last-activity TTL refresh (parity with registerScrapedLinks)
+    const pool = transcribedUrls.get(researchId)!;
+    links.forEach(l => pool.add(normalizeUrl(l)));
+}
+
+/** Whether a URL's content came from a YouTube transcript in this session. */
+export function isTranscribedLink(researchId: string, url: string): boolean {
+    return transcribedUrls.get(researchId)?.has(normalizeUrl(url)) ?? false;
+}
+
 /**
  * Deduplicate a list of candidate URLs against already scraped links.
  */
@@ -140,6 +164,7 @@ export function cleanupSharedLinks(researchId: string) {
     sessionScrapedContent.delete(researchId);
     sessionTimestamps.delete(researchId);
     researcherScrapes.delete(researchId);
+    transcribedUrls.delete(researchId);
     logger.debug(`[Shared Links] Cleaned up session: ${researchId}`);
 }
 
@@ -156,6 +181,7 @@ export function clearAllSharedLinks(): void {
     sessionScrapedContent.clear();
     sessionTimestamps.clear();
     researcherScrapes.clear();
+    transcribedUrls.clear();
     logger.debug('[Shared Links] All global state cleared');
 }
 

package/src/web-research/scraper-utils.ts

@@ -150,7 +150,10 @@ export function validateUrlForSSRFSync(url: string): boolean {
  *
  * FIX (#8): In addition to hostname pattern checks, resolves the hostname
  * via DNS and rejects any address that resolves to a private/reserved IP.
- * This defends against DNS rebinding and decimal/octal IP representations.
+ * This defends against DNS rebinding and AAAA-only private hosts. (Decimal/
+ * octal/hex IP encodings are handled earlier: WHATWG URL parsing normalizes
+ * them to dotted-quad, so the sync IP-literal gate blocks them — see the
+ * comment on the DNS pass below.)
  */
 export async function validateUrlForSSRF(url: string): Promise<void> {
   // Synchronous protocol/localhost/internal-pattern/IP-literal screen first.
@@ -161,8 +164,12 @@ export async function validateUrlForSSRF(url: string): Promise<void> {
   const hostname = new URL(url).hostname.toLowerCase().replace(/^\[|\]$/g, '');
 
   // Resolve hostname via DNS (both IPv4 and IPv6) and check all resulting addresses.
-  // This catches DNS rebinding, decimal IP representations (2130706433),
-  // AAAA-only hosts (::1, fc00::/7) and other hostname-based bypasses.
+  // This catches DNS rebinding, AAAA-only hosts (::1, fc00::/7) and other
+  // hostname-based bypasses. (It does NOT catch numeric-encoding forms like
+  // decimal 2130706433 — dns.resolve4/6 reject numeric hosts with EBADNAME — but
+  // it doesn't need to: WHATWG URL parsing normalizes decimal/octal/hex IPv4
+  // forms to dotted-quad before this function ever sees them, so the IP-literal
+  // gate in validateUrlForSSRFSync blocks them. Pinned by a regression test.)
   const [v4Results, v6Results] = await Promise.allSettled([
     dns.resolve4(hostname),
     dns.resolve6(hostname),