@taurgis/bonsai 3.2.0 → 4.0.0

package/dist/lib/research/markdown.js

@@ -47,15 +47,23 @@ function addGfmTableRule(service) {
     });
 }
 /**
- * Converts HTML content to clean, deterministic Markdown.
- * Configured to use ATX-style headings (#) and fenced code blocks (```), with GFM tables.
+ * Drops empty anchor links (e.g. `[](url)`) from Markdown. These arise from icon-only heading
+ * permalinks and ReadMe query-param chips that carry no text content, wasting tokens.
+ * Images (`![](url)`) are intentionally not matched.
+ *
+ * @param markdown - Markdown text to clean.
+ * @returns Markdown with text-less links removed.
  */
-// Icon-only/empty anchors (e.g. a heading's "#" permalink, a ReadMe query-param chip) convert to a
-// text-less link `[](url)` that carries no information and just wastes tokens. Drop them, but never
-// match images `![](url)` (empty alt is still a real image).
 export function dropEmptyLinks(markdown) {
     return markdown.replace(/(?<!!)\[\s*\]\([^)]*\)/g, '');
 }
+/**
+ * Converts HTML content to clean, deterministic Markdown.
+ * Configured to use ATX-style headings (#) and fenced code blocks (```), with GFM tables.
+ *
+ * @param html - HTML string to convert.
+ * @returns Clean Markdown with empty links stripped.
+ */
 export function htmlToMarkdown(html) {
     const turndownService = new TurndownService({
         headingStyle: 'atx',

package/dist/lib/research/metadata-filters.d.ts

@@ -0,0 +1,18 @@
+import type { ResearchArtifactMetadata } from './schema.js';
+/** Whether an artifact's topic matches a `--topic` filter (case-insensitive exact match). */
+export declare function matchesTopicFilter(meta: Pick<ResearchArtifactMetadata, 'topic'>, topic: string | undefined): boolean;
+/** Whether an artifact's tags satisfy a `--tags` filter (case-insensitive, must match all). */
+export declare function matchesTagsFilter(meta: Pick<ResearchArtifactMetadata, 'tags'>, tags: string[] | undefined): boolean;
+/**
+ * Reject an explicitly passed, whitespace-only `--topic` filter. Silently treating it as "no
+ * filter" (matching everything, as an empty/falsy value normally would in {@link matchesTopicFilter})
+ * would hide what's almost always a shell-quoting mistake — the same reasoning `--url` already
+ * applies via `emptyUrlFilterError`.
+ */
+export declare function emptyTopicFilterError(topic: string | undefined): string | undefined;
+/**
+ * Reject an explicitly passed, whitespace-only `--tags` filter entry. Unlike a missing/empty
+ * `--topic` (which reads as "no filter"), an empty tag string in {@link matchesTagsFilter} never
+ * matches any artifact's tags — silently returning zero results with no signal. Fail fast instead.
+ */
+export declare function emptyTagsFilterError(tags: string[] | undefined): string | undefined;

package/dist/lib/research/metadata-filters.js

@@ -0,0 +1,37 @@
+/** Whether an artifact's topic matches a `--topic` filter (case-insensitive exact match). */
+export function matchesTopicFilter(meta, topic) {
+    if (!topic)
+        return true;
+    return !!meta.topic && meta.topic.trim().toLowerCase() === topic.trim().toLowerCase();
+}
+/** Whether an artifact's tags satisfy a `--tags` filter (case-insensitive, must match all). */
+export function matchesTagsFilter(meta, tags) {
+    if (!tags || tags.length === 0)
+        return true;
+    const metaTagsLower = meta.tags.map((t) => t.toLowerCase());
+    return tags.every((t) => metaTagsLower.includes(t.toLowerCase()));
+}
+/**
+ * Reject an explicitly passed, whitespace-only `--topic` filter. Silently treating it as "no
+ * filter" (matching everything, as an empty/falsy value normally would in {@link matchesTopicFilter})
+ * would hide what's almost always a shell-quoting mistake — the same reasoning `--url` already
+ * applies via `emptyUrlFilterError`.
+ */
+export function emptyTopicFilterError(topic) {
+    if (topic === undefined)
+        return undefined;
+    if (topic.trim() === '') {
+        return '--topic must be a non-empty value (e.g. "React Suspense").';
+    }
+    return undefined;
+}
+/**
+ * Reject an explicitly passed, whitespace-only `--tags` filter entry. Unlike a missing/empty
+ * `--topic` (which reads as "no filter"), an empty tag string in {@link matchesTagsFilter} never
+ * matches any artifact's tags — silently returning zero results with no signal. Fail fast instead.
+ */
+export function emptyTagsFilterError(tags) {
+    if (!tags?.some((t) => t.trim() === ''))
+        return undefined;
+    return '--tags must be non-empty values (e.g. "react").';
+}

package/dist/lib/research/metadata-flags.d.ts

@@ -0,0 +1,34 @@
+/** Longest `--topic` value accepted; topics are short labels, not free text. */
+export declare const MAX_TOPIC_LENGTH = 200;
+/** Longest single `--tags` value accepted; tags are short taxonomic labels. */
+export declare const MAX_TAG_LENGTH = 100;
+/**
+ * Reject a `--topic`/`--tags` value longer than its cap before it ever reaches the cache.
+ * Unbounded input here would still round-trip through YAML frontmatter and `list`/`inspect`
+ * output correctly, but a single unreasonably long value wraps a human-readable listing line
+ * across dozens of terminal rows, so cap it at the flag boundary the same way `metadataNewlineError`
+ * catches the newline case.
+ *
+ * @param flags - The command's parsed `topic`/`tags` flags.
+ * @returns An error message naming the offending flag and its length cap, or `null` when both fit.
+ */
+export declare function metadataLengthError(flags: {
+    topic?: string;
+    tags?: string[];
+}): string | null;
+/**
+ * Reject a `--topic`/`--tags` value containing a line break before it ever reaches the cache.
+ * Stored as-is, an embedded newline would corrupt the single-line-per-field frontmatter format
+ * (see `sanitizeFrontmatterLine` in `artifact.ts`): at best a silently dropped stray line, at
+ * worst a spoofed `key: value` pair or a bare `---` that closes the frontmatter fence early and
+ * splices the rest of the metadata into the body. Failing fast here — rather than letting the
+ * serializer silently rewrite the caller's input — gives the same actionable-error treatment as
+ * every other flag validator (`durationFlagError`, etc.).
+ *
+ * @param flags - The command's parsed `topic`/`tags` flags.
+ * @returns An error message naming the offending flag, or `null` when both are clean.
+ */
+export declare function metadataNewlineError(flags: {
+    topic?: string;
+    tags?: string[];
+}): string | null;

package/dist/lib/research/metadata-flags.js

@@ -0,0 +1,45 @@
+/** Longest `--topic` value accepted; topics are short labels, not free text. */
+export const MAX_TOPIC_LENGTH = 200;
+/** Longest single `--tags` value accepted; tags are short taxonomic labels. */
+export const MAX_TAG_LENGTH = 100;
+/**
+ * Reject a `--topic`/`--tags` value longer than its cap before it ever reaches the cache.
+ * Unbounded input here would still round-trip through YAML frontmatter and `list`/`inspect`
+ * output correctly, but a single unreasonably long value wraps a human-readable listing line
+ * across dozens of terminal rows, so cap it at the flag boundary the same way `metadataNewlineError`
+ * catches the newline case.
+ *
+ * @param flags - The command's parsed `topic`/`tags` flags.
+ * @returns An error message naming the offending flag and its length cap, or `null` when both fit.
+ */
+export function metadataLengthError(flags) {
+    if (flags.topic !== undefined && flags.topic.length > MAX_TOPIC_LENGTH) {
+        return `--topic must be ${MAX_TOPIC_LENGTH} characters or fewer (got ${flags.topic.length}).`;
+    }
+    const longTag = flags.tags?.find((tag) => tag.length > MAX_TAG_LENGTH);
+    if (longTag !== undefined) {
+        return `--tags must be ${MAX_TAG_LENGTH} characters or fewer (got ${longTag.length}).`;
+    }
+    return null;
+}
+/**
+ * Reject a `--topic`/`--tags` value containing a line break before it ever reaches the cache.
+ * Stored as-is, an embedded newline would corrupt the single-line-per-field frontmatter format
+ * (see `sanitizeFrontmatterLine` in `artifact.ts`): at best a silently dropped stray line, at
+ * worst a spoofed `key: value` pair or a bare `---` that closes the frontmatter fence early and
+ * splices the rest of the metadata into the body. Failing fast here — rather than letting the
+ * serializer silently rewrite the caller's input — gives the same actionable-error treatment as
+ * every other flag validator (`durationFlagError`, etc.).
+ *
+ * @param flags - The command's parsed `topic`/`tags` flags.
+ * @returns An error message naming the offending flag, or `null` when both are clean.
+ */
+export function metadataNewlineError(flags) {
+    if (flags.topic !== undefined && /[\r\n]/.test(flags.topic)) {
+        return '--topic cannot contain line breaks.';
+    }
+    if (flags.tags?.some((tag) => /[\r\n]/.test(tag))) {
+        return '--tags cannot contain line breaks.';
+    }
+    return null;
+}

package/dist/lib/research/persist-artifact.d.ts

@@ -0,0 +1,23 @@
+import { type SecureWriteResult } from './secure-write.js';
+import type { StoreRoots } from './store-roots.js';
+import type { ResearchArtifact } from './schema.js';
+export type ArtifactWriteKind = 'import' | 'fetch';
+export interface PersistArtifactResult extends SecureWriteResult {
+    dryRun: boolean;
+    /** Secret-redirect warning for stderr, or null when no redirect. */
+    redirectWarning: string | null;
+}
+/**
+ * Persist (or dry-run preview) an artifact with secret-safe routing. Owns redirect warning copy
+ * so fetch/import cannot drift. When `scratchDir` is set (fetch dry-run), also writes a throwaway
+ * copy there for downstream extraction while reporting the real would-be `dataDir`.
+ */
+export declare function persistArtifact(opts: {
+    roots: StoreRoots;
+    cacheKey: string;
+    artifact: ResearchArtifact;
+    dryRun: boolean;
+    kind: ArtifactWriteKind;
+    /** Fetch dry-run throwaway directory; real destination still comes from the secure write. */
+    scratchDir?: string | null;
+}): PersistArtifactResult;

package/dist/lib/research/persist-artifact.js

@@ -0,0 +1,27 @@
+import { writeArtifact } from './storage.js';
+import { writeArtifactSecurely } from './secure-write.js';
+function redirectWarningFor(kind, dryRun, secretLabel) {
+    const content = kind === 'import' ? 'imported content' : 'page content';
+    const verb = dryRun ? 'would store' : 'stored';
+    return `Detected ${secretLabel} in the ${content}; ${verb} in the global cache instead of the project to avoid committing secrets.`;
+}
+/**
+ * Persist (or dry-run preview) an artifact with secret-safe routing. Owns redirect warning copy
+ * so fetch/import cannot drift. When `scratchDir` is set (fetch dry-run), also writes a throwaway
+ * copy there for downstream extraction while reporting the real would-be `dataDir`.
+ */
+export function persistArtifact(opts) {
+    const result = writeArtifactSecurely(opts.roots, opts.cacheKey, opts.artifact, {
+        dryRun: opts.dryRun,
+    });
+    if (opts.scratchDir) {
+        writeArtifact(opts.scratchDir, opts.cacheKey, opts.artifact);
+    }
+    return {
+        ...result,
+        dryRun: opts.dryRun,
+        redirectWarning: result.redirected
+            ? redirectWarningFor(opts.kind, opts.dryRun, result.secretLabel)
+            : null,
+    };
+}

package/dist/lib/research/prompt-injection.d.ts

@@ -1 +1,10 @@
+/**
+ * Scans Markdown for embedded prompt-injection attacks and redacts any block or line that matches.
+ * Detects direct patterns, plus base64/hex-encoded variants and typoglycemia obfuscation.
+ * HTML comments are checked first; the body is then split on paragraph breaks and scanned line-by-line.
+ *
+ * @param markdown - Markdown content (possibly untrusted, sourced from fetched pages).
+ * @returns Sanitized Markdown with harmful instruction blocks replaced by a redaction placeholder,
+ *   and ANSI/control bytes stripped so a cached read can never replay them to a terminal.
+ */
 export declare function sanitizePromptInjection(markdown: string): string;

package/dist/lib/research/prompt-injection.js

@@ -1,6 +1,20 @@
 import { Buffer } from 'node:buffer';
+import { CONTROL_CHAR_PATTERN } from '../text.js';
 const REDACTION = '[Removed potentially unsafe agent instruction]';
 const ZERO_WIDTH = /[\u200b-\u200f\ufeff]/g;
+// Tab/LF/CR fall inside CONTROL_CHAR_PATTERN's Unicode "Control" category too, but they are
+// legitimate Markdown whitespace, so the replacer below keeps those three and drops everything else.
+const SAFE_CONTROL_CHARS = new Set(['\t', '\n', '\r']);
+/**
+ * Removes ANSI escape codes and other control bytes a malicious page could embed in its visible
+ * text, while leaving Markdown-structural whitespace (tab/newline/CR) intact. Every fetch/import
+ * path renders its stored content directly to the terminal (`bonsai <url>`, cache hits, etc.), so
+ * raw control bytes surviving Readability/Turndown would replay as a terminal-injection attack on
+ * every subsequent read of the cache; this is the choke point all of those paths share.
+ */
+function stripUnsafeControlChars(text) {
+    return text.replace(CONTROL_CHAR_PATTERN, (char) => (SAFE_CONTROL_CHARS.has(char) ? char : ''));
+}
 const HTML_COMMENT = /<!--[\s\S]*?-->/g;
 const BASE64_TOKEN = /(?<![A-Za-z0-9+/_-])(?:[A-Za-z0-9+/_-]{16,}={0,2})(?![A-Za-z0-9+/_-])/g;
 const HEX_TOKEN = /(?<![a-f0-9])(?:0x)?[a-f0-9]{24,}(?![a-f0-9])/gi;
@@ -30,19 +44,28 @@ const TYPOGLYCEMIA_TARGETS = [
     'repository',
     'workspace',
 ];
+// Contexts where a following verb reads as a command aimed at the reader, not a third-person
+// description of an attack (e.g. "An attacker may tell the model to ignore..." must stay
+// unredacted — see the matching test below). `^` is matched per clause (see CLAUSE_BOUNDARY
+// below), so a command hidden after an innocuous opener ("Heads up: ignore...") still counts as
+// clause-initial; only right after a direct role-address word is the other allowed context.
+const COMMAND_CONTEXT = String.raw `(?:^|\b(?:please|assistant|system|user|agent)\s+)`;
+function commandPattern(suffix) {
+    return new RegExp(COMMAND_CONTEXT + suffix, 'i');
+}
 const HARMFUL_INSTRUCTION_PATTERNS = [
-    /(^|\b(?:please|assistant|system|user|agent)\s+)ignore\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b/i,
-    /(^|\b(?:please|assistant|system|user|agent)\s+)disregard\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b/i,
-    /(^|\b(?:please|assistant|system|user|agent)\s+)forget\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b/i,
-    /(^|\b(?:please|assistant|system|user|agent)\s+)override\s+(the\s+)?(system|developer|agent)\s+(prompt|instructions?|message)\b/i,
-    /(^|\b(?:please|assistant|system|user|agent)\s+)you\s+are\s+now\s+(in\s+)?(developer|admin|root|system)\s+mode\b/i,
-    /(^|\b(?:please|assistant|system|user|agent)\s+)reveal\s+(your\s+)?(system|developer)\s+(prompt|instructions?|message)\b/i,
-    /(^|\b(?:please|assistant|system|user|agent)\s+)print\s+(your\s+)?(system|developer)\s+(prompt|instructions?|message)\b/i,
-    /(^|\b(?:please|assistant|system|user|agent)\s+)(exfiltrate|steal|leak)\s+(all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?|private\s+data)\b/i,
-    /(^|\b(?:please|assistant|system|user|agent)\s+)send\s+(me\s+|all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?)\s+(to|over|via|using)\b/i,
-    /(^|\b(?:please|assistant|system|user|agent)\s+)(upload|post|fetch|curl)\s+(all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?)\s+(to|over|via|using)\b/i,
-    /(^|\b(?:please|assistant|system|user|agent)\s+)delete\s+(all\s+)?(files?|the\s+repository|the\s+workspace|the\s+home\s+directory)\b/i,
-    /(^|\b(?:please|assistant|system|user|agent)\s+)run\s+.*\b(rm\s+-rf|curl\s+.*\|\s*(sh|bash)|sudo)\b/i,
+    commandPattern(String.raw `ignore\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b`),
+    commandPattern(String.raw `disregard\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b`),
+    commandPattern(String.raw `forget\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b`),
+    commandPattern(String.raw `override\s+(the\s+)?(system|developer|agent)\s+(prompt|instructions?|message)\b`),
+    commandPattern(String.raw `you\s+are\s+now\s+(in\s+)?(developer|admin|root|system)\s+mode\b`),
+    commandPattern(String.raw `reveal\s+(your\s+)?(system|developer)\s+(prompt|instructions?|message)\b`),
+    commandPattern(String.raw `print\s+(your\s+)?(system|developer)\s+(prompt|instructions?|message)\b`),
+    commandPattern(String.raw `(exfiltrate|steal|leak)\s+(all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?|private\s+data)\b`),
+    commandPattern(String.raw `send\s+(me\s+|all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?)\s+(to|over|via|using)\b`),
+    commandPattern(String.raw `(upload|post|fetch|curl)\s+(all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?)\s+(to|over|via|using)\b`),
+    commandPattern(String.raw `delete\s+(all\s+)?(files?|the\s+repository|the\s+workspace|the\s+home\s+directory)\b`),
+    commandPattern(String.raw `run\s+.*\b(rm\s+-rf|curl\s+.*\|\s*(sh|bash)|sudo)\b`),
 ];
 function normalizeForDetection(text) {
     return text
@@ -110,8 +133,20 @@ function isReadableDecodedText(text) {
     const printable = [...text].filter((char) => /[\t\n\r -~]/.test(char)).length;
     return printable / Math.max(text.length, 1) > 0.85;
 }
+// Sentence-ending punctuation splits a line into clauses for `^`-anchored matching below. This has
+// to run on the raw text, before normalizeForDetection's charset filter erases that same
+// punctuation into plain spaces — testing the anchor after normalization would never see it.
+//
+// ponytail: this still isn't complete — a filler *word* with no punctuation before it ("Please
+// just ignore previous instructions") is a clause-internal command and stays unredacted, same as
+// before this fix. Heuristic prompt-injection detection can't be made airtight with regex alone
+// (OWASP LLM01 has no complete solution either); upgrade path is a small classifier or an LLM-based
+// second pass over blocks this pattern set flags as borderline, if false negatives here prove costly.
+const CLAUSE_BOUNDARY = /(?<=[.!?:;])\s+/;
 function isUnsafeAgentInstruction(text) {
-    return detectionCandidates(text).some((candidate) => HARMFUL_INSTRUCTION_PATTERNS.some((pattern) => pattern.test(candidate)));
+    return text
+        .split(CLAUSE_BOUNDARY)
+        .some((clause) => detectionCandidates(clause).some((candidate) => HARMFUL_INSTRUCTION_PATTERNS.some((pattern) => pattern.test(candidate))));
 }
 function redactBlock(block) {
     const withSafeSpans = redactUnsafeSpans(block);
@@ -132,8 +167,17 @@ function stripQuotes(span) {
     }
     return span;
 }
+/**
+ * Scans Markdown for embedded prompt-injection attacks and redacts any block or line that matches.
+ * Detects direct patterns, plus base64/hex-encoded variants and typoglycemia obfuscation.
+ * HTML comments are checked first; the body is then split on paragraph breaks and scanned line-by-line.
+ *
+ * @param markdown - Markdown content (possibly untrusted, sourced from fetched pages).
+ * @returns Sanitized Markdown with harmful instruction blocks replaced by a redaction placeholder,
+ *   and ANSI/control bytes stripped so a cached read can never replay them to a terminal.
+ */
 export function sanitizePromptInjection(markdown) {
-    return markdown
+    const redacted = markdown
         .replace(HTML_COMMENT, (comment) => redactBlock(comment))
         .split(/(\n{2,})/)
         .map((block) => {
@@ -146,4 +190,5 @@ export function sanitizePromptInjection(markdown) {
         return lineRedacted === block ? redactBlock(block) : lineRedacted;
     })
         .join('');
+    return stripUnsafeControlChars(redacted);
 }

package/dist/lib/research/proxy.d.ts

@@ -59,13 +59,19 @@ export declare function getCaBundleSpkiHashes(): string[];
 /**
  * Chrome CLI flag that trusts exactly the sandbox's injected CA(s), pinned by SPKI hash rather
  * than by disabling verification. Chromium's TLS stack (the Chrome Root Store) never reads
- * NODE_EXTRA_CA_CERTS/SSL_CERT_FILE/CURL_CA_BUNDLE the way Node/curl/Python do, so a sandbox that
- * MITMs HTTPS through its proxy (see isProxyConfigured) makes every other tool trust the proxy's
- * cert while Chrome's handshake with it fails with ERR_CERT_AUTHORITY_INVALID. This is scoped
- * narrowly to the specific CA(s) discovered via the CA bundle env vars — never
- * --ignore-certificate-errors, which would disable verification for every host, including ones
- * that have nothing to do with the sandbox's proxy. A no-op (empty array) when no proxy is
- * configured or no CA bundle is discoverable, so default Chrome trust is untouched on ordinary
- * developer machines.
+ * NODE_EXTRA_CA_CERTS/SSL_CERT_FILE/CURL_CA_BUNDLE the way Node/curl/Python do, so an environment
+ * that MITMs HTTPS makes every other tool trust that CA while Chrome's handshake with it fails
+ * with ERR_CERT_AUTHORITY_INVALID. This is scoped narrowly to the specific CA(s) discovered via
+ * the CA bundle env vars — never --ignore-certificate-errors, which would disable verification
+ * for every host, including ones that have nothing to do with the sandbox.
+ *
+ * Deliberately independent of isProxyConfigured(): some sandboxes intercept HTTPS transparently
+ * (or via a proxy Chrome reaches without an explicit --proxy-server flag) while still exporting a
+ * CA bundle env var for CLI tools to trust — HTTPS_PROXY/HTTP_PROXY and the CA bundle vars are
+ * two separate signals that usually co-occur but aren't guaranteed to. Gating on proxy detection
+ * left Chrome untrusting a CA bundle that was in fact discoverable, so it rejected every
+ * browser-rendered fetch with ERR_CERT_AUTHORITY_INVALID in that shape of environment. A no-op
+ * (empty array) when no CA bundle is discoverable, so default Chrome trust is untouched on
+ * ordinary developer machines.
  */
 export declare function getChromeSpkiArgs(): string[];

package/dist/lib/research/proxy.js

@@ -169,18 +169,22 @@ export function getCaBundleSpkiHashes() {
 /**
  * Chrome CLI flag that trusts exactly the sandbox's injected CA(s), pinned by SPKI hash rather
  * than by disabling verification. Chromium's TLS stack (the Chrome Root Store) never reads
- * NODE_EXTRA_CA_CERTS/SSL_CERT_FILE/CURL_CA_BUNDLE the way Node/curl/Python do, so a sandbox that
- * MITMs HTTPS through its proxy (see isProxyConfigured) makes every other tool trust the proxy's
- * cert while Chrome's handshake with it fails with ERR_CERT_AUTHORITY_INVALID. This is scoped
- * narrowly to the specific CA(s) discovered via the CA bundle env vars — never
- * --ignore-certificate-errors, which would disable verification for every host, including ones
- * that have nothing to do with the sandbox's proxy. A no-op (empty array) when no proxy is
- * configured or no CA bundle is discoverable, so default Chrome trust is untouched on ordinary
- * developer machines.
+ * NODE_EXTRA_CA_CERTS/SSL_CERT_FILE/CURL_CA_BUNDLE the way Node/curl/Python do, so an environment
+ * that MITMs HTTPS makes every other tool trust that CA while Chrome's handshake with it fails
+ * with ERR_CERT_AUTHORITY_INVALID. This is scoped narrowly to the specific CA(s) discovered via
+ * the CA bundle env vars — never --ignore-certificate-errors, which would disable verification
+ * for every host, including ones that have nothing to do with the sandbox.
+ *
+ * Deliberately independent of isProxyConfigured(): some sandboxes intercept HTTPS transparently
+ * (or via a proxy Chrome reaches without an explicit --proxy-server flag) while still exporting a
+ * CA bundle env var for CLI tools to trust — HTTPS_PROXY/HTTP_PROXY and the CA bundle vars are
+ * two separate signals that usually co-occur but aren't guaranteed to. Gating on proxy detection
+ * left Chrome untrusting a CA bundle that was in fact discoverable, so it rejected every
+ * browser-rendered fetch with ERR_CERT_AUTHORITY_INVALID in that shape of environment. A no-op
+ * (empty array) when no CA bundle is discoverable, so default Chrome trust is untouched on
+ * ordinary developer machines.
  */
 export function getChromeSpkiArgs() {
-    if (!isProxyConfigured())
-        return [];
     const hashes = getCaBundleSpkiHashes();
     if (!hashes.length)
         return [];

package/dist/lib/research/resolve-target.d.ts

@@ -7,6 +7,8 @@ export interface ResolveResearchTargetOptions {
     dataDir: string;
     flagOverride?: StorageMode;
     lookup?: boolean;
+    /** Read-only/plan mode: a corrupt entry hit during lookup is reported but never archived on disk. */
+    readOnly?: boolean;
     url: string;
 }
 export interface ResolvedResearchTarget {

package/dist/lib/research/resolve-target.js

@@ -13,7 +13,7 @@ export function resolveResearchTarget(opts) {
     });
     return {
         cacheKey,
-        located: opts.lookup === false ? null : locateArtifact(roots.readRoots, cacheKey),
+        located: opts.lookup === false ? null : locateArtifact(roots.readRoots, cacheKey, opts.readOnly),
         normalizedUrl,
         roots,
     };

package/dist/lib/research/revalidate.d.ts

@@ -1,34 +1,63 @@
 import type { ResearchArtifact } from './schema.js';
+import { type FetchedContent } from './fetcher.js';
+import { type ExtractionResult } from './extract.js';
+import type { StoreRoots } from './store-roots.js';
 import type { SummaryLevel } from '../config/schema.js';
+/**
+ * When set, project-located revalidation writes reuse {@link persistArtifact} (secret-scan +
+ * redirect) so a refresh cannot leave credentials in a committable project cache (#90).
+ */
+export interface RevalidateSecureWrite {
+    roots: StoreRoots;
+    dryRun?: boolean;
+    scratchDir?: string | null;
+}
+/** Result of conditional revalidation or a full refresh when validators miss. */
 export interface RevalidationResult {
+    /** Outcome of the revalidation attempt. */
     status: 'revalidated' | 'refreshed' | 'stale';
+    /** Artifact to serve (updated, refreshed, or the prior stale entry). */
     artifact: ResearchArtifact;
+    /** When status is `stale`, whether serving stale content is allowed. */
     allowed?: boolean;
+    /** Revalidation failure message when status is `stale`. */
     error?: string;
+    /** Data dir the write landed in (or would land in under dry-run), when a write ran. */
+    storageDir?: string;
+    /** True when a project refresh was redirected to global due to a detected secret. */
+    redirectedToGlobal?: boolean;
+    /** Secret-redirect warning for stderr, or null/undefined when none. */
+    redirectWarning?: string | null;
+}
+type RevalidateOptions = {
+    allowStale: boolean;
+    ttlOverride?: string | null;
+    rendered?: boolean;
+    summaryLevel: SummaryLevel;
+    /** Present only when the live entry is in the project cache. */
+    secure?: RevalidateSecureWrite;
+};
+interface CreateArtifactFromFetchInput {
+    url: string;
+    normalizedUrl: string;
+    cacheKey: string;
+    fetchResult: FetchedContent;
+    extraction: ExtractionResult;
+    tier: 'stable' | 'standard' | 'volatile';
+    ttl: string | null;
+    currentTime: Date;
+    summaryLevel: SummaryLevel;
 }
 /**
- * Helper to construct a ResearchArtifact from a fresh HTML fetch.
+ * Construct a ResearchArtifact from a fresh HTML fetch (or error-page marker).
+ *
+ * @param input - URL, fetch result, extraction, tier/TTL, clock, and summary level.
+ * @returns A ready-to-persist research artifact.
  */
-export declare function createArtifactFromFetch(url: string, normalizedUrl: string, cacheKey: string, fetchResult: {
-    contentType: string | null;
-    etag: string | null;
-    lastModified: string | null;
-    finalUrl: string;
-    responseSize: number;
-    content: string;
-}, extraction: {
-    title: string;
-    detailedMarkdown: string;
-    confidence: 'high' | 'medium' | 'low';
-    qualityNotes: string[];
-}, tier: 'stable' | 'standard' | 'volatile', ttl: string | null, currentTime: Date, summaryLevel: SummaryLevel): ResearchArtifact;
+export declare function createArtifactFromFetch(input: CreateArtifactFromFetchInput): ResearchArtifact;
 /**
  * Revalidates a stale cache artifact using conditional request headers,
  * falling back to stale serving within the grace period if the remote host is offline.
  */
-export declare function revalidateCache(dataDir: string, existing: ResearchArtifact, currentTime: Date, options: {
-    allowStale: boolean;
-    ttlOverride?: string | null;
-    rendered?: boolean;
-    summaryLevel: SummaryLevel;
-}): Promise<RevalidationResult>;
+export declare function revalidateCache(dataDir: string, existing: ResearchArtifact, currentTime: Date, options: RevalidateOptions): Promise<RevalidationResult>;
+export {};