@lincoln504/pi-research 1.1.0 → 1.2.0

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

@@ -10,7 +10,7 @@
  */
 
 import { parseCitations } from '../utils/text-utils.ts';
-import { normalizeCitations, formatCitedLinks, type GlobalCitation } from '../utils/citation-utils.ts';
+import { normalizeCitations, formatCitedLinks, rewriteCitationMarkers, type GlobalCitation } from '../utils/citation-utils.ts';
 import { lastCitedLinksHeaderIndex } from '../utils/text-utils.ts';
 import { getScrapedLinks, isTranscribedLink, normalizeUrl } from '../utils/shared-links.ts';
 import { stripTrailingLlmPunctuation } from '../utils/url-utils.ts';
@@ -33,86 +33,6 @@ const NO_SOURCES_NOTE =
 const UNVERIFIED_LINKS_NOTE =
   '_None of the links above could be verified: no page fetch succeeded this session and no citation could be matched to retrieved content. They may be inaccurate or invented — check each one before relying on it._';
 
-/**
- * Largest `[N]` treated as a citation marker. Inline markers index a source list
- * that is realistically well under this; the bound exists so an ordinary bracketed
- * number in prose — a year (`[2023]`), an issue id, an array index — is left alone
- * instead of being silently deleted as a "dangling citation".
- */
-const MAX_PLAUSIBLE_CITATION_MARKER = 200;
-
-/**
- * Rewrite inline `[N]` citation markers in a prose body: renumber the ones we can
- * map, delete the ones known to dangle, leave everything else untouched.
- *
- * Deletion is whitespace-aware rather than followed by a global space collapse.
- * A blanket `text.replace(/  +/g, ' ')` also eats *leading* indentation, which
- * silently flattens nested list levels into one and turns 4-space indented code
- * blocks into paragraphs — corrupting the structure of every report that contains
- * them. So the pad preceding a deleted marker is consumed only when the marker is
- * mid-line (i.e. real prose spacing); line-leading indentation is preserved.
- *
- * Code is skipped entirely. A report may quote code containing bracketed integers
- * (`items[12]`), and on the no-CITED-LINKS path *every* out-of-range marker is treated
- * as dangling — so without this guard a quoted array index would be silently deleted
- * from the user's code sample. Fenced blocks are tracked across lines; single-backtick
- * spans are detected by an odd backtick count earlier on the same line.
- *
- * @param remap  local marker number → verified global id
- * @param isDangling  whether a marker not present in `remap` should be deleted
- */
-function rewriteCitationMarkers(
-  text: string,
-  remap: Map<number, number>,
-  isDangling: (n: number) => boolean,
-): string {
-  const inFence = fencedCodeMask(text);
-  return text.replace(/([ \t]*)\[(\d+)\]/g, (match, pad: string, digits: string, offset: number) => {
-    const n = parseInt(digits, 10);
-    const mapped = remap.get(n);
-    if (mapped !== undefined) return `${pad}[${mapped}]`;
-    // Citation numbering is 1-based; `[0]` is always an index or a literal, never a marker.
-    if (n < 1 || n > MAX_PLAUSIBLE_CITATION_MARKER || !isDangling(n)) return match;
-    if (inFence(offset) || inInlineCodeSpan(text, offset)) return match;
-    // Preserve indentation when nothing but whitespace precedes on this line;
-    // otherwise drop the pad too so no double space is left behind.
-    const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
-    return text.slice(lineStart, offset).trim() === '' ? pad : '';
-  });
-}
-
-/**
- * Build an `offset → is inside a ``` fenced block` predicate for `text`.
- *
- * Computed once per rewrite (a single line scan) rather than per marker, so marker
- * rewriting stays linear in the body length.
- */
-function fencedCodeMask(text: string): (offset: number) => boolean {
-  const ranges: Array<[number, number]> = [];
-  let open = -1;
-  let pos = 0;
-  for (const line of text.split('\n')) {
-    if (/^\s{0,3}(```|~~~)/.test(line)) {
-      if (open < 0) open = pos;
-      else {
-        ranges.push([open, pos + line.length]);
-        open = -1;
-      }
-    }
-    pos += line.length + 1; // +1 for the '\n' consumed by split
-  }
-  // An unterminated fence runs to the end of the body — treat the remainder as code.
-  if (open >= 0) ranges.push([open, text.length]);
-  return (offset: number) => ranges.some(([start, end]) => offset >= start && offset < end);
-}
-
-/** Whether `offset` sits inside a single-backtick code span on its own line. */
-function inInlineCodeSpan(text: string, offset: number): boolean {
-  const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
-  let ticks = 0;
-  for (let i = lineStart; i < offset; i++) if (text[i] === '`') ticks++;
-  return ticks % 2 === 1;
-}
 
 /**
  * Redact inline `https?://` tokens in synthesis prose whose URL was NOT retrieved
@@ -172,9 +92,12 @@ export class ResearchSynthesisService implements IService {
       this.sessions.set(sessionId, reports);
       return reports;
     }
-    // Evict the least-recently-used session when at capacity. Because every
-    // store/read touches its session to the end (above), the head is the genuinely
-    // stalest session, not merely the first-created — so an in-flight run is spared.
+    // Evict the least-recently-used session when at capacity. Every STORE touches
+    // its session to the end (above); reads deliberately do not (peekSessionReports
+    // exists so a stray read cannot create-and-evict). A run in its read-only
+    // synthesis phase therefore stops refreshing its recency — tolerable only
+    // because reaching MAX_SESSIONS at all needs ~200 uncleaned sessions in one
+    // process (run cap 3, sessions cleared after each run), i.e. a leaking host.
     if (this.sessions.size >= ResearchSynthesisService.MAX_SESSIONS) {
       const oldestKey = this.sessions.keys().next().value;
       if (oldestKey !== undefined) {
@@ -187,6 +110,25 @@ export class ResearchSynthesisService implements IService {
     return reports;
   }
 
+  /**
+   * Read a session's reports WITHOUT creating an entry for an unknown id.
+   *
+   * The read-only accessors below must not go through `getSessionReports`: that
+   * is create-on-read, so a query for an id we have never seen inserts an empty
+   * map — and at MAX_SESSIONS that insert evicts the current head. The LRU touch
+   * protects sessions that are read or written, but an in-flight run whose
+   * researchers are all still executing (reports stored early, nothing touched
+   * since) is exactly the stalest key, so a stray read for an unknown session
+   * could evict a live run's reports and silently shrink its final synthesis.
+   *
+   * Returns a shared empty map for unknown ids — callers here only read.
+   */
+  private peekSessionReports(sessionId: string): ReadonlyMap<string, string> {
+    return this.sessions.get(sessionId) ?? ResearchSynthesisService.EMPTY_REPORTS;
+  }
+
+  private static readonly EMPTY_REPORTS: ReadonlyMap<string, string> = new Map<string, string>();
+
   /**
    * Store a researcher report
    * @param sessionId - Session identifier
@@ -201,14 +143,14 @@ export class ResearchSynthesisService implements IService {
    * Get a report by ID
    */
   getReport(sessionId: string, id: string): string | undefined {
-    return this.getSessionReports(sessionId).get(id);
+    return this.peekSessionReports(sessionId).get(id);
   }
 
   /**
    * Get all reports
    */
   getAllReports(sessionId: string): Map<string, string> {
-    return new Map(this.getSessionReports(sessionId));
+    return new Map(this.peekSessionReports(sessionId));
   }
 
   /**
@@ -217,7 +159,7 @@ export class ResearchSynthesisService implements IService {
   getReportsForRound(sessionId: string, round: number): Map<string, string> {
     const roundReports = new Map<string, string>();
     const prefix = `${round}.`;
-    for (const [key, report] of this.getSessionReports(sessionId).entries()) {
+    for (const [key, report] of this.peekSessionReports(sessionId).entries()) {
       if (key.startsWith(prefix)) {
         roundReports.set(key, report);
       }
@@ -229,14 +171,14 @@ export class ResearchSynthesisService implements IService {
    * Get total number of reports
    */
   getReportCount(sessionId: string): number {
-    return this.getSessionReports(sessionId).size;
+    return this.peekSessionReports(sessionId).size;
   }
 
   /**
    * Check if there are any reports
    */
   hasReports(sessionId: string): boolean {
-    return this.getSessionReports(sessionId).size > 0;
+    return this.peekSessionReports(sessionId).size > 0;
   }
 
   /**
@@ -257,7 +199,7 @@ export class ResearchSynthesisService implements IService {
    * @returns Fallback synthesis string
    */
   buildFallbackSynthesis(sessionId: string, currentRound: number = 0): string {
-    const reports = this.getSessionReports(sessionId);
+    const reports = this.peekSessionReports(sessionId);
     const reportCount = reports.size;
     const roundInfo = currentRound > 0 ? ` (up to Round ${currentRound})` : '';
     let synthesis = `Research Findings${roundInfo}\n\n`;
@@ -291,7 +233,7 @@ export class ResearchSynthesisService implements IService {
    * @returns Synthesis with guaranteed and verified CITED LINKS section
    */
   ensureCitedLinks(sessionId: string, synthesis: string): string {
-    const reports = this.getSessionReports(sessionId);
+    const reports = this.peekSessionReports(sessionId);
 
     // Primary source: citations the researchers wrote into their reports. These are
     // the richest (they carry descriptions and source tags), so they win when present.
@@ -454,7 +396,7 @@ export class ResearchSynthesisService implements IService {
   extractAllCitations(sessionId: string): Array<{ url: string; description: string; source?: string }> {
     const seen = new Set<string>();
     const allCitations: Array<{ url: string; description: string; source?: string }> = [];
-    const reports = this.getSessionReports(sessionId);
+    const reports = this.peekSessionReports(sessionId);
 
     for (const report of reports.values()) {
       const citations = parseCitations(report);

package/src/security/cisa-kev.ts

@@ -10,6 +10,7 @@ import type { Vulnerability, CisaKevResult } from './types.ts';
 import { createTimeoutSignal, retryWithBackoff, isTransientError } from '../web-research/retry-utils.ts';
 import { CircuitBreaker } from '../utils/circuit-breaker.ts';
 import { metrics } from '../utils/metrics.ts';
+import { readJsonCapped, BodyTooLargeError, MAX_BULK_JSON_BODY_BYTES } from '../utils/http-body.ts';
 
 const CISA_KEV_URL = 'https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json';
 
@@ -183,10 +184,16 @@ export async function searchCisaKev(
 
     let data: unknown;
     try {
-      data = await response.json();
-    } catch {
+      // The KEV feed is the whole catalogue in one document — legitimately tens of
+      // megabytes and growing — so it reads against the bulk cap, not the default.
+      data = await readJsonCapped(response, MAX_BULK_JSON_BODY_BYTES);
+    } catch (err) {
+      if (err instanceof BodyTooLargeError) {
+        metrics.increment('cisa_kev_errors_total', 1, { error_type: 'body_too_large' });
+        throw err;
+      }
       metrics.increment('cisa_kev_errors_total', 1, { error_type: 'malformed_json' });
-      throw new Error('CISA KEV feed returned a malformed JSON response.');
+      throw new Error('CISA KEV feed returned a malformed JSON response.', { cause: err });
     }
 
     // CISA KEV format is an array of vulnerability objects or nested in a response object

package/src/security/github-advisories.ts

@@ -17,6 +17,7 @@ import { normalizeEcosystem } from './ecosystem.ts';
 import { createTimeoutSignal, retryWithBackoff, isTransientError } from '../web-research/retry-utils.ts';
 import { CircuitBreaker } from '../utils/circuit-breaker.ts';
 import { metrics } from '../utils/metrics.ts';
+import { readJsonCapped, BodyTooLargeError } from '../utils/http-body.ts';
 import { logger } from '../logger.ts';
 import {
   isGitHubAdvisoryRaw,
@@ -153,10 +154,16 @@ export async function searchGitHubAdvisories(
 
       let data: unknown;
       try {
-        data = await response.json();
-      } catch {
+        data = await readJsonCapped(response);
+      } catch (err) {
+        // Size failures keep their own identity rather than being reported as a
+        // syntax error, which would point diagnosis at the wrong thing entirely.
+        if (err instanceof BodyTooLargeError) {
+          metrics.increment('github_search_errors_total', 1, { error_type: 'body_too_large' });
+          throw err;
+        }
         metrics.increment('github_search_errors_total', 1, { error_type: 'malformed_json' });
-        throw new Error('GitHub API returned a malformed JSON response (repo advisories).');
+        throw new Error('GitHub API returned a malformed JSON response (repo advisories).', { cause: err });
       }
       let repoAdvisories: readonly GitHubAdvisoryRaw[] = [];
 
@@ -244,10 +251,14 @@ export async function searchGitHubAdvisories(
         // A 404 on a direct GHSA/CVE lookup means "no such advisory", not failure.
         let data: unknown;
         try {
-          data = await response.json();
-        } catch {
+          data = await readJsonCapped(response);
+        } catch (err) {
+          if (err instanceof BodyTooLargeError) {
+            metrics.increment('github_search_errors_total', 1, { error_type: 'body_too_large', endpoint: endpointType });
+            throw err;
+          }
           metrics.increment('github_search_errors_total', 1, { error_type: 'malformed_json', endpoint: endpointType });
-          throw new Error(`GitHub API returned a malformed JSON response for term "${term}".`);
+          throw new Error(`GitHub API returned a malformed JSON response for term "${term}".`, { cause: err });
         }
         let items: readonly GitHubAdvisoryRaw[] = [];
 
@@ -259,7 +270,7 @@ export async function searchGitHubAdvisories(
           items = data.items.filter(isGitHubAdvisoryRaw);
         }
 
-        metrics.increment(items.length > 0 ? 'github_cache_hits_total' : 'github_cache_misses_total', 1, { term, endpoint: endpointType });
+        metrics.increment(items.length > 0 ? 'github_cache_hits_total' : 'github_cache_misses_total', 1, { endpoint: endpointType });
 
         return items.map(mapGitHubAdvisory);
       };

package/src/security/nvd-client.ts

@@ -24,6 +24,7 @@ import { createTimeoutSignal, retryWithBackoff, isTransientError } from '../web-
 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 {
   isWeaknessDescription,
   isWeakness,
@@ -396,11 +397,17 @@ async function fetchPaginated(
     const response = await fetchWithRetry(url, signal);
     let data: unknown;
     try {
-      data = await response.json();
-    } catch {
+      // A page can legitimately carry up to MAX_RESULTS_PER_PAGE (2000) full CVE
+      // records, so pagination reads against the bulk cap rather than the default.
+      data = await readJsonCapped(response, MAX_BULK_JSON_BODY_BYTES);
+    } catch (err) {
       // A 200 with a truncated/HTML body (proxy or CDN error page) would otherwise
-      // throw and discard this whole term. Stop paginating this term instead.
-      metrics.increment('nvd_search_errors_total', 1, { error_type: 'malformed_json' });
+      // throw and discard this whole term. Stop paginating this term instead —
+      // the pages already gathered are kept. An over-cap body degrades the same
+      // way but is counted separately so the cause stays diagnosable.
+      metrics.increment('nvd_search_errors_total', 1, {
+        error_type: err instanceof BodyTooLargeError ? 'body_too_large' : 'malformed_json',
+      });
       break;
     }
 
@@ -412,10 +419,14 @@ async function fetchPaginated(
     const admitted = rawEntries.filter(admitEntry).map((entry) => parseNVDEntry(entry, options));
 
     if (rawEntries.length === 0) {
-      metrics.increment('nvd_cache_misses_total', 1, { term });
+      // No `term` label: the metrics registry keys counters by label set and is only
+      // cleared by an explicit clearSession(), so labelling by the raw search term made
+      // every distinct security query add a permanent entry for the life of a pi host
+      // session — unbounded growth driven straight by user input.
+      metrics.increment('nvd_cache_misses_total', 1);
       break;
     }
-    metrics.increment('nvd_cache_hits_total', 1, { term });
+    metrics.increment('nvd_cache_hits_total', 1);
 
     allVulnerabilities.push(...admitted);
 

package/src/security/osv-client.ts

@@ -14,6 +14,7 @@ import { logger } from '../logger.ts';
 import { OSV_TIMEOUT_MS, DEFAULT_MAX_RETRIES, DEFAULT_INITIAL_DELAY_MS, DEFAULT_MAX_DELAY_MS } from '../constants.ts';
 import { CircuitBreaker } from '../utils/circuit-breaker.ts';
 import { metrics } from '../utils/metrics.ts';
+import { readJsonCapped, BodyTooLargeError } from '../utils/http-body.ts';
 import {
   isOsvVulnerability,
   isOsvQueryResponse,
@@ -137,10 +138,17 @@ export async function searchOSV(
 
       let data: unknown;
       try {
-        data = await response.json();
-      } catch {
+        data = await readJsonCapped(response);
+      } catch (err) {
+        // An over-cap body is a size failure, not a syntax one. Rethrowing it
+        // unwrapped keeps the diagnosis honest instead of reporting a 40MB reply
+        // as malformed JSON.
+        if (err instanceof BodyTooLargeError) {
+          metrics.increment('osv_search_errors_total', 1, { error_type: 'body_too_large' });
+          throw err;
+        }
         metrics.increment('osv_search_errors_total', 1, { error_type: 'malformed_json' });
-        throw new Error(`OSV returned a malformed JSON response for "${term}".`);
+        throw new Error(`OSV returned a malformed JSON response for "${term}".`, { cause: err });
       }
 
       let items: OsvVulnerability[];
@@ -154,7 +162,9 @@ export async function searchOSV(
       }
 
       const endpoint = isIdLookup ? 'vulns_by_id' : 'query';
-      metrics.increment(items.length > 0 ? 'osv_cache_hits_total' : 'osv_cache_misses_total', 1, { term, endpoint });
+      // `endpoint` only — see the nvd-client note: a raw-term label grows the counter
+      // registry without bound across a session.
+      metrics.increment(items.length > 0 ? 'osv_cache_hits_total' : 'osv_cache_misses_total', 1, { endpoint });
 
       const vulns: Vulnerability[] = [];
       for (const item of items) {

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

@@ -18,6 +18,7 @@
  * only written on explicit opt-in (callers must pass them deliberately).
  */
 
+import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -57,6 +58,24 @@ export const HARNESSES: readonly HarnessDef[] = [
 const SKILL_NAME = 'pi-research';
 const PACKAGE_NAME = '@lincoln504/pi-research';
 
+/**
+ * This package's version, used to stamp manifest entries so a stale COPY can be
+ * detected and refreshed. Read from the SKILL.md we are about to install rather
+ * than from package.json: that file is the copied artifact, its metadata line is
+ * kept in sync by the `version` npm script, and it is present in every layout
+ * (repo, published tarball, installed copy). Returns null if unreadable, which
+ * simply means "cannot tell" — the entry is then always treated as stale, which
+ * refreshes rather than skips.
+ */
+function readSkillVersion(sourceDir: string): string | null {
+  try {
+    const md = fs.readFileSync(path.join(sourceDir, 'SKILL.md'), 'utf-8');
+    return /"version"\s*:\s*"([^"]+)"/.exec(md)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The coding agents the in-app installer (the /research-config TUI) targets:
  * Claude, Codex, and OpenClaw. Each loads skills from a home-directory
@@ -81,6 +100,22 @@ export interface ManifestEntry {
   /** Absolute path of the skill source this was linked/copied from. */
   source: string;
   createdAt: string;
+  /**
+   * Package version that produced this entry.
+   *
+   * Only load-bearing for `copy` entries: a symlink re-reads the package on every
+   * use and so is always current, but a COPY is a point-in-time snapshot that
+   * nothing ever refreshed — reconcile skipped non-symlinks entirely, and the
+   * entry recorded no version, so drift was undetectable by construction. Copies
+   * are not rare: they happen on Windows without symlink privilege, cross-device,
+   * with `--copy`, and via the documented OpenClaw install route. Those users kept
+   * the SKILL.md their engine shipped with *forever* — including its exit-code
+   * contract — while the engine underneath them changed.
+   *
+   * Optional so manifests written before this field are still valid; an entry with
+   * no version simply reads as "not current" and is refreshed once.
+   */
+  version?: string;
 }
 
 interface Manifest {
@@ -293,6 +328,7 @@ export function installSkill(toolIds: string[], opts: InstallOptions = {}): Inst
   const manifest = readManifest(opts);
   const results: InstallResult[] = [];
   const now = new Date().toISOString();
+  const skillVersion = readSkillVersion(source);
 
   for (const id of toolIds) {
     const def = HARNESSES.find(h => h.id === id);
@@ -315,16 +351,22 @@ export function installSkill(toolIds: string[], opts: InstallOptions = {}): Inst
         if (lst.isSymbolicLink()) {
           const dest = path.resolve(path.dirname(absSkillPath), fs.readlinkSync(absSkillPath));
           if (dest !== path.resolve(source)) {
+            // dryRun means "plan only, touch nothing" — the re-point is a real
+            // unlink+symlink and must honour it like the fresh-install path does.
+            if (opts.dryRun) {
+              results.push({ tool: id, path: absSkillPath, type: 'symlink', status: 'planned', message: 'would re-point stale symlink to current source' });
+              continue;
+            }
             fs.unlinkSync(absSkillPath);
             fs.symlinkSync(source, absSkillPath, process.platform === 'win32' ? 'junction' : 'dir');
-            upsertEntry(manifest, { tool: id, path: absSkillPath, type: 'symlink', source, createdAt: now });
+            upsertEntry(manifest, { tool: id, path: absSkillPath, type: 'symlink', source, createdAt: now, ...(skillVersion ? { version: skillVersion } : {}) });
             results.push({ tool: id, path: absSkillPath, type: 'symlink', status: 'installed', message: 're-pointed stale symlink to current source' });
             continue;
           }
         }
       } catch { /* fall through to already-installed below */ }
       results.push({ tool: id, path: absSkillPath, type, status: 'already-installed' });
-      upsertEntry(manifest, { tool: id, path: absSkillPath, type: isSymlinkPresent(absSkillPath) ? 'symlink' : 'copy', source, createdAt: now });
+      upsertEntry(manifest, { tool: id, path: absSkillPath, type: isSymlinkPresent(absSkillPath) ? 'symlink' : 'copy', source, createdAt: now, ...(skillVersion ? { version: skillVersion } : {}) });
       continue;
     }
     if (fs.existsSync(absSkillPath) || isSymlinkPresent(absSkillPath)) {
@@ -344,14 +386,14 @@ export function installSkill(toolIds: string[], opts: InstallOptions = {}): Inst
         } catch (err: any) {
           // Windows without privilege, or cross-device: fall back to copy.
           copyDir(source, absSkillPath);
-          upsertEntry(manifest, { tool: id, path: absSkillPath, type: 'copy', source, createdAt: now });
+          upsertEntry(manifest, { tool: id, path: absSkillPath, type: 'copy', source, createdAt: now, ...(skillVersion ? { version: skillVersion } : {}) });
           results.push({ tool: id, path: absSkillPath, type: 'copy', status: 'installed', message: `symlink unavailable (${err?.code ?? err?.message}); copied instead` });
           continue;
         }
       } else {
         copyDir(source, absSkillPath);
       }
-      upsertEntry(manifest, { tool: id, path: absSkillPath, type, source, createdAt: now });
+      upsertEntry(manifest, { tool: id, path: absSkillPath, type, source, createdAt: now, ...(skillVersion ? { version: skillVersion } : {}) });
       results.push({ tool: id, path: absSkillPath, type, status: 'installed' });
     } catch (err: any) {
       results.push({ tool: id, path: absSkillPath, type, status: 'error', message: err?.message ?? String(err) });
@@ -412,7 +454,7 @@ export function uninstallSkill(toolIds?: string[], opts: InstallOptions = {}): U
     }
     try {
       if (isSymlinkPresent(skillPath)) fs.unlinkSync(skillPath);
-      else fs.rmSync(skillPath, { recursive: true, force: true });
+      else fs.rmSync(skillPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
       results.push({ tool, path: skillPath, status: 'removed' });
     } catch (err: any) {
       results.push({ tool, path: skillPath, status: 'error', message: err?.message ?? String(err) });
@@ -441,6 +483,12 @@ export interface ReconcileResult {
   pruned: string[];
   /** Stale/dangling owned symlinks re-pointed to the current package source. */
   repointed: string[];
+  /**
+   * Owned COPIES refreshed because the package version moved on. A symlink tracks
+   * the package automatically; a copy does not, so without this an upgrade left
+   * copy-installed users on the previous SKILL.md indefinitely.
+   */
+  refreshed: string[];
 }
 
 /**
@@ -460,17 +508,77 @@ export interface ReconcileResult {
  * Foreign (non-owned) paths and self-contained copies are never touched.
  */
 export function reconcileSkillInstalls(opts: InstallOptions = {}): ReconcileResult {
-  const result: ReconcileResult = { pruned: [], repointed: [] };
+  const result: ReconcileResult = { pruned: [], repointed: [], refreshed: [] };
   const manifest = readManifest(opts);
   if (manifest.entries.length === 0) return result;
 
   let source: string | null;
   try { source = resolveSkillSourceDir(opts.skillSourceDir); } catch { source = null; }
 
+  const currentVersion = source !== null ? readSkillVersion(source) : null;
+
   const keep: ManifestEntry[] = [];
   for (const e of manifest.entries) {
-    // Copies are self-contained (no target to dangle); leave them as-is.
-    if (e.type !== 'symlink') { keep.push(e); continue; }
+    // A COPY has no target to dangle, but it is a point-in-time snapshot: unlike a
+    // symlink it does not track the package, so an engine upgrade leaves it serving
+    // the OLD SKILL.md — including its exit-code contract — indefinitely. Refresh it
+    // when the stamped version differs from what we now ship. An entry written
+    // before versions were stamped has none, so it reads as stale and is refreshed
+    // once. Ownership is re-checked first: a foreign directory at this path is
+    // never overwritten.
+    if (e.type !== 'symlink') {
+      const stale = currentVersion !== null && e.version !== currentVersion;
+      if (stale && source !== null && fs.existsSync(e.path) && isOwnedCopy(e.path)) {
+        // Build-then-swap, never rm-then-copy. The old shape (rmSync, then
+        // copyDir) destroyed the install permanently when the copy failed
+        // (ENOSPC, a locked file): the retry guard requires the path to exist,
+        // so a vanished install was never retried either. The staging names are
+        // dot-prefixed so a crash mid-swap cannot leave a directory a skill
+        // scanner would pick up as a duplicate skill.
+        const dir = path.dirname(e.path);
+        const base = path.basename(e.path);
+        // Sweep leftovers from a previous crashed swap before starting a new one.
+        try {
+          for (const name of fs.readdirSync(dir)) {
+            if (name.startsWith(`.${base}.new-`) || name.startsWith(`.${base}.old-`)) {
+              fs.rmSync(path.join(dir, name), { recursive: true, force: true });
+            }
+          }
+        } catch { /* hygiene only */ }
+        const suffix = crypto.randomBytes(4).toString('hex');
+        const fresh = path.join(dir, `.${base}.new-${suffix}`);
+        const retired = path.join(dir, `.${base}.old-${suffix}`);
+        try {
+          copyDir(source, fresh);
+        } catch {
+          try { fs.rmSync(fresh, { recursive: true, force: true }); } catch { /* best effort */ }
+          keep.push(e); // source unreadable / disk full — install intact, retry next startup
+          continue;
+        }
+        try {
+          fs.renameSync(e.path, retired);
+        } catch {
+          try { fs.rmSync(fresh, { recursive: true, force: true }); } catch { /* best effort */ }
+          keep.push(e); // could not move the old copy aside (locked on Windows) — intact
+          continue;
+        }
+        try {
+          fs.renameSync(fresh, e.path);
+        } catch {
+          // Put the old copy back — an old skill is strictly better than none.
+          try { fs.renameSync(retired, e.path); } catch { /* skills dir itself broken */ }
+          try { fs.rmSync(fresh, { recursive: true, force: true }); } catch { /* best effort */ }
+          keep.push(e);
+          continue;
+        }
+        try { fs.rmSync(retired, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 }); } catch { /* leaked dot-dir; swept next reconcile */ }
+        keep.push({ ...e, source, version: currentVersion });
+        result.refreshed.push(e.path);
+      } else {
+        keep.push(e);
+      }
+      continue;
+    }
 
     // Link the user deleted by hand — nothing on disk; drop the stale entry.
     if (!isSymlinkPresent(e.path)) { result.pruned.push(e.path); continue; }
@@ -514,6 +622,24 @@ export function reconcileSkillInstalls(opts: InstallOptions = {}): ReconcileResu
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Recursive copy at the JS level — deliberately NOT fs.cpSync. cpSync's native
+ * implementation (std::filesystem) ABORTS the whole process on an unreadable
+ * directory instead of throwing a catchable error (observed on Node 25:
+ * "terminate called after throwing an instance of
+ * 'std::filesystem::__cxx11::filesystem_error'"). This runs inside
+ * reconcileSkillInstalls at every startup, where a copy failure must be caught
+ * and rolled back — never take the host down. statSync/copyFileSync follow
+ * symlinks, matching the dereference behaviour cpSync was given.
+ */
 function copyDir(src: string, dest: string): void {
-  fs.cpSync(src, dest, { recursive: true, dereference: true });
+  const st = fs.statSync(src);
+  if (st.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const name of fs.readdirSync(src)) {
+      copyDir(path.join(src, name), path.join(dest, name));
+    }
+  } else {
+    fs.copyFileSync(src, dest);
+  }
 }

package/src/stackexchange/rest-client.ts

@@ -7,6 +7,7 @@ import type { StackExchangeWrapper } from './types.ts';
 import { logger } from '../logger.ts';
 import { CircuitBreaker } from '../utils/circuit-breaker.ts';
 import { metrics } from '../utils/metrics.ts';
+import { readJsonCapped, BodyTooLargeError } from '../utils/http-body.ts';
 
 const API_BASE = 'https://api.stackexchange.com/2.3';
 
@@ -99,7 +100,7 @@ export class StackExchangeClient {
 
         // NB: the timeout is cleared in `finally`, not here. Clearing it now —
         // when only the headers have arrived — would leave the body read
-        // (response.json() below) with no timeout, so a stalled body could hang
+        // (readJsonCapped below) with no timeout, so a stalled body could hang
         // for the whole process lifetime.
 
         // The SE API returns a structured JSON wrapper (with error_id) even for
@@ -109,8 +110,11 @@ export class StackExchangeClient {
         // "Unexpected token <" SyntaxError that hides the real cause.
         let data: StackExchangeWrapper<T>;
         try {
-          data = await response.json() as StackExchangeWrapper<T>;
+          data = await readJsonCapped<StackExchangeWrapper<T>>(response);
         } catch (parseErr) {
+          // An over-cap body is a size failure, not a malformed-JSON one: rethrow
+          // it unwrapped so it can't be relabelled as an HTTP-status error below.
+          if (parseErr instanceof BodyTooLargeError) throw parseErr;
           if (!response.ok) throw new Error(`HTTP ${response.status} from Stack Exchange API`, { cause: parseErr });
           throw parseErr;
         }