@kinqs/brainrouter-cli 0.3.4

package/dist/state/hookifyStore.js

@@ -0,0 +1,237 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getWorkspaceStateRoot } from './cliState.js';
+function hookDir(workspaceRoot) {
+    return path.join(getWorkspaceStateRoot(workspaceRoot), 'hooks');
+}
+export function ensureHookDir(workspaceRoot) {
+    const dir = hookDir(workspaceRoot);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function listHookifyRules(workspaceRoot) {
+    const dir = hookDir(workspaceRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(dir)) {
+        if (!entry.endsWith('.md'))
+            continue;
+        const full = path.join(dir, entry);
+        try {
+            const rule = parseHookifyFile(full);
+            if (rule)
+                out.push(rule);
+        }
+        catch {
+            // Skip malformed rule files; surfacing the error is the REPL's job.
+        }
+    }
+    return out;
+}
+export function parseHookifyFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(content);
+    if (!match)
+        return null;
+    const frontmatter = match[1];
+    const body = match[2].trim();
+    const meta = {};
+    let currentList = null;
+    let currentCond = null;
+    for (const rawLine of frontmatter.split('\n')) {
+        const line = rawLine.replace(/\r$/, '');
+        if (!line.trim())
+            continue;
+        if (line.trimStart().startsWith('-') && currentList) {
+            const inner = line.trim().slice(1).trim();
+            currentCond = { field: '', operator: 'regex_match', pattern: '' };
+            const [k, ...rest] = inner.split(':');
+            if (rest.length > 0)
+                currentCond[k.trim()] = rest.join(':').trim();
+            currentList.push(currentCond);
+            continue;
+        }
+        if (line.startsWith('  ') && currentCond) {
+            const [k, ...rest] = line.trim().split(':');
+            if (rest.length > 0)
+                currentCond[k.trim()] = rest.join(':').trim();
+            continue;
+        }
+        const [k, ...rest] = line.split(':');
+        if (rest.length === 0)
+            continue;
+        const key = k.trim();
+        const value = rest.join(':').trim();
+        if (key === 'conditions') {
+            currentList = [];
+            meta.conditions = currentList;
+            currentCond = null;
+            continue;
+        }
+        currentList = null;
+        currentCond = null;
+        meta[key] = value;
+    }
+    const id = path.basename(filePath).replace(/\.md$/, '');
+    if (!meta.event)
+        return null;
+    return {
+        id,
+        name: typeof meta.name === 'string' ? meta.name : id,
+        enabled: meta.enabled === undefined ? true : meta.enabled === 'true' || meta.enabled === true,
+        event: meta.event,
+        pattern: typeof meta.pattern === 'string' ? meta.pattern : undefined,
+        conditions: Array.isArray(meta.conditions) && meta.conditions.length > 0 ? meta.conditions : undefined,
+        action: (meta.action === 'block' ? 'block' : 'warn'),
+        message: body,
+        sourcePath: filePath,
+    };
+}
+/**
+ * Map a brainrouter tool invocation to the hookify event taxonomy. Returns
+ * the canonical event and the field bag that condition checks will probe.
+ */
+export function buildHookifyContext(toolName, args) {
+    if (toolName === 'run_command') {
+        return { event: 'bash', fields: { command: String(args.command ?? '') } };
+    }
+    if (toolName === 'write_file') {
+        return {
+            event: 'file',
+            fields: {
+                file_path: String(args.path ?? ''),
+                content: String(args.content ?? ''),
+                new_text: String(args.content ?? ''),
+            },
+        };
+    }
+    if (toolName === 'edit_file') {
+        return {
+            event: 'file',
+            fields: {
+                file_path: String(args.path ?? ''),
+                old_text: String(args.targetContent ?? ''),
+                new_text: String(args.replacementContent ?? ''),
+            },
+        };
+    }
+    if (toolName === 'apply_patch') {
+        return { event: 'file', fields: { new_text: String(args.patch ?? '') } };
+    }
+    return { event: 'all', fields: {} };
+}
+export function buildPromptContext(prompt) {
+    return { event: 'prompt', fields: { user_prompt: prompt } };
+}
+export function buildStopContext(transcript) {
+    return { event: 'stop', fields: { transcript } };
+}
+function fieldMatches(value, op, pattern) {
+    if (!pattern)
+        return false;
+    switch (op) {
+        case 'regex_match':
+            try {
+                return new RegExp(pattern).test(value);
+            }
+            catch {
+                return false;
+            }
+        case 'contains':
+            return value.includes(pattern);
+        case 'equals':
+            return value === pattern;
+        case 'not_contains':
+            return !value.includes(pattern);
+        case 'starts_with':
+            return value.startsWith(pattern);
+        case 'ends_with':
+            return value.endsWith(pattern);
+        default:
+            return false;
+    }
+}
+export function evaluateHookify(rules, ctx) {
+    const out = [];
+    for (const rule of rules) {
+        if (!rule.enabled)
+            continue;
+        if (rule.event !== 'all' && rule.event !== ctx.event)
+            continue;
+        let matched = false;
+        if (rule.pattern) {
+            const haystack = Object.values(ctx.fields).join('\n');
+            try {
+                matched = new RegExp(rule.pattern).test(haystack);
+            }
+            catch {
+                matched = false;
+            }
+        }
+        if (!matched && rule.conditions && rule.conditions.length > 0) {
+            matched = rule.conditions.every((c) => {
+                const value = ctx.fields[c.field] ?? '';
+                return fieldMatches(value, c.operator, c.pattern);
+            });
+        }
+        if (matched)
+            out.push({ rule, action: rule.action });
+    }
+    return out;
+}
+export function createHookifyRule(workspaceRoot, rule) {
+    const dir = ensureHookDir(workspaceRoot);
+    const slug = rule.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || `rule-${Date.now()}`;
+    const file = path.join(dir, `${slug}.md`);
+    const lines = ['---'];
+    lines.push(`name: ${rule.name}`);
+    lines.push(`enabled: ${rule.enabled === false ? 'false' : 'true'}`);
+    lines.push(`event: ${rule.event}`);
+    if (rule.pattern)
+        lines.push(`pattern: ${rule.pattern}`);
+    if (rule.action)
+        lines.push(`action: ${rule.action}`);
+    if (rule.conditions && rule.conditions.length > 0) {
+        lines.push('conditions:');
+        for (const c of rule.conditions) {
+            lines.push(`  - field: ${c.field}`);
+            lines.push(`    operator: ${c.operator}`);
+            lines.push(`    pattern: ${c.pattern}`);
+        }
+    }
+    lines.push('---');
+    lines.push('');
+    lines.push(rule.message.trim());
+    lines.push('');
+    fs.writeFileSync(file, lines.join('\n'), 'utf8');
+    const parsed = parseHookifyFile(file);
+    if (!parsed)
+        throw new Error(`Failed to read back created rule at ${file}`);
+    return parsed;
+}
+export function deleteHookifyRule(workspaceRoot, id) {
+    const dir = hookDir(workspaceRoot);
+    const file = path.join(dir, `${id}.md`);
+    if (!fs.existsSync(file))
+        return false;
+    fs.unlinkSync(file);
+    return true;
+}
+export function toggleHookifyRule(workspaceRoot, id, enabled) {
+    const dir = hookDir(workspaceRoot);
+    const file = path.join(dir, `${id}.md`);
+    if (!fs.existsSync(file))
+        return false;
+    const content = fs.readFileSync(file, 'utf8');
+    const next = content.replace(/(\nenabled:\s*)(true|false)/, `$1${enabled ? 'true' : 'false'}`);
+    if (next === content) {
+        const inserted = content.replace(/^---\n/, `---\nenabled: ${enabled ? 'true' : 'false'}\n`);
+        fs.writeFileSync(file, inserted, 'utf8');
+    }
+    else {
+        fs.writeFileSync(file, next, 'utf8');
+    }
+    return true;
+}

package/dist/state/hooksStore.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Lifecycle shell hooks. A hook is a shell command string that runs at a
+ * specific agent-loop point (pre-tool, post-tool, stop). Non-zero exit codes
+ * from `pre-tool` hooks can block the tool call ("approval gate"); other
+ * events are informational.
+ *
+ * Persisted at <workspace>/.brainrouter/cli/hooks.json so they survive CLI
+ * restarts and travel with the project.
+ */
+export type HookEvent = 'pre-tool' | 'post-tool' | 'pre-turn' | 'post-turn' | 'session-start' | 'session-end';
+export interface Hook {
+    id: string;
+    event: HookEvent;
+    command: string;
+    match?: string;
+    enabled: boolean;
+    createdAt: string;
+}
+export declare function readHooks(workspaceRoot: string): Hook[];
+export declare function addHook(workspaceRoot: string, input: {
+    event: HookEvent;
+    command: string;
+    match?: string;
+}): Hook;
+export declare function removeHook(workspaceRoot: string, id: string): boolean;
+export declare function setHookEnabled(workspaceRoot: string, id: string, enabled: boolean): boolean;
+export interface HookRunResult {
+    hook: Hook;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Run all enabled hooks for the given event. The CLI uses synchronous spawning
+ * with a hard timeout — hooks are meant for fast lifecycle taps (lint, notify,
+ * log), not long-running work. A `pre-tool` hook returning non-zero blocks the
+ * tool call; other events are advisory.
+ */
+export declare function runHooks(workspaceRoot: string, event: HookEvent, context?: {
+    tool?: string;
+    payload?: Record<string, unknown>;
+}, timeoutMs?: number): HookRunResult[];

package/dist/state/hooksStore.js

@@ -0,0 +1,71 @@
+import { execSync } from 'node:child_process';
+import { getCliStateFile, readJsonFile, writeJsonFile } from './cliState.js';
+const EMPTY = { hooks: [] };
+export function readHooks(workspaceRoot) {
+    return readJsonFile(getCliStateFile(workspaceRoot, 'hooks.json'), EMPTY).hooks;
+}
+export function addHook(workspaceRoot, input) {
+    const all = readHooks(workspaceRoot);
+    const hook = {
+        id: `hook_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`,
+        event: input.event,
+        command: input.command,
+        match: input.match,
+        enabled: true,
+        createdAt: new Date().toISOString(),
+    };
+    all.push(hook);
+    writeJsonFile(getCliStateFile(workspaceRoot, 'hooks.json'), { hooks: all });
+    return hook;
+}
+export function removeHook(workspaceRoot, id) {
+    const all = readHooks(workspaceRoot);
+    const filtered = all.filter((h) => h.id !== id);
+    if (filtered.length === all.length)
+        return false;
+    writeJsonFile(getCliStateFile(workspaceRoot, 'hooks.json'), { hooks: filtered });
+    return true;
+}
+export function setHookEnabled(workspaceRoot, id, enabled) {
+    const all = readHooks(workspaceRoot);
+    const target = all.find((h) => h.id === id);
+    if (!target)
+        return false;
+    target.enabled = enabled;
+    writeJsonFile(getCliStateFile(workspaceRoot, 'hooks.json'), { hooks: all });
+    return true;
+}
+/**
+ * Run all enabled hooks for the given event. The CLI uses synchronous spawning
+ * with a hard timeout — hooks are meant for fast lifecycle taps (lint, notify,
+ * log), not long-running work. A `pre-tool` hook returning non-zero blocks the
+ * tool call; other events are advisory.
+ */
+export function runHooks(workspaceRoot, event, context = {}, timeoutMs = 5000) {
+    const results = [];
+    for (const hook of readHooks(workspaceRoot)) {
+        if (!hook.enabled || hook.event !== event)
+            continue;
+        if (hook.match && context.tool && !context.tool.includes(hook.match))
+            continue;
+        const env = {
+            ...process.env,
+            BRAINROUTER_HOOK_EVENT: event,
+            BRAINROUTER_HOOK_TOOL: context.tool ?? '',
+            BRAINROUTER_HOOK_PAYLOAD: context.payload ? JSON.stringify(context.payload) : '',
+        };
+        try {
+            const stdout = execSync(hook.command, { env, timeout: timeoutMs, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+            results.push({ hook, exitCode: 0, stdout, stderr: '' });
+        }
+        catch (err) {
+            results.push({
+                hook,
+                exitCode: typeof err.status === 'number' ? err.status : 1,
+                stdout: typeof err.stdout === 'string' ? err.stdout : (err.stdout?.toString?.() ?? ''),
+                stderr: typeof err.stderr === 'string' ? err.stderr : (err.stderr?.toString?.() ?? err.message ?? ''),
+            });
+        }
+    }
+    return results;
+}

package/dist/state/preferencesStore.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-workspace runtime preferences that don't justify their own file.
+ *
+ * Persisted at `<workspace>/.brainrouter/cli/preferences.json` so they survive
+ * CLI restarts but stay scoped to the project (different repos can have
+ * different settings).
+ */
+export interface Preferences {
+    /** When true, every worker spawn is auto-followed by a reviewer pass on the diff. */
+    autoReview: boolean;
+    /** Editor mode for the readline composer. */
+    editorMode: 'emacs' | 'vi';
+    /** Status-line layout: comma-separated segments from {mode,branch,dirty,model,tokens,session}. */
+    statusline: string;
+    /**
+     * When true, `run_command` skips the per-call confirmation prompt and runs
+     * immediately. Pair with sandboxing (BRAINROUTER_SANDBOX=on) if you want
+     * the safety net without the friction. Off by default — opt-in via /yolo.
+     */
+    autoApproveShell: boolean;
+    /** Syntax highlighting theme for markdown output. Tied to/theme. */
+    theme: 'auto' | 'light' | 'dark' | 'mono';
+    /** Terminal title format segments (model, branch, session, mode) or 'off'. Tied to/title. */
+    terminalTitle: string;
+    /** Communication style for the agent. Tied to/personality. */
+    personality: 'concise' | 'standard' | 'detailed' | 'pair-programmer';
+    /** When true, REPL output skips markdown rendering for copy-friendly raw text. Tied to/raw. */
+    rawScrollback: boolean;
+    /** When true, gated experimental features are unlocked. Tied to/experimental. */
+    experimental: boolean;
+    /** When true, the memory pipeline runs phase1/phase2 consolidation on session start. Tied to/memories. */
+    memoriesEnabled: boolean;
+    /** Custom keybindings as JSON-stringified map for /keymap. Empty means defaults. */
+    keymap: string;
+    /** Extra read-only paths granted to sandboxed run_command. Workspace is always readable+writable. */
+    sandboxReadPaths: string[];
+    /** Extra write-allowed paths granted to sandboxed run_command. */
+    sandboxWritePaths: string[];
+}
+export declare function readPreferences(workspaceRoot: string): Preferences;
+export declare function writePreferences(workspaceRoot: string, prefs: Partial<Preferences>): Preferences;

package/dist/state/preferencesStore.js

@@ -0,0 +1,25 @@
+import { getCliStateFile, readJsonFile, writeJsonFile } from './cliState.js';
+const DEFAULT = {
+    autoReview: false,
+    editorMode: 'emacs',
+    statusline: 'mode',
+    autoApproveShell: false,
+    theme: 'auto',
+    terminalTitle: 'model,session',
+    personality: 'standard',
+    rawScrollback: false,
+    experimental: false,
+    memoriesEnabled: true,
+    keymap: '',
+    sandboxReadPaths: [],
+    sandboxWritePaths: [],
+};
+export function readPreferences(workspaceRoot) {
+    const stored = readJsonFile(getCliStateFile(workspaceRoot, 'preferences.json'), {});
+    return { ...DEFAULT, ...stored };
+}
+export function writePreferences(workspaceRoot, prefs) {
+    const merged = { ...readPreferences(workspaceRoot), ...prefs };
+    writeJsonFile(getCliStateFile(workspaceRoot, 'preferences.json'), merged);
+    return merged;
+}

package/dist/state/sessionStore.d.ts

@@ -0,0 +1,42 @@
+export interface TranscriptEntry {
+    role: string;
+    content?: unknown;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: unknown;
+    isError?: boolean;
+    timestamp: string;
+}
+export declare function appendTranscriptEntry(workspaceRoot: string, sessionKey: string, entry: Omit<TranscriptEntry, 'timestamp'> & {
+    timestamp?: string;
+}): void;
+export declare function readTranscriptEntries(workspaceRoot: string, sessionKey: string, limit?: number): TranscriptEntry[];
+/**
+ * Resolve the transcript path for writes. Always uses the per-session bucket
+ * at `<state>/sessions/<encodedKey>/transcript.jsonl` so each chat session
+ * keeps its history co-located with its goal/plan/etc.
+ */
+export declare function getTranscriptPath(workspaceRoot: string, sessionKey: string): string;
+export declare function redactText(value: string): string;
+export declare function redactTranscriptEntry(entry: TranscriptEntry): TranscriptEntry;
+export interface TranscriptSummary {
+    sessionKey: string;
+    fileName: string;
+    modifiedAt: string;
+    turnCount: number;
+    firstUserMessage?: string;
+    /** Absolute path to the session bucket (new layout) or undefined for legacy. */
+    sessionDir?: string;
+}
+/**
+ * List all persisted transcripts under the workspace, newest first. Scans the
+ * new `sessions/<encodedKey>/transcript.jsonl` layout AND the legacy
+ * `transcripts/<encodedKey>.jsonl` files so the picker shows every session
+ * even after the upgrade. Per-session files always win on dedupe.
+ */
+export declare function listTranscripts(workspaceRoot: string): TranscriptSummary[];
+/**
+ * Read all transcript entries for a session, in order. Used by `/resume`
+ * to seed the Agent's chatHistory.
+ */
+export declare function loadTranscript(workspaceRoot: string, sessionKey: string): TranscriptEntry[];

package/dist/state/sessionStore.js

@@ -0,0 +1,193 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { decodeSessionKey, encodeSessionKey, getCliStateDir, getSessionStateDir, isPathInside, } from './cliState.js';
+const SECRET_TOKEN_PATTERNS = [
+    /\bbr_[A-Za-z0-9._-]{8,}\b/g,
+    /\bsk-[A-Za-z0-9._-]{8,}\b/g,
+];
+const TRANSCRIPT_FILE = 'transcript.jsonl';
+export function appendTranscriptEntry(workspaceRoot, sessionKey, entry) {
+    const filePath = getTranscriptPath(workspaceRoot, sessionKey);
+    const payload = redactTranscriptEntry({
+        ...entry,
+        timestamp: entry.timestamp ?? new Date().toISOString(),
+    });
+    // Dedup consecutive identical user prompts (e.g. arrow-up + Enter to repeat
+    // the same prompt) so /transcript and /resume don't accumulate identical
+    // replay-spam entries. Only applied to role='user' entries — assistant +
+    // tool replies legitimately differ between turns even when the prompt is
+    // the same.
+    if (payload.role === 'user' && isConsecutiveDuplicate(filePath, payload)) {
+        return;
+    }
+    fs.appendFileSync(filePath, `${JSON.stringify(payload)}\n`, 'utf8');
+}
+/**
+ * Check if the last line of the transcript file matches the new entry on
+ * role + content. Bounded read (last ~32KB) so the dedup check stays cheap
+ * even for huge transcripts; consecutive duplicates that span beyond that
+ * window weren't going to be visually adjacent anyway.
+ */
+function isConsecutiveDuplicate(filePath, candidate) {
+    try {
+        if (!fs.existsSync(filePath))
+            return false;
+        const stat = fs.statSync(filePath);
+        if (stat.size === 0)
+            return false;
+        const start = Math.max(0, stat.size - 32 * 1024);
+        const fd = fs.openSync(filePath, 'r');
+        try {
+            const buf = Buffer.alloc(stat.size - start);
+            fs.readSync(fd, buf, 0, buf.length, start);
+            const tail = buf.toString('utf8').trimEnd();
+            if (!tail)
+                return false;
+            const lastLine = tail.slice(tail.lastIndexOf('\n') + 1);
+            const last = JSON.parse(lastLine);
+            return last.role === candidate.role && last.content === candidate.content;
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        // Any read/parse failure: don't dedup — write the entry normally.
+        return false;
+    }
+}
+export function readTranscriptEntries(workspaceRoot, sessionKey, limit = 40) {
+    const filePath = resolveExistingTranscriptPath(workspaceRoot, sessionKey);
+    if (!filePath) {
+        return [];
+    }
+    const lines = fs.readFileSync(filePath, 'utf8').trim().split('\n').filter(Boolean);
+    // A single corrupted line — most often the tail line from a Ctrl-C mid-write
+    // because appendFileSync is not atomic for large payloads — must not crash
+    // /resume or anything else that scans the transcript. Tolerate bad lines
+    // and warn once; the visible-entry slice handles the rest.
+    const entries = [];
+    let dropped = 0;
+    for (const line of lines.slice(Math.max(0, lines.length - limit))) {
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            dropped++;
+        }
+    }
+    if (dropped > 0) {
+        console.warn(`[brainrouter] dropped ${dropped} unparseable transcript line(s) in ${filePath}`);
+    }
+    return entries;
+}
+/**
+ * Resolve the transcript path for writes. Always uses the per-session bucket
+ * at `<state>/sessions/<encodedKey>/transcript.jsonl` so each chat session
+ * keeps its history co-located with its goal/plan/etc.
+ */
+export function getTranscriptPath(workspaceRoot, sessionKey) {
+    const sessionDir = getSessionStateDir(workspaceRoot, sessionKey);
+    const filePath = path.join(sessionDir, TRANSCRIPT_FILE);
+    if (!isPathInside(sessionDir, filePath)) {
+        throw new Error('Transcript path escapes session directory.');
+    }
+    return filePath;
+}
+/**
+ * Read-side resolver: prefer the per-session bucket, fall back to the legacy
+ * `transcripts/<encodedKey>.jsonl` location so `/resume` still works for
+ * sessions captured by older builds.
+ */
+function resolveExistingTranscriptPath(workspaceRoot, sessionKey) {
+    const sessionPath = getTranscriptPath(workspaceRoot, sessionKey);
+    if (fs.existsSync(sessionPath))
+        return sessionPath;
+    const legacy = path.join(getCliStateDir(workspaceRoot), 'transcripts', `${encodeSessionKey(sessionKey)}.jsonl`);
+    if (fs.existsSync(legacy))
+        return legacy;
+    return undefined;
+}
+export function redactText(value) {
+    const redactedAssignments = value.replace(/((?:"(?:apiKey|api_key|BRAINROUTER_API_KEY|OPENAI_API_KEY)"|(?:apiKey|api_key|BRAINROUTER_API_KEY|OPENAI_API_KEY))\s*[:=]\s*)("[^"\n]*"|'[^'\n]*'|[^\s,\]}]+)/gi, '$1"[REDACTED]"');
+    return SECRET_TOKEN_PATTERNS.reduce((text, pattern) => text.replace(pattern, '[REDACTED]'), redactedAssignments);
+}
+export function redactTranscriptEntry(entry) {
+    return JSON.parse(redactText(JSON.stringify(entry)));
+}
+/**
+ * List all persisted transcripts under the workspace, newest first. Scans the
+ * new `sessions/<encodedKey>/transcript.jsonl` layout AND the legacy
+ * `transcripts/<encodedKey>.jsonl` files so the picker shows every session
+ * even after the upgrade. Per-session files always win on dedupe.
+ */
+export function listTranscripts(workspaceRoot) {
+    const stateDir = getCliStateDir(workspaceRoot);
+    const seen = new Map();
+    // New layout: sessions/<encodedKey>/transcript.jsonl
+    const sessionsDir = path.join(stateDir, 'sessions');
+    if (fs.existsSync(sessionsDir)) {
+        for (const entry of fs.readdirSync(sessionsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const sessionDir = path.join(sessionsDir, entry.name);
+            const transcriptPath = path.join(sessionDir, TRANSCRIPT_FILE);
+            if (!fs.existsSync(transcriptPath))
+                continue;
+            const sessionKey = decodeSessionKey(entry.name);
+            const summary = summarizeTranscript(transcriptPath, sessionKey, sessionDir);
+            seen.set(sessionKey, summary);
+        }
+    }
+    // Legacy layout: transcripts/<encodedKey>.jsonl
+    const legacyDir = path.join(stateDir, 'transcripts');
+    if (fs.existsSync(legacyDir)) {
+        for (const fileName of fs.readdirSync(legacyDir)) {
+            if (!fileName.endsWith('.jsonl'))
+                continue;
+            const encoded = fileName.slice(0, -'.jsonl'.length);
+            const sessionKey = decodeSessionKey(encoded);
+            if (seen.has(sessionKey))
+                continue;
+            const filePath = path.join(legacyDir, fileName);
+            seen.set(sessionKey, summarizeTranscript(filePath, sessionKey));
+        }
+    }
+    return Array.from(seen.values()).sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+}
+function summarizeTranscript(filePath, sessionKey, sessionDir) {
+    let modifiedAt = new Date(0).toISOString();
+    let turnCount = 0;
+    let firstUserMessage;
+    try {
+        modifiedAt = fs.statSync(filePath).mtime.toISOString();
+        const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+        turnCount = lines.length;
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                if (entry.role === 'user' && typeof entry.content === 'string' && entry.content.trim()) {
+                    firstUserMessage = entry.content.toString().replace(/\s+/g, ' ').slice(0, 120);
+                    break;
+                }
+            }
+            catch { /* skip malformed */ }
+        }
+    }
+    catch { /* unreadable file */ }
+    return {
+        sessionKey,
+        fileName: path.basename(filePath),
+        modifiedAt,
+        turnCount,
+        firstUserMessage,
+        sessionDir,
+    };
+}
+/**
+ * Read all transcript entries for a session, in order. Used by `/resume`
+ * to seed the Agent's chatHistory.
+ */
+export function loadTranscript(workspaceRoot, sessionKey) {
+    return readTranscriptEntries(workspaceRoot, sessionKey, Number.MAX_SAFE_INTEGER);
+}

package/dist/state/taskStore.d.ts

@@ -0,0 +1,23 @@
+export type PlanItemStatus = 'pending' | 'in_progress' | 'completed';
+export interface PlanItem {
+    step: string;
+    status: PlanItemStatus;
+}
+export interface PlanState {
+    explanation?: string;
+    updatedAt: string;
+    items: PlanItem[];
+}
+/**
+ * Durable per-session plan. Lives at
+ *   <workspace>/.brainrouter/cli/sessions/<encodedKey>/tasks.json
+ *
+ * Legacy callers that don't pass a sessionKey read/write the older workspace-
+ * level `tasks.json` so existing workspaces keep their plan after the upgrade.
+ */
+export declare function readPlan(workspaceRoot: string, sessionKey?: string): PlanState;
+export declare function updatePlan(workspaceRoot: string, input: {
+    explanation?: string;
+    plan: PlanItem[];
+}, sessionKey?: string): PlanState;
+export declare function formatPlan(state: PlanState): string;