@taurgis/bonsai 3.2.2 → 4.1.0

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/context-dashboard.d.ts

@@ -0,0 +1,19 @@
+import type { ContextDashboard } from '../cli-result-types.js';
+/** Entries beyond this count are still counted in `total`/`byFreshness`, just not listed. */
+export declare const CONTEXT_DASHBOARD_DEFAULT_LIMIT = 5;
+/**
+ * Builds the directory-scoped cache summary shown by `bonsai context` and injected by the
+ * `setup`-installed SessionStart hooks (AXI principle 7: ambient session-start context). Reuses
+ * the same scan/freshness primitives as `list` so the two commands can never disagree about what
+ * "active" or "fresh" means; unlike `list`, this applies no filters and always includes every
+ * matched artifact in `total`/`byFreshness`, previewing only the most recent `limit` in `entries`.
+ *
+ * @param readRoots - Data dirs to scan, in lookup order (see {@link loadStoreRoots}).
+ * @param currentTime - Clock used for freshness evaluation.
+ * @param options.limit - Max entries to preview; the count itself is never truncated.
+ * @param options.persistIndex - Whether to persist the search-index sidecar (false under read-only).
+ */
+export declare function buildContextDashboard(readRoots: string[], currentTime: Date, options?: {
+    limit?: number;
+    persistIndex?: boolean;
+}): ContextDashboard;

package/dist/lib/research/context-dashboard.js

@@ -0,0 +1,43 @@
+import { scanCacheDirs } from './storage.js';
+import { evaluateFreshness } from './freshness.js';
+/** Entries beyond this count are still counted in `total`/`byFreshness`, just not listed. */
+export const CONTEXT_DASHBOARD_DEFAULT_LIMIT = 5;
+/**
+ * Builds the directory-scoped cache summary shown by `bonsai context` and injected by the
+ * `setup`-installed SessionStart hooks (AXI principle 7: ambient session-start context). Reuses
+ * the same scan/freshness primitives as `list` so the two commands can never disagree about what
+ * "active" or "fresh" means; unlike `list`, this applies no filters and always includes every
+ * matched artifact in `total`/`byFreshness`, previewing only the most recent `limit` in `entries`.
+ *
+ * @param readRoots - Data dirs to scan, in lookup order (see {@link loadStoreRoots}).
+ * @param currentTime - Clock used for freshness evaluation.
+ * @param options.limit - Max entries to preview; the count itself is never truncated.
+ * @param options.persistIndex - Whether to persist the search-index sidecar (false under read-only).
+ */
+export function buildContextDashboard(readRoots, currentTime, options = {}) {
+    const limit = options.limit ?? CONTEXT_DASHBOARD_DEFAULT_LIMIT;
+    const rows = scanCacheDirs(readRoots, (artifact) => {
+        if (artifact.metadata.status !== 'active')
+            return null;
+        // Section children are sub-chunks of a page, not something a dashboard should list on its
+        // own — same exclusion `list` applies (see list.ts's scanCacheDirForList).
+        if (artifact.metadata.artifact_type === 'section')
+            return null;
+        return {
+            topic: artifact.metadata.topic,
+            sourceUrls: artifact.metadata.source_urls,
+            freshness: evaluateFreshness(artifact.metadata, currentTime, null),
+            recencyKey: artifact.metadata.validated_at ?? artifact.metadata.fetched_at ?? null,
+        };
+    }, { persistIndex: options.persistIndex ?? true });
+    rows.sort((a, b) => new Date(b.recencyKey ?? 0).getTime() - new Date(a.recencyKey ?? 0).getTime());
+    const byFreshness = { fresh: 0, stale_grace: 0, stale_expired: 0 };
+    for (const row of rows)
+        byFreshness[row.freshness]++;
+    const entries = rows.slice(0, limit).map((row) => ({
+        topic: row.topic,
+        sourceUrls: row.sourceUrls,
+        freshness: row.freshness,
+    }));
+    return { total: rows.length, byFreshness, shown: entries.length, entries };
+}

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,55 @@ 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);
+    // AXI content-truncation: only nudge toward the escape hatch when something was actually
+    // condensed — `detailedTokenEstimate` equals `tokenEstimate` whenever `format` is already
+    // `detailed`, or when compression happened to produce no smaller result.
+    if (resultData.format === 'compressed' &&
+        typeof resultData.tokenEstimate === 'number' &&
+        typeof resultData.detailedTokenEstimate === 'number' &&
+        resultData.detailedTokenEstimate > resultData.tokenEstimate) {
+        io.warn(formatTip(`${io.bin} ${normalizedUrl} --format detailed for the full ${resultData.detailedTokenEstimate}-token ` +
+            `version (currently showing ${resultData.tokenEstimate}).`));
+    }
+    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/fetch-result.d.ts

@@ -57,6 +57,7 @@ export declare function buildFetchResultData(input: FetchResultInput): {
     searchProvider: string | null;
     format: "compressed" | "detailed";
     tokenEstimate: number | null;
+    detailedTokenEstimate: number | null;
     content: string;
 };
 export interface FetchFailureGuidance {

package/dist/lib/research/fetch-result.js

@@ -75,6 +75,10 @@ export function buildFetchResultData(input) {
         tokenEstimate: format === 'compressed'
             ? artifact.metadata.token_estimate.compressed
             : artifact.metadata.token_estimate.detailed,
+        // Always the true detailed count, even when `format` is `compressed` (AXI content-truncation
+        // principle: show the total size so the agent knows how much a `--format detailed` re-fetch
+        // would add, without a second round trip). Equals `tokenEstimate` when nothing was truncated.
+        detailedTokenEstimate: artifact.metadata.token_estimate.detailed,
         content,
     };
 }

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());
     }
 }
 /**

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

@@ -5,6 +5,7 @@ import { loadSummaryLevel } from '../config/index.js';
 import { buildCompressed } from './compress.js';
 import { durationFlagError, resolveFreshnessPolicy } from './freshness.js';
 import { applyAutoTags } from './keywords.js';
+import { metadataLengthError, metadataNewlineError } from './metadata-flags.js';
 import { persistArtifact } from './persist-artifact.js';
 import { sanitizePromptInjection } from './prompt-injection.js';
 import { getArtifactPath } from './storage.js';
@@ -14,6 +15,7 @@ import { deriveCacheKey } from './cache-key.js';
 import { normalizeUrl } from './url.js';
 import { failInvalidUrl } from './cli-io.js';
 import { formatHumanFields } from '../cli-presentation.js';
+import { sanitizeForTerminal } from '../text.js';
 const INPUT_LIMIT_BYTES = 1024 * 1024;
 // ponytail: 1s stdin idle timeout is enough for piped agent input; raise if interactive paste
 // workflows need longer before the read aborts.
@@ -29,6 +31,22 @@ export async function prepareImportCommandService(opts) {
     const ttlErr = durationFlagError('--ttl', flags.ttl);
     if (ttlErr)
         io.error(ttlErr, { 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.'],
+        });
+    }
     validateSourceMode(hasSingle, hasMulti, flags, io);
     const rawInput = await readAndValidateInput(flags, input, io);
     const sourceUrls = getSourceUrls(hasMulti, flags.sourceUrls, args.url, io);
@@ -128,9 +146,12 @@ function logImportHumanSuccess(io, opts) {
         ['Cache Key', cacheKey],
         ['Storage Path', storagePath],
     ];
+    // The agent-supplied --topic is untrusted the same way fetched content is (it may be lifted
+    // straight from a page an agent just read), so it gets the same terminal sanitization as
+    // list/inspect/prune apply to a cached topic before printing it.
     let topic;
     if (!hasSingle) {
-        topic = resolvedTopic(flags);
+        topic = sanitizeForTerminal(resolvedTopic(flags));
         fields.push(['Topic', topic], ['Source URLs', sourceUrls.join(', ')]);
     }
     for (const line of formatHumanFields(fields))

package/dist/lib/research/list-row.d.ts

@@ -0,0 +1,15 @@
+import type { ListFreshness, ListRow } from '../cli-result-types.js';
+import type { ResearchArtifact } from './schema.js';
+/**
+ * Maps a parsed artifact to the shared page-level row shape (`ListRow`) that `list` and `search`
+ * both return — single source of truth so the two commands' JSON row schemas can never drift on
+ * which metadata fields a "row" exposes.
+ */
+export declare function toListRow(artifact: ResearchArtifact, filePath: string, freshness: ListRow['freshness']): ListRow;
+/**
+ * Counts rows per freshness tier for the `list`/`search` envelope's `summary.byFreshness` — single
+ * source of truth so the two commands' aggregate always agree on the shape and the counting logic.
+ */
+export declare function countByFreshness(rows: readonly {
+    freshness: ListFreshness;
+}[]): Record<ListFreshness, number>;

package/dist/lib/research/list-row.js

@@ -0,0 +1,31 @@
+/**
+ * Maps a parsed artifact to the shared page-level row shape (`ListRow`) that `list` and `search`
+ * both return — single source of truth so the two commands' JSON row schemas can never drift on
+ * which metadata fields a "row" exposes.
+ */
+export function toListRow(artifact, filePath, freshness) {
+    return {
+        cacheKey: artifact.metadata.cache_key,
+        path: filePath,
+        artifactType: artifact.metadata.artifact_type,
+        sourceUrls: artifact.metadata.source_urls,
+        topic: artifact.metadata.topic,
+        tags: artifact.metadata.tags,
+        freshness,
+        captureMethod: artifact.metadata.capture_method,
+        tokenEstimate: artifact.metadata.token_estimate,
+        qualityNotes: artifact.metadata.quality_notes,
+        fetchedAt: artifact.metadata.fetched_at,
+        validatedAt: artifact.metadata.validated_at,
+    };
+}
+/**
+ * Counts rows per freshness tier for the `list`/`search` envelope's `summary.byFreshness` — single
+ * source of truth so the two commands' aggregate always agree on the shape and the counting logic.
+ */
+export function countByFreshness(rows) {
+    const counts = { fresh: 0, stale_grace: 0, stale_expired: 0 };
+    for (const row of rows)
+        counts[row.freshness]++;
+    return counts;
+}

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

@@ -0,0 +1,39 @@
+import type { ArtifactType, CaptureMethod, 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;
+/** The metadata filter flags `list` and `search` both expose, beyond content/topic search. */
+export interface CommonMetadataFilterFlags {
+    topic?: string;
+    tags?: string[];
+    url?: string;
+    artifactType?: ArtifactType;
+    captureMethod?: CaptureMethod;
+    freshness?: 'fresh' | 'stale_grace' | 'stale_expired';
+}
+/**
+ * Shared page-level metadata filter combinator for `list` and `search` (topic/tags/url/artifact
+ * type/capture method/freshness) — single source of truth so the two commands can never drift on
+ * what "matches the given filters" means.
+ */
+export declare function matchesCommonMetadataFilters(meta: ResearchArtifactMetadata, freshness: 'fresh' | 'stale_grace' | 'stale_expired', flags: CommonMetadataFilterFlags): boolean;
+/**
+ * Whether any of the shared metadata filter flags was passed — used to pick empty-result guidance
+ * ("no matches for your filters" vs. "the cache is empty"). `search` combines this with its own
+ * `--query` check; `list` has no filters beyond these, so it uses the result directly.
+ */
+export declare function hasActiveMetadataFilters(flags: CommonMetadataFilterFlags): boolean;