@byterover/claude-plugin 1.0.0 → 1.1.0

package/dist/commands/install-statusline.js

@@ -0,0 +1,124 @@
+import { join } from "node:path";
+import { select } from "@inquirer/prompts";
+import pc from "picocolors";
+import { buildHookCommand, isBridgeHook, resolveBridgeExecutable, } from "../bridge-command.js";
+import { getClaudeConfigHome } from "../memory-path.js";
+import { backupSettings, readSettingsRaw, writeSettingsRaw, } from "../schemas/cc-settings.js";
+/**
+ * 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 function diagnoseStatuslineConflict(settings) {
+    const sl = settings.statusLine;
+    if (sl === undefined)
+        return "absent";
+    if (typeof sl === "object" && sl !== null) {
+        const obj = sl;
+        if (typeof obj.command === "string" && isBridgeHook({ command: obj.command })) {
+            return "ours";
+        }
+    }
+    return "foreign";
+}
+/** Re-run cadence (seconds) on top of Claude Code's event-driven triggers. */
+const REFRESH_INTERVAL_SECONDS = 5;
+/**
+ * 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 function setStatuslineEntry(settings, command) {
+    settings.statusLine = {
+        type: "command",
+        command,
+        refreshInterval: REFRESH_INTERVAL_SECONDS,
+    };
+    return settings;
+}
+export function registerInstallStatuslineCommand(program) {
+    program
+        .command("install-statusline")
+        .description("Install the byterover status line into Claude Code (opt-in)")
+        .option("--dry-run", "Show what would be written without modifying files")
+        .option("--force", "Overwrite an existing foreign statusLine without prompting")
+        .option("--settings-path <path>", "Override path to Claude Code settings.json")
+        .action(async (opts) => {
+        try {
+            const exe = resolveBridgeExecutable();
+            console.log(pc.dim(`Resolved executable: ${exe}`));
+            const settingsPath = opts.settingsPath ?? join(getClaudeConfigHome(), "settings.json");
+            const settings = readSettingsRaw(settingsPath);
+            const state = diagnoseStatuslineConflict(settings);
+            const command = buildHookCommand("status");
+            if (state === "ours") {
+                // Compare current entry to what we'd write. If identical, no-op.
+                // If our shape has drifted (e.g. plugin upgrade added refreshInterval),
+                // upgrade in place — backup + rewrite.
+                const expected = { type: "command", command, refreshInterval: REFRESH_INTERVAL_SECONDS };
+                if (JSON.stringify(settings.statusLine) === JSON.stringify(expected)) {
+                    console.log(pc.yellow("Status line already installed. No changes made."));
+                    return;
+                }
+                // Falls through to write path below — the install message will read "upgraded".
+            }
+            if (state === "foreign") {
+                const decision = await resolveForeignConflict(opts);
+                if (decision === "abort") {
+                    console.log(pc.yellow("Aborted. Existing statusLine left in place."));
+                    process.exit(1);
+                }
+                if (decision === "keep") {
+                    console.log(pc.yellow("Keeping existing statusLine. No changes made."));
+                    return;
+                }
+                // decision === "replace" — fall through
+            }
+            setStatuslineEntry(settings, command);
+            if (opts.dryRun) {
+                console.log(pc.cyan("Dry run — would write:"));
+                console.log(JSON.stringify(settings, null, 2));
+                return;
+            }
+            const backupPath = backupSettings(settingsPath);
+            console.log(pc.dim(`Backup: ${backupPath}`));
+            writeSettingsRaw(settingsPath, settings);
+            console.log(pc.green(`Installed status line into ${settingsPath}`));
+            console.log(pc.dim(`Command: ${command}`));
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(pc.yellow("\nAborted."));
+                process.exit(1);
+            }
+            console.error(pc.red(`Install failed: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+}
+async function resolveForeignConflict(opts) {
+    if (opts.force)
+        return "replace";
+    if (!process.stdin.isTTY) {
+        console.error(pc.red("An existing statusLine is configured. Re-run with --force to overwrite, " +
+            "or remove it first."));
+        process.exit(1);
+    }
+    return select({
+        message: "An existing statusLine is configured. What should I do?",
+        choices: [
+            { name: "Abort — leave it alone (default)", value: "abort" },
+            { name: "Keep existing — install nothing", value: "keep" },
+            { name: "Replace with byterover's status line", value: "replace" },
+        ],
+        default: "abort",
+    });
+}
+export function isPromptCancelled(err) {
+    return (err instanceof Error &&
+        (err.name === "ExitPromptError" || err.message.includes("force closed")));
+}
+//# sourceMappingURL=install-statusline.js.map

package/dist/commands/install.js

@@ -72,8 +72,7 @@ export function registerInstallCommand(program) {
             // Validate executable resolves before touching settings
             const exe = resolveBridgeExecutable();
             console.log(pc.dim(`Resolved executable: ${exe}`));
-            const settingsPath = opts.settingsPath ??
-                join(getClaudeConfigHome(), "settings.json");
+            const settingsPath = opts.settingsPath ?? join(getClaudeConfigHome(), "settings.json");
             const settings = readSettingsRaw(settingsPath);
             // Ensure hooks object exists
             if (!settings.hooks || typeof settings.hooks !== "object") {
@@ -119,7 +118,7 @@ export function registerInstallCommand(program) {
             console.log(pc.dim(`Backup: ${backupPath}`));
             writeSettingsRaw(settingsPath, settings);
             console.log(pc.green(`Installed ${added} hook(s) into ${settingsPath}`));
-            console.log(pc.dim("Hooks: PostToolUse(Write), PostToolUse(Edit), Stop"));
+            console.log(pc.dim("Hooks: PostToolUse(Write), PostToolUse(Edit), Stop, UserPromptSubmit"));
         }
         catch (err) {
             console.error(pc.red(`Install failed: ${err instanceof Error ? err.message : String(err)}`));

package/dist/commands/recall.js

@@ -1,4 +1,5 @@
 import { BrvBridge } from "@byterover/brv-bridge";
+import { buildRecallOutput } from "../build-recall-output.js";
 import { UserPromptSubmitHookInputSchema } from "../schemas/cc-hook-input.js";
 import { readStdinJson } from "../stdin.js";
 export function registerRecallCommand(program) {
@@ -13,22 +14,16 @@ export function registerRecallCommand(program) {
             if (prompt.trim().length < 5) {
                 process.exit(0);
             }
-            // Query ByteRover with the actual user prompt
+            // Query ByteRover with the actual user prompt. Newer brv CLIs return
+            // matchedDocs/tier/timing alongside content; older CLIs return content only, and
+            // buildRecallOutput falls back to parsing the **Sources** block in that case.
             const bridge = new BrvBridge({ cwd, recallTimeoutMs: 6_000 });
-            const { content } = await bridge.recall(prompt);
-            if (!content) {
+            const { content, matchedDocs } = await bridge.recall(prompt);
+            const output = buildRecallOutput({ content, matchedDocs, cwd });
+            if (!output) {
+                // No content retrieved — exit silently without injecting anything.
                 process.exit(0);
             }
-            // Return additionalContext wrapped in hookSpecificOutput for Claude Code
-            const output = {
-                hookSpecificOutput: {
-                    hookEventName: "UserPromptSubmit",
-                    additionalContext: `<byterover-context>\n` +
-                        `The following knowledge is from ByteRover context engine:\n\n` +
-                        `${content}\n` +
-                        `</byterover-context>`,
-                },
-            };
             console.log(JSON.stringify(output));
             process.exit(0);
         }

package/dist/commands/status.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+/**
+ * Given a parsed Claude Code status payload (or any value), return the line to
+ * print on stdout, or `""` when no `.brv/` project is reachable from the
+ * resolved cwd. Empty stdout tells Claude Code to hide the status line.
+ *
+ * `input` is `unknown` so empty/malformed stdin is graceful — when the value
+ * is not a usable object, we fall back to `process.cwd()`.
+ */
+export declare function produceStatusLine(input: unknown): string;
+export declare function registerStatusCommand(program: Command): void;

package/dist/commands/status.js

@@ -0,0 +1,61 @@
+import { formatStatusLine } from "../format-status-line.js";
+import { detectState, findBrvDir } from "../state-detector.js";
+/**
+ * Given a parsed Claude Code status payload (or any value), return the line to
+ * print on stdout, or `""` when no `.brv/` project is reachable from the
+ * resolved cwd. Empty stdout tells Claude Code to hide the status line.
+ *
+ * `input` is `unknown` so empty/malformed stdin is graceful — when the value
+ * is not a usable object, we fall back to `process.cwd()`.
+ */
+export function produceStatusLine(input) {
+    const cwd = resolveCwd(input);
+    const brvDir = findBrvDir(cwd);
+    if (brvDir === undefined)
+        return "";
+    return formatStatusLine(detectState(brvDir, cwd));
+}
+function resolveCwd(input) {
+    if (typeof input === "object" && input !== null) {
+        const obj = input;
+        const workspace = obj.workspace;
+        if (typeof workspace === "object" && workspace !== null) {
+            const wsDir = workspace.current_dir;
+            if (typeof wsDir === "string" && wsDir.length > 0)
+                return wsDir;
+        }
+        if (typeof obj.cwd === "string" && obj.cwd.length > 0)
+            return obj.cwd;
+    }
+    return process.cwd();
+}
+export function registerStatusCommand(program) {
+    program
+        .command("status")
+        .description("Print the byterover status line for Claude Code (reads CC status payload from stdin)")
+        .action(async () => {
+        const raw = await readAllStdin();
+        let input;
+        try {
+            input = raw ? JSON.parse(raw) : undefined;
+        }
+        catch {
+            input = undefined;
+        }
+        const line = produceStatusLine(input);
+        if (line.length > 0) {
+            process.stdout.write(line + "\n");
+        }
+        process.exit(0);
+    });
+}
+async function readAllStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8").trim();
+}
+//# sourceMappingURL=status.js.map

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

@@ -0,0 +1,8 @@
+import type { Command } from "commander";
+/**
+ * Remove the `statusLine` entry from a settings object only when it carries
+ * our bridge marker. Returns true when removed, false otherwise (foreign
+ * statusLines are left alone). Mutates `settings`.
+ */
+export declare function removeOurStatusline(settings: Record<string, unknown>): boolean;
+export declare function registerUninstallStatuslineCommand(program: Command): void;

package/dist/commands/uninstall-statusline.js

@@ -0,0 +1,54 @@
+import { join } from "node:path";
+import pc from "picocolors";
+import { isBridgeHook } from "../bridge-command.js";
+import { getClaudeConfigHome } from "../memory-path.js";
+import { backupSettings, readSettingsRaw, writeSettingsRaw, } from "../schemas/cc-settings.js";
+/**
+ * Remove the `statusLine` entry from a settings object only when it carries
+ * our bridge marker. Returns true when removed, false otherwise (foreign
+ * statusLines are left alone). Mutates `settings`.
+ */
+export function removeOurStatusline(settings) {
+    const sl = settings.statusLine;
+    if (sl === undefined)
+        return false;
+    if (typeof sl !== "object" || sl === null)
+        return false;
+    const obj = sl;
+    if (typeof obj.command !== "string")
+        return false;
+    if (!isBridgeHook({ command: obj.command }))
+        return false;
+    delete settings.statusLine;
+    return true;
+}
+export function registerUninstallStatuslineCommand(program) {
+    program
+        .command("uninstall-statusline")
+        .description("Remove the byterover status line from Claude Code settings (leaves foreign statusLines alone)")
+        .option("--settings-path <path>", "Override path to Claude Code settings.json")
+        .action(async (opts) => {
+        try {
+            const settingsPath = opts.settingsPath ?? join(getClaudeConfigHome(), "settings.json");
+            const settings = readSettingsRaw(settingsPath);
+            const removed = removeOurStatusline(settings);
+            if (!removed) {
+                if (settings.statusLine !== undefined) {
+                    console.log(pc.yellow("Existing statusLine is not ours. Leaving it untouched."));
+                }
+                else {
+                    console.log(pc.yellow("No status line installed. Nothing to remove."));
+                }
+                return;
+            }
+            backupSettings(settingsPath);
+            writeSettingsRaw(settingsPath, settings);
+            console.log(pc.green(`Removed status line from ${settingsPath}`));
+        }
+        catch (err) {
+            console.error(pc.red(`Uninstall failed: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=uninstall-statusline.js.map

package/dist/commands/uninstall.js

@@ -3,6 +3,7 @@ import pc from "picocolors";
 import { isBridgeHook } from "../bridge-command.js";
 import { getClaudeConfigHome } from "../memory-path.js";
 import { backupSettings, readSettingsRaw, writeSettingsRaw, } from "../schemas/cc-settings.js";
+import { removeOurStatusline } from "./uninstall-statusline.js";
 export function registerUninstallCommand(program) {
     program
         .command("uninstall")
@@ -14,54 +15,59 @@ export function registerUninstallCommand(program) {
                 join(getClaudeConfigHome(), "settings.json");
             const settings = readSettingsRaw(settingsPath);
             const hooks = settings.hooks;
-            if (!hooks || typeof hooks !== "object") {
-                console.log(pc.yellow("No hooks found in settings. Nothing to remove."));
-                return;
-            }
             let removed = 0;
-            for (const event of Object.keys(hooks)) {
-                const eventHooks = hooks[event];
-                if (!Array.isArray(eventHooks))
-                    continue;
-                // Per-hook removal: within each matcher entry, remove only bridge hooks
-                for (let i = eventHooks.length - 1; i >= 0; i--) {
-                    const matcherEntry = eventHooks[i];
-                    const innerHooks = matcherEntry.hooks;
-                    if (!Array.isArray(innerHooks))
+            if (hooks && typeof hooks === "object") {
+                for (const event of Object.keys(hooks)) {
+                    const eventHooks = hooks[event];
+                    if (!Array.isArray(eventHooks))
                         continue;
-                    const filtered = innerHooks.filter((h) => {
-                        if (typeof h === "object" &&
-                            h !== null &&
-                            isBridgeHook(h)) {
-                            removed++;
-                            return false;
+                    // Per-hook removal: within each matcher entry, remove only bridge hooks
+                    for (let i = eventHooks.length - 1; i >= 0; i--) {
+                        const matcherEntry = eventHooks[i];
+                        const innerHooks = matcherEntry.hooks;
+                        if (!Array.isArray(innerHooks))
+                            continue;
+                        const filtered = innerHooks.filter((h) => {
+                            if (typeof h === "object" &&
+                                h !== null &&
+                                isBridgeHook(h)) {
+                                removed++;
+                                return false;
+                            }
+                            return true;
+                        });
+                        if (filtered.length === 0) {
+                            // All hooks in this matcher entry were bridge hooks — remove the entry
+                            eventHooks.splice(i, 1);
+                        }
+                        else {
+                            matcherEntry.hooks = filtered;
                         }
-                        return true;
-                    });
-                    if (filtered.length === 0) {
-                        // All hooks in this matcher entry were bridge hooks — remove the entry
-                        eventHooks.splice(i, 1);
                     }
-                    else {
-                        matcherEntry.hooks = filtered;
+                    // Clean up empty event arrays
+                    if (eventHooks.length === 0) {
+                        delete hooks[event];
                     }
                 }
-                // Clean up empty event arrays
-                if (eventHooks.length === 0) {
-                    delete hooks[event];
+                // Clean up empty hooks object
+                if (Object.keys(hooks).length === 0) {
+                    delete settings.hooks;
                 }
             }
-            // Clean up empty hooks object
-            if (Object.keys(hooks).length === 0) {
-                delete settings.hooks;
-            }
-            if (removed === 0) {
-                console.log(pc.yellow("No bridge hooks found. Nothing to remove."));
+            // Also remove our statusLine entry (foreign statusLines are left alone).
+            const statuslineRemoved = removeOurStatusline(settings);
+            if (removed === 0 && !statuslineRemoved) {
+                console.log(pc.yellow("No bridge hooks or status line found. Nothing to remove."));
                 return;
             }
             backupSettings(settingsPath);
             writeSettingsRaw(settingsPath, settings);
-            console.log(pc.green(`Removed ${removed} bridge hook(s) from ${settingsPath}`));
+            const summary = [];
+            if (removed > 0)
+                summary.push(`${removed} bridge hook(s)`);
+            if (statuslineRemoved)
+                summary.push("status line");
+            console.log(pc.green(`Removed ${summary.join(" + ")} from ${settingsPath}`));
         }
         catch (err) {
             console.error(pc.red(`Uninstall failed: ${err instanceof Error ? err.message : String(err)}`));

package/dist/format-status-line.d.ts

@@ -0,0 +1,2 @@
+import type { BrvState } from "./state-detector.js";
+export declare function formatStatusLine(state: BrvState): string;

package/dist/format-status-line.js

@@ -0,0 +1,21 @@
+// ANSI escape sequences scoped to the state suffix only — the
+// `🧠 ByteRover · ` brand prefix stays neutral. Raw escape codes (no
+// picocolors) because picocolors disables colors on non-TTY stdout, but
+// Claude Code reads our stdout from a piped context and renders the ANSI
+// in its own TTY panel.
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+const BRAND_PREFIX = "🧠 ByteRover · ";
+export function formatStatusLine(state) {
+    switch (state) {
+        case "idle":
+            return BRAND_PREFIX + DIM + "idle" + RESET;
+        case "curating":
+            return BRAND_PREFIX + YELLOW + "📝 curating" + RESET;
+        case "dreaming":
+            return BRAND_PREFIX + CYAN + "💭 dreaming" + RESET;
+    }
+}
+//# sourceMappingURL=format-status-line.js.map

package/dist/parse-sources.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Plugin-only fallback for extracting source paths from a synthesized recall response.
+ *
+ * Used when the brv CLI does not surface `matchedDocs` in the
+ * `brv query --format json` envelope. All five resolution tiers in the CLI emit a
+ * `**Sources**:` block in the synthesized content (the format is locked in by the
+ * synthesis prompt's `responseFormat` rules and grounding rules), so we can recover paths
+ * by parsing the content. When the CLI is current we use `matchedDocs` directly and skip
+ * this parser entirely.
+ *
+ * Returns an empty array on any of:
+ * - No `**Sources**:` block at all
+ * - `**Sources**: None` (Tier 2 not-found)
+ * - Block exists but contains no extractable list items
+ */
+export declare function parseSourcesFromContent(content: string): string[];

package/dist/parse-sources.js

@@ -0,0 +1,46 @@
+/**
+ * Plugin-only fallback for extracting source paths from a synthesized recall response.
+ *
+ * Used when the brv CLI does not surface `matchedDocs` in the
+ * `brv query --format json` envelope. All five resolution tiers in the CLI emit a
+ * `**Sources**:` block in the synthesized content (the format is locked in by the
+ * synthesis prompt's `responseFormat` rules and grounding rules), so we can recover paths
+ * by parsing the content. When the CLI is current we use `matchedDocs` directly and skip
+ * this parser entirely.
+ *
+ * Returns an empty array on any of:
+ * - No `**Sources**:` block at all
+ * - `**Sources**: None` (Tier 2 not-found)
+ * - Block exists but contains no extractable list items
+ */
+const PREFIX_TO_STRIP = ".brv/context-tree/";
+// Capture from "**Sources**:" through the next blank-line-then-heading boundary OR end of string.
+// Backticked items are isolated by a non-greedy capture; non-list lines after Sources end the block.
+const SOURCES_BLOCK_REGEX = /\*\*Sources\*\*:\s*\n([\s\S]*?)(?:\n\s*\n|$)/;
+// Match list items with OR without backtick fencing — Tier 2 direct-search emits backticked paths
+// (`- \`path\``) but LLM-synthesised output in Tier 3/4 often drops the backticks (`- path`).
+// Backtick group is optional so both render the same captured path.
+const LIST_ITEM_REGEX = /^\s*-\s*`?([^`\n]+?)`?\s*$/gm;
+export function parseSourcesFromContent(content) {
+    if (!content)
+        return [];
+    const blockMatch = content.match(SOURCES_BLOCK_REGEX);
+    if (!blockMatch)
+        return [];
+    const block = blockMatch[1] ?? "";
+    // "Sources: None" inline (no list items) → empty
+    if (/^\s*None\s*$/i.test(block))
+        return [];
+    const paths = [];
+    for (const itemMatch of block.matchAll(LIST_ITEM_REGEX)) {
+        const raw = itemMatch[1] ?? "";
+        paths.push(stripPrefix(raw));
+    }
+    return paths;
+}
+function stripPrefix(path) {
+    return path.startsWith(PREFIX_TO_STRIP)
+        ? path.slice(PREFIX_TO_STRIP.length)
+        : path;
+}
+//# sourceMappingURL=parse-sources.js.map

package/dist/project-data-dir.d.ts

@@ -0,0 +1,7 @@
+export declare function getGlobalDataDir(): string;
+export declare function sanitizeProjectPath(resolvedPath: string): string;
+/**
+ * `<getGlobalDataDir()>/projects/<sanitizeProjectPath(realpath(cwd))>/`
+ * Throws if `cwd` does not exist (matches daemon's `realpathSync` semantics).
+ */
+export declare function getProjectDataDir(cwd: string): string;

package/dist/project-data-dir.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+/**
+ * Mirrors byterover-cli's project data dir resolution. Kept narrowly in sync
+ * with byterover-cli's `src/server/utils/path-utils.ts` and
+ * `src/server/utils/global-data-path.ts` so we can locate per-project artifacts
+ * (curate-log, query-log) the daemon writes outside the project's own `.brv/`.
+ *
+ * Daemon contract reproduced here:
+ *   <getGlobalDataDir()>/projects/<sanitizeProjectPath(realpath(cwd))>/
+ *
+ * If the daemon ever changes either function, this module must be updated in
+ * lockstep — there is no runtime contract enforcing parity.
+ */
+const GLOBAL_DATA_DIR = "brv";
+const GLOBAL_PROJECTS_DIR = "projects";
+const MAX_SANITIZED_LENGTH = 200;
+const HASH_SUFFIX_LENGTH = 12;
+const WINDOWS_ILLEGAL_CHARS = new Map([
+    ['"', "%22"],
+    ["*", "%2A"],
+    [":", "%3A"],
+    ["<", "%3C"],
+    [">", "%3E"],
+    ["?", "%3F"],
+    ["|", "%7C"],
+]);
+export function getGlobalDataDir() {
+    if (process.env.BRV_DATA_DIR !== undefined && process.env.BRV_DATA_DIR !== "") {
+        return process.env.BRV_DATA_DIR;
+    }
+    const p = platform();
+    if (p === "win32") {
+        const localAppData = process.env.LOCALAPPDATA;
+        if (localAppData !== undefined && localAppData !== "") {
+            return join(localAppData, GLOBAL_DATA_DIR);
+        }
+        return join(homedir(), "AppData", "Local", GLOBAL_DATA_DIR);
+    }
+    if (p === "darwin") {
+        return join(homedir(), "Library", "Application Support", GLOBAL_DATA_DIR);
+    }
+    if (p === "linux") {
+        const xdgDataHome = process.env.XDG_DATA_HOME;
+        if (xdgDataHome !== undefined && xdgDataHome !== "") {
+            return join(xdgDataHome, GLOBAL_DATA_DIR);
+        }
+    }
+    return join(homedir(), ".local", "share", GLOBAL_DATA_DIR);
+}
+export function sanitizeProjectPath(resolvedPath) {
+    const normalized = resolvedPath.replace(/^([A-Za-z]):/, "$1");
+    const components = normalized.split(/[/\\]+/).filter(Boolean);
+    const encoded = components.map((c) => {
+        let result = c.replaceAll("%", "%25").replaceAll("--", "%2D%2D");
+        for (const [char, replacement] of WINDOWS_ILLEGAL_CHARS) {
+            result = result.replaceAll(char, replacement);
+        }
+        return result;
+    });
+    const joined = encoded.join("--");
+    if (joined.length <= MAX_SANITIZED_LENGTH) {
+        return joined;
+    }
+    const hash = createHash("sha256")
+        .update(joined)
+        .digest("hex")
+        .slice(0, HASH_SUFFIX_LENGTH);
+    const prefixLength = MAX_SANITIZED_LENGTH - HASH_SUFFIX_LENGTH - 3;
+    return joined.slice(0, prefixLength) + "---" + hash;
+}
+/**
+ * `<getGlobalDataDir()>/projects/<sanitizeProjectPath(realpath(cwd))>/`
+ * Throws if `cwd` does not exist (matches daemon's `realpathSync` semantics).
+ */
+export function getProjectDataDir(cwd) {
+    const resolved = realpathSync(cwd);
+    return join(getGlobalDataDir(), GLOBAL_PROJECTS_DIR, sanitizeProjectPath(resolved));
+}
+//# sourceMappingURL=project-data-dir.js.map

package/dist/resolve-context-tree-age.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve the "age" of a context-tree document for the visible recall summary.
+ *
+ * Resolution order, falling through on any failure:
+ *   1. Frontmatter `updatedAt`   — standard topic files (post-curate timestamp)
+ *   2. Frontmatter `synthesized_at` — synthesis files produced by `brv dream`
+ *   3. Frontmatter `createdAt`   — older standard files that lack updatedAt
+ *   4. File `mtime`              — last resort for files without timestamp frontmatter
+ *   5. `undefined`               — file missing or path is a cross-project shared source
+ *
+ * Cross-project paths in the form `[alias]:relative/path.md` are not resolved here —
+ * they live in another project's `.brv/context-tree/`, which the plugin does not see.
+ */
+export declare function resolveContextTreeAge(projectRoot: string, relativePath: string): Date | undefined;