@taurgis/bonsai 3.2.2 → 4.0.0

package/dist/lib/config/io.js

@@ -5,43 +5,93 @@ import { KEY_META, ALL_KEYS } from './schema.js';
 /** Global, user-level config lives in the OCLIF config dir; project config sits at the repo root. */
 export const USER_CONFIG_FILENAME = 'config.json';
 export const PROJECT_CONFIG_FILENAME = '.bonsai.json';
-/** Parse a config file, keeping only known keys with valid values. Invalid input degrades to {}. */
-function parseConfigFile(raw) {
+/**
+ * Parse a config file, keeping only known keys with valid values. Unparseable JSON, a non-object
+ * top level, or an invalid value for a known key degrades that part to "absent" rather than
+ * throwing — callers that only need values (`readUserConfig`/`readProjectConfig`) ignore
+ * `warnings`; {@link invalidConfigFileWarnings} surfaces them so the degradation is never silent.
+ */
+function parseConfigFile(filePath, raw, scopeFlag, bin) {
+    let parsed;
     try {
-        const parsed = JSON.parse(raw);
-        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
-            return {};
-        const obj = parsed;
-        const result = {};
-        for (const key of ALL_KEYS) {
-            const val = obj[key];
-            if (val !== undefined && KEY_META[key].isValid(val)) {
-                Object.assign(result, { [key]: val });
-            }
-        }
-        return result;
+        parsed = JSON.parse(raw);
     }
     catch {
-        return {};
+        return {
+            values: {},
+            warnings: [
+                `Ignoring ${filePath}: not valid JSON. Using the configured value or default instead. ` +
+                    `Fix the file by hand, or overwrite it with ${bin} config set <key> <value> ${scopeFlag}.`,
+            ],
+        };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return {
+            values: {},
+            warnings: [
+                `Ignoring ${filePath}: expected a JSON object at the top level. Using the configured value or default instead.`,
+            ],
+        };
+    }
+    const obj = parsed;
+    const values = {};
+    const warnings = [];
+    for (const key of ALL_KEYS) {
+        const val = obj[key];
+        if (val === undefined)
+            continue;
+        if (KEY_META[key].isValid(val)) {
+            Object.assign(values, { [key]: val });
+        }
+        else {
+            const validValues = KEY_META[key].values;
+            const validValuesHint = validValues ? ` Valid values: ${validValues.join(', ')}.` : '';
+            warnings.push(`Ignoring "${key}" in ${filePath}: invalid value ${JSON.stringify(val)}.${validValuesHint} ` +
+                `Using the configured value or default instead.`);
+        }
     }
+    return { values, warnings };
 }
-function readConfigFile(filePath) {
+// Only the "fix it" suggestion in a warning message names the binary; every value-only caller
+// below (readUserConfig/readProjectConfig, and transitively write*Config) discards warnings
+// entirely, so this default never reaches a user — it's a placeholder for an unused code path,
+// not a claim about the real bin name. invalidConfigFileWarnings passes the real `this.config.bin`.
+const DEFAULT_BIN = 'bonsai';
+function readConfigFile(filePath, scopeFlag, bin = DEFAULT_BIN) {
     if (!existsSync(filePath))
-        return {};
+        return { values: {}, warnings: [] };
+    let raw;
     try {
-        return parseConfigFile(readFileSync(filePath, 'utf-8'));
+        raw = readFileSync(filePath, 'utf-8');
     }
     catch {
-        return {};
+        return { values: {}, warnings: [] };
     }
+    return parseConfigFile(filePath, raw, scopeFlag, bin);
 }
 export function readUserConfig(configDir) {
     if (!configDir)
         return {};
-    return readConfigFile(join(configDir, USER_CONFIG_FILENAME));
+    return readConfigFile(join(configDir, USER_CONFIG_FILENAME), '--global').values;
 }
 export function readProjectConfig(cwd) {
-    return readConfigFile(join(cwd, PROJECT_CONFIG_FILENAME));
+    return readConfigFile(join(cwd, PROJECT_CONFIG_FILENAME), '--local').values;
+}
+/**
+ * Warnings for the user and project config files, so a corrupted or hand-edited file that would
+ * otherwise silently degrade to `{}` (or drop just the offending key) is never a silent surprise —
+ * mirrors {@link invalidEnvOverrideWarnings} for env vars. Empty when both files are missing,
+ * unreadable, or valid.
+ *
+ * @param bin - CLI binary name (`this.config.bin`) for the "fix it" suggestion in a warning.
+ */
+export function invalidConfigFileWarnings(configDir, cwd, bin) {
+    const warnings = [];
+    if (configDir) {
+        warnings.push(...readConfigFile(join(configDir, USER_CONFIG_FILENAME), '--global', bin).warnings);
+    }
+    warnings.push(...readConfigFile(join(cwd, PROJECT_CONFIG_FILENAME), '--local', bin).warnings);
+    return warnings;
 }
 function writeAtomically(filePath, data) {
     atomicWriteFile(filePath, JSON.stringify(data, null, 2) + '\n');

package/dist/lib/config/schema.d.ts

@@ -29,3 +29,5 @@ export declare function isKnownKey(key: string): key is ConfigKey;
 export declare function suggestKey(input: string): ConfigKey | undefined;
 /** Comma-joined valid key list for error messages, kept in one place. */
 export declare function validKeysHint(): string;
+/** Valid keys with their accepted values, e.g. "storage (global|project), summary (…)", for `--help` descriptions. */
+export declare function keyValuesHint(): string;

package/dist/lib/config/schema.js

@@ -40,3 +40,10 @@ export function suggestKey(input) {
 export function validKeysHint() {
     return ALL_KEYS.join(', ');
 }
+/** Valid keys with their accepted values, e.g. "storage (global|project), summary (…)", for `--help` descriptions. */
+export function keyValuesHint() {
+    return ALL_KEYS.map((key) => {
+        const { values } = KEY_META[key];
+        return values ? `${key} (${values.join('|')})` : key;
+    }).join(', ');
+}

package/dist/lib/envelope.js

@@ -1,4 +1,5 @@
 import { EXIT_RUNTIME_FAILURE } from './cli-error-policy.js';
+import { pluralize } from './text.js';
 /** Map oclif parse-time errors to stable Bonsai codes when the throw site did not set one. */
 export function stableErrorCodeFrom(err) {
     const e = err;
@@ -117,8 +118,9 @@ export function enrichCacheMissEnvelope(envelope, data, bin) {
         exitCode: EXIT_RUNTIME_FAILURE,
         message: (first, failures) => {
             const url = first.normalizedUrl ?? '';
-            return failures.length > 1
-                ? `Cache miss for ${url} and ${failures.length - 1} other URLs`
+            const otherCount = failures.length - 1;
+            return otherCount > 0
+                ? `Cache miss for ${url} and ${otherCount} other ${pluralize(otherCount, 'URL', 'URLs')}`
                 : `Cache miss for ${url}`;
         },
         // A URL that is already a secondary source of a different cached artifact must not be pointed
@@ -141,8 +143,13 @@ export function enrichRowErrorEnvelope(envelope, data) {
             return row.error ?? null;
         },
         code: (first) => first.code ?? 'FETCH_FAILED',
-        message: (first, failures) => (first.message ?? '') +
-            (failures.length > 1 ? `\n…and ${failures.length - 1} other URL failure(s)` : ''),
+        message: (first, failures) => {
+            const otherCount = failures.length - 1;
+            const suffix = otherCount > 0
+                ? `\n…and ${otherCount} other URL ${pluralize(otherCount, 'failure', 'failures')}`
+                : '';
+            return (first.message ?? '') + suffix;
+        },
         suggestions: (failures) => failures[0]?.suggestions,
         ref: (first) => first.ref,
         exitCode: EXIT_RUNTIME_FAILURE,

package/dist/lib/prune-flags.d.ts

@@ -14,6 +14,8 @@ export interface PruneFlagInput {
     inactive?: string;
     artifactType?: string;
     url?: string;
+    topic?: string;
+    tags?: string[];
     dryRun: boolean;
     yes: boolean;
     readOnly: boolean;

package/dist/lib/prune-flags.js

@@ -1,16 +1,22 @@
 import { emptyUrlFilterError } from './research/url.js';
 import { durationFlagError } from './research/freshness.js';
+import { emptyTopicFilterError, emptyTagsFilterError } from './research/metadata-filters.js';
 function missingFilterError(input) {
     // Treat an explicitly passed empty string as "filter was attempted" so `--older-than ''`
     // is not misreported as MISSING_FILTER (durationError rejects it as INVALID_DURATION).
+    // `tags` is the one array-valued flag here: oclif never parses a bare `--tags` into `[]` (a
+    // multiple string flag requires a value per occurrence), so a non-empty array is the correct
+    // "was this filter attempted" test, mirroring the `!== undefined` check used for every scalar flag.
     if (input.olderThan !== undefined ||
         input.inactive !== undefined ||
         input.artifactType !== undefined ||
-        input.url !== undefined) {
+        input.url !== undefined ||
+        input.topic !== undefined ||
+        (input.tags?.length ?? 0) > 0) {
         return null;
     }
     return {
-        message: 'Must specify at least one pruning filter: --older-than, --inactive, --artifact-type, or --url.',
+        message: 'Must specify at least one pruning filter: --older-than, --inactive, --artifact-type, --url, --topic, or --tags.',
         code: 'MISSING_FILTER',
         suggestions: [`Preview age-based pruning: ${input.bin} prune --older-than 30d --dry-run`],
     };
@@ -41,10 +47,14 @@ function mutationSafetyError(input) {
     if (!input.readOnly && !input.dryRun && !input.yes) {
         const olderThanPart = input.olderThan ? ` --older-than ${input.olderThan}` : '';
         const urlPart = input.url ? ` --url "${input.url}"` : '';
+        const topicPart = input.topic ? ` --topic "${input.topic}"` : '';
+        const tagsPart = (input.tags ?? []).map((tag) => ` --tags "${tag}"`).join('');
         return {
             message: 'Safety check: use --yes to confirm pruning, or --dry-run to preview files that would be deleted.',
             code: 'SAFETY_CHECK_REQUIRED',
-            suggestions: [`Preview first: ${input.bin} prune --dry-run${olderThanPart}${urlPart}`],
+            suggestions: [
+                `Preview first: ${input.bin} prune --dry-run${olderThanPart}${urlPart}${topicPart}${tagsPart}`,
+            ],
         };
     }
     return null;
@@ -66,9 +76,11 @@ function durationError(input) {
  * @returns Error descriptor for `this.error`, or `null`.
  */
 export function pruneFlagError(input) {
-    const urlErr = emptyUrlFilterError(input.url);
-    if (urlErr)
-        return { message: urlErr, code: 'INVALID_FLAG_VALUE' };
+    const flagValueErr = emptyUrlFilterError(input.url) ??
+        emptyTopicFilterError(input.topic) ??
+        emptyTagsFilterError(input.tags);
+    if (flagValueErr)
+        return { message: flagValueErr, code: 'INVALID_FLAG_VALUE' };
     // Duration before missing-filter so `--older-than ''` reports INVALID_DURATION, not MISSING_FILTER.
     return durationError(input) ?? missingFilterError(input) ?? mutationSafetyError(input);
 }

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

@@ -39,7 +39,13 @@ function getOrUpdateIndexEntry(filePath, cached, onChanged) {
         return cached;
     }
     try {
-        const entry = { sig, artifact: parseArtifactShallow(readFileSync(filePath, 'utf-8')) };
+        const artifact = parseArtifactShallow(readFileSync(filePath, 'utf-8'));
+        // Mirrors the same guard in storage.ts's scanCacheDir: parseArtifact never throws on a foreign
+        // or garbled *.md file that merely has `---`/`---` fences, it just defaults cache_key to ''. Treat
+        // that the same as a parse failure so it's skipped rather than indexed as a phantom entry.
+        if (!artifact.metadata.cache_key)
+            return undefined;
+        const entry = { sig, artifact };
         onChanged();
         return entry;
     }

package/dist/lib/research/artifact.js

@@ -1,12 +1,30 @@
+import { CONTROL_CHAR_PATTERN } from '../text.js';
+// Frontmatter is one field per line. An embedded newline (or tab, treated the same way as
+// legitimate Markdown whitespace elsewhere in this codebase — see sanitizeForTerminal in
+// ../text.ts and stripUnsafeControlChars in ./prompt-injection.ts) in a free-form value (e.g. an
+// agent-supplied --topic or --tags) would inject a bogus extra line — at best a dropped stray
+// line, at worst a fake `key: value` pair, or a bare `---` that closes the frontmatter fence early
+// and splices the remaining metadata fields (and even the closing fence and body sections) into
+// what parseArtifact then treats as free-text content. Collapsing that whitespace to a space
+// (rather than deleting it, which would silently merge adjacent words) keeps every value confined
+// to the single line the format requires, regardless of where the string originated. Other control
+// characters (e.g. a raw ANSI escape byte, whether from an agent-supplied flag or extracted page
+// text) are stripped outright: the cache file is plain text meant to be `cat`ed or displayed by
+// `inspect`/`list`, and an uncaught escape sequence there would reach a real terminal — unlike
+// --json output, which JSON-escapes control characters by construction.
+function sanitizeFrontmatterLine(value) {
+    return value.replace(/[\t\r\n]+/g, ' ').replace(CONTROL_CHAR_PATTERN, '');
+}
 function serializeArrayField(lines, name, items) {
     lines.push(`${name}:`);
     for (const item of items) {
-        lines.push(`  - ${item}`);
+        lines.push(`  - ${sanitizeFrontmatterLine(item)}`);
     }
 }
 // A scalar frontmatter line, blanking null/undefined. Using `??` (not `||`) preserves a numeric 0.
 function serializeScalarField(lines, name, value) {
-    lines.push(`${name}: ${value ?? ''}`);
+    const safeValue = typeof value === 'string' ? sanitizeFrontmatterLine(value) : value;
+    lines.push(`${name}: ${safeValue ?? ''}`);
 }
 /**
  * Serializes artifact metadata to standard YAML frontmatter text.

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

@@ -1,3 +1,4 @@
+import { ChildProcess } from 'node:child_process';
 export interface BrowserFetchOptions {
     timeoutMs?: number;
     bodyLimitBytes?: number;
@@ -25,6 +26,16 @@ export declare class CdpClient {
 }
 export declare function findChromePath(): string;
 export declare function buildChromeArgs(): string[];
+/**
+ * Kill Chrome and every child process it spawned (zygote, gpu-process, renderer, crashpad).
+ * `chromeProcess.kill()` alone only signals that one PID — per Node's child_process docs, a signal
+ * sent to a child is not propagated to *that child's own* children on Linux, so Chrome's
+ * multi-process tree survives a plain kill on every rendered fetch, not just an interrupted one.
+ * Spawning with `detached: true` makes Chrome the leader of its own process group, so signaling the
+ * negative PID reaches the whole tree in one call. Falls back to a direct kill if group-kill fails
+ * (already exited, or a platform without POSIX process groups).
+ */
+export declare function killChromeTree(chromeProcess: ChildProcess): void;
 export declare function waitForLoad(client: CdpClient, sessionId: string, timeoutMs: number, settleMs?: number): Promise<void>;
 export declare const BLOCKED_ASSET_URLS: string[];
 export interface CdpPage {
@@ -106,6 +117,7 @@ export declare const SANDBOX_EGRESS_ERROR_MARKER = "sandboxed execution environm
  * against the environment directly and fall back to a manual fetch if it's still unreachable.
  */
 export declare function describeNavigationFailure(errorText: string, url: string): Error;
+export declare function isTransientBrowserError(err: unknown): boolean;
 /**
  * Navigates an already-open CDP page to `currentUrl` and captures the rendered HTML, honoring the
  * openCdpPage Fetch-domain safety guard at every point a blocked navigation could otherwise be

package/dist/lib/research/browser.js

@@ -130,13 +130,63 @@ export function buildChromeArgs() {
 // CI runners occasionally starve headless Chrome's startup (disk/CPU contention from concurrent
 // jobs), so this is generous enough to absorb that rather than a "typical" local startup time.
 const CHROME_STARTUP_TIMEOUT_MS = 20_000;
+// Node's default SIGINT/SIGTERM disposition kills the process immediately, without waiting for the
+// async `finally { page.close() }` in fetchRenderedHtmlOnce to run — so an interrupted --rendered
+// fetch otherwise abandons a whole Chrome process tree (main + zygote/gpu/renderer children). The
+// plain 'exit' event covers ordinary completion (belt-and-braces alongside close()'s own cleanup);
+// a `once` signal listener runs the same cleanup, then re-sends the signal to this process. Because
+// `once` already removed itself, that re-delivery has no listener left and Node's own default
+// disposition takes over — the process still exits with the normal 128+signum code, with no exit-code
+// bookkeeping of our own.
+const liveChromeProcesses = new Set();
+let chromeCleanupRegistered = false;
+function killLiveChromeProcesses() {
+    for (const chromeProcess of liveChromeProcesses)
+        killChromeTree(chromeProcess);
+}
+function ensureChromeCleanupRegistered() {
+    if (chromeCleanupRegistered)
+        return;
+    chromeCleanupRegistered = true;
+    process.once('exit', killLiveChromeProcesses);
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.once(signal, () => {
+            killLiveChromeProcesses();
+            process.kill(process.pid, signal);
+        });
+    }
+}
+/**
+ * Kill Chrome and every child process it spawned (zygote, gpu-process, renderer, crashpad).
+ * `chromeProcess.kill()` alone only signals that one PID — per Node's child_process docs, a signal
+ * sent to a child is not propagated to *that child's own* children on Linux, so Chrome's
+ * multi-process tree survives a plain kill on every rendered fetch, not just an interrupted one.
+ * Spawning with `detached: true` makes Chrome the leader of its own process group, so signaling the
+ * negative PID reaches the whole tree in one call. Falls back to a direct kill if group-kill fails
+ * (already exited, or a platform without POSIX process groups).
+ */
+export function killChromeTree(chromeProcess) {
+    if (typeof chromeProcess.pid === 'number') {
+        try {
+            process.kill(-chromeProcess.pid, 'SIGKILL');
+            return;
+        }
+        catch {
+            // Fall through to a best-effort direct kill below.
+        }
+    }
+    chromeProcess.kill('SIGKILL');
+}
 async function spawnChrome(chromePath) {
-    const chromeProcess = spawn(chromePath, buildChromeArgs());
+    ensureChromeCleanupRegistered();
+    const chromeProcess = spawn(chromePath, buildChromeArgs(), { detached: true });
+    liveChromeProcesses.add(chromeProcess);
+    chromeProcess.once('exit', () => liveChromeProcesses.delete(chromeProcess));
     try {
         const wsUrl = await new Promise((resolve, reject) => {
             let output = '';
             const timeoutId = setTimeout(() => {
-                chromeProcess.kill('SIGKILL');
+                killChromeTree(chromeProcess);
                 reject(new Error('Timed out waiting for Chrome to start.'));
             }, CHROME_STARTUP_TIMEOUT_MS);
             const onData = (data) => {
@@ -168,7 +218,7 @@ async function spawnChrome(chromePath) {
         return { chromeProcess, wsUrl };
     }
     catch (err) {
-        chromeProcess.kill('SIGKILL');
+        killChromeTree(chromeProcess);
         throw err;
     }
 }
@@ -286,7 +336,7 @@ export async function openCdpPage() {
             }
             catch { }
             client.close();
-            chromeProcess.kill('SIGKILL');
+            killChromeTree(chromeProcess);
         };
         const takeBlockedNavigationError = () => {
             const err = blockedNavigationError;
@@ -297,7 +347,7 @@ export async function openCdpPage() {
     }
     catch (err) {
         client.close();
-        chromeProcess.kill('SIGKILL');
+        killChromeTree(chromeProcess);
         throw err;
     }
 }
@@ -414,8 +464,11 @@ export function describeNavigationFailure(errorText, url) {
         `or bypassing the proxy: confirm "${host}" is reachable from this environment (e.g. test the ` +
         `proxy directly), or fetch the page from a network with access and import it instead.`);
 }
-// Chrome can emit these on first navigation in headless CI when the cert verifier reloads mid-run.
-const TRANSIENT_NAV_ERROR_CODES = ['ERR_CERT_VERIFIER_CHANGED'];
+// ERR_CERT_VERIFIER_CHANGED: Chrome can emit this on first navigation in headless CI when the cert
+// verifier reloads mid-run. ERR_CONNECTION_CLOSED is Chromium's code for a plain remote TCP FIN
+// (net_error_list.h), which CI runners can hit as a one-off network blip against a real host
+// rather than a real block.
+const TRANSIENT_NAV_ERROR_CODES = ['ERR_CERT_VERIFIER_CHANGED', 'ERR_CONNECTION_CLOSED'];
 // Resource contention in CI (concurrent jobs competing for CPU/disk) can make Chrome itself fail
 // to come up in time, or die before its devtools websocket URL is printed. Neither reflects a
 // problem with the target page, so it's worth a fresh attempt rather than failing the whole fetch.
@@ -423,7 +476,9 @@ const TRANSIENT_CHROME_STARTUP_MESSAGES = [
     'Timed out waiting for Chrome to start.',
     'Chrome exited prematurely',
 ];
-function isTransientBrowserError(err) {
+// Exported so tests can assert the transient-error classification directly rather than only
+// indirectly through a live fetchRenderedHtml retry, which needs a real Chrome navigation to fail.
+export function isTransientBrowserError(err) {
     const message = err instanceof Error ? err.message : String(err);
     return (TRANSIENT_NAV_ERROR_CODES.some((code) => message.includes(code)) ||
         TRANSIENT_CHROME_STARTUP_MESSAGES.some((text) => message.includes(text)));

package/dist/lib/research/cli-io.d.ts

@@ -18,6 +18,13 @@ export interface CliIo {
     warn(msg: string): void;
     log(msg: string): void;
     error(msg: string, opts: CliErrorOptions): never;
+    /**
+     * Print one row of a batch failure with the same "Error: … / Code: … / Try this: …" rendering as
+     * {@link error}, but without exiting the process — a batch (`fetch url1 url2`) must keep
+     * processing the remaining rows after one fails. Using `warn` for this mislabels a real failure
+     * as non-fatal even though the row still flips the command's exit code and JSON `ok` to false.
+     */
+    errorRow(msg: string, opts: Omit<CliErrorOptions, 'exit'>): void;
 }
 /**
  * Single exit point for a URL that failed normalization, shared by BaseCommand and the command

package/dist/lib/research/fetch-command-service.js

@@ -3,10 +3,10 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { finalizeBatch } from '../batch.js';
-import { formatErrorForJson } from '../envelope.js';
 import { loadSummaryLevel } from '../config/index.js';
 import { buildFetchFailureFromCaught, buildFetchFailureResult, buildFetchResultData, describeError, extractionQualityWarnings, FETCH_STATUS_LABEL, fetchFailureGuidance, reportCacheStatus, } from './fetch-result.js';
 import { durationFlagError, evaluateFreshnessWithMaxAge } from './freshness.js';
+import { metadataLengthError, metadataNewlineError } from './metadata-flags.js';
 import { fetchRenderedHtml } from './browser.js';
 import { capturePage } from './capture.js';
 import { persistSectionArtifacts } from './docs/section-artifacts.js';
@@ -15,8 +15,10 @@ import { applyAutoTags } from './keywords.js';
 import { persistArtifact } from './persist-artifact.js';
 import { createArtifactFromFetch, revalidateCache, } from './revalidate.js';
 import { resolveResearchTarget } from './resolve-target.js';
+import { locateArtifact } from './storage.js';
 import { failInvalidUrl } from './cli-io.js';
 import { batchSeparator } from '../cache-view.js';
+import { formatTip } from '../text.js';
 import { EXIT_STALE_SERVED } from '../cli-error-policy.js';
 import { detectSite } from '../../sites/index.js';
 import { applySiteFetchProvenance } from '../../sites/types.js';
@@ -34,6 +36,22 @@ export function validateFetchCommandFlags(io, flags) {
         if (msg)
             io.error(msg, { exit: 2, code: 'INVALID_DURATION' });
     }
+    const newlineErr = metadataNewlineError(flags);
+    if (newlineErr) {
+        io.error(newlineErr, {
+            exit: 2,
+            code: 'INVALID_METADATA_VALUE',
+            suggestions: ['Remove line breaks from the value.'],
+        });
+    }
+    const lengthErr = metadataLengthError(flags);
+    if (lengthErr) {
+        io.error(lengthErr, {
+            exit: 2,
+            code: 'INVALID_METADATA_VALUE',
+            suggestions: ['Shorten the value.'],
+        });
+    }
     // --force skips cache lookup; --allow-stale only applies when serving a stale entry after a
     // failed revalidation. Together they are a no-op combination that looks intentional -- reject it.
     if (flags.force && flags.allowStale) {
@@ -112,7 +130,7 @@ async function executeCacheHit(cached, targetDir, run, secure) {
         redirectedToGlobal: Boolean(revalidationResult.redirectedToGlobal),
     };
 }
-async function executeCacheMiss(normalizedUrl, cacheKey, run) {
+async function executeCacheMiss(normalizedUrl, cacheKey, readRoots, run) {
     const { currentTime, flags, summaryLevel } = run;
     const siteModule = detectSite(normalizedUrl);
     const useRendered = flags.rendered || Boolean(siteModule?.defaults?.rendered);
@@ -141,8 +159,13 @@ async function executeCacheMiss(normalizedUrl, cacheKey, run) {
         currentTime,
         summaryLevel,
     });
-    artifact.metadata.topic = flags.topic || null;
-    artifact.metadata.tags = flags.tags || [];
+    // --force bypasses the normal revalidation-hit path (it always re-fetches instead of
+    // conditionally refreshing), so this "miss" may actually be overwriting a previously curated
+    // entry. Read-only lookup, purely to carry topic/tags forward like every other refresh path
+    // (revalidate.ts's preserveUserMetadata) — explicit --topic/--tags on this call still win.
+    const priorArtifact = locateArtifact(readRoots, cacheKey, true)?.artifact ?? null;
+    artifact.metadata.topic = flags.topic || priorArtifact?.metadata.topic || null;
+    artifact.metadata.tags = flags.tags?.length ? flags.tags : (priorArtifact?.metadata.tags ?? []);
     artifact.metadata.site_module_id = siteModule?.id ?? null;
     if (capture) {
         applyCaptureMetadata(artifact, capture);
@@ -177,7 +200,7 @@ async function resolveArtifact(target, run) {
             redirectedToGlobal: hit.redirectedToGlobal,
         };
     }
-    const artifact = await executeCacheMiss(normalizedUrl, cacheKey, run);
+    const artifact = await executeCacheMiss(normalizedUrl, cacheKey, roots.readRoots, run);
     const write = persistArtifact({
         roots,
         cacheKey,
@@ -234,11 +257,17 @@ function failureRowOrRethrow(url, err, run) {
     const row = err instanceof Errors.CLIError
         ? buildFetchFailureResult({ url, dryRun, err })
         : buildFetchFailureFromCaught(io.bin, url, err, dryRun);
-    // Human batches only get the spinner "failed" label unless we echo the reason. Mirror the
-    // single-URL error format (message + Code: + Try this:) rather than a bare message, so a row
-    // failure in a batch is exactly as actionable as it is standalone.
-    if (!io.json)
-        io.warn(formatErrorForJson(row.error));
+    // Human batches only get the spinner "failed" label unless we echo the reason. Render it with
+    // the same "Error:" formatting as a single-URL failure (io.errorRow reuses oclif's own
+    // exit:false renderer) rather than io.warn, since a row failure still fails the command overall
+    // and should never read as merely a warning.
+    if (!io.json) {
+        io.errorRow(row.error.message, {
+            code: row.error.code,
+            suggestions: row.error.suggestions,
+            ref: row.error.ref,
+        });
+    }
     return row;
 }
 async function fetchSingleTarget(url, run) {
@@ -252,6 +281,10 @@ async function fetchSingleTarget(url, run) {
             url,
             flagOverride: flags.storage,
             lookup: !flags.force,
+            // `dryRun` already merges explicit --dry-run with global read-only/plan mode
+            // (BaseCommand.effectiveDryRun), so a corrupt entry hit while resolving the cache target is
+            // never archived (renamed) on disk during either kind of no-write fetch.
+            readOnly: dryRun,
         });
     }
     catch (err) {
@@ -279,21 +312,45 @@ async function fetchSingleTarget(url, run) {
         redirectedToGlobal,
         dryRun,
     });
-    if (!io.json) {
-        if (dryRun && cacheStatus !== 'hit' && cacheStatus !== 'stale') {
-            io.log('[dry-run] Preview only — cache was not written.');
-        }
-        for (const warning of extractionQualityWarnings(resultData.source.qualityNotes)) {
-            io.warn(`${normalizedUrl}: ${warning}`);
-        }
-        io.log(resultData.content);
-        const separator = batchSeparator(run.urlCount > 1);
-        if (separator) {
-            io.log(`\n${separator}\n`);
-        }
-    }
+    logHumanFetchResult({ io, resultData, cacheStatus, dryRun, normalizedUrl, run });
     return resultData;
 }
+/** True when this run launched Chrome on its own (no --rendered flag) to capture `url`, rather than
+ * just reporting a stored artifact's capture history from an earlier run (cache 'hit'/'stale'/
+ * 'revalidated'). Human mode uses this to decide whether the browser-fallback note would be accurate. */
+function usedAutomaticBrowserFallback(cacheStatus, captureMethod, rendered) {
+    const capturedThisRun = cacheStatus === 'miss' || cacheStatus === 'refreshed';
+    return capturedThisRun && captureMethod === 'browser_fallback' && !rendered;
+}
+/**
+ * Human-mode-only side effects for one fetch result: dry-run notice, the automatic browser-fallback
+ * note, extraction-quality warnings, the content itself, and the batch separator. No-op under
+ * `--json` (that output goes through the envelope instead).
+ */
+function logHumanFetchResult(input) {
+    const { io, resultData, cacheStatus, dryRun, normalizedUrl, run } = input;
+    if (io.json)
+        return;
+    if (dryRun && cacheStatus !== 'hit' && cacheStatus !== 'stale') {
+        io.log('[dry-run] Preview only — cache was not written.');
+    }
+    // Launching Chrome is real added latency and a real dependency that was otherwise invisible
+    // outside --json; an explicit --rendered already tells the caller a browser was used.
+    if (usedAutomaticBrowserFallback(cacheStatus, resultData.source.captureMethod, run.flags.rendered)) {
+        io.log('Note: used browser-rendered capture (static content was insufficient).');
+    }
+    for (const warning of extractionQualityWarnings(resultData.source.qualityNotes)) {
+        io.warn(`${normalizedUrl}: ${warning}`);
+    }
+    io.log(resultData.content);
+    if (!dryRun) {
+        io.warn(formatTip(`${io.bin} inspect ${normalizedUrl} for cached metadata.`));
+    }
+    const separator = batchSeparator(run.urlCount > 1);
+    if (separator) {
+        io.log(`\n${separator}\n`);
+    }
+}
 // Copies Phase 2 capability provenance from a capture outcome onto the artifact metadata.
 function applyCaptureMetadata(artifact, capture) {
     const meta = artifact.metadata;

package/dist/lib/research/fetcher.js

@@ -156,7 +156,9 @@ function notModifiedResult(res, currentUrl) {
 }
 function assertOk(res) {
     if (!res.ok) {
-        throw new Error(`Fetch failed with status ${res.status} ${res.statusText}`);
+        // statusText is often empty (e.g. HTTP/2 responses carry no reason phrase); trim so a
+        // reasonless status never leaves a dangling trailing space, matching browser.ts's assertOk.
+        throw new Error(`Fetch failed with status ${res.status} ${res.statusText}`.trimEnd());
     }
 }
 /**