@phuetz/code-buddy 1.1.0 → 1.2.0

package/dist/agent/model-benchmark.js

@@ -0,0 +1,309 @@
+/**
+ * Live model benchmarking for Tailnet Ollama peers.
+ *
+ * Measures actual request latency and simple compliance signals so the router
+ * can prefer the best network model instead of relying on a static ordering.
+ * The benchmark is intentionally lightweight: a few objective prompts, temp=0,
+ * streamed completions, and a persisted score cache that the model-tier ladder
+ * can use to rank candidates.
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { normalizeBaseURL } from '../utils/base-url.js';
+export const BENCHMARK_PROMPT_SETS = {
+    balanced: [
+        {
+            name: 'exact-ok',
+            prompt: 'Reply with exactly OK and nothing else.',
+            maxTokens: 8,
+            validate: (output) => output.trim() === 'OK',
+        },
+        {
+            name: 'json-object',
+            prompt: 'Return exactly this JSON object and nothing else: {"model":"darkstar","status":"ok"}',
+            maxTokens: 32,
+            validate: (output) => {
+                try {
+                    const parsed = JSON.parse(stripCodeFences(output));
+                    return parsed?.model === 'darkstar' && parsed?.status === 'ok';
+                }
+                catch {
+                    return false;
+                }
+            },
+        },
+        {
+            name: 'code-dedupe',
+            prompt: 'Write a TypeScript function named dedupeById that removes duplicate objects by id using a Map. Output only the function.',
+            maxTokens: 96,
+            validate: (output) => /dedupeById/.test(output) && /Map/.test(output) && /return/.test(output),
+        },
+    ],
+    coding: [
+        {
+            name: 'json-object',
+            prompt: 'Return exactly this JSON object and nothing else: {"model":"darkstar","status":"ok"}',
+            maxTokens: 32,
+            validate: (output) => {
+                try {
+                    const parsed = JSON.parse(stripCodeFences(output));
+                    return parsed?.model === 'darkstar' && parsed?.status === 'ok';
+                }
+                catch {
+                    return false;
+                }
+            },
+        },
+        {
+            name: 'code-dedupe',
+            prompt: 'Write a TypeScript function named dedupeById that removes duplicate objects by id using a Map. Output only the function.',
+            maxTokens: 96,
+            validate: (output) => /dedupeById/.test(output) && /Map/.test(output) && /return/.test(output),
+        },
+    ],
+    latency: [
+        {
+            name: 'exact-ok',
+            prompt: 'Reply with exactly OK and nothing else.',
+            maxTokens: 8,
+            validate: (output) => output.trim() === 'OK',
+        },
+        {
+            name: 'short-json',
+            prompt: 'Return exactly {"ok":true} and nothing else.',
+            maxTokens: 16,
+            validate: (output) => {
+                try {
+                    const parsed = JSON.parse(stripCodeFences(output));
+                    return parsed?.ok === true;
+                }
+                catch {
+                    return false;
+                }
+            },
+        },
+    ],
+};
+export function defaultBenchmarkIndexPath(homeDir = os.homedir()) {
+    return path.join(homeDir, '.codebuddy', 'model-benchmarks.json');
+}
+export function benchmarkCandidateKey(candidate) {
+    return `${normalizeBaseURL(candidate.baseUrl)}::${candidate.model}`;
+}
+export async function benchmarkCandidates(candidates, options = {}) {
+    const promptSet = options.promptSet ?? 'balanced';
+    const prompts = BENCHMARK_PROMPT_SETS[promptSet];
+    const runs = Math.max(1, options.runs ?? 1);
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const reports = [];
+    for (const candidate of candidates) {
+        const candidateRuns = [];
+        for (let runIndex = 0; runIndex < runs; runIndex += 1) {
+            for (const prompt of prompts) {
+                candidateRuns.push(await runSinglePrompt(candidate, prompt, fetchImpl, options.timeoutMs));
+            }
+        }
+        reports.push({
+            candidate,
+            runs: candidateRuns,
+            summary: summarizeBenchmarkRuns(candidateRuns),
+        });
+    }
+    return reports;
+}
+export function summarizeBenchmarkRuns(runs) {
+    const runsCount = runs.length;
+    const successes = runs.filter((run) => run.success).length;
+    const complianceRuns = runs.filter((run) => run.success && run.compliance).length;
+    const successfulRuns = runs.filter((run) => run.success);
+    const avgTtftMs = average(successfulRuns.map((run) => run.ttftMs));
+    const avgTotalMs = average(successfulRuns.map((run) => run.totalMs));
+    const avgOutputTokensEstimate = average(successfulRuns.map((run) => run.outputTokensEstimate));
+    const complianceRate = runsCount > 0 ? complianceRuns / runsCount : 0;
+    // Weighted score: correctness dominates, then speed. Higher is better.
+    const failurePenalty = (runsCount - successes) * 1000;
+    const score = successes === 0
+        ? -1_000_000 - failurePenalty
+        : (complianceRate * 1000)
+            - avgTtftMs
+            - (avgTotalMs * 0.5)
+            + (successes / Math.max(1, runsCount)) * 100
+            - failurePenalty;
+    return {
+        runs: runsCount,
+        successes,
+        complianceRate,
+        avgTtftMs,
+        avgTotalMs,
+        avgOutputTokensEstimate,
+        score,
+    };
+}
+export async function writeBenchmarkIndex(reports, suite, indexPath = defaultBenchmarkIndexPath()) {
+    const entries = reports
+        .map((report) => ({
+        model: report.candidate.model,
+        baseUrl: normalizeBaseURL(report.candidate.baseUrl),
+        ...(report.candidate.label ? { label: report.candidate.label } : {}),
+        score: report.summary.score,
+        complianceRate: report.summary.complianceRate,
+        avgTtftMs: report.summary.avgTtftMs,
+        avgTotalMs: report.summary.avgTotalMs,
+        updatedAt: new Date().toISOString(),
+    }))
+        .sort((a, b) => b.score - a.score);
+    const index = {
+        updatedAt: new Date().toISOString(),
+        suite,
+        entries,
+    };
+    await fs.mkdir(path.dirname(indexPath), { recursive: true });
+    await fs.writeFile(indexPath, `${JSON.stringify(index, null, 2)}\n`, 'utf8');
+    return index;
+}
+export async function loadBenchmarkIndex(indexPath = defaultBenchmarkIndexPath()) {
+    try {
+        const raw = await fs.readFile(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.entries))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function loadBenchmarkScoreMap(indexPath = defaultBenchmarkIndexPath()) {
+    const index = await loadBenchmarkIndex(indexPath);
+    const map = new Map();
+    for (const entry of index?.entries ?? []) {
+        map.set(`${normalizeBaseURL(entry.baseUrl)}::${entry.model}`, entry.score);
+    }
+    return map;
+}
+async function runSinglePrompt(candidate, prompt, fetchImpl, timeoutMs) {
+    const endpoint = `${normalizeBaseURL(candidate.baseUrl)}/chat/completions`;
+    const startedAt = performance.now();
+    const headers = { 'Content-Type': 'application/json' };
+    try {
+        const response = await fetchImpl(endpoint, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                model: candidate.model,
+                messages: [{ role: 'user', content: prompt.prompt }],
+                temperature: 0,
+                max_tokens: prompt.maxTokens,
+                stream: true,
+                stream_options: { include_usage: true },
+            }),
+            signal: AbortSignal.timeout(timeoutMs ?? 60_000),
+        });
+        if (!response.ok || !response.body) {
+            const body = await safeText(response);
+            return failureRun(prompt.name, startedAt, `HTTP ${response.status}: ${body.slice(0, 200)}`);
+        }
+        const streamed = await readOpenAIChatStream(response, startedAt);
+        const totalMs = performance.now() - startedAt;
+        const compliance = prompt.validate(streamed.output);
+        return {
+            promptName: prompt.name,
+            success: true,
+            compliance,
+            ttftMs: streamed.ttftMs ?? totalMs,
+            totalMs,
+            outputChars: streamed.output.length,
+            outputTokensEstimate: streamed.outputTokensEstimate ?? estimateTokens(streamed.output),
+            ...(streamed.output.length ? { outputPreview: trimPreview(streamed.output) } : {}),
+        };
+    }
+    catch (error) {
+        return failureRun(prompt.name, startedAt, error instanceof Error ? error.message : String(error));
+    }
+}
+async function readOpenAIChatStream(response, startedAt) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        return { output: '', ttftMs: null, outputTokensEstimate: null };
+    }
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let output = '';
+    let ttftMs = null;
+    let firstContentSeen = false;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        let newlineIndex = buffer.indexOf('\n');
+        while (newlineIndex >= 0) {
+            const rawLine = buffer.slice(0, newlineIndex);
+            buffer = buffer.slice(newlineIndex + 1);
+            const line = rawLine.trim();
+            if (line.startsWith('data:')) {
+                const payload = line.slice(5).trim();
+                if (payload && payload !== '[DONE]') {
+                    try {
+                        const parsed = JSON.parse(payload);
+                        const delta = parsed.choices?.[0]?.delta?.content ?? '';
+                        if (delta) {
+                            output += delta;
+                            if (!firstContentSeen) {
+                                ttftMs = performance.now() - startedAt;
+                                firstContentSeen = true;
+                            }
+                        }
+                    }
+                    catch {
+                        // Ignore malformed SSE frames and continue reading the stream.
+                    }
+                }
+            }
+            newlineIndex = buffer.indexOf('\n');
+        }
+    }
+    return {
+        output,
+        ttftMs,
+        outputTokensEstimate: estimateTokens(output),
+    };
+}
+function failureRun(promptName, startedAt, error) {
+    const totalMs = performance.now() - startedAt;
+    return {
+        promptName,
+        success: false,
+        compliance: false,
+        ttftMs: totalMs,
+        totalMs,
+        outputChars: 0,
+        outputTokensEstimate: 0,
+        error,
+    };
+}
+function average(values) {
+    if (values.length === 0)
+        return 0;
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function estimateTokens(text) {
+    return Math.max(1, Math.ceil(text.trim().length / 4));
+}
+function trimPreview(text, maxChars = 200) {
+    const trimmed = text.trim().replace(/\s+/g, ' ');
+    return trimmed.length > maxChars ? `${trimmed.slice(0, maxChars)}...` : trimmed;
+}
+function stripCodeFences(text) {
+    return text.trim().replace(/^```(?:json|ts|typescript)?\s*/i, '').replace(/\s*```$/i, '');
+}
+async function safeText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=model-benchmark.js.map

package/dist/agent/model-tier.d.ts

@@ -32,6 +32,13 @@ export interface ModelTierConfig {
     /** Paid cloud model, last resort (undefined = never escalate to paid). */
     escalationModel?: string;
 }
+export interface LiveModelTierDiscoveryOptions {
+    /**
+     * When true, the resolver keeps the static `CODEBUDDY_NETWORK_MODELS`
+     * entries and appends live Tailnet peers discovered at runtime.
+     */
+    augmentConfiguredNetworkModels?: boolean;
+}
 export interface EscalationSignal {
     /** Caller explicitly wants the strongest available model for this turn. */
     escalate?: boolean;
@@ -65,6 +72,13 @@ export interface AutonomousModelChoice {
  * - escalation:     `CODEBUDDY_ESCALATION_MODEL` → `GROK_MODEL` → none.
  */
 export declare function resolveModelTierConfig(env?: NodeJS.ProcessEnv): ModelTierConfig;
+/**
+ * Resolve the ladder and enrich the network rung with live Tailnet Ollama peers
+ * when the `tailscale` CLI is available. This keeps the system dynamic: the
+ * network tier grows as peers come and go instead of relying on a hardcoded
+ * host list.
+ */
+export declare function resolveLiveModelTierConfig(env?: NodeJS.ProcessEnv, options?: LiveModelTierDiscoveryOptions): Promise<ModelTierConfig>;
 export declare function parseNetworkModels(raw: string | undefined): NetworkModel[];
 /**
  * Choose the model for an autonomous turn. Free-first: local by default, the

package/dist/agent/model-tier.js

@@ -14,6 +14,7 @@
  * Pure decision core: given the configured tiers and an escalation signal, it
  * returns which model to use and why. It performs no inference/routing itself.
  */
+import { normalizeBaseURL } from '../utils/base-url.js';
 const PRIORITY_RANK = { critical: 3, high: 2, medium: 1, low: 0 };
 const DEFAULT_LOCAL_MODEL = 'llama3.2';
 const DEFAULT_LOCAL_BASE_URL = 'http://localhost:11434/v1';
@@ -41,6 +42,43 @@ export function resolveModelTierConfig(env = process.env) {
         ...(escalationModel ? { escalationModel } : {}),
     };
 }
+/**
+ * Resolve the ladder and enrich the network rung with live Tailnet Ollama peers
+ * when the `tailscale` CLI is available. This keeps the system dynamic: the
+ * network tier grows as peers come and go instead of relying on a hardcoded
+ * host list.
+ */
+export async function resolveLiveModelTierConfig(env = process.env, options = {}) {
+    const config = resolveModelTierConfig(env);
+    let discovered = [];
+    let benchmarkScores = new Map();
+    try {
+        const { TailscaleManager } = await import('../integrations/tailscale.js');
+        discovered = (await TailscaleManager.getInstance().discoverOllamaPeers()).flatMap((peer) => peer.models.map((model) => ({
+            model,
+            baseUrl: peer.baseURL,
+            label: peer.hostname,
+        })));
+    }
+    catch {
+        discovered = [];
+    }
+    try {
+        const { loadBenchmarkScoreMap } = await import('./model-benchmark.js');
+        benchmarkScores = await loadBenchmarkScoreMap();
+    }
+    catch {
+        benchmarkScores = new Map();
+    }
+    const configured = config.networkModels ?? [];
+    const merged = options.augmentConfiguredNetworkModels === false
+        ? discovered
+        : mergeNetworkModels(configured, discovered);
+    return {
+        ...config,
+        networkModels: rankNetworkModelsByBenchmark(merged, benchmarkScores),
+    };
+}
 export function parseNetworkModels(raw) {
     if (!raw?.trim())
         return [];
@@ -56,6 +94,39 @@ export function parseNetworkModels(raw) {
 function normalizeBaseUrl(url) {
     return url.replace(/\/+$/, '');
 }
+function mergeNetworkModels(primary, secondary) {
+    const seen = new Set();
+    const merged = [];
+    for (const item of [...primary, ...secondary]) {
+        const key = `${item.model}@${normalizeBaseUrl(item.baseUrl)}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(item);
+    }
+    return merged;
+}
+function rankNetworkModelsByBenchmark(networkModels, benchmarkScores) {
+    if (networkModels.length === 0 || benchmarkScores.size === 0) {
+        return networkModels;
+    }
+    return networkModels
+        .map((model, index) => ({
+        model,
+        index,
+        score: benchmarkScores.get(`${normalizeBaseURL(model.baseUrl)}::${model.model}`),
+    }))
+        .sort((a, b) => {
+        const aHas = typeof a.score === 'number';
+        const bHas = typeof b.score === 'number';
+        if (aHas && bHas && a.score !== b.score)
+            return (b.score ?? 0) - (a.score ?? 0);
+        if (aHas !== bHas)
+            return aHas ? -1 : 1;
+        return a.index - b.index;
+    })
+        .map((entry) => entry.model);
+}
 /** Escalation rung 0 (local) / 1 (network) / 2 (paid) implied by the signal. */
 function escalationLevel(signal, policy) {
     let level = 0;

package/dist/agent/multi-agent/agents/orchestrator-agent.js

@@ -64,7 +64,12 @@ DECISION MAKING:
         "bash",
         "codebase_map",
     ],
-    maxRounds: 20,
+    // Bounded so a model that over-explores during planning/synthesis can't loop
+    // indefinitely on a large repo. With the "plan directly" task prompt, planning
+    // normally terminates in 1 round; if a model still exhausts this cap without
+    // emitting a <plan>, parsePlan() falls back to a default coder task so the
+    // workflow still delegates to the worker agents.
+    maxRounds: 8,
 };
 export class OrchestratorAgent extends BaseAgent {
     executionPlan = null;
@@ -88,16 +93,18 @@ export class OrchestratorAgent extends BaseAgent {
         const planningTask = {
             id: createId("task"),
             title: "Create Execution Plan",
-            description: `Analyze the following goal and create a detailed execution plan:
+            description: `Analyze the following goal and OUTPUT an execution plan using the <plan> XML format from your instructions.
 
 GOAL: ${goal}
 
-Explore the codebase to understand the current state, then create a comprehensive plan that:
-1. Breaks down the goal into manageable phases
+Plan directly. Do NOT explore the codebase unless it is strictly required to plan — for self-contained tasks, skip exploration entirely and emit the plan in your first response. A good plan:
+1. Breaks the goal into manageable phases
 2. Identifies specific tasks within each phase
 3. Assigns each task to the most appropriate agent
 4. Considers dependencies and parallelization opportunities
-5. Includes validation and review steps`,
+5. Includes validation and review steps
+
+Respond with ONLY the <plan>...</plan> block and no other prose.`,
             status: "in_progress",
             priority: "critical",
             assignedTo: "orchestrator",
@@ -153,7 +160,11 @@ Explore the codebase to understand the current state, then create a comprehensiv
                     description: taskDescMatch?.[1]?.trim() ?? "",
                     status: "pending",
                     priority: priority,
-                    assignedTo: agent,
+                    // Normalize role casing: the planning prompt lists specialists as
+                    // "Coder"/"Reviewer"/"Tester" (capitalized), so models often emit
+                    // `agent="Coder"`, but the agent registry is keyed lowercase. Without
+                    // this, `agents.get("Coder")` misses and the worker never runs.
+                    assignedTo: (agent ?? "coder").toLowerCase(),
                     dependencies: [],
                     subtasks: [],
                     artifacts: [],

package/dist/agent/multi-agent/multi-agent-system.js

@@ -507,7 +507,9 @@ export class MultiAgentSystem extends EventEmitter {
             this.addTimelineEvent("task_started", `Reallocated: ${task.title} → ${resolvedRole}`, { task, originalRole: task.assignedTo, resolvedRole });
             task.assignedTo = resolvedRole;
         }
-        const agent = this.agents.get(task.assignedTo);
+        // Case-insensitive lookup: plans may carry capitalized roles ("Coder").
+        const agent = this.agents.get(task.assignedTo) ??
+            this.agents.get(String(task.assignedTo).toLowerCase());
         if (!agent) {
             errors.push(`No agent found for role: ${task.assignedTo}`);
             return;

package/dist/agent/multi-agent/session-fleet-bridge.d.ts

@@ -28,6 +28,8 @@
  *   could fill the WS send buffer.
  */
 import type { SessionRegistry } from './session-registry.js';
+export type FleetEventBroadcaster = (type: any, payload: any, agentId?: string) => void;
+export declare function registerSessionFleetBroadcaster(broadcaster: FleetEventBroadcaster): void;
 export interface SessionFleetBridgeHandle {
     /** Detach listeners. Idempotent. */
     disable: () => void;

package/dist/agent/multi-agent/session-fleet-bridge.js

@@ -27,7 +27,15 @@
  * - No back-pressure (same as (d).1 deferral). Bursty session activity
  *   could fill the WS send buffer.
  */
-import { broadcastFleetEvent } from '../../server/websocket/fleet-bridge.js';
+let _fleetBroadcaster = null;
+export function registerSessionFleetBroadcaster(broadcaster) {
+    _fleetBroadcaster = broadcaster;
+}
+function broadcastFleetEvent(type, payload, agentId) {
+    if (_fleetBroadcaster) {
+        _fleetBroadcaster(type, payload, agentId);
+    }
+}
 function isFleetStreamEnabled() {
     const v = process.env.CODEBUDDY_FLEET_STREAM;
     return v === '1' || v === 'true' || v === 'TRUE';

package/dist/agent/multi-agent/session-tools.js

@@ -368,21 +368,36 @@ export class SessionToolExecutor {
         const limit = this.parseSessionSearchLimit(args.limit);
         const { getSessionStore } = await import('../../persistence/session-store.js');
         const sessions = (await getSessionStore().searchSessions(query)).slice(0, limit);
+        const citations = [];
         const formatted = sessions.map(session => {
             const metadata = session.metadata && typeof session.metadata === 'object'
                 ? session.metadata
                 : {};
+            const messageId = typeof metadata.searchMessageId === 'number' ? metadata.searchMessageId : undefined;
+            const role = typeof metadata.searchRole === 'string' ? metadata.searchRole : undefined;
+            const snippet = typeof metadata.searchSnippet === 'string' ? metadata.searchSnippet : '';
+            const citation = {
+                sessionId: session.id,
+                snippet,
+                label: messageId ? `session:${session.id}#message:${messageId}` : `session:${session.id}`,
+            };
+            if (messageId !== undefined)
+                citation.messageId = messageId;
+            if (role)
+                citation.role = role;
             const match = {
-                snippet: metadata.searchSnippet ?? '',
+                snippet,
+                citation,
             };
-            if (metadata.searchRole)
-                match.role = metadata.searchRole;
+            if (role)
+                match.role = role;
             if (typeof metadata.searchScore === 'number')
                 match.score = metadata.searchScore;
-            if (typeof metadata.searchMessageId === 'number')
-                match.messageId = metadata.searchMessageId;
+            if (messageId !== undefined)
+                match.messageId = messageId;
             if (metadata.parentSessionId)
                 match.parentSessionId = metadata.parentSessionId;
+            citations.push(citation);
             return {
                 id: session.id,
                 name: session.name,
@@ -391,6 +406,7 @@ export class SessionToolExecutor {
                 messageCount: Array.isArray(session.messages) ? session.messages.length : 0,
                 createdAt: session.createdAt.toISOString(),
                 lastAccessedAt: session.lastAccessedAt.toISOString(),
+                citation,
                 match,
             };
         });
@@ -398,6 +414,7 @@ export class SessionToolExecutor {
             query,
             total: formatted.length,
             sessions: formatted,
+            citations,
         };
         return {
             success: true,

package/dist/agent/reasoning/mcts.js

@@ -487,21 +487,35 @@ export class MCTS {
     findBestSolution() {
         if (!this.root)
             return null;
+        // Preferred tier: the best-scoring terminal-typed node (a concrete
+        // `implementation` or an explicit `conclusion`). Fallback tier: the
+        // best-scoring *derived* node of any type — many problems/models yield only
+        // analysis/verification/hypothesis thoughts, and a high-scoring one of those
+        // is still the best answer the search found. Without the fallback, such a
+        // search returns null even when a node scored 1.0. Both tiers exclude pruned
+        // nodes and the root (the problem statement, depth 0 — not a derived solution).
         let best = null;
         let bestScore = -1;
+        let fallback = null;
+        let fallbackScore = -1;
         const traverse = (node) => {
-            if (node.state !== 'pruned' &&
-                (node.type === 'implementation' || node.type === 'conclusion') &&
-                node.score > bestScore) {
-                bestScore = node.score;
-                best = node;
+            if (node.state !== 'pruned' && node.depth > 0) {
+                if ((node.type === 'implementation' || node.type === 'conclusion') &&
+                    node.score > bestScore) {
+                    bestScore = node.score;
+                    best = node;
+                }
+                if (node.score > fallbackScore) {
+                    fallbackScore = node.score;
+                    fallback = node;
+                }
             }
             for (const child of node.children) {
                 traverse(child);
             }
         };
         traverse(this.root);
-        return best;
+        return best ?? fallback;
     }
     /**
      * Get the path from root to a node

package/dist/agent/session-end-flush.d.ts

@@ -9,7 +9,10 @@
  *  2. reusable lesson candidates via the existing review-gated
  *     auto-proposer (PENDING only — a human approves them into lessons.md,
  *     which the per-turn `<lessons_context>` injection then re-injects on
- *     future runs).
+ *     future runs);
+ *  3. declarative long-term memory candidates via the review-gated memory
+ *     queue. These do not enter prompt-injected persistent memory until a
+ *     human accepts them.
  *
  * Guard-rails: trivial sessions are skipped (no LLM call, no file), and
  * everything written here passes the privacy lint first (PII/secret spans
@@ -32,6 +35,8 @@ export interface SessionEndFlushInput {
 export interface SessionEndFlushResult {
     /** Lesson candidates enqueued for review (`buddy lessons` to approve). */
     proposedLessons: number;
+    /** Declarative memory candidates enqueued for review (`/memory candidates`). */
+    proposedMemories: number;
     /** Absolute path of the handoff file, when one was (re)written. */
     handoffPath?: string;
     openRisks: string[];