@taurgis/bonsai 1.0.3 → 1.0.5

package/dist/commands/config/list.js

@@ -1,9 +1,9 @@
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { ALL_KEYS, KEY_META, BUILT_IN_DEFAULTS, readScopedConfig } from '../../lib/config/index.js';
+import { ALL_KEYS, KEY_META, BUILT_IN_DEFAULTS, readScopedConfig, validKeysHint, } from '../../lib/config/index.js';
 export default class ConfigList extends ConfigCommand {
     static id = 'config list';
     static summary = 'List all research configuration keys and their effective values.';
-    static description = 'Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: storage.';
+    static description = `Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: ${validKeysHint()}.`;
     static examples = [
         {
             description: 'Show all effective config values',

package/dist/commands/config/set.js

@@ -1,11 +1,11 @@
 import { Args, Flags } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { KEY_META, writeUserConfig, writeProjectConfig } from '../../lib/config/index.js';
+import { KEY_META, writeUserConfig, writeProjectConfig, validKeysHint, } from '../../lib/config/index.js';
 export default class ConfigSet extends ConfigCommand {
     static id = 'config set';
     static summary = 'Set a research configuration key.';
     static description = 'Persist a configuration value. Writes user-level config by default; pass --local to write the project-level config (.bonsai.json in cwd).\n\n' +
-        'Valid keys: storage. The inline form `<key>=<value>` is also accepted.';
+        `Valid keys: ${validKeysHint()}. The inline form \`<key>=<value>\` is also accepted.`;
     static examples = [
         {
             description: 'Store research cache inside the current project',

package/dist/commands/config/unset.js

@@ -1,10 +1,10 @@
 import { Args, Flags } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { writeUserConfig, writeProjectConfig } from '../../lib/config/index.js';
+import { writeUserConfig, writeProjectConfig, validKeysHint } from '../../lib/config/index.js';
 export default class ConfigUnset extends ConfigCommand {
     static id = 'config unset';
     static summary = 'Remove a research configuration key.';
-    static description = 'Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: storage.';
+    static description = `Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: ${validKeysHint()}.`;
     static examples = [
         {
             description: 'Remove the user-level storage setting',

package/dist/commands/fetch.d.ts

@@ -30,8 +30,13 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
     private executeCacheMiss;
     private buildResultData;
     private validateDurationFlags;
+    private emitFetchError;
     private resolveArtifact;
     private persistFreshArtifact;
     private persistSectionsIfFresh;
     run(): Promise<unknown>;
 }
+export declare function fetchFailureGuidance(message: string, url: string): {
+    suggestions: string[];
+    ref?: string;
+} | undefined;

package/dist/commands/fetch.js

@@ -5,13 +5,15 @@ import { join } from 'node:path';
 import { BaseCommand } from '../base-command.js';
 import { writeArtifact, getArtifactPath } from '../lib/research/storage.js';
 import { writeArtifactSecurely } from '../lib/research/secure-write.js';
-import { evaluateFreshness, parseTtlToMs, checkMaxAgeExpired } from '../lib/research/freshness.js';
+import { loadSummaryLevel } from '../lib/config/index.js';
+import { evaluateFreshness, checkMaxAgeExpired, durationFlagError, } from '../lib/research/freshness.js';
 import { revalidateCache, createArtifactFromFetch } from '../lib/research/revalidate.js';
 import { fetchStaticHtml, fetchText } from '../lib/research/fetcher.js';
 import { fetchRenderedHtml } from '../lib/research/browser.js';
 import { capturePage } from '../lib/research/capture.js';
 import { persistSectionArtifacts } from '../lib/research/docs/section-artifacts.js';
 import { resolveResearchTarget } from '../lib/research/resolve-target.js';
+import { applyAutoTags } from '../lib/research/keywords.js';
 import { detectSite } from '../sites/index.js';
 const CAPTURE_DEPS = {
     fetchStatic: (url) => fetchStaticHtml(url),
@@ -22,7 +24,7 @@ export default class FetchCommand extends BaseCommand {
     static id = 'fetch';
     static hidden = true;
     static summary = 'An advanced, locally cached web research tool optimized for LLM ingestion.';
-    static description = 'Scrapes the specified URL, strips HTML boilerplate, converts the semantic payload into clean Markdown format, and caches the result locally using dynamic TTL rules.';
+    static description = 'Scrapes the specified URL, strips HTML boilerplate, converts the semantic payload into clean Markdown format, and caches the result locally using dynamic TTL rules.\n\nUsually invoked via the shorthand `bonsai <url>` rather than `bonsai fetch <url>`.';
     static examples = [
         {
             description: 'Research a URL with detailed output, tagged with topic and tags',
@@ -62,7 +64,7 @@ export default class FetchCommand extends BaseCommand {
         })(),
         ttl: Flags.string({
             char: 'l',
-            description: 'Predicted lifespan of the data (e.g., "2h", "7d", "3m").',
+            description: 'Predicted lifespan: number + h/d/w/m/y (m = months), e.g. "2h", "7d", "6m".',
         }),
         'max-age': Flags.string({
             description: 'Maximum age of cache to accept (e.g., "1d", "30d").',
@@ -92,7 +94,7 @@ export default class FetchCommand extends BaseCommand {
     envelopeCommandId() {
         return this.config.bin;
     }
-    async executeCacheHit(cached, targetDir, currentTime) {
+    async executeCacheHit(cached, targetDir, currentTime, summaryLevel) {
         const { ttl, 'max-age': maxAge, 'allow-stale': allowStale, rendered } = this.flags;
         const isExpired = checkMaxAgeExpired(cached, currentTime, maxAge);
         const freshnessState = isExpired
@@ -105,6 +107,7 @@ export default class FetchCommand extends BaseCommand {
             allowStale: Boolean(allowStale),
             ttlOverride: ttl,
             rendered: Boolean(rendered),
+            summaryLevel,
         });
         handleStaleRevalidationResult(this, revalResult);
         return {
@@ -113,7 +116,7 @@ export default class FetchCommand extends BaseCommand {
             artifact: revalResult.artifact,
         };
     }
-    async executeCacheMiss(normalizedUrl, currentTime, cacheKey) {
+    async executeCacheMiss(normalizedUrl, currentTime, cacheKey, summaryLevel) {
         const { topic, tags, tier, ttl, rendered } = this.flags;
         const siteModule = detectSite(normalizedUrl);
         const useRendered = rendered || Boolean(siteModule?.defaults?.rendered);
@@ -129,7 +132,7 @@ export default class FetchCommand extends BaseCommand {
             fetchResult = capture.fetchResult;
             extraction = capture.extraction;
         }
-        const artifact = createArtifactFromFetch(normalizedUrl, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl || null, currentTime);
+        const artifact = createArtifactFromFetch(normalizedUrl, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl || null, currentTime, summaryLevel);
         artifact.metadata.topic = topic || null;
         artifact.metadata.tags = tags || [];
         artifact.metadata.site_module_id = siteModule?.id ?? null;
@@ -139,7 +142,9 @@ export default class FetchCommand extends BaseCommand {
         else if (useRendered) {
             artifact.metadata.capture_method = 'browser_fallback';
         }
-        return artifact;
+        // Auto-tag from the fetched content when the caller supplied none, keeping cached pages
+        // searchable by keyword. Explicit --tags always win (handled in applyAutoTags).
+        return applyAutoTags(artifact);
     }
     buildResultData(url, normalizedUrl, cacheKey, storageDir, storageMode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal) {
         return {
@@ -178,36 +183,41 @@ export default class FetchCommand extends BaseCommand {
     }
     // Validates the duration flags up front, exiting with code 2 on a malformed value.
     validateDurationFlags(ttl, maxAge) {
-        for (const [label, value] of [
-            ['TTL', ttl],
-            ['max-age', maxAge],
-        ]) {
-            if (!value)
-                continue;
-            try {
-                parseTtlToMs(value);
-            }
-            catch (err) {
-                this.error(`Invalid ${label}: ${err.message}`, { exit: 2 });
-            }
+        for (const msg of [durationFlagError('--ttl', ttl), durationFlagError('--max-age', maxAge)]) {
+            if (msg)
+                this.error(msg, { exit: 2 });
         }
     }
+    // Re-emit a runtime fetch failure with actionable next steps. Deep fetch/extract code throws plain
+    // Errors that otherwise reach the user as a bare "what broke" line with no "what to do"; this
+    // attaches recovery hints (e.g. import an auth-blocked page). Everything reaching here is a runtime
+    // failure — validation errors (bad flags/URL) exit before the try — so the contract's runtime code
+    // (1) applies. Suggestions render on stderr for humans only; under --json the envelope carries just
+    // the message (toErrorJson), so machine output is unchanged.
+    emitFetchError(err, url) {
+        const message = err instanceof Error ? err.message : String(err);
+        const guidance = fetchFailureGuidance(message, url);
+        this.error(message, { exit: 1, suggestions: guidance?.suggestions, ref: guidance?.ref });
+    }
     // Serves the cache when a fresh/revalidatable entry exists, otherwise fetches fresh. Reads fall
     // back project→global; the resolved artifact is returned with the dir it lives in / landed in.
-    async resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located) {
+    async resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located, summaryLevel) {
         if (located) {
             // Revalidate where the entry already lives; on dry-run use the throwaway dir so the cache is
             // never mutated. ponytail: revalidation rewrites in place, so a refreshed project entry that
             // gains a secret is not re-routed — only first-time project writes are scanned.
             const revalDir = tmpDir ?? located.dataDir;
-            const hit = await this.executeCacheHit(located.artifact, revalDir, currentTime);
+            const hit = await this.executeCacheHit(located.artifact, revalDir, currentTime, summaryLevel);
             return { ...hit, storageDir: located.dataDir, redirectedToGlobal: false };
         }
-        const artifact = await this.executeCacheMiss(normalizedUrl, currentTime, cacheKey);
+        const artifact = await this.executeCacheMiss(normalizedUrl, currentTime, cacheKey, summaryLevel);
         const { dir, redirectedToGlobal } = this.persistFreshArtifact(roots, tmpDir, cacheKey, artifact);
+        // No entry existed at lookup, so there is no prior freshness to report. 'none' (not
+        // 'stale_expired') keeps the field honest — nothing expired; the page was simply uncached and
+        // has now been fetched fresh. Mirrors the `status` command's miss reporting.
         return {
             cacheStatus: 'miss',
-            freshnessState: 'stale_expired',
+            freshnessState: 'none',
             artifact,
             storageDir: dir,
             redirectedToGlobal,
@@ -230,11 +240,11 @@ export default class FetchCommand extends BaseCommand {
     }
     // Long references are split into searchable/inspectable section children whenever the page artifact
     // is freshly written (T-22). Best-effort: never let chunking break the main result.
-    persistSectionsIfFresh(targetDir, artifact, currentTime, cacheStatus) {
+    persistSectionsIfFresh(targetDir, artifact, currentTime, cacheStatus, summaryLevel) {
         if (cacheStatus !== 'miss' && cacheStatus !== 'refreshed')
             return;
         try {
-            persistSectionArtifacts(targetDir, artifact, currentTime);
+            persistSectionArtifacts(targetDir, artifact, currentTime, summaryLevel);
         }
         catch {
             /* section generation is non-essential; ignore failures */
@@ -259,11 +269,12 @@ export default class FetchCommand extends BaseCommand {
             this.error(`Invalid URL: ${err.message}`, { exit: 2 });
         }
         const { cacheKey, located, normalizedUrl, roots } = target;
+        const summaryLevel = loadSummaryLevel(this.config.configDir, process.cwd());
         const tmpDir = dryRun ? mkdtempSync(join(tmpdir(), 'fnr-dry-run-')) : null;
         const currentTime = new Date();
         try {
-            const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await this.resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located);
-            this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, cacheStatus);
+            const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await this.resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located, summaryLevel);
+            this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, cacheStatus, summaryLevel);
             const content = format === 'compressed' ? artifact.compressed : artifact.detailed;
             const resultData = this.buildResultData(url, normalizedUrl, cacheKey, storageDir, roots.mode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal);
             if (!this.jsonEnabled()) {
@@ -271,6 +282,13 @@ export default class FetchCommand extends BaseCommand {
             }
             return resultData;
         }
+        catch (err) {
+            // Stale-serve (exit 5) signals via process.exitCode and never throws, so it bypasses this
+            // path; only genuine fetch/extract failures land here and get classified guidance. Use the
+            // normalized URL in hints so the copy-paste command is canonical (and never echoes raw,
+            // unsanitized user input back to the terminal).
+            this.emitFetchError(err, normalizedUrl);
+        }
         finally {
             if (tmpDir) {
                 rmSync(tmpDir, { recursive: true, force: true });
@@ -278,6 +296,59 @@ export default class FetchCommand extends BaseCommand {
         }
     }
 }
+// Maps a runtime fetch failure to recovery steps keyed off its message. Returns undefined for
+// unrecognized failures, which then surface with their original message and no extra hint. The
+// patterns match the thrown text in fetcher.ts/browser.ts; keep them in sync if those messages
+// change. Resolutions mirror the published troubleshooting guide.
+export function fetchFailureGuidance(message, url) {
+    const ref = 'https://taurgis.github.io/bonsai/troubleshooting';
+    // Name the pipe step explicitly: bare `import --stdin` blocks waiting for input, so a reader (or
+    // an agent) running the hint verbatim would hang. Show the content being piped in from a file.
+    const importHint = `Open it in a browser, save the page, then import it: cat page.md | bonsai import ${url} --stdin`;
+    // 401/403: an auth wall or anti-scraping WAF. Bonsai has no authenticated-fetch path in v1.
+    if (/failed with status 40[13]\b/.test(message)) {
+        return {
+            suggestions: ['The page requires authentication or blocks automated requests.', importHint],
+            ref,
+        };
+    }
+    if (/failed with status 404\b/.test(message)) {
+        return { suggestions: ['Check the URL is correct and the page still exists.'] };
+    }
+    if (/failed with status 5\d\d\b/.test(message)) {
+        return {
+            suggestions: ['The server returned an error. Retry later or verify the host is healthy.'],
+        };
+    }
+    // Server returned a non-HTML body (JSON, binary, or no Content-Type at all). Scope the opener to
+    // the real failure: --rendered does produce HTML, so "only scrapes HTML" would read as misleading.
+    if (/Rejected content type|does not look like HTML/.test(message)) {
+        return {
+            suggestions: [
+                'The server returned a non-HTML response (e.g. JSON or binary).',
+                'If the page is rendered by client-side JavaScript, retry with --rendered.',
+                importHint,
+            ],
+            ref,
+        };
+    }
+    if (/DNS resolution failed/.test(message)) {
+        return {
+            suggestions: ['Check the hostname is spelled correctly and resolves on a public network.'],
+        };
+    }
+    // A hostname that only resolves to a private/local IP at request time (literal private addresses
+    // are rejected earlier with exit 2). Blocked to prevent SSRF; only public hosts can be fetched.
+    if (/blocked local or private target/.test(message)) {
+        return {
+            suggestions: [
+                'The hostname resolves to a private or local address, which is blocked to prevent SSRF. Only public http(s) hosts can be fetched.',
+            ],
+            ref,
+        };
+    }
+    return undefined;
+}
 // Copies Phase 2 capability provenance from a capture outcome onto the artifact metadata.
 function applyCaptureMetadata(artifact, capture) {
     const meta = artifact.metadata;

package/dist/commands/import.d.ts

@@ -23,6 +23,7 @@ export default class ResearchImport extends BaseCommand<typeof ResearchImport> {
         storage: import("@oclif/core/interfaces").OptionFlag<"global" | "project" | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
+    protected stdinIsInteractive(): boolean;
     private readStdin;
     private getSourceUrls;
     private validateSourceMode;

package/dist/commands/import.js

@@ -1,4 +1,4 @@
-import { Args, Flags } from '@oclif/core';
+import { Args, Errors, Flags } from '@oclif/core';
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -8,8 +8,10 @@ import { deriveCacheKey } from '../lib/research/cache-key.js';
 import { getArtifactPath } from '../lib/research/storage.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
 import { writeArtifactSecurely } from '../lib/research/secure-write.js';
+import { loadSummaryLevel } from '../lib/config/index.js';
 import { getPolicy } from '../lib/research/freshness.js';
-import { compressMarkdown } from '../lib/research/compress.js';
+import { buildCompressed } from '../lib/research/compress.js';
+import { applyAutoTags } from '../lib/research/keywords.js';
 import { estimateTokens } from '../lib/research/token-estimate.js';
 export default class ResearchImport extends BaseCommand {
     static id = 'import';
@@ -32,6 +34,10 @@ export default class ResearchImport extends BaseCommand {
     static args = {
         url: Args.string({
             required: false,
+            // oclif fills an omitted optional arg from piped stdin unless ignoreStdin is set. Without
+            // this, the Markdown piped for `--stdin` is swallowed into `url`, making multi-source import
+            // (`import --stdin --source-url ...`) wrongly look like it also got a positional URL.
+            ignoreStdin: true,
             description: 'The single source URL of the page (only for single-source import).',
         }),
     };
@@ -76,6 +82,11 @@ export default class ResearchImport extends BaseCommand {
         })(),
     };
     static stdoutIsPrimaryData = true;
+    // Isolated so tests can force the interactive branch; `isTTY` is `true` only on a real terminal and
+    // falsy (undefined) for pipes, files, and /dev/null. See https://nodejs.org/api/process.html#processstdin
+    stdinIsInteractive() {
+        return process.stdin.isTTY === true;
+    }
     async readStdin(limitBytes = 1024 * 1024) {
         return new Promise((resolve, reject) => {
             let data = '';
@@ -162,16 +173,34 @@ export default class ResearchImport extends BaseCommand {
     }
     async readAndValidateInput() {
         if (this.flags.stdin) {
+            // On an interactive terminal with nothing piped, reading stdin blocks forever waiting for EOF —
+            // a silent hang with no feedback. Fail fast with a usage error instead; piped/redirected input
+            // (the agent and CI path) has isTTY falsy and reads normally.
+            if (this.stdinIsInteractive()) {
+                this.error('No data piped to --stdin.', {
+                    exit: 2,
+                    suggestions: [
+                        'Pipe Markdown content, e.g. cat notes.md | bonsai import <url> --stdin',
+                        'Or read from a file: bonsai import <url> --file notes.md',
+                    ],
+                });
+            }
+            // Initialized so the post-catch read below never depends on this.error()'s `never` return type
+            // for definite assignment; the empty-content guard rejects '' as a usage error anyway.
+            let rawInput = '';
             try {
-                const rawInput = await this.readStdin();
-                if (!rawInput.trim()) {
-                    this.error('Empty stdin content provided.', { exit: 2 });
-                }
-                return rawInput;
+                rawInput = await this.readStdin();
             }
             catch (err) {
+                // Genuine stream/size failure reading stdin → I/O failure (exit 1).
                 this.error(err.message, { exit: 1 });
             }
+            // Empty input is a usage error (exit 2), not an I/O failure — keep it out of the
+            // catch above so its exit code is not clobbered to 1.
+            if (!rawInput.trim()) {
+                this.error('Empty stdin content provided.', { exit: 2 });
+            }
+            return rawInput;
         }
         if (this.flags.file) {
             const filePath = path.resolve(this.flags.file);
@@ -179,6 +208,11 @@ export default class ResearchImport extends BaseCommand {
                 return this.readAndValidateFile(filePath);
             }
             catch (err) {
+                // readAndValidateFile raises usage errors (missing/not-a-file/empty) via this.error,
+                // which throw CLIErrors carrying their own exit code and message — preserve those.
+                // Only an unexpected read failure becomes a wrapped I/O failure (exit 1).
+                if (err instanceof Errors.CLIError)
+                    throw err;
                 this.error(`Failed to read file: ${err.message}`, { exit: 1 });
             }
         }
@@ -200,7 +234,11 @@ export default class ResearchImport extends BaseCommand {
         const staleAfterTime = new Date(currentTime.getTime() + freshWindowMs);
         const inputFormat = this.flags['input-format'];
         const detailed = rawInput;
-        const compressed = inputFormat === 'detailed' ? compressMarkdown(rawInput) : rawInput;
+        // A caller-supplied compressed input is trusted as-is; only a detailed import is condensed here,
+        // and it shares the same buildCompressed policy (structural pass + extractive fallback) as fetch.
+        const compressed = inputFormat === 'detailed'
+            ? buildCompressed(rawInput, loadSummaryLevel(this.config.configDir, process.cwd()))
+            : rawInput;
         const contentHash = createHash('sha256').update(detailed).digest('hex');
         const metadata = {
             schema_version: 1,
@@ -240,13 +278,15 @@ export default class ResearchImport extends BaseCommand {
             section_anchor: null,
             section_heading_path: null,
         };
-        return {
+        // Auto-tag from the content when the caller supplied none, so imported notes stay searchable by
+        // keyword without forcing manual tagging. Explicit --tags always win (handled in applyAutoTags).
+        return applyAutoTags({
             metadata,
             summary: `Synthesized research for ${hasSingle ? singleNormalizedUrl : this.flags.topic}`,
             compressed,
             detailed,
             provenance: `Imported via agent-supplied research at ${currentTime.toISOString()}`,
-        };
+        });
     }
     async run() {
         const hasSingle = Boolean(this.args.url);
@@ -292,7 +332,7 @@ export default class ResearchImport extends BaseCommand {
                 captureMethod: 'agent_supplied',
                 extractionStatus: 'agent_supplied',
                 extractionConfidence: 'high',
-                qualityNotes: ['agent-supplied research import'],
+                qualityNotes: artifact.metadata.quality_notes,
                 fetchedAt: null,
                 validatedAt: artifact.metadata.validated_at,
                 staleAfter: artifact.metadata.stale_after,

package/dist/commands/list.js

@@ -3,6 +3,9 @@ import { BaseCommand } from '../base-command.js';
 import { scanCacheDirs } from '../lib/research/storage.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
 import { evaluateFreshness } from '../lib/research/freshness.js';
+import { resultListHeading, truncationNotice } from '../lib/text.js';
+// Listings are ordered newest-first, so the truncation word is "first"; --limit caps at 100.
+const LIST_LABELS = { noun: 'cached research', order: 'first', maxLimit: 100 };
 export default class ResearchList extends BaseCommand {
     static id = 'list';
     static summary = 'List cached research artifacts by metadata filters.';
@@ -82,6 +85,12 @@ export default class ResearchList extends BaseCommand {
         return scanCacheDirs(readRoots, (artifact, filePath) => {
             if (artifact.metadata.status !== 'active')
                 return null;
+            // Section children are sub-chunks of a page, not artifacts a user "has" — they would flood the
+            // listing (one page yields dozens) and aren't in the documented source/research_note contract.
+            // They stay discoverable through `search` (which ranks them) and `inspect` (which lists a
+            // page's sections). `list` answers "what pages/notes do I have?", so keep it page-level.
+            if (artifact.metadata.artifact_type === 'section')
+                return null;
             const freshness = evaluateFreshness(artifact.metadata, currentTime, null);
             if (!this.matchesFilters(artifact.metadata, freshness))
                 return null;
@@ -101,14 +110,14 @@ export default class ResearchList extends BaseCommand {
             };
         });
     }
-    logListResults(finalResults) {
+    logListResults(finalResults, totalMatched) {
         if (this.jsonEnabled())
             return;
         if (finalResults.length === 0) {
             this.log('No cached research entries found matching filters.');
             return;
         }
-        this.log(`Found ${finalResults.length} cached research entries:\n`);
+        this.log(`${resultListHeading(totalMatched, finalResults.length, LIST_LABELS)}\n`);
         finalResults.forEach((res, index) => {
             this.log(`${index + 1}. [${res.topic || 'No Topic'}] Key: ${res.cacheKey}`);
             this.log(`   Type: ${res.artifactType} | Freshness: ${res.freshness}`);
@@ -132,7 +141,13 @@ export default class ResearchList extends BaseCommand {
             return timeB - timeA;
         });
         const finalResults = results.slice(0, this.flags.limit);
-        this.logListResults(finalResults);
+        // Under --json the human heading is suppressed, so surface truncation on stderr instead (warn
+        // always emits, even in --json) without touching the stdout envelope. Human mode already shows
+        // it in the heading, so only warn under --json.
+        const notice = truncationNotice(results.length, finalResults.length, LIST_LABELS);
+        if (notice && this.jsonEnabled())
+            this.warn(notice);
+        this.logListResults(finalResults, results.length);
         return finalResults;
     }
 }

package/dist/commands/prune.js

@@ -4,7 +4,8 @@ import { join } from 'node:path';
 import { BaseCommand } from '../base-command.js';
 import { scanCacheDir } from '../lib/research/storage.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
-import { parseTtlToMs } from '../lib/research/freshness.js';
+import { parseTtlToMs, durationFlagError } from '../lib/research/freshness.js';
+import { pluralize } from '../lib/text.js';
 export default class ResearchPrune extends BaseCommand {
     static id = 'prune';
     static summary = 'Clean up old or inactive research cache entries.';
@@ -48,6 +49,15 @@ export default class ResearchPrune extends BaseCommand {
         if (!this.flags['dry-run'] && !this.flags.yes) {
             this.error('Safety check: Please specify --yes to confirm pruning, or --dry-run to list files that would be deleted.', { exit: 2 });
         }
+        // Validate durations up front: scanCacheDir swallows per-file errors, so a malformed
+        // --older-than/--inactive would otherwise be silently ignored and report "0 entries".
+        for (const msg of [
+            durationFlagError('--older-than', this.flags['older-than']),
+            durationFlagError('--inactive', this.flags.inactive),
+        ]) {
+            if (msg)
+                this.error(msg, { exit: 2 });
+        }
     }
     shouldPrune(meta, currentTime) {
         const fetched = meta.fetched_at ? new Date(meta.fetched_at).getTime() : 0;
@@ -109,24 +119,30 @@ export default class ResearchPrune extends BaseCommand {
         const filesToPrune = this.findPruneCandidates(roots.readRoots, currentTime);
         const dryRun = this.flags['dry-run'];
         const count = filesToPrune.length;
+        // Track deletions actually performed so the JSON envelope and human output agree even when an
+        // unlink fails (e.g. a permission error). Reporting candidate count as `prunedCount` would
+        // overstate success and mislead an agent branching on the result.
+        let prunedCount = 0;
         if (dryRun) {
             if (!this.jsonEnabled()) {
-                this.log(`[Dry Run] Found ${count} research cache entries that would be pruned:\n`);
+                const noun = pluralize(count, 'entry', 'entries');
+                this.log(`[Dry Run] Found ${count} research cache ${noun} that would be pruned:\n`);
                 filesToPrune.forEach((f) => {
                     this.log(`- [${f.topic || 'No Topic'}] Key: ${f.cacheKey} (${f.url || 'Imported note'})`);
                 });
             }
         }
         else {
-            const prunedCount = this.deletePruneCandidates(filesToPrune);
+            prunedCount = this.deletePruneCandidates(filesToPrune);
             if (!this.jsonEnabled()) {
-                this.log(`Successfully pruned ${prunedCount} of ${count} research cache entries.`);
+                const noun = pluralize(count, 'entry', 'entries');
+                this.log(`Successfully pruned ${prunedCount} of ${count} research cache ${noun}.`);
             }
         }
         return {
             dryRun,
-            prunedCount: dryRun ? 0 : filesToPrune.length,
-            candidateCount: filesToPrune.length,
+            prunedCount,
+            candidateCount: count,
             files: filesToPrune.map((f) => ({
                 cacheKey: f.cacheKey,
                 path: f.path,