brainclaw 1.9.1 → 1.10.1

package/dist/commands/run-profile.js

@@ -37,8 +37,9 @@ export function runRunProfile(profileName, options = {}) {
             console.error(`Unknown agent: ${options.agent}. Using profile invoke template.`);
         }
     }
-    // Replace {prompt} placeholder with the profile prompt
-    const command = invoke.replace(/\{prompt\}/g, profile.prompt.replace(/"/g, '\\"'));
+    // Replace {prompt} placeholder with the profile prompt. Escape backslashes
+    // before quotes so a backslash in the prompt can't break out of the quoting.
+    const command = invoke.replace(/\{prompt\}/g, profile.prompt.replace(/\\/g, '\\\\').replace(/"/g, '\\"'));
     if (options.dry) {
         console.log(`[dry-run] Profile: ${profile.name}`);
         console.log(`[dry-run] Command: ${command}`);

package/dist/commands/sequence.js

@@ -11,7 +11,7 @@ function parseItems(raw) {
         parsed = JSON.parse(raw);
     }
     catch (error) {
-        throw new Error(`Invalid --items JSON: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Invalid --items JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
     if (!Array.isArray(parsed)) {
         throw new Error('Invalid --items JSON: expected an array');

package/dist/commands/switch.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { loadActiveProject, saveActiveProject, clearActiveProject } from '../core/active-project.js';
-import { buildOperationalIdentity, loadCurrentSession, loadSessionById, saveCurrentSession } from '../core/identity.js';
+import { buildOperationalIdentity, loadCurrentSession, loadSessionById, resolveCurrentSessionId, saveCurrentSession } from '../core/identity.js';
 import { memoryExists } from '../core/io.js';
 import { resolveProjectRef } from '../core/store-resolution.js';
 import { resolveCrossProjectLinks, resolveProjectCwd } from '../core/cross-project.js';
@@ -160,59 +160,70 @@ export function runSwitch(projectRef, options = {}) {
     }
     // --list: show available projects
     if (options.list) {
-        listProjects(wsRoot, options.json ?? false);
+        listProjects(wsRoot, cwd, options.json ?? false);
         return;
     }
-    // --clear: remove active project
+    // --clear: remove active project. Session-scoped by default (F3) — clearing
+    // the SHARED global pointer is an opt-in (--global) so one agent's clear no
+    // longer wipes every other agent's resolution.
     if (options.clear) {
-        const session = loadCurrentSession(cwd);
-        if (session?.active_project) {
-            const { active_project: _removed, ...rest } = session;
-            saveCurrentSession(rest, cwd);
+        let scope;
+        if (options.global) {
+            clearActiveProject(wsRoot);
+            scope = 'global';
+        }
+        else {
+            const session = loadCurrentSession(cwd);
+            if (session?.active_project) {
+                const { active_project: _removed, ...rest } = session;
+                saveCurrentSession(rest, cwd);
+            }
+            scope = 'session';
         }
-        clearActiveProject(wsRoot);
         if (options.json) {
-            console.log(JSON.stringify({ cleared: true }));
+            console.log(JSON.stringify({ cleared: true, scope }));
         }
         else {
-            console.log('✔ Active project cleared. Commands will use current directory.');
+            const hint = scope === 'session' ? ' (session-scoped)' : ' (global)';
+            console.log(`✔ Active project cleared${hint}. Commands will use current directory.`);
         }
         return;
     }
     // No argument: show current active project
     if (!projectRef) {
-        showCurrent(wsRoot, options.json ?? false);
+        showCurrent(wsRoot, cwd, options.json ?? false);
         return;
     }
     // Switch to project
-    const resolved = resolveProjectRef(projectRef, cwd);
-    if (!resolved) {
-        console.error(`Error: cannot resolve project "${projectRef}".`);
-        console.error('Use `brainclaw switch --list` to see available projects.');
-        process.exit(1);
-    }
-    let projectName;
-    try {
-        const config = loadConfig(resolved);
-        projectName = config.project_name;
-    }
-    catch {
-        // name is optional
-    }
     const now = new Date().toISOString();
-    const session = loadCurrentSession(cwd);
-    const scopedToSession = options.session ?? !!session;
     let scope;
-    if (scopedToSession && session) {
-        // Write to session state — only this agent sees this switch
-        saveCurrentSession({
-            ...session,
-            active_project: { path: resolved, name: projectName, switched_at: now },
-        }, cwd);
-        scope = 'session';
-    }
-    else {
-        // Fall back to global active-project.json
+    let switchedPath;
+    let switchedName;
+    if (options.global) {
+        // Opt-in, audited: set the SHARED workspace default for every agent on the
+        // host. Bypasses the session entirely (an operator setting a default).
+        // Resolve store-chain children AND cross-project links (mirror switchProject)
+        // so `switch <linked> --global` matches what --list shows and what the
+        // session path can target (Codex final review F3-F5 finding).
+        let resolved = resolveProjectRef(projectRef, cwd);
+        if (!resolved) {
+            try {
+                const linkResolved = resolveProjectCwd(projectRef, cwd);
+                if (linkResolved !== cwd)
+                    resolved = linkResolved;
+            }
+            catch { /* falls through to the error below */ }
+        }
+        if (!resolved) {
+            console.error(`Error: cannot resolve project "${projectRef}".`);
+            console.error('Use `brainclaw switch --list` to see available projects.');
+            process.exit(1);
+        }
+        let projectName;
+        try {
+            projectName = loadConfig(resolved).project_name;
+        }
+        catch { /* name is optional */ }
         saveActiveProject(wsRoot, {
             path: resolved,
             name: projectName,
@@ -220,21 +231,47 @@ export function runSwitch(projectRef, options = {}) {
             switched_by: process.env.BRAINCLAW_AGENT_NAME ?? process.env.USER ?? 'unknown',
         });
         scope = 'global';
+        switchedPath = resolved;
+        switchedName = projectName;
+    }
+    else {
+        // F3 default: session-scoped + isolated. Delegate to switchProject — the
+        // safe model that auto-creates the session, honours an explicit
+        // BRAINCLAW_SESSION_ID (resolveCurrentSessionId returns it WITHOUT
+        // persisting, so the session file must be created), resolves cross-project
+        // links, and never touches the shared global pointer.
+        try {
+            const explicitSessionId = resolveCurrentSessionId(process.env, cwd) || undefined;
+            const result = switchProject(projectRef, { cwd, sessionOnly: true, sessionId: explicitSessionId });
+            scope = 'session';
+            switchedPath = result.path;
+            switchedName = result.name;
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            console.error('Use `brainclaw switch --list` to see available projects.');
+            process.exit(1);
+        }
     }
     if (options.json) {
-        console.log(JSON.stringify({ switched: true, path: resolved, name: projectName, scope }));
+        console.log(JSON.stringify({ switched: true, path: switchedPath, name: switchedName, scope }));
     }
     else {
-        const rel = path.relative(wsRoot, resolved) || '.';
-        const scopeHint = scope === 'session' ? ' (session-scoped)' : '';
-        console.log(`✔ Switched to ${projectName ? `"${projectName}" (${rel})` : rel}${scopeHint}`);
+        const rel = path.relative(wsRoot, switchedPath) || '.';
+        const scopeHint = scope === 'session' ? ' (session-scoped)' : ' (global — all agents)';
+        console.log(`✔ Switched to ${switchedName ? `"${switchedName}" (${rel})` : rel}${scopeHint}`);
     }
 }
-function showCurrent(wsRoot, json) {
-    const active = loadActiveProject(wsRoot);
+function showCurrent(wsRoot, cwd, json) {
+    // F5: prefer the session's own active project so an agent sees its own
+    // session-scoped switch, not just the shared global pointer.
+    const sessionActive = loadCurrentSession(cwd)?.active_project;
+    const globalActive = loadActiveProject(wsRoot);
+    const active = sessionActive ?? globalActive;
+    const source = sessionActive ? 'session' : globalActive ? 'global' : 'none';
     if (!active) {
         if (json) {
-            console.log(JSON.stringify({ active: false }));
+            console.log(JSON.stringify({ active: false, scope: 'none' }));
         }
         else {
             console.log('No active project. Commands use current directory.');
@@ -243,67 +280,41 @@ function showCurrent(wsRoot, json) {
         return;
     }
     const rel = path.relative(wsRoot, active.path) || '.';
+    const switchedBy = 'switched_by' in active ? active.switched_by : undefined;
     if (json) {
-        console.log(JSON.stringify({ active: true, ...active, relative_path: rel }));
+        console.log(JSON.stringify({ active: true, ...active, relative_path: rel, scope: source }));
     }
     else {
-        console.log(`Active project: ${active.name ? `"${active.name}" (${rel})` : rel}`);
+        const scopeHint = source === 'session' ? ' (session-scoped)' : ' (global — all agents)';
+        console.log(`Active project: ${active.name ? `"${active.name}" (${rel})` : rel}${scopeHint}`);
         console.log(`  switched at: ${active.switched_at}`);
-        if (active.switched_by)
-            console.log(`  switched by: ${active.switched_by}`);
+        if (switchedBy)
+            console.log(`  switched by: ${switchedBy}`);
     }
 }
-function listProjects(wsRoot, json) {
-    const active = loadActiveProject(wsRoot);
-    const projects = [];
-    // Add workspace root itself
-    if (memoryExists(wsRoot)) {
-        try {
-            const config = loadConfig(wsRoot);
-            projects.push({
-                name: config.project_name,
-                path: wsRoot,
-                relative_path: '.',
-                active: active?.path === wsRoot,
-            });
-        }
-        catch {
-            projects.push({
-                path: wsRoot,
-                relative_path: '.',
-                active: active?.path === wsRoot,
-            });
-        }
-    }
-    // Discover child projects (depth 7 covers deep workspace layouts like /srv/dev/repos/global/applications/*/...)
-    const children = scanNestedBrainclawProjects(wsRoot, 7);
-    for (const child of children) {
-        const childPath = path.resolve(child.path);
-        if (childPath === wsRoot)
-            continue;
-        const rel = path.relative(wsRoot, childPath) || '.';
-        projects.push({
-            name: child.project_name,
-            path: childPath,
-            relative_path: rel,
-            active: active?.path === childPath,
-        });
-    }
+function listProjects(wsRoot, cwd, json) {
+    // F5: delegate to the session-aware lister so the active marker reflects the
+    // agent's own session active project, falling back to the global pointer.
+    const result = listAvailableProjectsForSession(cwd);
     if (json) {
-        console.log(JSON.stringify({ workspace: wsRoot, projects }, null, 2));
+        console.log(JSON.stringify({
+            workspace: result.workspace_root,
+            active_source: result.active_source,
+            projects: result.projects,
+        }, null, 2));
         return;
     }
-    if (projects.length === 0) {
+    if (result.projects.length === 0) {
         console.log('No brainclaw projects found in this workspace.');
         return;
     }
-    console.log(`Projects in ${wsRoot}:\n`);
-    for (const p of projects) {
+    console.log(`Projects in ${result.workspace_root}:\n`);
+    for (const p of result.projects) {
         const marker = p.active ? '→ ' : '  ';
         const name = p.name ? `${p.name} (${p.relative_path})` : p.relative_path;
         console.log(`${marker}${name}`);
     }
-    if (!active) {
+    if (result.active_source === 'none') {
         console.log('\nNo active project. Use `brainclaw switch <project>` to set one.');
     }
 }

package/dist/commands/sync.js

@@ -61,7 +61,7 @@ export function runSync(options = {}) {
         return;
     }
     // Check git status of .brainclaw/
-    let gitStatus = '';
+    let gitStatus;
     try {
         // Security: execFileSync (no shell) + scopePaths spread as separate args so
         // path specs cannot inject (Socket 2026-06-08 class).

package/dist/commands/upgrade.js

@@ -463,13 +463,6 @@ function upsertSection(existingContent, section) {
     const trimmed = existingContent.trimEnd();
     return trimmed.length > 0 ? `${trimmed}\n\n${section}\n` : `${section}\n`;
 }
-function listJsonFiles(dir) {
-    if (!fs.existsSync(dir))
-        return [];
-    return fs.readdirSync(dir)
-        .filter(f => f.endsWith('.json'))
-        .map(f => path.join(dir, f));
-}
 function listJsonFilesRecursive(dir) {
     if (!fs.existsSync(dir))
         return [];

package/dist/core/agent-context.js

@@ -63,7 +63,7 @@ function readAgentsMarkdown(cwd) {
     // Only extract rules from actionable sections, not from descriptive sections
     // like "why this matters" which contain explanatory bullets, not instructions.
     const SKIP_SECTIONS = /why this matters|what it provides|what brainclaw/i;
-    let currentSection = '';
+    let currentSection;
     let skipSection = false;
     const rules = [];
     for (const line of lines) {

package/dist/core/agent-files.js

@@ -24,6 +24,18 @@ This project uses brainclaw for shared coordination between humans and agents.
 2. Check **Your open work** for active claims and in-progress plans assigned to you
 3. Respect active claims from other agents — check \`brainclaw claim list\` before editing a claimed scope
 
+### Before editing unfamiliar code (Code Map)
+
+Don't grep the repo blind. Orient with the Code Map first:
+
+\`\`\`bash
+brainclaw code-map brief <symbol-or-path>   # ranked reading list + related decisions/traps (MCP: bclaw_code_brief)
+brainclaw code-map find <name>              # locate a symbol/class/component (MCP: bclaw_code_find)
+brainclaw code-map status                   # freshness
+brainclaw code-map refresh --all            # when status is missing_index
+brainclaw code-map refresh --changed        # when status is stale_*
+\`\`\`
+
 ### Before finishing (required)
 
 1. Release claims you opened: \`brainclaw claim release <id>\` — or \`brainclaw session-end --auto-release\`
@@ -1146,7 +1158,7 @@ export function ensureClaudeCodeCommand(cwd) {
         relativePath: CLAUDE_CODE_COMMAND_RELATIVE_PATH,
     };
 }
-export function ensureClaudeCodeUserSettings(homeDir, env = process.env) {
+export function ensureClaudeCodeUserSettings(homeDir, _env = process.env) {
     if (!homeDir)
         return undefined;
     const filePath = path.join(homeDir, '.claude', 'settings.json');
@@ -1618,7 +1630,6 @@ export function ensureCodexMcpConfig(homeDir, env = process.env) {
         const autoApprovedSet = new Set(getHeadlessAutoApprovedToolNames());
         const toolSectionRe = /^\[mcp_servers\.brainclaw\.tools\.([^\]]+)\]/gm;
         const approvalModeRe = /^\s*approval_mode\s*=\s*"([^"]+)"/m;
-        let m;
         const warnings = [];
         // Split into sections to check each tool block
         const lines = existing.split('\n');

package/dist/core/agent-integrations.js

@@ -160,8 +160,8 @@ export function extractMcpCommandVal(agentName, expectedPath) {
         return { is_valid: false };
     }
     if (expectedPath.endsWith('.toml')) {
-        const cmdMatch = content.match(/\[mcp_servers\.brainclaw\](?:[^\[]*)command\s*=\s*(["'])(.+?)\1/is);
-        const argsMatch = content.match(/\[mcp_servers\.brainclaw\](?:[^\[]*)args\s*=\s*\[(.+?)\]/is);
+        const cmdMatch = content.match(/\[mcp_servers\.brainclaw\](?:[^[]*)command\s*=\s*(["'])(.+?)\1/is);
+        const argsMatch = content.match(/\[mcp_servers\.brainclaw\](?:[^[]*)args\s*=\s*\[(.+?)\]/is);
         let args;
         if (argsMatch) {
             args = argsMatch[1]
@@ -274,7 +274,7 @@ export function assessAgentIntegrationReadiness(config, cwd, env = process.env)
         const surfaces = declaration.surfaces.map((surface) => surfaceExists(surface, cwd, env, declaration.agent_name));
         const missingSurfaces = surfaces.filter((surface) => !surface.exists);
         const driftingSurfaces = surfaces.filter((surface) => surface.drift_message != null);
-        let effectiveTier = 'tier-b';
+        let effectiveTier;
         const selfHealingGuidance = [];
         const hasMissingMcpOrHook = missingSurfaces.some((s) => s.kind === 'mcp' || s.kind === 'hook');
         const hasDriftingMcp = driftingSurfaces.some((s) => s.kind === 'mcp');

package/dist/core/agent-registry.js

@@ -275,7 +275,7 @@ export function registerAgentIdentity(input) {
     saveAgentIdentity(created, input.cwd, input.preferredDirName);
     return created;
 }
-export function resolveCurrentAgentIdentity(cwd, preferredDirName, homeDir) {
+export function resolveCurrentAgentIdentity(cwd, preferredDirName, _homeDir) {
     // env var takes priority over config — allows AI agent to self-identify
     const envAgentId = (process.env.BRAINCLAW_AGENT_ID ?? '').trim();
     const envAgentName = (process.env.BRAINCLAW_AGENT_NAME ?? process.env.BRAINCLAW_AGENT ?? '').trim();
@@ -537,7 +537,7 @@ export function resolveCurrentModel(cwd) {
  * Note: config.current_agent is intentionally NOT used here — it's a singleton
  * global that causes cross-agent confusion in multi-agent setups.
  */
-export function resolveCurrentAgentName(cwd, _homeDir) {
+export function resolveCurrentAgentName(_cwd, _homeDir) {
     const fromEnv = (process.env.BRAINCLAW_AGENT_NAME ?? process.env.BRAINCLAW_AGENT)?.trim();
     if (fromEnv)
         return fromEnv;

package/dist/core/assignments.js

@@ -1,3 +1,15 @@
+/**
+ * Assignment lifecycle — Agent SDK runtime protocol.
+ *
+ * An Assignment is the canonical coordination entity that tracks the full
+ * lifecycle of dispatched work: from creation through offer, acceptance,
+ * execution, and completion (or failure/timeout/reroute).
+ *
+ * Assignments reference Claims (scope lock) and InboxMessages (brief delivery)
+ * but don't replace them. They own the status FSM and heartbeat tracking.
+ *
+ * @module
+ */
 import fs from 'node:fs';
 import { AssignmentSchema } from './schema.js';
 import { resolveEntityDir } from './io.js';

package/dist/core/brainclaw-version.js

@@ -555,7 +555,7 @@ function readWorkspaceBrainclawPackage(cwd) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to read package.json: ${message}`);
+        throw new Error(`Failed to read package.json: ${message}`, { cause: error });
     }
     const name = typeof parsed.name === 'string' ? parsed.name.trim() : '';
     const version = typeof parsed.version === 'string' ? parsed.version.trim() : '';
@@ -617,7 +617,7 @@ function parseNpmDistTags(stdout) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`npm view returned invalid JSON: ${message}`);
+        throw new Error(`npm view returned invalid JSON: ${message}`, { cause: error });
     }
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new Error('npm view did not return a dist-tag object.');

package/dist/core/code-map/backend.js

@@ -0,0 +1,176 @@
+/**
+ * CodeQueryBackend — the agent-facing query contract (spec §8).
+ *
+ * Introduced in P0 so a future Memgraph (or other) backend can be added without
+ * changing the agent-facing APIs. P0 ships exactly one implementation:
+ * `JsonlBackend`. In this sprint, `status()` and `refresh()` are minimally real
+ * (they read/init the durable store and report freshness); `find()`/`brief()`
+ * return not-yet-implemented placeholders that still carry a real
+ * `freshness_badge`, locking the response shape for later sprints.
+ */
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { readManifest, storeExists } from './store.js';
+import { refresh as runRefresh } from './refresh.js';
+import { applyGitHeadDrift } from './freshness.js';
+import { brief as runBrief, find as runFind } from './query.js';
+import { defaultMemoryReader } from './memory-reader.js';
+/** spec §9 caps the brief reading list at 12 files. */
+export const BRIEF_FILE_CAP = 12;
+function badge(status, details = {}) {
+    return { status, details };
+}
+/**
+ * Read the working tree's current commit at `root` (read-path git-HEAD drift,
+ * trp_42688015). Returns null on any failure or a non-git project (also detached
+ * HEAD resolves to the commit sha, which is the correct comparison key) — a null
+ * makes the comparison a no-op, preserving existing behaviour.
+ *
+ * COST (review finding, LOW): one synchronous `git rev-parse HEAD` per status/
+ * find/brief call. These are interactive, human-/agent-paced reads (not a tight
+ * loop), so a single ~5–15ms spawn is acceptable and keeps branch-switch detection
+ * immediate. If this ever shows up on a profile, memoize per `root` behind a short
+ * TTL (a few seconds) — short enough that a checkout is still caught promptly.
+ */
+function readCurrentGitHead(root) {
+    try {
+        const out = execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd: root,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * P0 JSONL-backed query backend. Reads the durable file store (manifest +
+ * shards + indexes); no graph DB. find()/brief() are stubbed for Sprint 1.
+ */
+export class JsonlBackend {
+    /**
+     * Related-memory read seam (spec §11). Defaults to the canonical entity read
+     * path; tests inject an in-memory reader to assert attachment without a store.
+     */
+    memoryReader;
+    /** Read-path git-HEAD reader (injectable for tests). trp_42688015. */
+    gitHeadReader;
+    constructor(opts = {}) {
+        this.memoryReader = opts.memoryReader ?? defaultMemoryReader;
+        this.gitHeadReader = opts.gitHeadReader ?? readCurrentGitHead;
+    }
+    async status(input) {
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        if (!manifest) {
+            return {
+                store_exists: storeExists(input.cwd, input.preferredDirName),
+                freshness_badge: badge('missing_index'),
+                stats: null,
+            };
+        }
+        const base = badge(manifest.freshness.status, {
+            stale_file_count: manifest.freshness.stale_file_count,
+            partial_reason: manifest.freshness.partial_reason,
+        });
+        return {
+            store_exists: true,
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
+            stats: {
+                files_indexed: manifest.stats.files_indexed,
+                nodes: manifest.stats.nodes,
+                edges: manifest.stats.edges,
+            },
+        };
+    }
+    /**
+     * Real refresh (spec §7): resolves project identity (input -> manifest ->
+     * cwd-derived default), then runs the Tree-sitter parse + index + materialize
+     * pipeline behind the project lock. A live competing lock fails fast with a
+     * clear status — refresh never blocks bclaw_work (rule 8).
+     */
+    async refresh(input) {
+        const scope = input.scope ?? 'changed';
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const projectRoot = input.projectRoot ?? manifest?.project_root ?? input.cwd ?? process.cwd();
+        const projectId = input.projectId ?? manifest?.project_id ?? `prj_${path.basename(path.resolve(projectRoot))}`;
+        const result = await runRefresh({
+            projectId,
+            projectRoot,
+            scope,
+            cwd: input.cwd,
+            preferredDirName: input.preferredDirName,
+            ownerAgent: input.ownerAgent ?? null,
+            ownerAgentId: input.ownerAgentId ?? null,
+        });
+        return {
+            ran: result.ran,
+            scope,
+            lock_acquired: result.lock_acquired,
+            freshness_badge: badge(result.freshness.status, {
+                stale_file_count: result.freshness.stale_file_count,
+                partial_reason: result.freshness.partial_reason,
+                files_parsed: result.files_parsed,
+                files_compacted: result.files_compacted,
+                duration_ms: result.duration_ms,
+            }),
+            ...(result.lock_status ? { lock_status: result.lock_status } : {}),
+        };
+    }
+    /**
+     * Agent-facing symbol search (spec §12.1). Ranks symbols-index matches and
+     * lazily validates each backing shard against the live file before serving it
+     * as confident (§6.1); the response badge reflects any detected drift.
+     */
+    async find(input) {
+        const ctx = this.queryContext(input);
+        const out = runFind(input.query, input.limit, ctx);
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const base = {
+            status: out.freshness_badge.status,
+            details: out.freshness_badge.details,
+        };
+        return {
+            query: out.query,
+            matches: out.matches,
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
+        };
+    }
+    /**
+     * Agent-facing reading list (spec §9, §11). Produces a ranked
+     * suggested_files_to_read (cap 12), attaches related brainclaw memory (cap 5),
+     * and carries a §6.1 lazy-validated freshness badge.
+     */
+    async brief(input) {
+        const ctx = this.queryContext(input);
+        const out = runBrief(input.target, input.limit, ctx, this.memoryReader);
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const base = {
+            status: out.freshness_badge.status,
+            details: out.freshness_badge.details,
+        };
+        return {
+            target: out.target,
+            suggested_files_to_read: out.suggested_files_to_read,
+            related_memory: out.related_memory,
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
+        };
+    }
+    /**
+     * Annotate a read badge with git-HEAD drift vs the commit the index was built
+     * against (`manifest.git.head`). trp_42688015 — a branch switch (whole-tree move)
+     * is otherwise unflagged because `status` reads only write-side freshness and the
+     * per-file lazy check is query-scoped + budgeted. No-op for non-git projects.
+     */
+    withHeadDrift(base, manifest, cwd) {
+        if (!manifest)
+            return base;
+        const root = manifest.project_root || cwd || process.cwd();
+        return applyGitHeadDrift(base, manifest.git.head, this.gitHeadReader(root));
+    }
+    queryContext(input) {
+        return { cwd: input.cwd, preferredDirName: input.preferredDirName };
+    }
+}
+//# sourceMappingURL=backend.js.map