osborn 0.9.211 → 0.9.213

package/dist/claude-llm.js

@@ -11,8 +11,10 @@ import { query } from '@anthropic-ai/claude-agent-sdk';
 import { EventEmitter } from 'events';
 import { saveSessionMetadata, getSessionWorkspace } from './config.js';
 import { statusManager } from './status-manager.js';
-import { getResearchSystemPrompt, getDirectModeResearchPrompt } from './prompts.js';
+import { getResearchSystemPrompt, getDirectModeResearchPrompt, getGroundingBlock, getRecalledContextBlock } from './prompts.js';
 import { getIndexPath } from './summary-index.js';
+import { openStore, recall, storeExists, updateSessionStore, getStorePath } from './session-store.js';
+import { getEmbedder } from './embedder.js';
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -20,6 +22,70 @@ import { homedir } from 'node:os';
 // Directory of this module — used to locate co-located prompt files (e.g., turn-shape reminder).
 const __claudeLlmDir = dirname(fileURLToPath(import.meta.url));
 const TURN_SHAPE_REMINDER_PATH = join(__claudeLlmDir, 'prompts', 'turn-shape-reminder.md');
+// ── Recall auto-injection (reliable "remembers to check" per Agent-SDK research) ──
+// The RELIABLE primitive the Agent SDK exposes is a UserPromptSubmit hook returning
+// additionalContext: deterministic per-turn injection the model cannot skip (vs. an
+// MCP/skill recall tool the model must elect to call). We piggyback on the existing
+// turn-shape-reminder hook and append the top-K prior messages relevant to THIS prompt.
+//
+// Scope: this hook lives on the MAIN conductor's query options only. Named adversarial
+// sub-agents (reviewer/tester) are spawned as SEPARATE query() calls with their own
+// options and NO UserPromptSubmit hook — they stay deliberately un-grounded, so this
+// injection never leaks into them. Task-delegated agents (researcher/writer/…) don't
+// fire UserPromptSubmit (that event is for real user turns), so they're unaffected too.
+//
+// COMPACT by design: paid on every turn, so top-5 with a per-hit char cap (~800) →
+// ~4KB. FULL untruncated text stays available on demand via `osborn-recall`.
+const RECALL_TOP_K = 5;
+const RECALL_PER_HIT_CHARS = 800;
+const RECALL_ENABLED = () => process.env.OSBORN_RECALL_INJECT !== '0';
+// Warm the embedder once (fire-and-forget) so hybrid recall is ready without blocking
+// the first turn; until it's warm, recall() falls back to keyword-only (~16ms).
+let __embedderWarmed = false;
+function warmEmbedder() {
+    if (__embedderWarmed || process.env.OSBORN_EMBED === '0')
+        return;
+    __embedderWarmed = true;
+    getEmbedder().catch(() => { });
+}
+/** Build the recalled-context block to inject alongside the turn-shape reminder. '' on any miss. */
+async function buildRecallInjection(sessionId, workingDir, prompt) {
+    try {
+        if (!RECALL_ENABLED() || !sessionId || !workingDir)
+            return '';
+        const q = String(prompt || '').trim();
+        if (q.length < 3)
+            return '';
+        if (!storeExists(sessionId, workingDir))
+            return '';
+        warmEmbedder();
+        // Only use the embedder if it's already loaded — never block the turn on a cold load.
+        const embed = (__embedderWarmed && process.env.OSBORN_EMBED !== '0') ? (await getEmbedder()) ?? undefined : undefined;
+        const { getStorePath } = await import('./session-store.js');
+        const db = openStore(getStorePath(sessionId, workingDir));
+        let hits;
+        try {
+            hits = await recall(db, q, { mode: embed ? 'hybrid' : 'keyword', topK: RECALL_TOP_K, embed });
+        }
+        finally {
+            db.close();
+        }
+        if (!hits.length)
+            return '';
+        const lines = hits.map((h, i) => {
+            let body = h.text.replace(/\n{3,}/g, '\n\n').trim();
+            if (body.length > RECALL_PER_HIT_CHARS)
+                body = body.slice(0, RECALL_PER_HIT_CHARS) + ' …';
+            const src = `${h.source} L${h.lineNum} · ${h.msgType}${h.toolName ? `:${h.toolName}` : ''}`;
+            return `[${i + 1}] (${src})\n${body}`;
+        });
+        // Static wrapper is centralized + parameterized in ./prompts/recalled-context.md.
+        return getRecalledContextBlock(lines.join('\n\n'));
+    }
+    catch {
+        return ''; // recall is best-effort — never break the turn
+    }
+}
 // ≤3 direct tool call budget per turn. Reset on every UserPromptSubmit (new user message).
 // Enforced mechanically in PreToolUse — the model CANNOT exceed this regardless of JSONL history.
 // Task/Agent delegations are exempt (delegation is what we WANT). Sub-agent tool calls
@@ -133,6 +199,58 @@ function loadAllSkills(_workingDir) {
     console.log(`📚 Loaded ${skillMap.size} skill(s) from ${homeSkillsDir}`);
     return `<available-skills>\n${[...skillMap.values()].join('\n\n---\n\n')}\n</available-skills>`;
 }
+/**
+ * Enumerate the agent's CURRENT skills (name + one-line description) from
+ * ~/.claude/skills, for injection into the PreCompact instruction. This is the
+ * list the compaction model dedupes/merges against so it stops re-emitting
+ * duplicate skills every session. Description is taken from YAML frontmatter
+ * (`description:`) when present, else the WHEN: line, else the first non-heading
+ * line. Returns one `- name: description` per line, or '' if none.
+ */
+function enumerateSkillsForCompaction() {
+    const dir = join(homedir(), '.claude', 'skills');
+    if (!existsSync(dir))
+        return '';
+    const lines = [];
+    try {
+        for (const name of readdirSync(dir).sort()) {
+            const file = join(dir, name, 'SKILL.md');
+            if (!existsSync(file))
+                continue;
+            let desc = '';
+            try {
+                const raw = readFileSync(file, 'utf-8');
+                const fm = raw.match(/^---\n([\s\S]*?)\n---/);
+                if (fm) {
+                    const m = fm[1].match(/^description:\s*(.+)$/m);
+                    if (m)
+                        desc = m[1].trim();
+                }
+                if (!desc) {
+                    const body = raw.replace(/^---\n[\s\S]*?\n---\n?/, '');
+                    const when = body.match(/^\s*WHEN:\s*(.+)$/mi);
+                    if (when)
+                        desc = when[1].trim();
+                }
+                if (!desc) {
+                    const body = raw.replace(/^---\n[\s\S]*?\n---\n?/, '');
+                    const first = body.split('\n').map(l => l.trim()).find(l => l && !l.startsWith('#'));
+                    desc = first || '(no description)';
+                }
+            }
+            catch {
+                desc = '(unreadable)';
+            }
+            if (desc.length > 180)
+                desc = desc.slice(0, 177) + '…';
+            lines.push(`- ${name}: ${desc}`);
+        }
+    }
+    catch (err) {
+        console.warn('⚠️ enumerateSkillsForCompaction failed:', err instanceof Error ? err.message : err);
+    }
+    return lines.join('\n');
+}
 // Compaction threshold: Fable 5 runs a 1M context window, so let sessions use
 // all of it before auto-compacting. autoCompactWindow max is 1_000_000; the SDK
 // reads it from settings.json (settingSources includes 'user'), so merge it into
@@ -201,6 +319,7 @@ export const NAMED_AGENTS = {
             'GROUNDED: reads the session search-index for prior findings before researching.',
         ].join(' '),
         tools: ['Read', 'Glob', 'Grep', 'Bash', 'WebSearch', 'WebFetch', 'Task'],
+        grounded: true, // applyGrounding() injects the osborn-recall command + ensures Bash
         model: 'sonnet',
         prompt: [
             'You are Osborn\'s research agent. Your job is information gathering — thorough, structured, factual.',
@@ -209,8 +328,7 @@ export const NAMED_AGENTS = {
             'Gather information the main agent needs to answer the user\'s question or make a decision.',
             'You are a scout — go find things, read them carefully, and report back.',
             '',
-            '## Grounding — check the session index first',
-            'Before researching, locate the session index (search-index.txt — a compact line-per-message log of this mission, under .claude/projects/<slug>/osb/<session>/; if several exist pick the most recently modified) and Grep it for the topic you are about to investigate. Read ONLY the matching slice, never the whole file.',
+            'Before researching, GROUND yourself using the recall command in the Grounding section appended to this prompt — check prior findings, decisions, and gotchas so you do not redo settled work.',
             'Purpose: find what has ALREADY been decided, answered, or ruled out so you do not re-research a settled question. If the index already establishes the answer, report that (with the index reference) instead of redoing the work.',
             'If you cannot find the index, proceed normally — this is an optimization, not a hard dependency.',
             '',
@@ -303,6 +421,7 @@ export const NAMED_AGENTS = {
             'GROUNDED: reads the session search-index before editing to avoid contradicting prior decisions.',
         ].join(' '),
         tools: ['Read', 'Write', 'Edit', 'MultiEdit', 'Bash', 'Glob', 'Grep', 'NotebookRead', 'NotebookEdit'],
+        grounded: true, // applyGrounding() injects the osborn-recall command
         model: 'opus',
         prompt: [
             'You are Osborn\'s writer agent. You execute file changes with a verify-first approach.',
@@ -311,8 +430,7 @@ export const NAMED_AGENTS = {
             'Handle ALL file operations — code, config, documentation, scripts, data files.',
             'You are the only agent that writes. The main agent and reasoner produce plans; you execute them.',
             '',
-            '## Grounding — consult the session index (light touch)',
-            'Before editing, locate the session index (search-index.txt under .claude/projects/<slug>/osb/<session>/; newest if several) and Grep it ONLY for: (a) the files/symbols you are about to change, and (b) any recorded DECISIONS or known GOTCHAS relevant to this change. Read only the matching lines — do NOT read the whole index (thousands of lines). This is a lighter dose than the reviewer: a targeted lookup.',
+            'Before editing, GROUND yourself using the recall command in the Grounding section appended to this prompt — check for prior DECISIONS and known GOTCHAS on the files/symbols you are about to change.',
             'If a decision or gotcha contradicts your task, STOP and report to the main agent before editing. If you find nothing or no index exists, proceed normally.',
             '',
             '## VERIFY-FIRST workflow (mandatory)',
@@ -367,7 +485,7 @@ export const NAMED_AGENTS = {
             'observed behavior without a matching requirement is a regression — treat behavioral surprise as a defect.',
             '',
             '## Grounding — consult shared context before writing or running tests',
-            'Before deciding what to test, locate the session index (search-index.txt under .claude/projects/<slug>/osb/<session>/; newest if several) and Grep it for the changes/work under test. Also check project docs and known-issues files. Key doc locations to consult: `/workspace/osborn/CLAUDE.md`, `/workspace/osborn/docs/critical-patterns.md`, the `docs/` directory, `README.md`, and `CHANGELOG.md`. Check these for: (a) KNOWN ISSUES and gotchas already recorded, and (b) what behavior is ALREADY covered by existing tests.',
+            'Before deciding what to test, check project docs and known-issues files (these live under the working dir and ARE readable). Key doc locations to consult: `/workspace/osborn/CLAUDE.md`, `/workspace/osborn/docs/critical-patterns.md`, the `docs/` directory, `README.md`, and `CHANGELOG.md`. Check these for: (a) KNOWN ISSUES and gotchas already recorded, and (b) what behavior is ALREADY covered by existing tests. (You are adversarial and deliberately NOT given session recall — validate with fresh eyes.)',
             'Purpose: target regression coverage at real GAPS and known-risk areas rather than testing blind or duplicating coverage — and stay IN SYNC with the reviewer, which reads the same sources.',
             'Read only the relevant slice of the index, never the whole file. If you find nothing or no index/docs exist, proceed normally — this is an optimization, not a hard dependency.',
             'If the change adds or renames a feature, flag any doc now out of date (see DOC STALENESS in "What to return").',
@@ -450,6 +568,7 @@ export const NAMED_AGENTS = {
             'GROUNDED: reads the session search-index before planning to respect prior decisions.',
         ].join(' '),
         tools: ['Read', 'Glob', 'Grep', 'WebSearch'],
+        grounded: true, // applyGrounding() injects the osborn-recall command + adds Bash
         model: 'sonnet',
         prompt: [
             'You are Osborn\'s planning agent. Your job is to decompose complex tasks into clear, atomic steps.',
@@ -459,7 +578,7 @@ export const NAMED_AGENTS = {
             'step by step without guessing. You are the bridge between "what" and "how".',
             '',
             '## Grounding — plan against what already exists',
-            'Before drafting a plan, locate the session index (search-index.txt under .claude/projects/<slug>/osb/<session>/; newest if several) and Grep it for prior DECISIONS, constraints, and known GOTCHAS relevant to the task. Read only the matching slice, never the whole file.',
+            'Before drafting a plan, GROUND yourself using the recall command in the Grounding section appended to this prompt — check prior DECISIONS, constraints, and known GOTCHAS relevant to the task.',
             'Purpose: make the plan fit what has already been decided or tried — do not propose an approach the mission already ruled out. If a prior decision conflicts with the obvious plan, surface it in the plan rather than silently contradicting it.',
             'If you cannot find the index, proceed normally.',
             '',
@@ -630,6 +749,47 @@ export function applyTurbo(agents, turbo) {
     }
     return out;
 }
+/**
+ * Inject session-recall grounding into any agent flagged `grounded: true`.
+ *
+ * WHY: a sub-agent's file tools (Read/Grep/Glob) are sandboxed to its cwd +
+ * additionalDirectories, so it CANNOT read the session index / session.db that live
+ * under $HOME/.claude/projects/… — the old "grep search-index.txt" grounding silently
+ * failed. Bash, however, is NOT cwd-restricted, so `osborn-recall` reaches the store.
+ *
+ * So for every grounded agent we (1) hand it the EXACT, absolute-path osborn-recall
+ * command (resolved once here — the single dynamic resolver, so we never hardcode a
+ * per-agent path; works for named AND user-created custom grounded agents), and
+ * (2) guarantee Bash is in its tool set so it can run that command. The `grounded`
+ * flag is stripped before the roster reaches the SDK. NEVER mutates the input.
+ *
+ * Adversarial agents (reviewer/tester) leave `grounded` unset → untouched, stay blind.
+ */
+export function applyGrounding(agents, sessionId, workingDir) {
+    const out = {};
+    // Resolve the store command ONCE — absolute --db path, cwd-independent.
+    const dbPath = (sessionId && sessionId !== 'pending' && workingDir)
+        ? getStorePath(sessionId, workingDir) : null;
+    for (const [name, agent] of Object.entries(agents)) {
+        if (!agent?.grounded) {
+            out[name] = agent;
+            continue;
+        }
+        const { grounded, ...rest } = agent;
+        // Ensure Bash is available so the agent can actually run osborn-recall.
+        const tools = Array.isArray(rest.tools) ? [...rest.tools] : [];
+        if (!tools.includes('Bash'))
+            tools.push('Bash');
+        // Push the grounding block into the system prompt (arrives at spawn — sandbox-proof).
+        const cmd = dbPath
+            ? `osborn-recall "<terms from your task>" --db ${dbPath} --top-k 8`
+            : `osborn-recall "<terms from your task>" --top-k 8`;
+        // Body is centralized + parameterized in ./prompts/grounding-recall.md.
+        const groundingBlock = getGroundingBlock(cmd);
+        out[name] = { ...rest, tools, prompt: `${rest.prompt || ''}\n${groundingBlock}` };
+    }
+    return out;
+}
 const RESEARCH_TOOLS = [
     'Read', 'Write', 'Edit', 'Glob', 'Grep',
     'Bash', 'WebSearch', 'WebFetch',
@@ -714,6 +874,11 @@ export class ClaudeLLM extends llm.LLM {
     // Dedup guard — prevents double-firing reviewer/gate if SubagentStop fires
     // more than once for the same agent_id (e.g. retry edge cases).
     #dispatchedFor = new Set();
+    // Embedded session.db write-through guard. The store write is triggered from the
+    // UserPromptSubmit hook (once per real user submission, main-thread only) and sweeps
+    // the FULL source set — main JSONL + every sub-agent JSONL — exactly like the flat
+    // index. Incremental (byte-offset resume) + fire-and-forget, so it never blocks a turn.
+    #storeUpdating = false;
     // Turbo mode — when true, every spawned agent (main + sub-agents) runs on
     // FAST_MODEL regardless of individual model config. Default off = no-op.
     #turbo = false;
@@ -806,6 +971,34 @@ export class ClaudeLLM extends llm.LLM {
     // ============================================================
     // MCP SERVER MANAGEMENT - Runtime enable/disable MCP servers
     // ============================================================
+    /**
+     * Guarded, fire-and-forget write-through to the embedded session.db. Called from the
+     * main agent's UserPromptSubmit hook (once per real user submission). Sweeps the FULL
+     * source set — main JSONL + every sub-agent JSONL — incrementally (byte-offset resume).
+     * The guard lives here (on the long-lived ClaudeLLM, not the per-turn stream) so a slow
+     * write can't overlap the next turn's write. Never throws; never blocks the caller.
+     */
+    triggerStoreUpdate(sessionId, workingDir) {
+        if (this.#storeUpdating || !sessionId || sessionId === 'pending' || !workingDir)
+            return;
+        if (process.env.OSBORN_STORE === '0')
+            return;
+        this.#storeUpdating = true;
+        (async () => {
+            try {
+                const embed = process.env.OSBORN_EMBED === '0' ? undefined : (await getEmbedder()) ?? undefined;
+                const stats = await updateSessionStore(sessionId, workingDir, { embed });
+                if (stats.newRows > 0)
+                    console.log(`🗄️  [store] +${stats.newRows} rows (${stats.totalRows} total, embedded=${stats.embeddedRows}) across main+subagents`);
+            }
+            catch (err) {
+                console.error('🗄️  [store] update failed:', err?.message);
+            }
+            finally {
+                this.#storeUpdating = false;
+            }
+        })();
+    }
     /**
      * Get all currently enabled MCP servers
      */
@@ -1920,11 +2113,31 @@ class ClaudeLLMStream extends llm.LLMStream {
                                         turnToolCallCount = 0;
                                         const reminder = readFileSync(TURN_SHAPE_REMINDER_PATH, 'utf-8');
                                         const promptPreview = String(input?.prompt || '').substring(0, 60).replace(/\n/g, ' ');
-                                        console.log(`📌 UserPromptSubmit: injected turn-shape reminder (${reminder.length} chars) for prompt="${promptPreview}..." [tool budget reset to 0/${TOOL_CALL_BUDGET}]`);
+                                        // Reliable recall: retrieve prior messages relevant to THIS prompt and inject
+                                        // them deterministically. MAIN CONDUCTOR ONLY — gate explicitly on agent_id.
+                                        // Per the SDK: agent_id is present ONLY when a hook fires from within a subagent,
+                                        // absent on the main thread. So `agent_id` set ⇒ skip (grounded sub-agents pull
+                                        // via osborn-recall from their own prompt; adversarial ones stay un-grounded).
+                                        const fromSubagent = Boolean(input?.agent_id);
+                                        const sid = input?.session_id || this.#sessionId;
+                                        // Consolidated WRITE trigger: on every real user submission (main thread only),
+                                        // sweep main + ALL sub-agent JSONLs into session.db. Naturally debounced to the
+                                        // user's speech cadence (one submission = one sweep); guarded + fire-and-forget
+                                        // on the long-lived ClaudeLLM so injection below never waits on it. This is the
+                                        // single canonical write path — mirrors the flat index's sub-agent sweep, but
+                                        // stores FULL untruncated text + FTS5 + sqlite-vec instead of truncated summaries.
+                                        if (!fromSubagent && sid && this.#opts.workingDirectory) {
+                                            this.#llmRef.triggerStoreUpdate(sid, this.#opts.workingDirectory);
+                                        }
+                                        const recalled = fromSubagent
+                                            ? ''
+                                            : await buildRecallInjection(sid, this.#opts.workingDirectory, String(input?.prompt || ''));
+                                        const additionalContext = recalled ? `${reminder}\n\n${recalled}` : reminder;
+                                        console.log(`📌 UserPromptSubmit: injected turn-shape reminder (${reminder.length} chars)${recalled ? ` + recall (${recalled.length} chars)` : ''} for prompt="${promptPreview}..." [tool budget reset to 0/${TOOL_CALL_BUDGET}]`);
                                         return {
                                             hookSpecificOutput: {
                                                 hookEventName: 'UserPromptSubmit',
-                                                additionalContext: reminder,
+                                                additionalContext,
                                             },
                                         };
                                     }
@@ -1944,8 +2157,28 @@ class ClaudeLLMStream extends llm.LLMStream {
                                     try {
                                         this.#opts.onCompactionEvent?.({ type: 'compaction_started', trigger: input?.trigger });
                                         const instructionPath = join(__claudeLlmDir, 'prompts', 'compact-learnings-instruction.md');
-                                        const instruction = existsSync(instructionPath) ? readFileSync(instructionPath, 'utf-8') : '';
-                                        console.log(`🧠 PreCompact: injecting instruction (${instruction.length} chars, trigger=${input?.trigger || 'unknown'})`);
+                                        const instructionRaw = existsSync(instructionPath) ? readFileSync(instructionPath, 'utf-8') : '';
+                                        // Populate the EXISTING SKILLS section the instruction .md already refers to
+                                        // (lines 42 & 55) but that nothing used to fill. Without this, the model is told
+                                        // to "not re-emit skills already shown" against a list it never received — so it
+                                        // proliferated duplicates. We hand it the current skill set + an adversarial,
+                                        // self-critical directive to merge/refine rather than create anew.
+                                        const existingSkills = enumerateSkillsForCompaction();
+                                        const skillCount = existingSkills ? existingSkills.split('\n').length : 0;
+                                        const criticBlock = existingSkills
+                                            ? `\n\n---\n\n=== EXISTING SKILLS (${skillCount}) ===\n`
+                                                + `These skills ALREADY EXIST for this user (name: description). Before you emit `
+                                                + `SKILL_CANDIDATES or BEHAVIORAL_LEARNINGS, act as an ADVERSARIAL reviewer of your own output:\n`
+                                                + `1. If a candidate duplicates or substantially overlaps one below, DO NOT create a new skill — `
+                                                + `re-emit it under the EXACT SAME kebab-case name, and only if it needs a substantive update; otherwise omit it.\n`
+                                                + `2. Propose a brand-new skill ONLY if nothing below covers it, it was CONFIRMED working this session, `
+                                                + `and it generalizes to future sessions on different tasks.\n`
+                                                + `3. Prefer merging/refining over proliferating. A small set of sharp, non-overlapping skills is the goal — `
+                                                + `reject your own low-signal or one-off candidates.\n\n`
+                                                + `${existingSkills}\n`
+                                            : '';
+                                        const instruction = instructionRaw + criticBlock;
+                                        console.log(`🧠 PreCompact: injecting instruction (${instruction.length} chars, ${skillCount} existing skills, trigger=${input?.trigger || 'unknown'})`);
                                         return { systemMessage: instruction };
                                     }
                                     catch (err) {
@@ -2005,7 +2238,7 @@ class ClaudeLLMStream extends llm.LLMStream {
                                                     const decPath = join(decFolder, 'SKILL.md');
                                                     mkdirSync(decFolder, { recursive: true });
                                                     const existing = existsSyncFs(decPath) ? readSyncFs(decPath, 'utf-8') : '';
-                                                    const header = existing ? '' : `# Project Decisions\n\nAuto-extracted from compact summaries.\n\n`;
+                                                    const header = existing ? '' : `---\nname: decisions\ndescription: "Project-scoped architectural and implementation decisions auto-extracted from compaction summaries; consult before revisiting settled choices."\nmetadata:\n  type: learned\n  source: postcompact\n---\n\n# Project Decisions\n\nAuto-extracted from compact summaries.\n\n`;
                                                     const entry = `\n## ${today} (session ${sessionId.substring(0, 8)})\n${projectLines.join('\n')}\n`;
                                                     writeSyncFs(decPath, header + existing + entry, 'utf-8');
                                                     console.log(`🧠 PostCompact: appended ${projectLines.length} decision(s) to ${decPath}`);
@@ -2035,8 +2268,14 @@ class ClaudeLLMStream extends llm.LLMStream {
                                                     const skillFolder = join(skillDir, '.claude', 'skills', name);
                                                     const skillPath = join(skillFolder, 'SKILL.md');
                                                     mkdirSync(skillFolder, { recursive: true });
-                                                    const header = `# ${name}\nAuto-extracted: ${today} | Session: ${sessionId.substring(0, 8)}\n\n`;
-                                                    writeSyncFs(skillPath, header + body + '\n', 'utf-8');
+                                                    // Emit STANDARD skill format: YAML frontmatter (name + description) so
+                                                    // learned skills conform to the same shape the loader/other agents expect.
+                                                    // Description is derived from the candidate's WHEN: line; JSON.stringify
+                                                    // yields a safely-quoted YAML scalar even when it contains colons/quotes.
+                                                    const whenMatch = body.match(/^\s*WHEN:\s*(.+)$/mi);
+                                                    const desc = (whenMatch ? whenMatch[1].trim() : `Learned procedure: ${name}`).replace(/\s+/g, ' ').slice(0, 200);
+                                                    const frontmatter = `---\nname: ${name}\ndescription: ${JSON.stringify(desc)}\nmetadata:\n  type: learned\n  source: postcompact\n  session: ${sessionId.substring(0, 8)}\n  updated: ${today}\n---\n\n`;
+                                                    writeSyncFs(skillPath, frontmatter + `# ${name}\n\n` + body + '\n', 'utf-8');
                                                     console.log(`🧠 PostCompact: wrote skill '${name}' to ${skillPath}`);
                                                     skillsWritten++;
                                                     skillNames.push(name);
@@ -2055,7 +2294,7 @@ class ClaudeLLMStream extends llm.LLMStream {
                                                 const skillFolder = join(skillDir, '.claude', 'skills', 'learned-behaviors');
                                                 const skillPath = join(skillFolder, 'SKILL.md');
                                                 mkdirSync(skillFolder, { recursive: true });
-                                                const header = `# Learned Behaviors\n\nAuto-extracted from voice sessions via PostCompact.\nLast updated: ${today} | Session: ${sessionId.substring(0, 8)}...\n\n`;
+                                                const header = `---\nname: learned-behaviors\ndescription: "User corrections, preferences, domain knowledge, effective patterns, and anti-patterns learned across sessions; apply to align with how this user works."\nmetadata:\n  type: learned\n  source: postcompact\n  updated: ${today}\n---\n\n# Learned Behaviors\n\nAuto-extracted from voice sessions via PostCompact.\nLast updated: ${today} | Session: ${sessionId.substring(0, 8)}...\n\n`;
                                                 writeSyncFs(skillPath, header + learnings + '\n', 'utf-8');
                                                 console.log(`🧠 PostCompact: wrote learned behaviors to ${skillPath} (${learnings.length} chars)`);
                                                 skillsWritten++;
@@ -2159,9 +2398,9 @@ class ClaudeLLMStream extends llm.LLMStream {
                 // opts.agents is undefined — the ?? NAMED_AGENTS fallback would skip
                 // the override entirely. Explicitly apply applyTurbo(NAMED_AGENTS)
                 // so built-in agents always get FAST_MODEL when turbo is on.
-                agents: this.#llmRef.turbo
+                agents: applyGrounding(this.#llmRef.turbo
                     ? applyTurbo(this.#opts.agents ?? NAMED_AGENTS, true)
-                    : (this.#opts.agents ?? NAMED_AGENTS),
+                    : (this.#opts.agents ?? NAMED_AGENTS), this.#sessionId, this.#opts.workingDirectory),
             };
             // Run Claude Agent SDK query() and stream results
             let hasOutput = false;

package/dist/embedder.d.ts

@@ -0,0 +1,23 @@
+/**
+ * embedder.ts — Local text→vector embedder for the semantic (vec) layer of session-store.
+ *
+ * Uses all-MiniLM-L6-v2 (384-dim) via @xenova/transformers, running fully local (no API,
+ * no per-write network cost). Output is L2-normalized float32, quantized to int8[384]
+ * (×127) to match the sqlite-vec `int8[384]` column — 4× smaller than float32 with
+ * ~98–99% recall.
+ *
+ * DESIGN FOR RELIABILITY:
+ *   • Lazy — the model is loaded on first use, never at import (startup stays fast).
+ *   • Best-effort — if the package or model can't load, getEmbedder() returns null and
+ *     the store runs keyword-only. Embeddings never block the keyword write path.
+ *   • Gated — set OSBORN_EMBED=0 to force keyword-only (e.g. on machines without the
+ *     model cached, or to avoid the first-run model download).
+ *
+ * Model cache honors TRANSFORMERS_CACHE / HF_HOME so it can be baked into the image.
+ */
+import { type Embedder } from './session-store.js';
+/**
+ * Returns an Embedder, or null if embeddings are unavailable/disabled.
+ * The returned function itself also degrades to null on runtime failure.
+ */
+export declare function getEmbedder(): Promise<Embedder | null>;

package/dist/embedder.js

@@ -0,0 +1,98 @@
+/**
+ * embedder.ts — Local text→vector embedder for the semantic (vec) layer of session-store.
+ *
+ * Uses all-MiniLM-L6-v2 (384-dim) via @xenova/transformers, running fully local (no API,
+ * no per-write network cost). Output is L2-normalized float32, quantized to int8[384]
+ * (×127) to match the sqlite-vec `int8[384]` column — 4× smaller than float32 with
+ * ~98–99% recall.
+ *
+ * DESIGN FOR RELIABILITY:
+ *   • Lazy — the model is loaded on first use, never at import (startup stays fast).
+ *   • Best-effort — if the package or model can't load, getEmbedder() returns null and
+ *     the store runs keyword-only. Embeddings never block the keyword write path.
+ *   • Gated — set OSBORN_EMBED=0 to force keyword-only (e.g. on machines without the
+ *     model cached, or to avoid the first-run model download).
+ *
+ * Model cache honors TRANSFORMERS_CACHE / HF_HOME so it can be baked into the image.
+ */
+import { EMBED_DIM } from './session-store.js';
+const MODEL_ID = process.env.OSBORN_EMBED_MODEL || 'Xenova/all-MiniLM-L6-v2';
+let pipelinePromise = null;
+let disabled = false;
+/** Quantize a normalized float32 embedding to int8[dim] (×127, clamped). */
+function quantizeInt8(floats) {
+    const out = new Int8Array(EMBED_DIM);
+    const n = Math.min(EMBED_DIM, floats.length);
+    for (let i = 0; i < n; i++) {
+        let v = Math.round(floats[i] * 127);
+        if (v > 127)
+            v = 127;
+        else if (v < -128)
+            v = -128;
+        out[i] = v;
+    }
+    return out;
+}
+async function loadPipeline() {
+    if (disabled)
+        return null;
+    if (process.env.OSBORN_EMBED === '0') {
+        disabled = true;
+        return null;
+    }
+    if (!pipelinePromise) {
+        pipelinePromise = (async () => {
+            // Lazy import — @xenova/transformers is heavy and optional.
+            const mod = await import('@xenova/transformers').catch(() => null);
+            if (!mod)
+                throw new Error('@xenova/transformers not installed');
+            if (mod.env) {
+                mod.env.allowLocalModels = true;
+                // Avoid noisy multi-thread wasm issues in the agent process.
+                if (mod.env.backends?.onnx?.wasm)
+                    mod.env.backends.onnx.wasm.numThreads = 1;
+            }
+            return mod.pipeline('feature-extraction', MODEL_ID);
+        })().catch((err) => {
+            disabled = true;
+            pipelinePromise = null;
+            throw err;
+        });
+    }
+    return pipelinePromise;
+}
+/**
+ * Returns an Embedder, or null if embeddings are unavailable/disabled.
+ * The returned function itself also degrades to null on runtime failure.
+ */
+export async function getEmbedder() {
+    if (process.env.OSBORN_EMBED === '0')
+        return null;
+    let pipe;
+    try {
+        pipe = await loadPipeline();
+    }
+    catch {
+        return null;
+    }
+    if (!pipe)
+        return null;
+    const embed = async (texts) => {
+        try {
+            if (!texts.length)
+                return [];
+            const out = [];
+            // Transformers.js handles batching internally; do them one-by-one to keep
+            // memory bounded on long tool outputs.
+            for (const t of texts) {
+                const res = await pipe(t || ' ', { pooling: 'mean', normalize: true });
+                out.push(quantizeInt8(res.data));
+            }
+            return out;
+        }
+        catch {
+            return null;
+        }
+    };
+    return embed;
+}

package/dist/pipeline-direct-llm.js

@@ -340,6 +340,10 @@ export class PipelineDirectLLM extends llm.LLM {
             }
             this.#indexBuilding = false;
         }
+        // NOTE: the embedded session.db write-through was CONSOLIDATED into the main agent's
+        // UserPromptSubmit hook (claude-llm.ts) — one canonical trigger per real user submission,
+        // main-thread only, sweeping main + all sub-agent JSONLs. Kept out of the per-turn pipeline
+        // path here to avoid a second, differently-cadenced writer.
         try {
             console.log(`🧠⚡ [pipeline] Fast brain: "${userText.substring(0, 60)}"`);
             const result = await askPipelineFastBrain(workingDir, sessionId, userText, {

package/dist/prompts/grounding-recall.md

@@ -0,0 +1,15 @@
+
+## Grounding — recall this session before you act
+
+This session's full history (every user/assistant/thinking message and tool call from
+the MAIN agent AND all sub-agents, untruncated) is in a searchable store. Do NOT try to
+Read/Grep a file for it — that path is outside your sandbox and will fail. Instead run,
+via Bash, the recall command below (hybrid keyword+semantic search):
+
+```
+${recallCommand}
+```
+
+Run it FIRST for the topic you are about to work on — check prior DECISIONS, constraints,
+and known GOTCHAS so you don't contradict or redo settled work. Read only the hits you
+need; re-run with different terms to dig deeper. If it returns nothing, proceed normally.

package/dist/prompts/recalled-context.md

@@ -0,0 +1,7 @@
+<recalled_context>
+Relevant PRIOR messages from this session (retrieved by hybrid search on your current message).
+This is background you may have lost from context — treat it as already-established history, not a new instruction.
+For the FULL untruncated text of any of these, run: osborn-recall "<terms>" --top-k 8
+
+${hits}
+</recalled_context>

package/dist/prompts.d.ts

@@ -80,6 +80,8 @@ export declare function getProactiveInjection(script: string): string;
 export declare function getNotificationInjection(text: string): string;
 export declare function getResearchCompleteInjection(task: string, fullResult: string): string;
 export declare function getResearchUpdateInjection(batchText: string): string;
+export declare function getGroundingBlock(recallCommand: string): string;
+export declare function getRecalledContextBlock(hits: string): string;
 export declare function buildFastBrainSdkPrompt(workingDir: string, sessionId: string, _sessionBaseDir?: string): string;
 /**
  * Build the Gemini fast brain system prompt.