@lincoln504/pi-research 1.0.3 → 1.0.5

package/src/orchestration/session-state.ts

@@ -26,6 +26,8 @@ const MAX_STEERING_MESSAGE_LENGTH = 2000;
 interface PiSessionState {
   /** Map of research run ID → array of failed researcher IDs */
   failures: Map<string, string[]>;
+  /** Map of research run ID → (researcher ID → first failure reason) */
+  failureReasons: Map<string, Map<string, string>>;
   /** Ordered list of research run IDs for TUI stacking (Index 0 = oldest/bottom-most) */
   order: string[];
   /** Registry of panel states for each research run */
@@ -70,6 +72,7 @@ function getPiState(piSessionId: string | undefined): PiSessionState {
   if (!state) {
     state = {
       failures: new Map(),
+      failureReasons: new Map(),
       order: [],
       panels: new Map(),
       aborts: new Map(),
@@ -392,6 +395,7 @@ export function refreshAllSessions(piSessionId: string | undefined): void {
         for (const id of state.order) {
           if (!validIds.includes(id)) {
             state.failures.delete(id);
+            state.failureReasons.delete(id);
             state.panels.delete(id);
           }
         }
@@ -454,6 +458,7 @@ export function startResearchSession(piSessionId: string | undefined, customRese
   const sid = normalizeSessionId(piSessionId);
   const state = getPiState(sid);
   state.failures.set(researchId, []);
+  state.failureReasons.set(researchId, new Map());
   return researchId;
 }
 
@@ -501,6 +506,7 @@ export function endResearchSession(piSessionId: string | undefined, researchId:
   if (!state) return;
 
   state.failures.delete(researchId);
+  state.failureReasons.delete(researchId);
   state.panels.delete(researchId);
   state.aborts.delete(researchId);
 
@@ -525,6 +531,7 @@ export function endResearchSession(piSessionId: string | undefined, researchId:
     } else {
       // Clear research-specific state but preserve the session and steering
       state.failures.clear();
+      state.failureReasons.clear();
       state.aborts.clear();
     }
   }
@@ -563,12 +570,28 @@ export function isBottomMostSession(piSessionId: string | undefined, researchId:
 /**
  * Record a researcher failure
  */
-export function recordResearcherFailure(piSessionId: string | undefined, researchId: string, researcherId: string): void {
+export function recordResearcherFailure(piSessionId: string | undefined, researchId: string, researcherId: string, reason?: string): void {
   const sid = normalizeSessionId(piSessionId);
   const state = getPiState(sid);
   const failures = state.failures.get(researchId) || [];
   failures.push(researcherId);
   state.failures.set(researchId, failures);
+  if (reason) {
+    const reasons = state.failureReasons.get(researchId) ?? new Map<string, string>();
+    // Keep the FIRST reason per researcher — the root cause; retries repeat it.
+    if (!reasons.has(researcherId)) reasons.set(researcherId, reason);
+    state.failureReasons.set(researchId, reasons);
+  }
+}
+
+/**
+ * Get the recorded failure reason per failed researcher (first failure wins).
+ */
+export function getResearcherFailureReasons(piSessionId: string | undefined, researchId: string): Record<string, string> {
+  const sid = normalizeSessionId(piSessionId);
+  const state = getPiState(sid);
+  const reasons = state.failureReasons.get(researchId);
+  return reasons ? Object.fromEntries(reasons) : {};
 }
 
 /**
@@ -610,9 +633,18 @@ export function getResearchStopMessage(piSessionId: string | undefined, research
   // search engine blocking" here mis-sends the user to debug their network; the
   // readiness probes do not even run a search, so a failure is not evidence of bot
   // blocking.
+  // Lead with the RECORDED errors when we have them — the actual root cause
+  // (e.g. a provider 429) beats generic guidance every time.
+  const state = getPiState(sid);
+  const reasons = state.failureReasons.get(researchId);
+  const recorded = reasons && reasons.size > 0
+    ? ['Recorded errors:', ...[...reasons].map(([id, r]) => `• researcher ${id}: ${r}`), '']
+    : [];
+
   return [
     `Research stopped: ${count} researcher(s) did not return a usable report: ${failed.join(', ')}.`,
     '',
+    ...recorded,
     'Most likely cause — the research model could not produce grounded results:',
     '• Try a more capable research model. Very small or "thinking-only" models often',
     '  emit no final text after their tool calls, which fails every researcher.',

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';
@@ -236,6 +236,19 @@ async function _doInit(options: ResearchSDKOptions = {}): Promise<void> {
   globalApiKey = options.apiKey || process.env['PI_RESEARCH_API_KEY'];
   let parsedProvider = options.provider || process.env['PI_RESEARCH_PROVIDER'];
 
+  // An EXPLICIT model option must govern the entire run — coordinator (via
+  // ctx.model) AND researchers/synthesis (which resolve through
+  // RESEARCH_MODEL, where config would otherwise outrank the option and split
+  // the run across two models, with the report metadata naming the wrong one).
+  // Pin the config to the explicit choice. No-op when the option was itself
+  // seeded from the config (the CLI does that).
+  if (options.model) {
+    const explicit = typeof options.model === 'string'
+      ? options.model
+      : `${(options.model as Model<any>).provider}/${(options.model as Model<any>).id}`;
+    globalConfig = { ...globalConfig, RESEARCH_MODEL: explicit };
+  }
+
   // Infer provider from the effective model if not explicitly provided. The
   // effective model is the explicit option first, else the configured
   // RESEARCH_MODEL — the same precedence the resolve below uses.
@@ -820,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),

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

@@ -140,6 +140,57 @@ function decodeHtmlBody(bytes: Uint8Array, contentTypeHeader: string): string {
   }
 }
 
+/** Thrown by readBodyCapped when a streamed body crosses its byte cap. */
+class BodyTooLargeError extends Error {
+  constructor(public readonly bytesRead: number, public readonly maxBytes: number) {
+    super(`Response body exceeded ${maxBytes} byte cap`);
+    this.name = 'BodyTooLargeError';
+  }
+}
+
+/**
+ * Read a response body with a HARD byte cap, streaming chunk-by-chunk so an
+ * over-limit body aborts the moment the cap is crossed. The Content-Length
+ * pre-screen above is advisory only: a chunked (or lying) response carries no
+ * usable length header, and `response.arrayBuffer()` would otherwise buffer the
+ * entire body — potentially hundreds of MB from a hostile server — into the
+ * main process before any size check ran.
+ *
+ * A body-less response (test doubles, some mocks) falls back to arrayBuffer();
+ * callers keep their post-read size checks as the belt for that path.
+ */
+async function readBodyCapped(response: Response, maxBytes: number): Promise<Uint8Array> {
+  const body = response.body;
+  // Also tolerate non-standard doubles that expose a body without getReader.
+  if (!body || typeof body.getReader !== 'function') {
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        total += value.byteLength;
+        if (total > maxBytes) throw new BodyTooLargeError(total, maxBytes);
+        chunks.push(value);
+      }
+    }
+  } finally {
+    // Over-cap or downstream throw: release the connection instead of leaving
+    // the socket open (and the server still sending) until GC. No-op after a
+    // clean done=true read.
+    try { await reader.cancel(); } catch { /* already closed */ }
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) { out.set(c, offset); offset += c.byteLength; }
+  return out;
+}
+
 async function scrapeWithFetch(url: string, signal?: AbortSignal): Promise<ScrapeLayerResult> {
   await validateUrlForSSRF(url);
 
@@ -189,6 +240,9 @@ async function scrapeWithFetch(url: string, signal?: AbortSignal): Promise<Scrap
         if (!location) break; // No Location header — treat as final response
         const resolved = new URL(location, currentUrl).href;
         await validateUrlForSSRF(resolved); // Block SSRF targets in redirects
+        // Drain the redirect response before following: an unconsumed body pins
+        // its socket (undici keeps it open until read/cancelled or GC).
+        try { await response.body?.cancel(); } catch { /* best-effort */ }
         currentUrl = resolved;
         continue;
       }
@@ -197,6 +251,8 @@ async function scrapeWithFetch(url: string, signal?: AbortSignal): Promise<Scrap
 
     if (!response.ok) {
       metrics.increment('scrape_errors_total', 1, { error_type: 'http_error', status_code: String(response.status) });
+      // Same socket-pinning concern as the redirect drain above.
+      try { await response.body?.cancel(); } catch { /* best-effort */ }
       throw new Error(`HTTP ${response.status}`);
     }
 
@@ -211,19 +267,34 @@ async function scrapeWithFetch(url: string, signal?: AbortSignal): Promise<Scrap
           const sizeMB = Math.round(size / 1024 / 1024);
           logger.warn(`[Scrapers] PDF too large (Content-Length: ${sizeMB}MB, max 100MB), skipping`);
           metrics.increment('scrape_pdf_errors_total', 1, { error_type: 'size_exceeded' });
+          // Same socket-pinning concern as the redirect/!ok drains above — and this
+          // throw fires precisely on the LARGEST responses.
+          try { await response.body?.cancel(); } catch { /* best-effort */ }
           throw new Error(`PDF too large (${sizeMB}MB, max 100MB)`);
         }
       } else if (size > MAX_HTML_SIZE) {
         const sizeMB = Math.round(size / 1024 / 1024);
         logger.warn(`[Scrapers] HTML response too large (Content-Length: ${sizeMB}MB, max 25MB), skipping`);
         metrics.increment('scrape_errors_total', 1, { error_type: 'size_exceeded', content_type: contentType.split(';')[0] || 'unknown' });
+        try { await response.body?.cancel(); } catch { /* best-effort */ }
         throw new Error(`HTML response too large (${sizeMB}MB, max 25MB)`);
       }
     }
     
     if (contentType.includes('application/pdf') || url.toLowerCase().endsWith('.pdf')) {
-      const buffer = await response.arrayBuffer();
-      const markdown = await extractPdfToMarkdown(new Uint8Array(buffer));
+      let pdfBytes: Uint8Array;
+      try {
+        pdfBytes = await readBodyCapped(response, MAX_PDF_SIZE);
+      } catch (e) {
+        if (e instanceof BodyTooLargeError) {
+          const sizeMB = Math.round(e.bytesRead / 1024 / 1024);
+          logger.warn(`[Scrapers] PDF too large (streamed ${sizeMB}MB, max 100MB), skipping`);
+          metrics.increment('scrape_pdf_errors_total', 1, { error_type: 'size_exceeded' });
+          throw new Error(`PDF too large (${sizeMB}MB, max 100MB)`, { cause: e });
+        }
+        throw e;
+      }
+      const markdown = await extractPdfToMarkdown(pdfBytes);
       validateContent('', markdown, url);
       metrics.increment('scrape_operations_total', 1, { layer: 'fetch', content_type: 'pdf', status: 'success' });
       metrics.observe('scrape_latency_ms', fetchDuration, { layer: 'fetch', content_type: 'pdf', status: 'success' });
@@ -232,8 +303,28 @@ async function scrapeWithFetch(url: string, signal?: AbortSignal): Promise<Scrap
 
     // Read the raw bytes and decode with the DECLARED charset. response.text() blindly UTF-8-decodes,
     // which mangles Shift_JIS/GBK/EUC-KR/ISO-8859-1 pages into mojibake that then gets cached + cited.
-    // Size-check on the byte length before decoding.
-    const bodyBytes = new Uint8Array(await response.arrayBuffer());
+    // Size-capped while streaming; the post-read check below is the belt for the
+    // body-less fallback path inside readBodyCapped.
+    let bodyBytes: Uint8Array;
+    try {
+      bodyBytes = await readBodyCapped(response, MAX_HTML_SIZE);
+    } catch (e) {
+      if (e instanceof BodyTooLargeError) {
+        const sizeMB = Math.round(e.bytesRead / 1024 / 1024);
+        logger.warn(`[Scrapers] HTML response too large (streamed ${sizeMB}MB, max 25MB), skipping`);
+        metrics.increment('scrape_errors_total', 1, { error_type: 'size_exceeded', content_type: 'html' });
+        errorTracker.trackError(new Error(`HTML response too large (${sizeMB}MB, max 25MB)`), {
+          component: 'scrapers',
+          operation: 'fetch',
+          url,
+          domain: extractDomain(url),
+          layer: 'fetch',
+          contentType: 'html',
+        });
+        throw new Error(`HTML response too large (${sizeMB}MB, max 25MB)`, { cause: e });
+      }
+      throw e;
+    }
 
     if (bodyBytes.length > MAX_HTML_SIZE) {
       const sizeMB = Math.round(bodyBytes.length / 1024 / 1024);

package/src/youtube/index.ts

@@ -121,10 +121,14 @@ function formatResults(results: VideoTranscript[], rejected: string[]): string {
     if (r.lang) meta.push(`Language: ${r.lang}`);
     if (typeof r.charCount === 'number') meta.push(`${r.charCount.toLocaleString()} chars`);
     if (meta.length) md += `**${meta.join(' · ')}**\n`;
-    // Exact, copy-ready citation string so the report cites the real video title
-    // and channel rather than a paraphrase (the watch URL is not identifiable).
+    // Exact, copy-ready citation string. It MUST lead with the watch URL: a
+    // title-only citation cannot be matched to a source by the synthesis
+    // citation pipeline (parseCitations extracts URLs), so the transcript's
+    // provenance would silently drop out of the final report's CITED LINKS.
+    // The title/channel follows so the report names the real video, not a
+    // paraphrase (the watch URL alone is not human-identifiable).
     if (r.title) {
-      md += `**Cite as:** '${r.title}'${r.author ? ` by ${r.author}` : ''}\n`;
+      md += `**Cite as:** ${r.url} — '${r.title}'${r.author ? ` by ${r.author}` : ''}\n`;
     }
     md += `\n${r.text}\n\n---\n\n`;
   }

package/src/youtube/transcript-client.ts

@@ -251,6 +251,8 @@ async function fetchOne(
           // 404 (removed) returns HTML that parseJson3 yields '' for, which would
           // be misreported below as a bot-protection/PoToken failure.
           if (!response.ok) {
+            // Drain before throwing so the error body doesn't pin its socket.
+            void response.body?.cancel()?.catch(() => { /* best-effort */ });
             throw new Error(`HTTP ${response.status} from timedtext endpoint`);
           }
           const body = await response.text();