@byterover/claude-plugin 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
-# @byterover/claude-bridge
+# @byterover/claude-plugin
 
-Native bridge between [ByteRover](https://www.byterover.dev) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Enriches Claude's auto-memory with ByteRover's full multi-tier retrieval — BM25 search, importance scoring, performance correlation, and LLM synthesis — giving Claude persistent, cross-referenced context that improves over time.
+Native plugin between [ByteRover](https://www.byterover.dev) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Enriches Claude's auto-memory with ByteRover's full multi-tier retrieval — BM25 search, importance scoring, performance correlation, and LLM synthesis — giving Claude persistent, cross-referenced context that improves over time.
 
 ## Table of contents
 
@@ -15,13 +15,14 @@ Native bridge between [ByteRover](https://www.byterover.dev) and [Claude Code](h
 
 ## What it does
 
-Claude Code has a built-in auto-memory system — it saves observations across sessions as flat markdown files. ByteRover has a richer context tree with multi-tier retrieval: BM25 text search, importance/recency scoring, maturity tier boosting, performance-memory correlation, and LLM-powered synthesis. This bridge connects the two:
+Claude Code has a built-in auto-memory system — it saves observations across sessions as flat markdown files. ByteRover has a richer context tree with multi-tier retrieval: BM25 text search, importance/recency scoring, maturity tier boosting, performance-memory correlation, and LLM-powered synthesis. This plugin connects the two:
 
 1. **Ingesting memories** — when Claude's extraction agent writes a memory file, a hook fires and sends the content to `brv curate`, which enriches it with tags, keywords, scoring metadata, and stores it in the context tree
 2. **Syncing context** — after each turn, a hook queries ByteRover for ranked knowledge and writes a cross-reference file that Claude's recall system can pick up
-3. **Zero workflow change** — you use `claude` exactly as before. The bridge runs in the background via Claude Code's hook system
+3. **Visible activation** — every prompt that retrieves curated knowledge gets a one-line `🧠 ByteRover returns …` summary in the chat showing which memories were used. An opt-in status line at the bottom of Claude Code surfaces daemon activity (idle / curating / dreaming) so you can see when the context tree is being updated in the background
+4. **Zero workflow change** — you use `claude` exactly as before. The plugin runs in the background via Claude Code's hook system
 
-The result: Claude's memories are indexed, scored, and searchable alongside the rest of your project knowledge in ByteRover.
+The result: Claude's memories are indexed, scored, and searchable alongside the rest of your project knowledge in ByteRover — and you can see the system working as you go.
 
 ## Prerequisites
 
@@ -31,10 +32,10 @@ The result: Claude's memories are indexed, scored, and searchable alongside the
 
 ## Quick start
 
-### 1. Install the bridge
+### 1. Install the plugin
 
 ```bash
-npm install -g @byterover/claude-bridge
+npm install -g @byterover/claude-plugin
 ```
 
 ### 2. Install hooks
@@ -52,7 +53,27 @@ This adds four hooks to `~/.claude/settings.json`:
 
 Your existing settings and hooks are preserved. A backup is saved to `settings.json.brv-backup`.
 
-### 3. Verify
+### 3. Install the status line (optional)
+
+```bash
+brv-claude-plugin install-statusline
+```
+
+Adds a `statusLine` entry to `~/.claude/settings.json` that renders one of three states at the bottom of Claude Code:
+
+```
+🧠 ByteRover · idle           (dim gray — no daemon work in progress)
+🧠 ByteRover · 📝 curating    (yellow — a curate task is running)
+🧠 ByteRover · 💭 dreaming    (cyan — a dream consolidation cycle is running)
+```
+
+The line is hidden when you're not in a brv-initialized project. Refreshes every 5 seconds in addition to Claude Code's event-driven triggers, so it picks up daemon state changes that happen while the assistant is mid-tool-call.
+
+If you already have a custom `statusLine` configured, the installer prompts you (in a TTY) to keep it, replace it, or abort. Pass `--force` to overwrite without prompting; non-interactive shells fail-fast with a hint to use `--force`.
+
+The status line is opt-in and removable via `brv-claude-plugin uninstall-statusline` (leaves foreign user statuslines alone) or as part of the full `brv-claude-plugin uninstall`.
+
+### 4. Verify
 
 ```bash
 brv-claude-plugin doctor
@@ -63,31 +84,34 @@ You should see all checks passing:
 ```
 brv-claude-plugin doctor
 
-  ✓ brv CLI — byterover-cli/2.5.0
+  ✓ brv CLI — byterover-cli/3.10.3 darwin-arm64 node-v22.21.1
   ✓ Context tree — /path/to/project/.brv/context-tree
   ✓ Claude settings — ~/.claude/settings.json
   ✓ Bridge hooks — PostToolUse + Stop + UserPromptSubmit hooks found
   ✓ Bridge executable — /usr/local/bin/brv-claude-plugin
+  ✓ Status line — registered, points to our binary
   ✓ Memory directory — ~/.claude/projects/-path-to-project/memory/
 
 All checks passed.
 ```
 
-### 4. Use Claude normally
+The `Status line` check is informational — it shows ✓ when our status line is registered and ✗ otherwise (with a hint to run `install-statusline`), but a missing status line does not flip the overall outcome since it's opt-in.
+
+### 5. Use Claude normally
 
 ```bash
 claude "fix the auth bug"
 ```
 
-Memories are ingested into `.brv/context-tree/_cc/` automatically. No changes to your workflow.
+Memories are ingested into `.brv/context-tree/` automatically. No changes to your workflow.
 
-### 5. Uninstall (if needed)
+### 6. Uninstall (if needed)
 
 ```bash
 brv-claude-plugin uninstall
 ```
 
-Removes only bridge hooks. Your other hooks and settings are untouched.
+Removes plugin hooks **and** our status line entry (if installed) in a single pass. Your other hooks, settings, and any foreign `statusLine` entry are untouched. To remove only the status line and keep the hooks, run `brv-claude-plugin uninstall-statusline` instead.
 
 ## Commands
 
@@ -104,12 +128,43 @@ Idempotent — safe to run multiple times. Deduplicates by checking for the `#br
 
 ### `brv-claude-plugin uninstall`
 
-Removes bridge hooks from settings. Per-hook removal — if a matcher entry contains both a bridge hook and your own hook, only the bridge hook is deleted.
+Removes plugin hooks **and** the plugin's status line entry from settings. Per-hook removal — if a matcher entry contains both a plugin hook and your own hook, only the plugin hook is deleted. Foreign user `statusLine` entries are left intact.
 
 | Option              | Description                                |
 | ------------------- | ------------------------------------------ |
 | `--settings-path`   | Override path to Claude Code settings.json |
 
+### `brv-claude-plugin install-statusline`
+
+Installs an opt-in `statusLine` entry into `~/.claude/settings.json` that surfaces daemon activity at the bottom of Claude Code. Idempotent. Backs up `settings.json` before writing.
+
+If a `statusLine` is already configured:
+
+- **Carries our `#brv-claude-plugin` marker:** idempotent — re-runs to upgrade fields if our shape has drifted (e.g., new `refreshInterval` value)
+- **Foreign (someone else's):** prompts on TTY (keep / replace / abort, default abort); fails fast on non-TTY with instructions to use `--force`
+
+| Option              | Description                                                       |
+| ------------------- | ----------------------------------------------------------------- |
+| `--dry-run`         | Show what would be written without saving                         |
+| `--force`           | Overwrite an existing foreign statusLine without prompting        |
+| `--settings-path`   | Override path to Claude Code settings.json                        |
+
+### `brv-claude-plugin uninstall-statusline`
+
+Removes only the plugin's `statusLine` entry. Marker-gated — leaves foreign user statuslines alone.
+
+| Option              | Description                                |
+| ------------------- | ------------------------------------------ |
+| `--settings-path`   | Override path to Claude Code settings.json |
+
+### `brv-claude-plugin status`
+
+Called by the `statusLine` command in Claude Code's settings. Reads CC's status payload from stdin, walks up from the current directory to find `.brv/`, classifies daemon state via filesystem inspection, and prints one ANSI-colored line.
+
+- Outputs nothing (line hidden) when no `.brv/` is reachable
+- Inspects `.brv/dream-log/`, `.brv/dream.lock`, and the daemon's per-project storage directory under the platform's user-data dir for `curate-log/`
+- Always exits 0; runs in well under 100ms in normal cases
+
 ### `brv-claude-plugin ingest`
 
 Called by the PostToolUse hook. Reads hook JSON from stdin, parses the memory file, and sends it to `brv curate --detach`.
@@ -139,20 +194,26 @@ Called by the Stop hook. Copies the context tree index from `.brv/context-tree/_
 
 ### `brv-claude-plugin recall`
 
-Called by the UserPromptSubmit hook. Reads the user's prompt from stdin, queries ByteRover with it, and returns targeted context as `additionalContext` that Claude sees before generating a response.
+Called by the UserPromptSubmit hook. Reads the user's prompt from stdin, queries ByteRover with it, and emits two things to Claude Code:
+
+- **`additionalContext`** — the retrieved context wrapped in `<byterover-context>` tags, injected before the model call so the response can use it
+- **`systemMessage`** — a one-line `🧠 ByteRover returns N memories: <path1> (3d ago), <path2> (1w ago), …` summary visible in the chat above Claude's response (capped at 3 paths, with humanized age suffixes)
+
+Behavior:
 
 - Runs **synchronously** — delays the model call until ByteRover responds (6s internal timeout, 8s hook timeout)
 - Skips trivially short prompts (< 5 chars)
+- Per-entry score filter (≥0.5) trims low-relevance hits from the visible summary; if no qualifying entries exist, the summary line is suppressed entirely
+- On cache hits or older `brv` versions that don't return structured `matchedDocs`, falls back to regex-parsing the `**Sources**:` block at the end of the response prose
 - If ByteRover query fails or times out, exits silently — prompt proceeds without context
-- Wraps results in `<byterover-context>` tags
 
 ### `brv-claude-plugin doctor`
 
-Runs 6 diagnostic checks: brv CLI, context tree, settings file, installed hooks, bridge executable, and memory directory resolution.
+Runs 7 diagnostic checks: brv CLI, context tree, settings file, installed hooks, plugin executable, status line registration, and memory directory resolution. The status line entry is informational — its absence does not flip the overall outcome since it's opt-in.
 
 ## How it works
 
-The bridge uses Claude Code's [hook system](https://docs.anthropic.com/en/docs/claude-code/hooks) to intercept memory operations without modifying Claude Code's source.
+The plugin uses Claude Code's [hook system](https://docs.anthropic.com/en/docs/claude-code/hooks) to intercept memory operations without modifying Claude Code's source.
 
 ### Recall flow (UserPromptSubmit hook)
 
@@ -163,10 +224,14 @@ User types: "fix the combo scoring bug"
 brv-claude-plugin recall
   │ brv query "fix the combo scoring bug" → targeted results
   ▼
-Claude sees <byterover-context> as system reminder
-  (live, relevant to this specific prompt)
+  • Claude sees <byterover-context> as system reminder
+    (live, relevant to this specific prompt)
+  • A one-line `🧠 ByteRover returns N memories: <path>(3d ago), …`
+    summary is shown in the chat above the response (capped at 3 paths)
 ```
 
+The visible summary is built from the structured `matchedDocs` returned by `brv query --format json` when available; on cache hits or older `brv` versions the plugin falls back to parsing the `**Sources**:` block at the end of the response prose. Per-entry score filtering (≥0.5) keeps the line concise — if no qualifying entries exist, the line is suppressed entirely.
+
 ### Ingest flow (PostToolUse hook)
 
 ```
@@ -175,12 +240,12 @@ Claude writes ~/.claude/projects/.../memory/feedback_testing.md
   ▼ PostToolUse hook fires, pipes JSON to stdin
 brv-claude-plugin ingest
   │ Parse cc-ts frontmatter (name, description, type)
-  │ Map type → domain (_cc/user, _cc/feedback, _cc/project, _cc/reference)
+  │ Map type → domain (/user, /feedback, /project, /reference)
   ▼
 brv curate --detach --format json -- "context string"
   │ Daemon queues curation (async, non-blocking)
   ▼
-.brv/context-tree/_cc/feedback/testing.md
+.brv/context-tree/feedback/testing.md
   (enriched with tags, keywords, importance scoring)
 ```
 
@@ -197,9 +262,33 @@ brv-claude-plugin sync
   (context tree index + guide to full tree)
 ```
 
+### Status line flow (statusLine entry)
+
+The status line uses the same `statusLine` mechanism Claude Code documents — it runs the configured command after each assistant message, after `/compact`, on permission/vim-mode changes, AND every 5 seconds (`refreshInterval: 5`). The 5-second tick is what catches daemon state changes during long tool calls when no event-driven trigger fires.
+
+```
+Claude Code refresh tick (event or every 5s)
+  │
+  ▼ runs statusLine command (with stdin JSON payload)
+brv-claude-plugin status
+  │ Walk up from cwd → find `.brv/`
+  │   (none → empty stdout → line hidden)
+  │ Inspect filesystem signals:
+  │   • <brvDir>/dream-log/*.json (project-local)
+  │   • <brvDir>/dream.lock        (project-local)
+  │   • <getProjectDataDir(cwd)>/curate-log/*.json
+  │     (per-project storage under the OS user-data dir —
+  │      mirrors the daemon's path resolution)
+  ▼
+Print one ANSI-colored line:
+  🧠 ByteRover · idle / 📝 curating / 💭 dreaming
+```
+
+State classification follows a confident-signals-first order: an active `dream-log` entry wins; an active `curate-log` entry wins over the `dream.lock` fallback; the lock alone is honored only if it's fresh (within 15 minutes) and the latest `dream-log` entry isn't already marked `completed`. This combination catches stale locks left behind by interrupted daemons and avoids masking active curate work. A residual edge case remains for daemons that crash mid-dream within the 15-minute window — the proper fix lives daemon-side and is tracked separately.
+
 ### Memory path resolution
 
-The bridge resolves Claude's memory directory using the same logic as Claude Code:
+The plugin resolves Claude's memory directory using the same logic as Claude Code:
 
 1. `CLAUDE_COWORK_MEMORY_PATH_OVERRIDE` env var (full override)
 2. `autoMemoryDirectory` from settings (local → user, excluding project settings for security)
@@ -209,7 +298,7 @@ Git worktrees are resolved to their canonical root so all worktrees share one me
 
 ### Multi-project support
 
-The bridge naturally supports multiple projects. Claude Code scopes memory per git repository, and ByteRover scopes its context tree per `.brv/` directory. Both use the same `cwd` from the hook input as their anchor:
+The plugin naturally supports multiple projects. Claude Code scopes memory per git repository, and ByteRover scopes its context tree per `.brv/` directory. Both use the same `cwd` from the hook input as their anchor:
 
 ```
 /Users/x/project-a/        ← claude session here
@@ -227,7 +316,7 @@ Each project's memories are ingested into its own context tree and synced back t
 
 **Important: initialize `.brv/` at the git root.** Claude Code resolves memory directories from the canonical git root. ByteRover walks up from `cwd` to find `.brv/`. When both are at the same level, everything maps correctly.
 
-If you initialize `.brv/` in a subdirectory instead of the git root, the bridge will encounter mismatches:
+If you initialize `.brv/` in a subdirectory instead of the git root, the plugin will encounter mismatches:
 
 ```
 /monorepo/                  ← git root (Claude memory lives here)
@@ -272,10 +361,10 @@ node dist/cli.js doctor
 ### Testing locally
 
 1. Initialize a brv project: `cd /your/project && brv init`
-2. Build the bridge: `npm run build`
+2. Build the plugin: `npm run build`
 3. Install hooks (dev mode): `node dist/cli.js install`
 4. Start a Claude session and make a few changes
-5. Check `.brv/context-tree/_cc/` for ingested memories
+5. Check `.brv/context-tree/` for ingested memories
 6. Check `~/.claude/projects/.../memory/_brv_context.md` for synced context
 
 ## Project structure
@@ -287,16 +376,26 @@ src/
   memory-path.ts              # Full cc-ts memory path resolution (git root, worktrees, env vars)
   stdin.ts                    # Read + validate JSON from stdin
   bridge-command.ts           # Executable resolution + #brv-claude-plugin marker
+  build-recall-output.ts      # Recall orchestrator — combines query result, score filter, fallback
+  build-visible-summary.ts    # Recall preamble formatter — `🧠 ByteRover returns N memories…` line
+  parse-sources.ts            # Regex fallback over **Sources**: blocks for cache-hit recovery
+  resolve-context-tree-age.ts # Frontmatter-based age resolution (updatedAt → mtime → undefined)
+  state-detector.ts           # Filesystem state classification for the status line
+  format-status-line.ts       # ANSI-colored status line formatter (idle / curating / dreaming)
+  project-data-dir.ts         # Mirrors daemon's getGlobalDataDir + sanitizeProjectPath
   schemas/
     cc-hook-input.ts          # Zod schemas for PostToolUse and Stop hook input
     cc-settings.ts            # Raw JSON read/write for settings.json (lossless)
   commands/
     install.ts                # Install hooks into settings.json (per-hook dedupe, backup)
-    uninstall.ts              # Remove bridge hooks (per-hook removal)
+    uninstall.ts              # Remove plugin hooks AND status line (per-hook removal)
+    install-statusline.ts     # Opt-in statusLine installer (prompt / --force / upgrade-in-place)
+    uninstall-statusline.ts   # Marker-gated statusLine removal
     ingest.ts                 # PostToolUse handler — Write/Edit split, brv curate
     sync.ts                   # Stop handler — _index.md copy, _brv_context.md, MEMORY.md pointer
-    recall.ts                 # UserPromptSubmit handler — live brv query with user prompt
-    doctor.ts                 # 6 diagnostic checks
+    recall.ts                 # UserPromptSubmit handler — live brv query, visible summary
+    status.ts                 # statusLine handler — daemon state classification → one-line output
+    doctor.ts                 # 7 diagnostic checks (incl. status line registration)
 ```
 
 ## License

package/dist/build-recall-output.d.ts

@@ -0,0 +1,39 @@
+/** Resolve a path's age. Injectable so unit tests can avoid touching the filesystem. */
+export type AgeResolver = (cwd: string, relativePath: string) => Date | undefined;
+export interface BuildRecallOutputArgs {
+    /** Synthesized prose returned by `brv query`. */
+    content: string;
+    /**
+     * Structured matches surfaced by newer brv CLIs. When undefined we fall back to
+     * regex-parsing the `**Sources**:` block in `content` for graceful degradation against
+     * older brv CLIs that do not emit this field.
+     */
+    matchedDocs?: ReadonlyArray<{
+        path: string;
+        score?: number;
+    }>;
+    /** Project root used to resolve frontmatter timestamps and mtime fallbacks. */
+    cwd: string;
+    /** Override the age resolver (test seam). Defaults to filesystem-backed resolver. */
+    getAge?: AgeResolver;
+    /** Override the reference clock (test seam). */
+    now?: Date;
+}
+export interface RecallHookOutput {
+    /**
+     * Visible single-line summary rendered by Claude Code beneath the prompt.
+     * Omitted when there are no recall paths to surface (cache hits with empty matchedDocs,
+     * older CLIs that returned content without a Sources block).
+     */
+    systemMessage?: string;
+    hookSpecificOutput: {
+        hookEventName: "UserPromptSubmit";
+        additionalContext: string;
+    };
+}
+/**
+ * Assemble the dual-channel UserPromptSubmit hook output (visible systemMessage + invisible
+ * additionalContext) from a recall result. Returns undefined when there is nothing to emit
+ * (no synthesized content), letting the caller exit silently without writing JSON to stdout.
+ */
+export declare function buildRecallOutput(args: BuildRecallOutputArgs): RecallHookOutput | undefined;

package/dist/build-recall-output.js

@@ -0,0 +1,59 @@
+import { buildVisibleSummary, } from "./build-visible-summary.js";
+import { parseSourcesFromContent } from "./parse-sources.js";
+import { resolveContextTreeAge } from "./resolve-context-tree-age.js";
+const MAX_VISIBLE_PATHS = 3;
+/** Drop individual matches whose score is below this threshold; if nothing qualifies, suppress the visible summary entirely. */
+const MIN_QUALIFYING_SCORE = 0.5;
+/**
+ * Assemble the dual-channel UserPromptSubmit hook output (visible systemMessage + invisible
+ * additionalContext) from a recall result. Returns undefined when there is nothing to emit
+ * (no synthesized content), letting the caller exit silently without writing JSON to stdout.
+ */
+export function buildRecallOutput(args) {
+    if (!args.content)
+        return undefined;
+    const paths = qualifyingPaths(args.matchedDocs, args.content).slice(0, MAX_VISIBLE_PATHS);
+    const summary = paths.length > 0 ? renderSummary(paths, args) : "";
+    return {
+        ...(summary ? { systemMessage: summary } : {}),
+        hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: `<byterover-context>\n` +
+                `The following knowledge is from ByteRover context engine:\n\n` +
+                `${args.content}\n` +
+                `</byterover-context>`,
+        },
+    };
+}
+function qualifyingPaths(matchedDocs, content) {
+    // Newer CLI with structured matches: matchedDocs is the source of truth. Drop entries
+    // whose score falls below the qualifying threshold.
+    //
+    // Empty matchedDocs has two meanings depending on CLI behaviour:
+    //   1. Cache hits (Tier 0/1) — QueryExecutor intentionally returns [] because the cache
+    //      stores only the response string, not match metadata. The synthesised content still
+    //      carries a `**Sources**:` block listing the docs that informed the cached answer.
+    //   2. True "no matches found" — no Sources block in content, parse returns [].
+    // In both cases we fall through to the Sources-block parser: case 1 recovers the paths,
+    // case 2 returns [] and the caller suppresses systemMessage.
+    if (matchedDocs !== undefined && matchedDocs.length > 0) {
+        return matchedDocs
+            .filter((d) => d.score === undefined || d.score >= MIN_QUALIFYING_SCORE)
+            .map((d) => d.path);
+    }
+    // Fallback path used by older CLIs (no matchedDocs at all) AND by cache hits (empty
+    // matchedDocs but `**Sources**:` block present in content). Per-entry score is not
+    // recoverable here, so paths flow through without per-entry filtering — acceptable
+    // because the cached/synthesised response was already deemed answer-worthy upstream.
+    return parseSourcesFromContent(content);
+}
+function renderSummary(paths, args) {
+    const resolve = args.getAge ?? resolveContextTreeAge;
+    const entries = paths.map((path) => {
+        const age = resolve(args.cwd, path);
+        return age ? { path, age } : { path };
+    });
+    const summaryOptions = args.now ? { now: args.now } : {};
+    return buildVisibleSummary(entries, summaryOptions);
+}
+//# sourceMappingURL=build-recall-output.js.map

package/dist/build-visible-summary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Format the visible "ByteRover returns N memories: …" line that the
+ * UserPromptSubmit hook emits via `systemMessage`. Pure function so it can
+ * be unit-tested without filesystem or clock dependencies — the caller is
+ * responsible for resolving each entry's age before calling.
+ */
+export interface VisibleSummaryEntry {
+    /** Path as it should be rendered. Caller is responsible for stripping the .brv/context-tree/ prefix. */
+    path: string;
+    /** Last-modified (or originally-curated) date; omit when no signal is available. */
+    age?: Date;
+}
+export interface BuildVisibleSummaryOptions {
+    /** Override the reference clock for deterministic age computation in tests. */
+    now?: Date;
+}
+export declare function buildVisibleSummary(entries: readonly VisibleSummaryEntry[], options?: BuildVisibleSummaryOptions): string;

package/dist/build-visible-summary.js

@@ -0,0 +1,40 @@
+/**
+ * Format the visible "ByteRover returns N memories: …" line that the
+ * UserPromptSubmit hook emits via `systemMessage`. Pure function so it can
+ * be unit-tested without filesystem or clock dependencies — the caller is
+ * responsible for resolving each entry's age before calling.
+ */
+const MAX_ENTRIES = 3;
+const MS_PER_DAY = 86_400_000;
+export function buildVisibleSummary(entries, options) {
+    if (entries.length === 0)
+        return "";
+    const shown = entries.slice(0, MAX_ENTRIES);
+    const now = options?.now ?? new Date();
+    const noun = shown.length === 1 ? "memory" : "memories";
+    const items = shown.map((entry) => renderEntry(entry, now)).join(", ");
+    return `🧠 ByteRover returns ${shown.length} ${noun}: ${items}`;
+}
+function renderEntry(entry, now) {
+    if (!entry.age)
+        return entry.path;
+    const elapsedMs = now.getTime() - entry.age.getTime();
+    // Defensive: future-dated entries (clock skew, bad frontmatter) get rendered without an age tag
+    // rather than something nonsensical like "-5d ago".
+    if (elapsedMs < 0)
+        return entry.path;
+    return `${entry.path} (${humanizeAge(elapsedMs)})`;
+}
+function humanizeAge(elapsedMs) {
+    const days = Math.floor(elapsedMs / MS_PER_DAY);
+    if (days < 1)
+        return "today";
+    if (days < 7)
+        return `${days}d ago`;
+    if (days < 30)
+        return `${Math.floor(days / 7)}w ago`;
+    if (days < 365)
+        return `${Math.floor(days / 30)}mo ago`;
+    return `${Math.floor(days / 365)}y ago`;
+}
+//# sourceMappingURL=build-visible-summary.js.map

package/dist/cli.js

@@ -1,20 +1,45 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { program } from "commander";
 import { registerInstallCommand } from "./commands/install.js";
+import { registerInstallStatuslineCommand } from "./commands/install-statusline.js";
 import { registerUninstallCommand } from "./commands/uninstall.js";
+import { registerUninstallStatuslineCommand } from "./commands/uninstall-statusline.js";
 import { registerIngestCommand } from "./commands/ingest.js";
 import { registerSyncCommand } from "./commands/sync.js";
 import { registerRecallCommand } from "./commands/recall.js";
+import { registerStatusCommand } from "./commands/status.js";
 import { registerDoctorCommand } from "./commands/doctor.js";
+function readPackageVersion() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (typeof pkg === "object" &&
+            pkg !== null &&
+            "version" in pkg &&
+            typeof pkg.version === "string") {
+            return pkg.version;
+        }
+    }
+    catch {
+        // Best-effort — return fallback
+    }
+    return "unknown";
+}
 program
     .name("brv-claude-plugin")
     .description("Native bridge between ByteRover context engine and Claude Code auto-memory")
-    .version("0.1.0");
+    .version(readPackageVersion());
 registerInstallCommand(program);
+registerInstallStatuslineCommand(program);
 registerUninstallCommand(program);
+registerUninstallStatuslineCommand(program);
 registerIngestCommand(program);
 registerSyncCommand(program);
 registerRecallCommand(program);
+registerStatusCommand(program);
 registerDoctorCommand(program);
 program.parse();
 //# sourceMappingURL=cli.js.map

package/dist/commands/doctor.js

@@ -5,6 +5,7 @@ import pc from "picocolors";
 import { isBridgeHook, resolveBridgeExecutable } from "../bridge-command.js";
 import { getCcMemoryDir, getClaudeConfigHome } from "../memory-path.js";
 import { readSettingsRaw } from "../schemas/cc-settings.js";
+import { diagnoseStatuslineConflict } from "./install-statusline.js";
 export function registerDoctorCommand(program) {
     program
         .command("doctor")
@@ -94,7 +95,43 @@ export function registerDoctorCommand(program) {
                 detail: err instanceof Error ? err.message : String(err),
             });
         }
-        // 6. cc memory dir resolves
+        // 6. Status line registered (opt-in)
+        if (settingsValid) {
+            const settings = readSettingsRaw(settingsPath);
+            const slState = diagnoseStatuslineConflict(settings);
+            if (slState === "ours") {
+                results.push({
+                    label: "Status line",
+                    pass: true,
+                    detail: "registered, points to our binary",
+                });
+            }
+            else if (slState === "absent") {
+                results.push({
+                    label: "Status line",
+                    pass: false,
+                    detail: "not installed (run `brv-claude-plugin install-statusline` to enable)",
+                    optional: true,
+                });
+            }
+            else {
+                results.push({
+                    label: "Status line",
+                    pass: false,
+                    detail: "another statusLine is configured (run `brv-claude-plugin install-statusline --force` to overwrite)",
+                    optional: true,
+                });
+            }
+        }
+        else {
+            results.push({
+                label: "Status line",
+                pass: false,
+                detail: "cannot check — settings invalid",
+                optional: true,
+            });
+        }
+        // 7. cc memory dir resolves
         try {
             const memDir = getCcMemoryDir(cwd);
             const memExists = existsSync(memDir);
@@ -120,7 +157,7 @@ export function registerDoctorCommand(program) {
             const icon = r.pass ? pc.green("\u2713") : pc.red("\u2717");
             const detail = r.detail ? pc.dim(` — ${r.detail}`) : "";
             console.log(`  ${icon} ${r.label}${detail}`);
-            if (!r.pass)
+            if (!r.pass && !r.optional)
                 allPass = false;
         }
         console.log();

package/dist/commands/install-statusline.d.ts

@@ -0,0 +1,19 @@
+import type { Command } from "commander";
+export type StatuslineConflictState = "absent" | "ours" | "foreign";
+/**
+ * Inspect a settings.json object and classify the existing `statusLine` entry:
+ *   - "absent":  no `statusLine` field
+ *   - "ours":    `statusLine.command` carries our bridge marker
+ *   - "foreign": some other statusLine is configured (or malformed)
+ */
+export declare function diagnoseStatuslineConflict(settings: Record<string, unknown>): StatuslineConflictState;
+/**
+ * Set our `statusLine` entry on a settings object. Padding is intentionally
+ * omitted so Claude Code's default applies. `refreshInterval` is set so the
+ * line reflects daemon-side state changes (curate, dream) that happen while
+ * the assistant is mid-tool-call — Claude Code's event triggers don't fire
+ * during those windows. Mutates and returns `settings`.
+ */
+export declare function setStatuslineEntry(settings: Record<string, unknown>, command: string): Record<string, unknown>;
+export declare function registerInstallStatuslineCommand(program: Command): void;
+export declare function isPromptCancelled(err: unknown): boolean;