osborn 0.9.211 → 0.9.212

package/.claude/skills/recall/SKILL.md

@@ -0,0 +1,87 @@
+# Recall
+
+## SKILL IDENTITY
+Name: recall
+Install path: ~/.claude/skills/recall/SKILL.md
+Portable: yes — drops into any agent's skills dir (Claude Code, osborn on Fly, other Claude Agent SDK hosts)
+
+## WHEN THIS SKILL ACTIVATES
+Whenever you need something from EARLIER in this session (or a prior session) that is
+no longer in your context window. Specifically:
+
+- The user refers to a past decision, file, error, number, or name you don't currently see
+  ("what did we decide about…", "that bug from earlier", "the token we used", "remind me why…").
+- You are a GROUNDED agent (researcher, reviewer, editor, planner, tester) about to act, and you
+  must not contradict prior decisions or redo prior work — check the record FIRST.
+- You suspect the answer was established before the last compaction.
+- Anytime you would otherwise say "I don't have that in context" about this project's history.
+
+Explicit triggers: "recall", "search the session", "what did we say about", "look back".
+
+## CORE PRINCIPLE
+This session's FULL history — every user message, assistant reply, thinking block, and tool
+call, untruncated — is stored in a per-session embedded database (`session.db`: SQLite +
+FTS5 keyword index + sqlite-vec semantic vectors). You do NOT grep a flat summary file and
+you do NOT rely only on what's in your context window. You query the store with a fixed
+command and read the real prior messages.
+
+Prefer recalling over guessing. If a fact was ever said in this project, it is retrievable.
+
+## HOW TO USE — the `osborn-recall` command
+
+```
+osborn-recall "<query>" [--mode hybrid|keyword|vector] [--top-k 8]
+                        [--session <id> --cwd <dir> | --db <path>]
+                        [--max-chars 1200] [--type user,assistant,thinking,tool_use,tool_result]
+                        [--json]
+osborn-recall --list [--cwd <dir>]          # list available session stores, newest first
+```
+
+- **Default is `hybrid`** — fuses keyword (BM25) + semantic (vector) ranking with RRF. Use it
+  unless you have a reason not to. It finds both exact terms and paraphrases.
+- **`--mode keyword`** — exact terms only; never loads the embedding model, so it's fastest.
+  Use for identifiers, error strings, tokens, file paths, function names.
+- **`--mode vector`** — pure semantic; use when you remember the MEANING but not the words
+  ("how we backed up the machine" → finds Fly/rsync content with no shared keywords).
+- **`--top-k`** — how many hits to return (default 8). Raise for a broad sweep, lower to focus.
+- **Store resolution**: with no `--db`/`--session`, it picks the newest `session.db` under the
+  current project. Pass `--session <id> --cwd <dir>` to target a specific past session, or
+  `--db <path>` to point directly at a file. Use `--list` to see what's available.
+- **`--type`** — filter to message kinds (comma-separated). E.g. `--type user` to see only what
+  the user actually asked; `--type tool_use,tool_result` to find a past command and its output.
+
+### Examples
+```
+# What did we decide about the deploy order?
+osborn-recall "deploy order npm publish git push railway fly" --top-k 5
+
+# Find the exact Supabase token string we used (exact match, fast)
+osborn-recall "SUPABASE_PERSONAL_ACCESS_TOKEN" --mode keyword
+
+# Semantic: remember the meaning, not the words
+osborn-recall "how did we recover the lost sessions" --mode vector
+
+# Only the user's own asks about a topic
+osborn-recall "marnmorgan authenticated onboarding" --type user
+
+# Machine-readable for programmatic use
+osborn-recall "sqlite-vec int8 rowid bug" --json
+```
+
+## WORKFLOW
+1. Turn the thing you're missing into a short query — include distinctive terms (names, error
+   text, identifiers) for keyword strength, but plain-language is fine (hybrid handles both).
+2. Run `osborn-recall "<query>"`. Read the returned hits — each is a REAL prior message with its
+   source line, message type, model, and timestamp.
+3. If nothing relevant: broaden the query, raise `--top-k`, or switch `--mode` (keyword↔vector).
+   If still empty, `--list` to confirm a store exists; the flat `search-index.txt` is the legacy
+   fallback but the store is authoritative and untruncated.
+4. Ground your next action in what you found. Cite the source line when it matters
+   ("per L214, we settled on X").
+
+## NOTES
+- The store is written incrementally each turn, so recent messages are usually present within a
+  turn or two. Very-latest exchanges may lag by one turn — that's fine, they're still in context.
+- Keyword mode never downloads the embedding model; hybrid/vector load MiniLM once (~12s cold,
+  cached after). If the embedder is unavailable, recall silently falls back to keyword-only.
+- This skill is READ-only recall. It never writes; the pipeline owns the write path.

package/bin/recall.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+// osborn-recall — thin shim. Runs src/recall-cli.ts via tsx in dev, or the
+// compiled dist/recall-cli.js after `npm install`. Mirrors bin/cli.js.
+
+import { spawn } from 'child_process'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { existsSync, lstatSync, symlinkSync } from 'fs'
+import os from 'os'
+
+// Same /workspace/.claude symlink guard as cli.js so stores resolve on Fly machines.
+try {
+  const home = os.homedir()
+  const target = '/workspace/.claude'
+  const link = join(home, '.claude')
+  if (existsSync(target) && home !== '/workspace') {
+    let needsLink = true
+    try { needsLink = !lstatSync(link).isSymbolicLink() } catch {}
+    if (needsLink) symlinkSync(target, link)
+  }
+} catch {}
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const args = process.argv.slice(2)
+
+const srcPath = join(__dirname, '..', 'src', 'recall-cli.ts')
+const distPath = join(__dirname, '..', 'dist', 'recall-cli.js')
+
+let child
+if (existsSync(srcPath)) {
+  const tsxPath = join(__dirname, '..', 'node_modules', '.bin', 'tsx')
+  child = spawn(tsxPath, [srcPath, ...args], { stdio: 'inherit', cwd: join(__dirname, '..'), env: process.env })
+} else if (existsSync(distPath)) {
+  child = spawn('node', [distPath, ...args], { stdio: 'inherit', cwd: join(__dirname, '..'), env: process.env })
+} else {
+  console.error('Error: neither src/recall-cli.ts nor dist/recall-cli.js found')
+  process.exit(1)
+}
+
+child.on('error', (err) => { console.error('Failed to start osborn-recall:', err.message); process.exit(1) })
+child.on('exit', (code) => process.exit(code || 0))

package/dist/claude-llm.d.ts

@@ -45,6 +45,7 @@ export declare const NAMED_AGENTS: {
     researcher: {
         description: string;
         tools: string[];
+        grounded: boolean;
         model: string;
         prompt: string;
     };
@@ -57,6 +58,7 @@ export declare const NAMED_AGENTS: {
     writer: {
         description: string;
         tools: string[];
+        grounded: boolean;
         model: string;
         prompt: string;
     };
@@ -69,6 +71,7 @@ export declare const NAMED_AGENTS: {
     planner: {
         description: string;
         tools: string[];
+        grounded: boolean;
         model: string;
         prompt: string;
     };
@@ -88,6 +91,23 @@ export declare const FALLBACK_MODEL = "minimax/minimax-m3";
  * NEVER mutates the input — NAMED_AGENTS and DB-sourced rows are untouched.
  */
 export declare function applyTurbo(agents: Record<string, any>, turbo: boolean): Record<string, any>;
+/**
+ * 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 declare function applyGrounding(agents: Record<string, any>, sessionId: string | null, workingDir: string | undefined): Record<string, any>;
 /**
  * Claude LLM - Wraps Claude Agent SDK for LiveKit
  * Research mode: reads anything, writes only to session workspace
@@ -111,6 +131,14 @@ export declare class ClaudeLLM extends llm.LLM {
         toolName: string;
         input: any;
     } | null;
+    /**
+     * 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: string, workingDir: string): void;
     /**
      * Get all currently enabled MCP servers
      */

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
@@ -201,6 +267,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 +276,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 +369,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 +378,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 +433,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 +516,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 +526,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 +697,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 +822,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 +919,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 +2061,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,
                                             },
                                         };
                                     }
@@ -2159,9 +2320,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.