@taurgis/bonsai 3.2.2 → 4.1.0

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

@@ -0,0 +1,71 @@
+import { artifactMatchesUrlFilter } from './url.js';
+/** 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").';
+}
+/**
+ * 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 function matchesCommonMetadataFilters(meta, freshness, flags) {
+    if (!matchesTopicFilter(meta, flags.topic))
+        return false;
+    if (!matchesTagsFilter(meta, flags.tags))
+        return false;
+    if (flags.url && !artifactMatchesUrlFilter(meta, flags.url))
+        return false;
+    if (flags.artifactType && meta.artifact_type !== flags.artifactType)
+        return false;
+    if (flags.captureMethod && meta.capture_method !== flags.captureMethod)
+        return false;
+    if (flags.freshness && freshness !== flags.freshness)
+        return false;
+    return true;
+}
+/**
+ * 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 function hasActiveMetadataFilters(flags) {
+    return Boolean(flags.topic ||
+        (flags.tags && flags.tags.length > 0) ||
+        flags.freshness ||
+        flags.artifactType ||
+        flags.captureMethod ||
+        flags.url);
+}

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/prompt-injection.d.ts

@@ -4,6 +4,7 @@
  * 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.
+ * @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;
@@ -159,10 +173,11 @@ function stripQuotes(span) {
  * 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.
+ * @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) => {
@@ -175,4 +190,5 @@ export function sanitizePromptInjection(markdown) {
         return lineRedacted === block ? redactBlock(block) : lineRedacted;
     })
         .join('');
+    return stripUnsafeControlChars(redacted);
 }

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

@@ -11,6 +11,8 @@ export type CaptureMethod = (typeof CAPTURE_METHODS)[number];
 export declare const ARTIFACT_TYPES: readonly ["source", "research_note", "index", "section"];
 /** Classification of a research artifact's role. */
 export type ArtifactType = (typeof ARTIFACT_TYPES)[number];
+/** Artifact types `list`/`search` report: every type except the heading-level `section` child. */
+export declare const PAGE_LEVEL_ARTIFACT_TYPES: ("source" | "research_note" | "index")[];
 /** Full metadata block stored alongside every cached research artifact. */
 export interface ResearchArtifactMetadata {
     schema_version: number;

package/dist/lib/research/schema.js

@@ -12,3 +12,7 @@ export const CAPTURE_METHODS = [
 // index; `section` = a heading-level child of a page. Command flag `options` derive from this.
 /** All recognized artifact types. `index` = navigation hub or llms.txt; `section` = heading-level child of a page. */
 export const ARTIFACT_TYPES = ['source', 'research_note', 'index', 'section'];
+// Shared by `list` and `search`: both report pages, never the `section` chunks a page is split
+// into (a single fetch can yield dozens) — `inspect` is where a page's sections are discoverable.
+/** Artifact types `list`/`search` report: every type except the heading-level `section` child. */
+export const PAGE_LEVEL_ARTIFACT_TYPES = ARTIFACT_TYPES.filter((type) => type !== 'section');

package/dist/lib/research/search-match.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Keyword scoring and snippet extraction for `search --query`. Matches only against fields already
+ * cheap to read from the search-index sidecar (topic, tags, summary, compressed) — see
+ * `artifact-index.ts` — so `search` never pays the cost of parsing the (often much larger)
+ * `detailed` body just to rank results.
+ */
+/** A field a query term can match against, in priority order (most to least specific). */
+export type SearchMatchField = 'topic' | 'tags' | 'summary' | 'compressed';
+/** Fields of an artifact that `search --query` matches against. */
+export interface SearchableFields {
+    topic: string | null;
+    tags: string[];
+    summary: string;
+    compressed: string;
+}
+/** Result of scoring one artifact against a tokenized query. */
+export interface SearchMatch {
+    score: number;
+    matchedFields: SearchMatchField[];
+}
+/** Split a `--query` value into lowercase, deduplicated terms on whitespace. */
+export declare function tokenizeSearchQuery(query: string): string[];
+/**
+ * Reject a whitespace-only `--query` instead of silently matching nothing (an empty term list would
+ * either match every artifact or none, both surprising) — same reasoning as `--topic`/`--tags`/`--url`.
+ */
+export declare function emptySearchQueryError(query: string | undefined): string | undefined;
+/**
+ * Scores one artifact against tokenized query terms. Returns `null` when the artifact does not
+ * satisfy the match mode (every term must match somewhere, unless `matchAny` allows just one).
+ */
+export declare function scoreSearchMatch(fields: SearchableFields, terms: readonly string[], matchAny: boolean): SearchMatch | null;
+/**
+ * A short excerpt around the first query-term match in `compressed` (falling back to `summary`),
+ * so an agent can judge relevance from the token-cheap index alone before deciding to `inspect` or
+ * re-fetch the full page. Returns `null` when no term appears in either — e.g. the match was only
+ * against `topic`/`tags` — rather than an unrelated excerpt with no bearing on the query.
+ */
+export declare function extractSearchSnippet(fields: Pick<SearchableFields, 'summary' | 'compressed'>, terms: readonly string[]): string | null;

package/dist/lib/research/search-match.js

@@ -0,0 +1,134 @@
+/**
+ * Keyword scoring and snippet extraction for `search --query`. Matches only against fields already
+ * cheap to read from the search-index sidecar (topic, tags, summary, compressed) — see
+ * `artifact-index.ts` — so `search` never pays the cost of parsing the (often much larger)
+ * `detailed` body just to rank results.
+ */
+/** Per-term score contribution when it matches the artifact's topic. */
+const SCORE_WEIGHT_TOPIC = 100;
+/** Per matching tag, per term. */
+const SCORE_WEIGHT_TAG = 50;
+/** Per occurrence in `summary`, per term (capped by {@link SUMMARY_OCCURRENCE_CAP}). */
+const SCORE_WEIGHT_SUMMARY = 10;
+/** Per occurrence in `compressed`, per term (capped by {@link COMPRESSED_OCCURRENCE_CAP}). */
+const SCORE_WEIGHT_COMPRESSED = 2;
+// Repeated boilerplate (e.g. a term that happens to be a common word in a large compressed body)
+// must not let one field dominate the score just by occurring many times; capping occurrences
+// counted keeps the topic/tag weights meaningfully dominant regardless of body length.
+const SUMMARY_OCCURRENCE_CAP = 5;
+const COMPRESSED_OCCURRENCE_CAP = 10;
+/** Characters of original-case text kept on each side of a matched term in an excerpt. */
+const SNIPPET_CONTEXT_CHARS = 90;
+/** Field priority order for a deterministic `matchedFields` list, independent of term iteration order. */
+const FIELD_PRIORITY = ['topic', 'tags', 'summary', 'compressed'];
+/** Split a `--query` value into lowercase, deduplicated terms on whitespace. */
+export function tokenizeSearchQuery(query) {
+    const terms = query
+        .trim()
+        .split(/\s+/)
+        .map((term) => term.toLowerCase());
+    return [...new Set(terms)];
+}
+/**
+ * Reject a whitespace-only `--query` instead of silently matching nothing (an empty term list would
+ * either match every artifact or none, both surprising) — same reasoning as `--topic`/`--tags`/`--url`.
+ */
+export function emptySearchQueryError(query) {
+    if (query === undefined)
+        return undefined;
+    if (query.trim() === '') {
+        return '--query must be a non-empty value (e.g. "suspense boundary").';
+    }
+    return undefined;
+}
+/** Count non-overlapping occurrences of `needle` in `haystack` (both already lowercased). */
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let fromIndex = 0;
+    let index;
+    while ((index = haystack.indexOf(needle, fromIndex)) !== -1) {
+        count++;
+        fromIndex = index + needle.length;
+    }
+    return count;
+}
+/**
+ * Scores one artifact against tokenized query terms. Returns `null` when the artifact does not
+ * satisfy the match mode (every term must match somewhere, unless `matchAny` allows just one).
+ */
+export function scoreSearchMatch(fields, terms, matchAny) {
+    const topicLower = (fields.topic ?? '').toLowerCase();
+    const tagsLower = fields.tags.map((tag) => tag.toLowerCase());
+    const summaryLower = fields.summary.toLowerCase();
+    const compressedLower = fields.compressed.toLowerCase();
+    let score = 0;
+    let matchedTermCount = 0;
+    const matchedFieldSet = new Set();
+    for (const term of terms) {
+        let termMatched = false;
+        if (topicLower.includes(term)) {
+            score += SCORE_WEIGHT_TOPIC;
+            matchedFieldSet.add('topic');
+            termMatched = true;
+        }
+        const tagHits = tagsLower.filter((tag) => tag.includes(term)).length;
+        if (tagHits > 0) {
+            score += SCORE_WEIGHT_TAG * tagHits;
+            matchedFieldSet.add('tags');
+            termMatched = true;
+        }
+        const summaryHits = Math.min(countOccurrences(summaryLower, term), SUMMARY_OCCURRENCE_CAP);
+        if (summaryHits > 0) {
+            score += SCORE_WEIGHT_SUMMARY * summaryHits;
+            matchedFieldSet.add('summary');
+            termMatched = true;
+        }
+        const compressedHits = Math.min(countOccurrences(compressedLower, term), COMPRESSED_OCCURRENCE_CAP);
+        if (compressedHits > 0) {
+            score += SCORE_WEIGHT_COMPRESSED * compressedHits;
+            matchedFieldSet.add('compressed');
+            termMatched = true;
+        }
+        if (termMatched)
+            matchedTermCount++;
+    }
+    const satisfied = matchAny ? matchedTermCount > 0 : matchedTermCount === terms.length;
+    if (!satisfied)
+        return null;
+    return { score, matchedFields: FIELD_PRIORITY.filter((field) => matchedFieldSet.has(field)) };
+}
+/** Earliest (leftmost) occurrence of any term in already-lowercased `textLower`, or `null`. */
+function findEarliestMatch(textLower, terms) {
+    let best = null;
+    for (const term of terms) {
+        const index = textLower.indexOf(term);
+        if (index !== -1 && (best === null || index < best.index)) {
+            best = { index, length: term.length };
+        }
+    }
+    return best;
+}
+/** Windowed excerpt of `text` around `match`, collapsed to one line with ellipsis on truncation. */
+function buildSnippetWindow(text, match) {
+    const start = Math.max(0, match.index - SNIPPET_CONTEXT_CHARS);
+    const end = Math.min(text.length, match.index + match.length + SNIPPET_CONTEXT_CHARS);
+    const windowed = text.slice(start, end).replace(/\s+/g, ' ').trim();
+    const prefix = start > 0 ? '…' : '';
+    const suffix = end < text.length ? '…' : '';
+    return `${prefix}${windowed}${suffix}`;
+}
+/**
+ * A short excerpt around the first query-term match in `compressed` (falling back to `summary`),
+ * so an agent can judge relevance from the token-cheap index alone before deciding to `inspect` or
+ * re-fetch the full page. Returns `null` when no term appears in either — e.g. the match was only
+ * against `topic`/`tags` — rather than an unrelated excerpt with no bearing on the query.
+ */
+export function extractSearchSnippet(fields, terms) {
+    const compressedMatch = findEarliestMatch(fields.compressed.toLowerCase(), terms);
+    if (compressedMatch)
+        return buildSnippetWindow(fields.compressed, compressedMatch);
+    const summaryMatch = findEarliestMatch(fields.summary.toLowerCase(), terms);
+    if (summaryMatch)
+        return buildSnippetWindow(fields.summary, summaryMatch);
+    return null;
+}

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

@@ -13,13 +13,10 @@ export declare function getArtifactPath(dataDir: string, key: string): string;
 /**
  * Scans the research storage directory, reading metadata of all valid markdown files
  * to find the active artifact for the given cache key with the newest validated_at timestamp.
- * If a corrupt artifact is found, it is skipped and archived as corrupt.
+ * If a corrupt artifact is found, it is skipped and archived as corrupt — unless `readOnly` is set,
+ * in which case it is only reported, never renamed on disk.
  */
-export declare function findArtifact(dataDir: string, key: string): ResearchArtifact | null;
-/**
- * Checks if a cached artifact exists on disk for a given cache key.
- */
-export declare function hasArtifact(dataDir: string, key: string): boolean;
+export declare function findArtifact(dataDir: string, key: string, readOnly?: boolean): ResearchArtifact | null;
 /**
  * Writes a ResearchArtifact to disk, creating the research storage folder if needed.
  * Writes to a temporary file first, then atomically renames it.
@@ -42,7 +39,7 @@ export interface LocatedArtifact {
  * returning the first match along with where it lives. Implements the project→global
  * read fallback: a missing project entry still resolves against the global cache.
  */
-export declare function locateArtifact(dataDirs: string[], key: string): LocatedArtifact | null;
+export declare function locateArtifact(dataDirs: string[], key: string, readOnly?: boolean): LocatedArtifact | null;
 /**
  * Multi-root variant of {@link scanCacheDir}. Scans the `research/` dir of each data dir in
  * order and deduplicates by cache key so an entry present in an earlier root (project) shadows

package/dist/lib/research/storage.js

@@ -18,7 +18,14 @@ export function scanCacheDir(dir, fn) {
             continue;
         try {
             const content = readFileSync(join(dir, file), 'utf-8');
-            const result = fn(parseArtifact(content), join(dir, file));
+            const artifact = parseArtifact(content);
+            // parseArtifact defaults unrecognized frontmatter to a valid-looking shell (cache_key: '',
+            // status: 'active'), so a foreign or otherwise-garbled *.md file with `---`/`---` fences never
+            // throws here — it would otherwise surface as a phantom entry with no usable cache key. Every
+            // artifact Bonsai itself writes always has one, so an empty cache_key means "not ours."
+            if (!artifact.metadata.cache_key)
+                continue;
+            const result = fn(artifact, join(dir, file));
             if (result !== null)
                 results.push(result);
         }
@@ -36,7 +43,7 @@ export function getArtifactPath(dataDir, key) {
     }
     return join(dataDir, 'research', `${key}.md`);
 }
-function processFileForLookup(file, dir, key) {
+function processFileForLookup(file, dir, key, readOnly) {
     // Same file filter as scanCacheDir — superseded/corrupt/tmp archives must not resolve as active.
     if (!isResearchFile(file)) {
         return null;
@@ -51,13 +58,17 @@ function processFileForLookup(file, dir, key) {
     }
     catch (err) {
         console.warn(`Warning: Corrupt research artifact found at "${filePath}": ${err.message}`);
-        try {
-            const corruptPath = `${filePath}.corrupt.${Date.now()}`;
-            renameSync(filePath, corruptPath);
-            console.warn(`Archived corrupt artifact to "${corruptPath}"`);
-        }
-        catch (archiveErr) {
-            console.error(`Failed to archive corrupt artifact: ${archiveErr.message}`);
+        // Archiving renames the file on disk — a write a read-only/plan-mode lookup (e.g. `status`,
+        // `inspect --read-only`) must never perform, even incidentally while diagnosing a corrupt entry.
+        if (!readOnly) {
+            try {
+                const corruptPath = `${filePath}.corrupt.${Date.now()}`;
+                renameSync(filePath, corruptPath);
+                console.warn(`Archived corrupt artifact to "${corruptPath}"`);
+            }
+            catch (archiveErr) {
+                console.error(`Failed to archive corrupt artifact: ${archiveErr.message}`);
+            }
         }
     }
     return null;
@@ -65,9 +76,10 @@ function processFileForLookup(file, dir, key) {
 /**
  * Scans the research storage directory, reading metadata of all valid markdown files
  * to find the active artifact for the given cache key with the newest validated_at timestamp.
- * If a corrupt artifact is found, it is skipped and archived as corrupt.
+ * If a corrupt artifact is found, it is skipped and archived as corrupt — unless `readOnly` is set,
+ * in which case it is only reported, never renamed on disk.
  */
-export function findArtifact(dataDir, key) {
+export function findArtifact(dataDir, key, readOnly = false) {
     const dir = join(dataDir, 'research');
     if (!existsSync(dir)) {
         return null;
@@ -76,7 +88,7 @@ export function findArtifact(dataDir, key) {
     let bestValidatedAt = -1;
     const files = readdirSync(dir);
     for (const file of files) {
-        const artifact = processFileForLookup(file, dir, key);
+        const artifact = processFileForLookup(file, dir, key, readOnly);
         if (!artifact) {
             continue;
         }
@@ -90,17 +102,6 @@ export function findArtifact(dataDir, key) {
     }
     return bestArtifact;
 }
-/**
- * Checks if a cached artifact exists on disk for a given cache key.
- */
-export function hasArtifact(dataDir, key) {
-    try {
-        return findArtifact(dataDir, key) !== null;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Writes a ResearchArtifact to disk, creating the research storage folder if needed.
  * Writes to a temporary file first, then atomically renames it.
@@ -149,9 +150,9 @@ export function readArtifact(dataDir, key) {
  * returning the first match along with where it lives. Implements the project→global
  * read fallback: a missing project entry still resolves against the global cache.
  */
-export function locateArtifact(dataDirs, key) {
+export function locateArtifact(dataDirs, key, readOnly = false) {
     for (const dataDir of dataDirs) {
-        const artifact = findArtifact(dataDir, key);
+        const artifact = findArtifact(dataDir, key, readOnly);
         if (artifact) {
             return { artifact, dataDir, path: getArtifactPath(dataDir, key) };
         }

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

@@ -0,0 +1,19 @@
+/** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
+export declare function scopeFlags(descriptions: {
+    global: string;
+    local: string;
+}): {
+    global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+/**
+ * Rejects `--global`/`--local` passed together. Shared by every command with this scope-flag pair
+ * (`config`, `setup`) so the guard, its message, and its error code can't drift between them.
+ *
+ * @param error - The command's own `this.error`, bound by the caller (it always throws, hence `never`).
+ */
+export declare function assertScopeFlagsExclusive(error: (message: string, options: {
+    exit: 2;
+    code: string;
+    suggestions: string[];
+}) => never, global: boolean | undefined, local: boolean | undefined): void;

package/dist/lib/scope-flags.js

@@ -0,0 +1,27 @@
+import { Flags } from '@oclif/core';
+/** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
+export function scopeFlags(descriptions) {
+    return {
+        global: Flags.boolean({ char: 'g', description: descriptions.global }),
+        local: Flags.boolean({
+            description: descriptions.local,
+            aliases: ['project'],
+            charAliases: ['p'],
+        }),
+    };
+}
+/**
+ * Rejects `--global`/`--local` passed together. Shared by every command with this scope-flag pair
+ * (`config`, `setup`) so the guard, its message, and its error code can't drift between them.
+ *
+ * @param error - The command's own `this.error`, bound by the caller (it always throws, hence `never`).
+ */
+export function assertScopeFlagsExclusive(error, global, local) {
+    if (global && local) {
+        error('--global and --local are mutually exclusive.', {
+            exit: 2,
+            code: 'CONFLICTING_FLAGS',
+            suggestions: ['Pass --global or --local, not both.'],
+        });
+    }
+}

package/dist/lib/setup/agents.d.ts

@@ -0,0 +1,16 @@
+import type { SetupAgent } from '../cli-result-types.js';
+/** Every agent `setup` currently knows how to install a SessionStart hook for. */
+export declare const SETUP_AGENTS: readonly SetupAgent[];
+/** Where a SessionStart hook lives for one agent, and how Bonsai's entry is shaped. */
+export interface SetupAgentTarget {
+    /** Hook-config file path, relative to the project root or the user's home directory. */
+    relativePath: string;
+    eventName: string;
+    matcher: string;
+    timeout: number;
+}
+/** Subcommand `setup` invokes at session start; appended to the resolved bin command. */
+export declare const SETUP_HOOK_COMMAND_SUFFIX = "context";
+/** Tag value stamped on every handler `setup` installs — see {@link SessionStartHookSpec.managedBy}. */
+export declare const SETUP_HOOK_MANAGED_BY = "bonsai";
+export declare const SETUP_AGENT_TARGETS: Record<SetupAgent, SetupAgentTarget>;

package/dist/lib/setup/agents.js

@@ -0,0 +1,20 @@
+/** Every agent `setup` currently knows how to install a SessionStart hook for. */
+export const SETUP_AGENTS = ['claude-code', 'codex'];
+// Both agents accept plain stdout as SessionStart context and share the same `source` matcher
+// values (startup/resume/clear/compact) — see the cached docs at
+// developers.openai.com/codex/hooks#sessionstart (.bonsai/research/4f69debe...) and
+// code.claude.com/docs/en/hooks (.bonsai/research/20106b0f3bee09dd540039d6a1a5294fbfbe0ae0b182affd4138cf3caa31e0c6.md,
+// imported rather than fetched — Bonsai's own fetch times out on this host in this environment).
+const SESSION_START = {
+    eventName: 'SessionStart',
+    matcher: 'startup|resume|clear|compact',
+    timeout: 10,
+};
+/** Subcommand `setup` invokes at session start; appended to the resolved bin command. */
+export const SETUP_HOOK_COMMAND_SUFFIX = 'context';
+/** Tag value stamped on every handler `setup` installs — see {@link SessionStartHookSpec.managedBy}. */
+export const SETUP_HOOK_MANAGED_BY = 'bonsai';
+export const SETUP_AGENT_TARGETS = {
+    'claude-code': { ...SESSION_START, relativePath: '.claude/settings.json' },
+    codex: { ...SESSION_START, relativePath: '.codex/hooks.json' },
+};

package/dist/lib/setup/bin-command.d.ts

@@ -0,0 +1,14 @@
+/** `which`/`where` lookup for a command name; `null` when not found on `PATH`. */
+export declare function findOnPath(command: string): string | null;
+/**
+ * Resolves the command a hook config should invoke to run this CLI (AXI rule: "hook commands
+ * should use a PATH-verified binary name when it resolves to the current executable, and fall
+ * back to the full absolute path otherwise"). This keeps a global install portable across
+ * machines while guaranteeing a hook never silently runs a different `bonsai` than the one that
+ * installed it.
+ *
+ * @param scriptPath - The currently running script (`process.argv[1]`).
+ * @param lookup - `PATH` lookup, injectable for tests.
+ * @returns `"bonsai"` when `PATH` resolves to this same script, otherwise `node "<absolute path>"`.
+ */
+export declare function resolveBinCommand(scriptPath: string, lookup?: typeof findOnPath): string;