@lincoln504/pi-research 1.1.2 → 1.3.0

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/index.ts

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

package/src/security/nvd-client.ts

@@ -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,
@@ -352,6 +353,11 @@ function fetchWithRetry(url: string, signal?: AbortSignal): Promise<Response> {
 
   return nvdCircuitBreaker.execute(async () => {
     return retryWithBackoff(async () => {
+      // Every attempt — the first AND each 2s/4s retry — must hold a rate-limiter
+      // slot: the limiter's spacing is the ONLY mechanism enforcing NVD's ~6s
+      // inter-request interval (the post-sweep sleep was removed), and an acquire
+      // outside this closure let 429/5xx retries re-hit the API faster than it.
+      await nvdRateLimiter.acquire(signal);
       let response: Response;
       try {
         response = await fetch(url, createFetchOptions(signal));
@@ -391,16 +397,22 @@ async function fetchPaginated(
     if (signal?.aborted) break; // stop paginating promptly on cancel
     const url = buildURL(term, options, pageSize, startIndex, severityVersion);
 
-    await nvdRateLimiter.acquire(signal);
-
+    // No acquire here: fetchWithRetry acquires a rate-limiter slot per ATTEMPT,
+    // so retries are spaced too — a second acquire would double-charge the page.
     const response = await fetchWithRetry(url, signal);
     let data: unknown;
     try {
-      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 +424,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 {
@@ -182,12 +217,28 @@ export function readManifest(opts?: { home?: string }): Manifest {
   return { version: 1, package: PACKAGE_NAME, entries: [] };
 }
 
+/** Monotonic per-process suffix for manifest tmp files (see writeManifest). */
+let manifestTmpSeq = 0;
+
 function writeManifest(manifest: Manifest, opts?: { home?: string }): void {
   const p = getManifestPath(opts);
   fs.mkdirSync(path.dirname(p), { recursive: true });
-  const tmp = `${p}.tmp`;
+  // Unique tmp name (pid + timestamp + counter, mirroring config.ts's registry
+  // writer): a FIXED `${p}.tmp` was a shared collision surface — concurrent
+  // runs' reconciles (the run cap allows 3 live runs) staged through the same
+  // path, the winner renamed it away, and the loser's renameSync threw ENOENT,
+  // surfacing as a spurious skill-install error. The read-modify-write around
+  // this stays deliberately UNLOCKED: a lost update is self-healing churn (the
+  // next reconcile re-derives the same state from disk), unlike the hard
+  // failure a tmp-name collision caused.
+  const tmp = `${p}.tmp.${process.pid}.${Date.now()}.${manifestTmpSeq++}`;
   fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tmp, p);
+  try {
+    fs.renameSync(tmp, p);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* best effort */ }
+    throw err;
+  }
 }
 
 function upsertEntry(manifest: Manifest, entry: ManifestEntry): void {
@@ -293,6 +344,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 +367,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 +402,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 +470,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 +499,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 +524,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 +638,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/index.ts

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

package/src/stackexchange/output/table.ts

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