@taurgis/bonsai 3.2.0 → 4.0.0

package/dist/commands/list.d.ts

@@ -1,8 +1,16 @@
 import { BaseCommand } from '../base-command.js';
+import type { ListRow, ListRowMinimal } from '../lib/cli-result-types.js';
+/** List cached research artifacts by metadata filters. */
 export default class ResearchList extends BaseCommand<typeof ResearchList> {
     static id: string;
     static summary: string;
     static description: string;
+    /**
+     * Aggregate counts (and an explicit empty/truncation signal) attached to the success envelope so
+     * agents get a cache-wide summary without a separate round trip (AXI principles: pre-computed
+     * aggregates, definitive empty states). Always set by `run()` before it returns.
+     */
+    private jsonSummary;
     static examples: {
         description: string;
         command: string;
@@ -15,12 +23,19 @@ export default class ResearchList extends BaseCommand<typeof ResearchList> {
         'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | "index" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'capture-method': import("@oclif/core/interfaces").OptionFlag<"static_fetch" | "browser_fallback" | "agent_supplied" | "route_markdown" | "github_source" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        full: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
-    private matchesTopic;
-    private matchesTags;
     private matchesFilters;
     private scanCacheDirForList;
+    private hasActiveFilters;
     private logListResults;
-    run(): Promise<unknown>;
+    /**
+     * Empty-cache / no-match tip (human mode only). Under `--json`/`--toon`, `data: []` is paired with
+     * `summary.empty: true` instead of prose — see {@link toSuccessJson}.
+     */
+    private emitEmptyListGuidance;
+    run(): Promise<ListRow[] | ListRowMinimal[]>;
+    /** Attach the aggregate `summary` computed in `run()` (see {@link ListSummary}). */
+    protected toSuccessJson(data: unknown): Record<string, unknown>;
 }

package/dist/commands/list.js

@@ -3,82 +3,109 @@ 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 { ARTIFACT_TYPES, CAPTURE_METHODS } from '../lib/research/schema.js';
-import { NO_TOPIC_LABEL, resultListHeading, truncationNotice, } from '../lib/text.js';
+import { ARTIFACT_TYPES, CAPTURE_METHODS, } from '../lib/research/schema.js';
+import { NO_TOPIC_LABEL, formatTip, resultListHeading, sanitizeForTerminal, } from '../lib/text.js';
 import { limitFlag } from '../lib/limit-flag.js';
-import { artifactMatchesUrlFilter } from '../lib/research/url.js';
+import { artifactMatchesUrlFilter, emptyUrlFilterError } from '../lib/research/url.js';
+import { matchesTopicFilter, matchesTagsFilter, emptyTopicFilterError, emptyTagsFilterError, } from '../lib/research/metadata-filters.js';
 import { colors } from '../lib/color.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 };
+import { CLI_FLAG_DESCRIPTIONS } from '../lib/cli-presentation.js';
+// Listings are ordered newest-first, so the truncation word is "first"; --limit caps at this value.
+const LIST_DEFAULT_MAX_LIMIT = 100;
+const LIST_LABELS = {
+    noun: 'cached research',
+    order: 'first',
+};
 // `list` answers "what pages/notes do I have?" and deliberately omits section children (see
 // scanCacheDirForList), so `section` is not an offered filter — every other artifact type can appear.
 const LISTABLE_ARTIFACT_TYPES = ARTIFACT_TYPES.filter((type) => type !== 'section');
+/** Project a full row down to the default minimal shape (see {@link ListRowMinimal}). */
+function toMinimalListRow(row) {
+    return {
+        sourceUrls: row.sourceUrls,
+        topic: row.topic,
+        freshness: row.freshness,
+        tokenEstimate: row.tokenEstimate,
+    };
+}
+/** Count matched rows per freshness tier for the envelope's `summary.byFreshness`. */
+function countByFreshness(rows) {
+    const counts = { fresh: 0, stale_grace: 0, stale_expired: 0 };
+    for (const row of rows)
+        counts[row.freshness]++;
+    return counts;
+}
+/** List cached research artifacts by metadata filters. */
 export default class ResearchList extends BaseCommand {
     static id = 'list';
-    static summary = 'List cached research artifacts by metadata filters.';
-    static description = 'Lists cached research artifacts, including metadata details like path, source count, freshness, token estimates, and quality metrics without printing full content.';
+    static summary = 'List cached research artifacts by metadata';
+    static description = 'List page-level cached artifacts by source URL, topic, freshness, and token estimate. ' +
+        'Pass --full for every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps).';
+    /**
+     * Aggregate counts (and an explicit empty/truncation signal) attached to the success envelope so
+     * agents get a cache-wide summary without a separate round trip (AXI principles: pre-computed
+     * aggregates, definitive empty states). Always set by `run()` before it returns.
+     */
+    jsonSummary = null;
     static examples = [
         {
-            description: 'list all cached entries',
+            description: 'list cached entries',
             command: '<%= config.bin %> list',
         },
         {
-            description: 'list cached entries for a specific topic with JSON output',
+            description: 'list entries for a topic as JSON',
             command: '<%= config.bin %> list --topic "React Suspense" --json',
         },
         {
-            description: 'list only fresh entries filtered by tags',
+            description: 'list fresh entries matching tags',
             command: '<%= config.bin %> list --freshness fresh --tags node --tags url',
         },
         {
-            description: 'list entries matching a specific URL glob',
+            description: 'list entries matching a URL glob',
             command: '<%= config.bin %> list --url "https://react.dev/*"',
         },
+        {
+            description: 'list every metadata field instead of the minimal default row',
+            command: '<%= config.bin %> list --full --json',
+        },
     ];
     static flags = {
         topic: Flags.string({
             char: 't',
-            description: 'filter by exact topic (case-insensitive)',
+            description: CLI_FLAG_DESCRIPTIONS.filterTopic,
         }),
         tags: Flags.string({
             char: 'g',
-            description: 'filter by tags (must match all tags specified)',
+            description: CLI_FLAG_DESCRIPTIONS.filterTags,
             multiple: true,
         }),
         url: Flags.string({
-            description: 'filter by source URL glob pattern (case-insensitive, supports * wildcard)',
+            description: CLI_FLAG_DESCRIPTIONS.sourceUrlGlob,
         }),
         freshness: Flags.option({
-            description: 'filter by freshness state',
+            description: 'freshness state',
             options: ['fresh', 'stale_grace', 'stale_expired'],
         })(),
         'artifact-type': Flags.option({
-            description: 'filter by artifact type',
+            description: CLI_FLAG_DESCRIPTIONS.listArtifactType,
             options: LISTABLE_ARTIFACT_TYPES,
         })(),
         'capture-method': Flags.option({
-            description: 'filter by capture method',
+            description: 'capture method',
             options: CAPTURE_METHODS,
         })(),
-        limit: limitFlag(100, 50, 'maximum number of results to return (default 50, max 100)'),
+        limit: limitFlag(LIST_DEFAULT_MAX_LIMIT, 50, `result count (max ${LIST_DEFAULT_MAX_LIMIT})`),
+        full: Flags.boolean({
+            default: false,
+            description: CLI_FLAG_DESCRIPTIONS.listFull,
+        }),
     };
     static stdoutIsPrimaryData = true;
-    matchesTopic(meta, topic) {
-        if (!topic)
-            return true;
-        return !!meta.topic && meta.topic.trim().toLowerCase() === topic.trim().toLowerCase();
-    }
-    matchesTags(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()));
-    }
     matchesFilters(meta, freshness) {
-        if (!this.matchesTopic(meta, this.flags.topic)) {
+        if (!matchesTopicFilter(meta, this.flags.topic)) {
             return false;
         }
-        if (!this.matchesTags(meta, this.flags.tags)) {
+        if (!matchesTagsFilter(meta, this.flags.tags)) {
             return false;
         }
         if (this.flags.url && !artifactMatchesUrlFilter(meta, this.flags.url)) {
@@ -96,6 +123,7 @@ export default class ResearchList extends BaseCommand {
         return true;
     }
     scanCacheDirForList(readRoots, currentTime) {
+        // Honor effective read-only: listing must not persist the derived search-index sidecar.
         return scanCacheDirs(readRoots, (artifact, filePath) => {
             if (artifact.metadata.status !== 'active')
                 return null;
@@ -124,19 +152,28 @@ export default class ResearchList extends BaseCommand {
                 fetchedAt: artifact.metadata.fetched_at,
                 validatedAt: artifact.metadata.validated_at,
             };
-        });
+        }, { persistIndex: !this.readOnly });
+    }
+    hasActiveFilters() {
+        return Boolean(this.flags.topic ||
+            (this.flags.tags && this.flags.tags.length > 0) ||
+            this.flags.freshness ||
+            this.flags['artifact-type'] ||
+            this.flags['capture-method'] ||
+            this.flags.url);
     }
     logListResults(finalResults, totalMatched) {
-        if (this.jsonEnabled())
-            return;
         if (finalResults.length === 0) {
-            this.log('No cached research entries found matching filters.');
-            this.log(`\nTip: populate the cache first: ${colors.cyan(this.config.bin + ' <url>')}`);
+            this.emitEmptyListGuidance();
             return;
         }
+        if (this.jsonEnabled())
+            return;
         this.log(`${resultListHeading(totalMatched, finalResults.length, LIST_LABELS)}\n`);
         finalResults.forEach((res, index) => {
-            const topicStr = res.topic ? colors.cyan(res.topic) : colors.gray(NO_TOPIC_LABEL);
+            const topicStr = res.topic
+                ? colors.cyan(sanitizeForTerminal(res.topic))
+                : colors.gray(NO_TOPIC_LABEL);
             const keyStr = colors.bold(res.cacheKey);
             this.log(`${index + 1}. [${topicStr}] Key: ${keyStr}`);
             const freshnessColorMap = {
@@ -144,14 +181,42 @@ export default class ResearchList extends BaseCommand {
                 stale_grace: colors.yellow,
                 stale_expired: colors.red,
             };
-            const freshnessColor = freshnessColorMap[res.freshness] || ((t) => t);
+            const freshnessColor = freshnessColorMap[res.freshness];
             const freshnessStr = freshnessColor(res.freshness);
             this.log(`   Type: ${colors.bold(res.artifactType)} | Freshness: ${freshnessStr}`);
             this.log(`   Tokens: compressed=${colors.bold(String(res.tokenEstimate?.compressed || 0))}, detailed=${colors.bold(String(res.tokenEstimate?.detailed || 0))}`);
             this.log(`   Source URLs: ${colors.gray(res.sourceUrls.join(', '))}\n`);
         });
     }
+    /**
+     * Empty-cache / no-match tip (human mode only). Under `--json`/`--toon`, `data: []` is paired with
+     * `summary.empty: true` instead of prose — see {@link toSuccessJson}.
+     */
+    emitEmptyListGuidance() {
+        if (this.jsonEnabled())
+            return;
+        const filtered = this.hasActiveFilters();
+        const headline = filtered
+            ? 'No cached research entries match the given filters.'
+            : 'No cached research entries found.';
+        const tipCmd = filtered ? `${this.config.bin} list` : `${this.config.bin} <url>`;
+        const tipLead = filtered
+            ? 'try relaxing filters, or list everything: '
+            : 'populate the cache first: ';
+        this.log(headline);
+        this.log(`\n${formatTip(`${tipLead}${colors.cyan(tipCmd)}`)}`);
+        // Bare `bonsai` (no args) redirects here (content-first default), so an empty, unfiltered cache
+        // is also the first thing a brand-new user sees — point at --help so command discovery isn't lost.
+        if (!filtered) {
+            this.log(formatTip(`see every command: ${colors.cyan(`${this.config.bin} --help`)}`));
+        }
+    }
     async run() {
+        const flagErr = emptyUrlFilterError(this.flags.url) ??
+            emptyTopicFilterError(this.flags.topic) ??
+            emptyTagsFilterError(this.flags.tags);
+        if (flagErr)
+            this.error(flagErr, { exit: 2, code: 'INVALID_FLAG_VALUE' });
         const roots = loadStoreRoots({
             configDir: this.config.configDir,
             cwd: process.cwd(),
@@ -159,20 +224,30 @@ export default class ResearchList extends BaseCommand {
         });
         const currentTime = new Date();
         const results = this.scanCacheDirForList(roots.readRoots, currentTime);
-        // Sort by validated_at or fetched_at descending (most recent first)
         results.sort((a, b) => {
             const timeA = new Date(a.validatedAt || a.fetchedAt || 0).getTime();
             const timeB = new Date(b.validatedAt || b.fetchedAt || 0).getTime();
             return timeB - timeA;
         });
         const finalResults = results.slice(0, this.flags.limit);
-        // 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);
+        // Human heading carries truncation inline; --json/--toon get the same counts (plus a freshness
+        // breakdown and an explicit `empty` flag) as an always-present envelope `summary` object.
+        this.jsonSummary = {
+            total: results.length,
+            shown: finalResults.length,
+            limit: this.flags.limit,
+            truncated: results.length > finalResults.length,
+            empty: results.length === 0,
+            byFreshness: countByFreshness(results),
+        };
         this.logListResults(finalResults, results.length);
-        return finalResults;
+        return this.flags.full ? finalResults : finalResults.map(toMinimalListRow);
+    }
+    /** Attach the aggregate `summary` computed in `run()` (see {@link ListSummary}). */
+    toSuccessJson(data) {
+        const envelope = this.baseSuccessJson(data);
+        if (!this.jsonSummary)
+            return envelope;
+        return { ...envelope, summary: this.jsonSummary };
     }
 }

package/dist/commands/prune.d.ts

@@ -1,4 +1,6 @@
 import { BaseCommand } from '../base-command.js';
+import type { PruneWriteResult } from '../lib/cli-result-types.js';
+/** Prune cached artifacts by age, idle time, or filters. */
 export default class ResearchPrune extends BaseCommand<typeof ResearchPrune> {
     static id: string;
     static summary: string;
@@ -11,14 +13,17 @@ export default class ResearchPrune extends BaseCommand<typeof ResearchPrune> {
         'older-than': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         inactive: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        topic: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        tags: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | "index" | "section" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
+    protected toSuccessJson(data: unknown): Record<string, unknown>;
     private validatePruneFlags;
     private shouldPrune;
     private findPruneCandidates;
     private deletePruneCandidates;
-    run(): Promise<unknown>;
+    run(): Promise<PruneWriteResult>;
 }

package/dist/commands/prune.js

@@ -2,131 +2,119 @@ import { Flags } from '@oclif/core';
 import { unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { BaseCommand } from '../base-command.js';
+import { enrichPrunePartialEnvelope } from '../lib/envelope.js';
 import { scanCacheDir } from '../lib/research/storage.js';
 import { loadStoreRoots } from '../lib/research/store-roots.js';
-import { parseTtlToMs, durationFlagError } from '../lib/research/freshness.js';
+import { parseTtlToMs } from '../lib/research/freshness.js';
 import { ARTIFACT_TYPES } from '../lib/research/schema.js';
-import { NO_TOPIC_LABEL, pluralize } from '../lib/text.js';
+import { NO_TOPIC_LABEL, pluralize, sanitizeForTerminal } from '../lib/text.js';
 import { artifactMatchesUrlFilter } from '../lib/research/url.js';
+import { matchesTopicFilter, matchesTagsFilter } from '../lib/research/metadata-filters.js';
+import { pruneFlagError } from '../lib/prune-flags.js';
 import { colors } from '../lib/color.js';
+import { CLI_FLAG_DESCRIPTIONS } from '../lib/cli-presentation.js';
+/** Prune cached artifacts by age, idle time, or filters. */
 export default class ResearchPrune extends BaseCommand {
     static id = 'prune';
-    static summary = 'Clean up old or inactive research cache entries.';
-    static description = 'Prunes cached research entries based on age, inactivity, or artifact type to free up disk space.';
+    static summary = 'Prune cached research artifacts';
+    static description = 'Delete cached artifacts by content age, idle time, URL glob, artifact type, topic, or tags.';
     static examples = [
         {
-            description: 'perform a dry run of pruning entries older than 90 days',
-            command: '<%= config.bin %> prune --older-than 90d --dry-run',
+            description: 'preview pruning entries older than 30 days',
+            command: '<%= config.bin %> prune --older-than 30d --dry-run',
         },
         {
-            description: 'actually prune entries older than 30 days that are source scrapes',
+            description: 'prune source artifacts older than 30 days',
             command: '<%= config.bin %> prune --older-than 30d --artifact-type source --yes',
         },
         {
-            description: 'prune entries matching a URL glob pattern',
+            description: 'prune entries matching a URL glob',
             command: '<%= config.bin %> prune --url "https://react.dev/*" --yes',
         },
+        {
+            description: 'prune entries tagged as deprecated',
+            command: '<%= config.bin %> prune --tags deprecated --yes',
+        },
     ];
     static flags = {
         'older-than': Flags.string({
-            description: 'prune entries older than duration (e.g. "30d", "90d")',
+            description: 'content age threshold (fetched_at, else validated_at), e.g. "30d"',
         }),
         inactive: Flags.string({
-            description: 'prune entries inactive (unvalidated/unfetched) for duration (e.g. "14d", "30d")',
+            description: 'idle time threshold (validated_at, else fetched_at), e.g. "14d"',
         }),
         url: Flags.string({
-            description: 'filter pruning to source URL glob pattern (case-insensitive, supports * wildcard)',
+            description: CLI_FLAG_DESCRIPTIONS.sourceUrlGlob,
+        }),
+        topic: Flags.string({
+            char: 't',
+            description: CLI_FLAG_DESCRIPTIONS.filterTopic,
+        }),
+        tags: Flags.string({
+            char: 'g',
+            description: CLI_FLAG_DESCRIPTIONS.filterTags,
+            multiple: true,
         }),
         'artifact-type': Flags.option({
             // Prune operates on every cached file, so it can target any artifact type — including the
             // `section`/`index` children a page generates (e.g. to clear orphans left after a source is
             // pruned with `--artifact-type source`).
-            description: 'filter pruning to specific artifact type',
+            description: CLI_FLAG_DESCRIPTIONS.pruneArtifactType,
             options: ARTIFACT_TYPES,
         })(),
         'dry-run': Flags.boolean({
-            description: 'list files that would be deleted without actually deleting them',
+            description: 'preview files without deleting',
             default: false,
         }),
         yes: Flags.boolean({
             char: 'y',
-            description: 'confirm deletion and prune matched entries (required unless --dry-run)',
+            description: 'confirm deletion (required unless --dry-run)',
             default: false,
         }),
     };
     static stdoutIsPrimaryData = true;
+    toSuccessJson(data) {
+        return enrichPrunePartialEnvelope(this.baseSuccessJson(data), data);
+    }
     validatePruneFlags() {
-        if (!this.flags['older-than'] &&
-            !this.flags.inactive &&
-            !this.flags['artifact-type'] &&
-            !this.flags.url) {
-            this.error('Must specify at least one pruning filter: --older-than, --inactive, --artifact-type, or --url.', {
-                exit: 2,
-                code: 'MISSING_FILTER',
-                suggestions: [
-                    `Preview age-based pruning: ${this.config.bin} prune --older-than 90d --dry-run`,
-                ],
-            });
-        }
-        // Checked before the generic --dry-run/--yes conflict below so a combination like
-        // `--dry-run --yes --read-only` reports the more specific READ_ONLY_MODE code, not
-        // CONFLICTING_FLAGS — read-only mode is the more fundamental constraint being violated.
-        if (this.readOnly && this.flags.yes) {
-            this.error('--yes cannot be used while read-only mode is active (--read-only/--plan or BONSAI_READ_ONLY/BONSAI_PLAN_MODE): mutations are disabled.', {
-                exit: 2,
-                code: 'READ_ONLY_MODE',
-                suggestions: [`Preview instead: ${this.config.bin} prune --dry-run`],
-            });
-        }
-        if (this.flags['dry-run'] && this.flags.yes) {
-            this.error('--dry-run and --yes are mutually exclusive: --dry-run previews without deleting, --yes confirms deletion. Choose one.', { exit: 2, code: 'CONFLICTING_FLAGS' });
-        }
-        // Read-only mode implicitly previews, so the usual "pick one" safety check is redundant here.
-        if (!this.readOnly && !this.flags['dry-run'] && !this.flags.yes) {
-            const olderThanPart = this.flags['older-than']
-                ? ` --older-than ${this.flags['older-than']}`
-                : '';
-            const urlPart = this.flags.url ? ` --url "${this.flags.url}"` : '';
-            this.error('Safety check: use --yes to confirm pruning, or --dry-run to preview files that would be deleted.', {
-                exit: 2,
-                code: 'SAFETY_CHECK_REQUIRED',
-                suggestions: [
-                    `Preview first: ${this.config.bin} prune --dry-run${olderThanPart}${urlPart}`,
-                ],
-            });
-        }
-        // 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, code: 'INVALID_DURATION' });
-        }
+        const err = pruneFlagError({
+            olderThan: this.flags['older-than'],
+            inactive: this.flags.inactive,
+            artifactType: this.flags['artifact-type'],
+            url: this.flags.url,
+            topic: this.flags.topic,
+            tags: this.flags.tags,
+            dryRun: this.flags['dry-run'],
+            yes: this.flags.yes,
+            readOnly: this.readOnly,
+            bin: this.config.bin,
+        });
+        if (err)
+            this.error(err.message, { exit: 2, code: err.code, suggestions: err.suggestions });
     }
     shouldPrune(meta, currentTime) {
-        const fetched = meta.fetched_at ? new Date(meta.fetched_at).getTime() : 0;
-        const validated = meta.validated_at ? new Date(meta.validated_at).getTime() : 0;
-        const baseTime = Math.max(fetched, validated);
-        const ageMs = currentTime.getTime() - baseTime;
         if (this.flags['artifact-type'] && meta.artifact_type !== this.flags['artifact-type']) {
             return false;
         }
         if (this.flags.url && !artifactMatchesUrlFilter(meta, this.flags.url)) {
             return false;
         }
-        if (this.flags['older-than']) {
-            const olderThanMs = parseTtlToMs(this.flags['older-than']);
-            if (ageMs < olderThanMs) {
-                return false;
-            }
+        if (!matchesTopicFilter(meta, this.flags.topic)) {
+            return false;
         }
-        if (this.flags.inactive) {
-            const inactiveMs = parseTtlToMs(this.flags.inactive);
-            if (ageMs < inactiveMs) {
-                return false;
-            }
+        if (!matchesTagsFilter(meta, this.flags.tags)) {
+            return false;
+        }
+        const now = currentTime.getTime();
+        // Content age (fetched_at, else validated_at) vs idle time (validated_at, else fetched_at) are
+        // deliberately distinct so a recently revalidated but originally-old page can match --older-than
+        // without also being treated as inactive.
+        if (this.flags['older-than'] &&
+            ageMs(meta, now, 'content') < parseTtlToMs(this.flags['older-than'])) {
+            return false;
+        }
+        if (this.flags.inactive && ageMs(meta, now, 'idle') < parseTtlToMs(this.flags.inactive)) {
+            return false;
         }
         return true;
     }
@@ -152,7 +140,12 @@ export default class ResearchPrune extends BaseCommand {
                 prunedCount++;
             }
             catch (err) {
-                this.warn(`Failed to delete cache file ${f.path}: ${err.message}`);
+                // A failed unlink still flips the command to exit 1 (see the caller's comment), so it must
+                // render as an Error, not a Warning — this.error's exit:false form prints the same "Error: …"
+                // line and returns instead of throwing, so the remaining candidates still get processed.
+                this.error(`Failed to delete cache file ${f.path}: ${err.message}`, {
+                    exit: false,
+                });
             }
         }
         return prunedCount;
@@ -181,8 +174,12 @@ export default class ResearchPrune extends BaseCommand {
                     const noun = pluralize(count, 'entry', 'entries');
                     this.log(colors.yellow(`[Dry Run] Found ${count} research cache ${noun} that would be pruned:\n`));
                     filesToPrune.forEach((f) => {
-                        this.log(`- [${f.topic ? colors.cyan(f.topic) : colors.gray(NO_TOPIC_LABEL)}] Key: ${colors.bold(f.cacheKey)} (${colors.gray(f.url || 'Imported note')})`);
+                        const topicStr = f.topic
+                            ? colors.cyan(sanitizeForTerminal(f.topic))
+                            : colors.gray(NO_TOPIC_LABEL);
+                        this.log(`- [${topicStr}] Key: ${colors.bold(f.cacheKey)} (${colors.gray(f.url || 'Imported note')})`);
                     });
+                    this.tip('re-run with --yes to prune these entries.');
                 }
             }
         }
@@ -192,9 +189,16 @@ export default class ResearchPrune extends BaseCommand {
                 const noun = pluralize(count, 'entry', 'entries');
                 this.log(colors.green(`Successfully pruned ${prunedCount} of ${count} research cache ${noun}.`));
             }
+            // Partial unlink failure is a runtime outcome agents must see: exit 1 with the counts still
+            // in `data` so callers can tell candidates from successes without parsing stderr warnings.
+            if (count > 0 && prunedCount < count) {
+                process.exitCode = 1;
+            }
         }
         return {
             dryRun,
+            status: dryRun ? 'would_prune' : 'pruned',
+            wouldPruneCount: dryRun ? count : 0,
             prunedCount,
             candidateCount: count,
             files: filesToPrune.map((f) => ({
@@ -204,3 +208,10 @@ export default class ResearchPrune extends BaseCommand {
         };
     }
 }
+/** Age in ms for prune filters. `content` prefers fetched_at; `idle` prefers validated_at. */
+function ageMs(meta, now, kind) {
+    const fetched = meta.fetched_at ? new Date(meta.fetched_at).getTime() : 0;
+    const validated = meta.validated_at ? new Date(meta.validated_at).getTime() : 0;
+    const base = kind === 'content' ? fetched || validated : validated || fetched;
+    return now - base;
+}

package/dist/commands/status.d.ts

@@ -1,4 +1,5 @@
 import { BaseCommand } from '../base-command.js';
+/** Report cache hit/miss and freshness without writing. */
 export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
     static id: string;
     static summary: string;
@@ -12,13 +13,13 @@ export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
-        tier: import("@oclif/core/interfaces").OptionFlag<"stable" | "standard" | "volatile", import("@oclif/core/interfaces").CustomOptions>;
+        tier: import("@oclif/core/interfaces").OptionFlag<"stable" | "standard" | "volatile" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         ttl: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'max-age': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
-    /** Enrich cache-miss envelopes with the same CACHE_MISS code and suggestions as inspect. */
     protected toSuccessJson(data: unknown): Record<string, unknown>;
     run(): Promise<unknown>;
     private checkSingleStatus;
+    private logStatusTable;
 }