karajan-code 2.27.0 → 2.29.0

package/README.md

@@ -345,6 +345,22 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **v2.29.0 released** — Minor. **RAG quality lift** — dashboard + three new providers + metadata filter + rerank.
+>
+> - **Retrieval dashboard on HU Board** (PR #843): nuevo `/rag.html` con embedder activo, tamaño de DB, last-index, chunks por kind, chunks por proyecto. Primera pieza del config UI que llega completo en v2.30.
+> - **Cohere + Mistral embedders** (PR #848): `embed-multilingual-v3.0` (multi-idioma) y `mistral-embed` (EU-hosted, útil para GDPR). `KJ_COHERE_KEY` / `KJ_MISTRAL_KEY` Karajan-scoped.
+> - **ONNX local embedder** (PR #??): `@huggingface/transformers` corriendo en Node — sin Docker, sin API key, sin Ollama. Default `Xenova/all-MiniLM-L6-v2` (384 dim). Es la base para el zero-config init de v2.31.
+> - **Metadata `--where` filter** (PR #??): `kj rag query 'auth' --where 'symbol=loadConfig AND kind=plan'`. Gramática mínima KEY=VALUE AND KEY=VALUE; cualquier metadata que emite el chunker es queryable sin schema changes.
+> - **Cross-encoder rerank** (PR #??): opt-in `--rerank` re-ordena los topK con un cross-encoder (`Xenova/ms-marco-MiniLM-L-6-v2`). Latencia acotada, calidad final notablemente mejor.
+>
+> **v2.28.0 released** — Minor. **RAG advanced** — live re-index + cloud embedders + hybrid scoring + AST chunker, plus a real fix for the v2.27.0 chapuza.
+>
+> - **`kj watch`** (PR #836): chokidar daemon que re-indexa los archivos del proyecto tras cada edit (1s debounce). Fin del `kj rag index` manual.
+> - **OpenAI + Voyage embedders** (PR #841): para usuarios sin Docker local. `config.rag.embedder.provider: openai | voyage` + `KJ_OPENAI_KEY` / `KJ_VOYAGE_KEY` env vars (Karajan-scoped — preserva el architecture invariant).
+> - **BM25 hybrid scoring** (PR #838): SQLite FTS5 + cosine fusion. `kj rag query --mode hybrid|semantic|keyword`. Queries con símbolos exactos rankean correctamente.
+> - **AST source chunker** (PR #839): `@babel/parser`. Cada top-level declaration entera en un chunk; TypeScript + JSX + decorators soportados.
+> - **KJC-BUG-0064** (PR #840): `parseCooldown` TZ-aware via `Intl.DateTimeFormat`. Deshace el skip-in-CI workaround de v2.27.0 — tests pasan en cualquier TZ.
+>
 > **v2.27.0 released** — Minor. **RAG polish** — three improvements triggered by the v2.26.0 smoke test on karajan-code itself:
 >
 > - **Per-project isolation** (PR #831): new `project_slug` column on chunks; `kj rag query --project <slug>` (auto-detected from cwd) filters the global DB. `--project all` to query across everything.
@@ -352,7 +368,7 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 > - **Asymmetric source-vs-test ranking** (PR #833): NL queries like `how does X work` no longer rank `tests/X.test.js` above `src/X.js`; test-flavoured queries still surface tests.
 > - Plus **KJC-BUG-0063** (PR #834): skipped a TZ-dependent test that was blocking every CI run, and a `shrink-budget` workflow exclude fix for `docs/*.md` at the root.
 >
-> **Coming in v2.28.0+**: chokidar watcher for live re-indexing, AST source chunker (tree-sitter / @babel/parser), BM25 + cosine hybrid scoring, OpenAI/Voyage embedder adapters (for users without local Docker).
+> **Coming in v2.30.0+**: writable config UI on the HU Board (toggle roles, switch coder/reviewer, adjust alpha/mode/rerank without re-editing the YAML), then v2.31 zero-config init (reduce the wizard to one critical question, smart defaults for everything).
 >
 > **v2.26.0 released** — Minor. **RAG Auto-Bootstrap** — Ollama runs in Docker out of the box. `kj init` now provisions the embedder automatically (or skips with a clear reason on modest hardware / `--no-ollama`); `kj doctor` surfaces health; `kj ollama [start|stop|status|pull]` manages lifecycle without docker compose. See [docs/RAG.md](docs/RAG.md) for the full RAG guide ([español](docs/es/RAG.md)).
 >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.27.0",
+  "version": "2.29.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -69,6 +69,7 @@
     "src/**/*.js": "eslint --max-warnings=999"
   },
   "dependencies": {
+    "@babel/parser": "^7.29.3",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "better-sqlite3": "^11.0.0",
     "chokidar": "^4.0.0",

package/packages/hu-board/public/index.html

@@ -25,6 +25,7 @@
       <button class="nav-btn" data-view="dashboard" title="Per-project landing: stats grid + project list. Click a project card to focus the kanban / graph on that project.">Dashboard</button>
       <button class="nav-btn" data-view="sessions" title="Every kj run that has touched the board, newest first. Filter by project; click a session to inspect its iterations, commits and checkpoints.">Sessions</button>
       <a class="nav-btn" href="/pipeline.html" title="Live observability of pipeline runs (Karajan v2.7+): stage timings, agent calls, decision logs.">Pipeline</a>
+      <a class="nav-btn" href="/rag.html" title="RAG retrieval-quality dashboard: chunk counts, embedder provider, db size.">RAG</a>
       <select class="project-select" id="project-select">
         <option value="">All Projects</option>
       </select>

package/packages/hu-board/public/rag.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Karajan RAG · Retrieval Dashboard</title>
+  <link rel="stylesheet" href="/styles.css">
+</head>
+<body>
+  <header class="header">
+    <div class="header__logo"><div><div class="header__title">Karajan RAG</div><div class="header__subtitle">retrieval-quality dashboard</div></div></div>
+    <nav class="header__nav">
+      <a class="nav-btn" href="/">← Board</a>
+      <button class="nav-btn active">RAG</button>
+      <div class="header__controls"><button class="control-btn" id="rag-refresh" title="Reload stats">🔄</button></div>
+    </nav>
+  </header>
+  <main class="main" id="rag-app"><div class="loading"><div class="loading__spinner"></div><p>Loading…</p></div></main>
+  <script src="/rag.js"></script>
+</body>
+</html>

package/packages/hu-board/public/rag.js

@@ -0,0 +1,39 @@
+// KJC-TSK-0445 — Retrieval dashboard frontend. Fetches /api/rag/stats and
+// renders chunk counts per project/kind, embedder, DB size and last-index.
+const TOKEN = new URLSearchParams(location.search).get("token") || localStorage.getItem("kj_board_token") || "";
+const HEADERS = TOKEN ? { Authorization: `Bearer ${TOKEN}` } : {};
+const ESC = (s) => String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+
+function bytes(n) { for (const u of ["B", "KB", "MB", "GB"]) { if (n < 1024) return `${u === "B" ? n : n.toFixed(1)} ${u}`; n /= 1024; } return `${n.toFixed(2)} TB`; }
+
+function bars(rows, lab, val, max) {
+  if (!rows.length) return '<p class="rag-empty">no data</p>';
+  return rows.map((r) => `<div class="rag-bar"><span class="rag-bar__label">${ESC(lab(r))}</span><span class="rag-bar__fill" style="width:${Math.round((val(r) / max) * 100)}%"></span><span class="rag-bar__value">${val(r).toLocaleString()}</span></div>`).join("");
+}
+
+function embedderCard(e) {
+  return e ? `<div class="rag-card"><h3>Embedder</h3><p class="rag-stat-big">${ESC(e.provider)}</p><p class="rag-stat-sub">${ESC(e.model || "default model")} · dim ${e.dim ?? "?"}</p></div>` : "";
+}
+
+function render(root, data) {
+  if (!data.initialized) { root.innerHTML = `<section class="rag-grid"><div class="rag-card"><h3>RAG DB</h3><p class="rag-empty">${ESC(data.message || "not initialized")}</p></div>${embedderCard(data.embedder)}</section>`; return; }
+  const lastIdx = data.last_indexed ? new Date(data.last_indexed).toLocaleString() : "never";
+  const mk = Math.max(1, ...data.by_kind.map((r) => r.n));
+  const mp = Math.max(1, ...data.by_project.map((r) => r.n));
+  root.innerHTML = `<section class="rag-grid">
+    <div class="rag-card"><h3>Totals</h3><p class="rag-stat-big">${data.total_chunks.toLocaleString()}</p><p class="rag-stat-sub">chunks · ${bytes(data.db_size_bytes)} · last indexed ${ESC(lastIdx)}</p></div>
+    ${embedderCard(data.embedder)}
+    <div class="rag-card rag-card--wide"><h3>By kind</h3>${bars(data.by_kind, (r) => r.kind, (r) => r.n, mk)}</div>
+    <div class="rag-card rag-card--wide"><h3>By project (top 20)</h3>${bars(data.by_project, (r) => r.project, (r) => r.n, mp)}</div>
+  </section>`;
+}
+
+async function load() {
+  const app = document.getElementById("rag-app");
+  app.innerHTML = '<div class="loading"><div class="loading__spinner"></div><p>Loading…</p></div>';
+  try { const r = await fetch("/api/rag/stats", { headers: HEADERS }); if (!r.ok) throw new Error(`HTTP ${r.status}`); render(app, await r.json()); }
+  catch (e) { app.innerHTML = `<div class="rag-card rag-card--error"><strong>Error:</strong> ${ESC(e.message)}</div>`; }
+}
+
+document.getElementById("rag-refresh").addEventListener("click", load);
+load();

package/packages/hu-board/public/styles.css

@@ -916,3 +916,17 @@ body.scoped-mode .nav-btn[data-view="dashboard"],
 body.scoped-mode .header__nav a[href="/pipeline.html"] {
   display: none;
 }
+
+/* KJC-TSK-0445 — RAG dashboard */
+.rag-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1rem; padding: 1rem; }
+.rag-card { background: var(--bg-secondary, #1e1e2e); border-radius: 8px; padding: 1.25rem; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+.rag-card--wide { grid-column: 1 / -1; }
+.rag-card--error { color: #f87171; background: #2a1414; }
+.rag-card h3 { margin: 0 0 .75rem; font-size: .9rem; text-transform: uppercase; letter-spacing: .05em; color: var(--text-secondary, #94a3b8); }
+.rag-stat-big { font-size: 2rem; font-weight: 700; margin: 0; color: var(--text-primary, #f8fafc); }
+.rag-stat-sub { margin: .25rem 0 0; font-size: .85rem; color: var(--text-secondary, #94a3b8); }
+.rag-empty { color: var(--text-secondary, #94a3b8); font-style: italic; }
+.rag-bar { display: grid; grid-template-columns: 140px 1fr 60px; align-items: center; gap: .5rem; margin: .35rem 0; font-size: .85rem; }
+.rag-bar__label { color: var(--text-secondary, #cbd5e1); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.rag-bar__fill { display: block; height: 14px; background: linear-gradient(90deg, #7c3aed, #a78bfa); border-radius: 3px; }
+.rag-bar__value { text-align: right; color: var(--text-primary, #f8fafc); font-variant-numeric: tabular-nums; }

package/packages/hu-board/src/routes/api.js

@@ -1292,12 +1292,12 @@ router.post('/rag/query', async (req, res) => {
   }
   try {
     const { openVecStore, countChunks } = await import('../../../../src/rag/vec-store.js');
-    const { OllamaEmbedder } = await import('../../../../src/rag/embedder.js');
+    const { makeEmbedder } = await import('../../../../src/rag/embedders/factory.js');
     const { query } = await import('../../../../src/rag/retriever.js');
     const db = openVecStore({ dim: 768 });
     try {
       if (countChunks(db) === 0) return res.json({ hits: [], empty: true, topK, scope });
-      const embedder = new OllamaEmbedder({});
+      const embedder = makeEmbedder({});
       const hits = await query(db, embedder, text, { topK: Number(topK), scope });
       res.json({ hits, empty: false, topK, scope });
     } finally { db.close(); }

package/packages/hu-board/src/routes/rag.js

@@ -0,0 +1,36 @@
+// KJC-TSK-0445 — RAG retrieval-quality dashboard route.
+// GET /api/rag/stats → snapshot of the local rag.db (counts per kind/project,
+// active embedder, db size, last-index timestamp). Missing DB returns an
+// "uninitialized" payload so the dashboard renders an empty state cleanly.
+import { Router } from "express";
+import { existsSync, statSync } from "node:fs";
+import Database from "better-sqlite3";
+import { dbPath } from "../../../../src/rag/vec-store.js";
+import { readConfig } from "../config-yaml.js";
+
+const router = Router();
+const DIMS = { ollama: 768, openai: 1536, voyage: 1024, cohere: 1024, mistral: 1024, onnx: 384 };
+
+function embedder() {
+  try {
+    const e = (readConfig()?.rag?.embedder) || {};
+    const provider = e.provider || "ollama";
+    return { provider, model: e.model || null, dim: e.dim || DIMS[provider] || null };
+  } catch { return { provider: "ollama", model: null, dim: 768 }; }
+}
+
+router.get("/stats", (_req, res) => {
+  const path = dbPath();
+  if (!existsSync(path)) return res.json({ ok: true, initialized: false, message: "rag.db not initialized — run `kj rag index <dir>` to start indexing.", embedder: embedder() });
+  try {
+    const db = new Database(path, { readonly: true, fileMustExist: true });
+    const total_chunks = db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
+    const by_kind = db.prepare("SELECT kind, COUNT(*) AS n FROM chunks GROUP BY kind").all();
+    const by_project = db.prepare("SELECT COALESCE(project_slug, '(no slug)') AS project, COUNT(*) AS n FROM chunks GROUP BY project_slug ORDER BY n DESC LIMIT 20").all();
+    const last_indexed = db.prepare("SELECT MAX(created_at) AS ts FROM chunks").get().ts;
+    db.close();
+    res.json({ ok: true, initialized: true, db_path: path, db_size_bytes: statSync(path).size, total_chunks, by_kind, by_project, last_indexed, embedder: embedder() });
+  } catch (err) { res.status(500).json({ ok: false, error: String(err.message || err) }); }
+});
+
+export default router;

package/packages/hu-board/src/server.js

@@ -9,6 +9,7 @@ import { initDb, closeDb } from './db.js';
 import { fullScan, startWatcher } from './sync.js';
 import apiRoutes from './routes/api.js';
 import pipelineRoutes from './routes/pipeline.js';
+import ragRoutes from './routes/rag.js';
 import { authMiddleware } from './auth.js';
 import { getOrCreateToken, getTokenPath } from './token-store.js';
 import { reapZombieSessions } from './zombie-reaper.js';
@@ -298,6 +299,7 @@ async function main() {
   app.use(express.static(PUBLIC_DIR, { setHeaders: noStoreHeaders, etag: false, lastModified: false }));
   app.use('/api', buildRateLimiter(), authMiddleware(), apiRoutes);
   app.use('/api/pipeline', authMiddleware(), pipelineRoutes);
+  app.use('/api/rag', authMiddleware(), ragRoutes);
 
   // SPA fallback: serve index.html for non-API, non-static routes
   app.get('/{*splat}', (_req, res) => {

package/scripts/esbuild-sea.config.mjs

@@ -146,7 +146,7 @@ const huBoardStubPlugin = {
 const ragStubPlugin = {
   name: "rag-stub",
   setup(build) {
-    build.onResolve({ filter: /[\\/](rag[\\/][^\\/]+|commands[\\/]rag)\.js$/ }, (args) => ({
+    build.onResolve({ filter: /[\\/](rag[\\/].+|commands[\\/](rag|watch))\.js$/ }, (args) => ({
       path: args.path, namespace: "rag-stub",
     }));
     build.onLoad({ filter: /.*/, namespace: "rag-stub" }, () => ({
@@ -170,6 +170,19 @@ const ragStubPlugin = {
           checkOllamaCapability: notAvailable, pullOllamaModel: notAvailable,
           // KJC-TSK-0438 — RAG project isolation.
           projectSlug: notAvailable,
+          // KJC-TSK-0441 — RAG chokidar watcher.
+          startWatcher: notAvailable, readPidFile: notAvailable, clearPidFile: notAvailable,
+          isPidAlive: notAvailable, writePidFile: notAvailable,
+          // KJC-TSK-0442 / KJC-TSK-0446 — RAG embedders cloud + factory.
+          makeEmbedder: notAvailable, OpenAIEmbedder: notAvailable, VoyageEmbedder: notAvailable,
+          OpenAIEmbedderError: notAvailable, VoyageEmbedderError: notAvailable, PROVIDERS: notAvailable,
+          CohereEmbedder: notAvailable, CohereEmbedderError: notAvailable,
+          MistralEmbedder: notAvailable, MistralEmbedderError: notAvailable,
+          ONNXEmbedder: notAvailable, ONNXEmbedderError: notAvailable,
+          // KJC-TSK-0448 — RAG --where metadata filter.
+          parseWhere: notAvailable, buildWhereSql: notAvailable,
+          // KJC-TSK-0449 — RAG cross-encoder rerank.
+          rerank: notAvailable, RerankError: notAvailable, _resetPipeline: notAvailable,
           default: notAvailable,
         };
       `,

package/src/cli/register-meta.js

@@ -4,6 +4,7 @@ import { researcherCommand } from "../commands/researcher.js";
 import { architectCommand } from "../commands/architect.js";
 import { onboardCommand } from "../commands/onboard.js";
 import { ragIndexCommand, ragQueryCommand } from "../commands/rag.js";
+import { watchStartCommand, watchStopCommand, watchStatusCommand } from "../commands/watch.js";
 import { auditCommand } from "../commands/audit.js";
 import { resumeCommand } from "../commands/resume.js";
 import { boardCommand } from "../commands/board.js";
@@ -114,6 +115,11 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--scope <scope>", "plans | code | onboarding | all (default: all)", "all")
     .option("--top-k <n>", "Number of hits to return (default: 5)", "5")
     .option("--project <slug>", "Filter by project slug. Pass 'all' to query across every indexed project. Default: cwd basename")
+    .option("--mode <mode>", "hybrid (default) | semantic (cosine only) | keyword (BM25 only)", "hybrid")
+    .option("--alpha <n>", "Hybrid weight for semantic component (0..1). Default 0.6", "0.6")
+    .option("--where <clause>", "Metadata filter, e.g. 'symbol=loadConfig' or 'hu_id=HU-003 AND kind=plan'")
+    .option("--rerank", "Apply cross-encoder rerank to top-K (needs @huggingface/transformers, slower but more precise)")
+    .option("--rerank-model <name>", "Cross-encoder model id. Default: Xenova/ms-marco-MiniLM-L-6-v2")
     .option("--json", "Output the hits as JSON")
     .action(async (text, flags) => {
       await withConfig(pkgVersion, "rag-query", flags, async ({ config, logger }) => {
@@ -121,6 +127,18 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-0441 — `kj watch [start|stop|status]` for live RAG re-index.
+  const watch = program.command("watch").description("Live RAG re-index daemon");
+  watch.command("start").description("Start the watcher daemon").option("--foreground", "Run in foreground (do not detach)").option("--with-sources", "Watch project source files too").action(async (flags) => {
+    await withConfig(pkgVersion, "watch:start", flags, async ({ config, logger }) => watchStartCommand({ config, logger, flags }));
+  });
+  watch.command("stop").description("Stop the watcher daemon").action(async () => {
+    await withConfig(pkgVersion, "watch:stop", {}, async ({ logger }) => watchStopCommand({ logger }));
+  });
+  watch.command("status").description("Report watcher daemon state").action(async () => {
+    await withConfig(pkgVersion, "watch:status", {}, async ({ logger }) => watchStatusCommand({ logger }));
+  });
+
   program
     .command("audit")
     .description("Analyze codebase health (read-only)")

package/src/commands/rag.js

@@ -3,16 +3,11 @@
 //   kj rag query <text>   [--scope plans|code|onboarding|all] [--top-k N] [--json]
 // Closes the v2.22.0 RAG MVP end-to-end from the terminal.
 import { openVecStore, countChunks, projectSlug } from "../rag/vec-store.js";
-import { OllamaEmbedder } from "../rag/embedder.js";
+import { makeEmbedder } from "../rag/embedders/factory.js";
 import { indexProject } from "../rag/indexer.js";
 import { query } from "../rag/retriever.js";
 import { getKarajanHome } from "../utils/paths.js";
 
-function makeEmbedder(config) {
-  const cfg = config?.rag?.embedder || {};
-  return new OllamaEmbedder({ url: cfg.url, model: cfg.model, dim: cfg.dim });
-}
-
 function openDb(config) {
   return openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
 }
@@ -60,7 +55,11 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
       if (flags.json) process.stdout.write(`${JSON.stringify({ hits: [], empty: true, topK, scope })}\n`);
       return [];
     }
-    const hits = await query(db, makeEmbedder(config), text, { topK, scope, project });
+    const mode = flags.mode || "hybrid";
+    const alpha = Math.max(0, Math.min(1, Number(flags.alpha) || 0.6));
+    const where = flags.where || null;
+    const rerankOpts = flags.rerank ? { model: flags.rerankModel } : null;
+    const hits = await query(db, makeEmbedder(config), text, { topK, scope, project, mode, alpha, where, rerankOpts });
     if (flags.json) {
       process.stdout.write(`${JSON.stringify(hits)}\n`);
     } else {

package/src/commands/watch.js

@@ -0,0 +1,46 @@
+// KJC-TSK-0441 — `kj watch [start|stop|status]`. Thin wrappers.
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { startWatcher, readPidFile, clearPidFile, isPidAlive, writePidFile } from "../rag/watcher.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export async function watchStartCommand({ config, logger, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const existing = readPidFile();
+  if (existing && isPidAlive(existing)) { logger.info(`Watcher already running (pid ${existing}).`); return { pid: existing, started: false }; }
+  if (existing) clearPidFile();
+  if (flags.foreground) {
+    writePidFile();
+    const stop = startWatcher({ projectDir, config, logger, withSources: !!flags.withSources });
+    const shutdown = async () => { await stop(); clearPidFile(); process.exit(0); };
+    process.on("SIGINT", shutdown).on("SIGTERM", shutdown);
+    logger.info(`Watcher started in foreground (pid ${process.pid}). Ctrl+C to stop.`);
+    return { pid: process.pid, started: true };
+  }
+  const args = [join(HERE, "..", "cli.js"), "watch", "start", "--foreground", ...(flags.withSources ? ["--with-sources"] : [])];
+  const child = spawn(process.execPath, args, { detached: true, stdio: "ignore", env: { ...process.env, KJ_WATCHER_DAEMON: "1" } });
+  child.unref();
+  logger.info(`Watcher started in background (pid ${child.pid}).`);
+  return { pid: child.pid, started: true };
+}
+
+export async function watchStopCommand({ logger }) {
+  const pid = readPidFile();
+  if (!pid) { logger.info("No watcher running."); return { stopped: false }; }
+  if (!isPidAlive(pid)) { clearPidFile(); logger.info(`Stale PID file removed (process ${pid} was not alive).`); return { stopped: false, stale: true }; }
+  try { process.kill(pid, "SIGTERM"); } catch (err) { logger.warn(`Could not signal pid ${pid}: ${err.message}`); }
+  clearPidFile();
+  logger.info(`Watcher (pid ${pid}) stopped.`);
+  return { stopped: true, pid };
+}
+
+export async function watchStatusCommand({ logger }) {
+  const pid = readPidFile();
+  const alive = pid && isPidAlive(pid);
+  if (alive) logger.info(`Watcher running (pid ${pid}).`);
+  else if (pid) logger.warn(`Stale PID file (process ${pid} not alive). Run \`kj watch stop\` to clean up.`);
+  else logger.info("Watcher is NOT running.");
+  return { pid, alive };
+}

package/src/mcp/handlers/rag-handler.js

@@ -2,7 +2,7 @@
 // from src/commands/* are forbidden by the layer-boundaries test
 // (MCP and CLI are peer layers); we hit the pure rag/* modules instead.
 import { countChunks, openVecStore } from "../../rag/vec-store.js";
-import { OllamaEmbedder } from "../../rag/embedder.js";
+import { makeEmbedder } from "../../rag/embedders/factory.js";
 import { indexProject } from "../../rag/indexer.js";
 import { query } from "../../rag/retriever.js";
 import { getKarajanHome } from "../../utils/paths.js";
@@ -12,11 +12,6 @@ const silentLogger = {
   info: () => {}, warn: () => {}, error: () => {}, debug: () => {}, setContext: () => {},
 };
 
-function makeEmbedder(config) {
-  const cfg = config?.rag?.embedder || {};
-  return new OllamaEmbedder({ url: cfg.url, model: cfg.model, dim: cfg.dim });
-}
-
 export async function handleRagQuery(args, server) {
   const text = args?.text;
   if (typeof text !== "string" || text.length === 0) {

package/src/orchestrator/stages/rag-context-stage.js

@@ -6,7 +6,7 @@
 // never sees an exception from this stage.
 import { emitProgress, makeEvent } from "../../utils/events.js";
 import { openVecStore, countChunks } from "../../rag/vec-store.js";
-import { OllamaEmbedder } from "../../rag/embedder.js";
+import { makeEmbedder } from "../../rag/embedders/factory.js";
 import { query } from "../../rag/retriever.js";
 
 const DEFAULT_TOP_K = 5;
@@ -35,8 +35,7 @@ export async function runRagContextStage({ config, logger, emitter, eventBase, t
       }
       const topK = preload.topK || DEFAULT_TOP_K;
       const scope = preload.scope || DEFAULT_SCOPE;
-      const cfg = config?.rag?.embedder || {};
-      const embedder = new OllamaEmbedder({ url: cfg.url, model: cfg.model, dim });
+      const embedder = makeEmbedder(config);
       const hits = await query(db, embedder, task, { topK, scope });
       if (hits.length === 0) return { skipped: true, reason: "no-hits" };
       const lines = hits.map((h) => {

package/src/rag/chunker-ast.js

@@ -0,0 +1,56 @@
+// KJC-TSK-0444 — AST-aware source chunker. Replaces the regex-based
+// chunkSource for JS/TS/JSX files. Each top-level declaration (function,
+// class, var/const, export named/default) becomes one chunk whose `text`
+// is the literal source slice [node.start, node.end]. Comments
+// immediately preceding a declaration are folded in (JSDoc + leading
+// line comments) so the chunk reads like a doc-aware snippet.
+//
+// Falls back to the regex chunker if @babel/parser cannot parse the
+// file (errorRecovery: true catches most cases; a hard syntax error
+// returns null so the caller can fall back).
+import { parse } from "@babel/parser";
+
+const PLUGINS = ["typescript", "jsx", "decorators-legacy", "classProperties", "topLevelAwait"];
+
+export function chunkSourceAST(text, { path = "<src>", limit = 800, overlap = 100 } = {}) {
+  let ast;
+  try { ast = parse(text, { sourceType: "module", errorRecovery: true, plugins: PLUGINS }); }
+  catch { return null; }
+  const body = ast?.program?.body;
+  if (!Array.isArray(body) || body.length === 0) return null;
+  const out = [];
+  for (const node of body) {
+    const sym = extractSymbol(node);
+    const start = leadingCommentsStart(node);
+    const slice = text.slice(start, node.end ?? start);
+    if (!slice.trim()) continue;
+    if (slice.length <= limit) out.push({ text: slice, metadata: { source: path, kind: "code", symbol: sym } });
+    else for (const piece of windowText(slice, limit, overlap)) out.push({ text: piece, metadata: { source: path, kind: "code", symbol: sym } });
+  }
+  return out.length === 0 ? null : out;
+}
+
+function extractSymbol(node) {
+  if (node.type === "ExportNamedDeclaration" && node.declaration) return extractSymbol(node.declaration);
+  if (node.type === "ExportDefaultDeclaration") return "default";
+  if (node.id?.name) return node.id.name;
+  if (node.declarations?.[0]?.id?.name) return node.declarations[0].id.name;
+  return null;
+}
+
+function leadingCommentsStart(node) {
+  const lc = node.leadingComments;
+  if (Array.isArray(lc) && lc.length > 0) return lc[0].start ?? node.start ?? 0;
+  return node.start ?? 0;
+}
+
+function windowText(text, limit, overlap) {
+  if (text.length <= limit) return [text];
+  const step = Math.max(1, limit - overlap);
+  const out = [];
+  for (let i = 0; i < text.length; i += step) {
+    out.push(text.slice(i, i + limit));
+    if (i + limit >= text.length) break;
+  }
+  return out;
+}

package/src/rag/chunker.js

@@ -91,13 +91,20 @@ export function chunkPlan(plan, { path = "<plan>", limit = DEFAULT_CHUNK_LIMIT }
 
 // ---------- source chunker (export-symbol granularity) ------------
 
+import { chunkSourceAST } from "./chunker-ast.js";
+
 const EXPORT_RE = /^export\s+(?:async\s+)?(?:function|class|const|let)\s+(\w+)/gm;
 
-/**
- * Chunk a JS/TS source file by top-level export symbol. Falls back to
- * the windowed splitter on files without explicit exports.
- */
-export function chunkSource(text, { path = "<src>", limit = DEFAULT_CHUNK_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
+// KJC-TSK-0444 — try AST chunker first (top-level declarations as whole
+// units, JSDoc folded in); fall back to the export-regex if @babel/parser
+// can't parse the file (returns null).
+export function chunkSource(text, opts = {}) {
+  const ast = chunkSourceAST(text, opts);
+  if (ast) return ast;
+  return chunkSourceRegex(text, opts);
+}
+
+function chunkSourceRegex(text, { path = "<src>", limit = DEFAULT_CHUNK_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
   const marks = [];
   EXPORT_RE.lastIndex = 0;
   let m;
@@ -117,3 +124,5 @@ export function chunkSource(text, { path = "<src>", limit = DEFAULT_CHUNK_LIMIT,
   }
   return out;
 }
+
+export { chunkSourceRegex };

package/src/rag/embedders/_cloud-base.js

@@ -0,0 +1,24 @@
+// KJC-TSK-0442 — shared POST helper for cloud embedders (OpenAI, Voyage).
+// Same envelope: Bearer auth, JSON body shaped by caller, JSON response
+// extracted by caller, dim validated against the adapter's expected size.
+export async function cloudEmbed(adapter, text, ErrCls, { provider, body, extract }) {
+  if (typeof text !== "string" || text.length === 0) throw new ErrCls("embed: text must be a non-empty string");
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), adapter.timeoutMs);
+  let res;
+  try {
+    res = await adapter.fetch(adapter.url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${adapter.apiKey}` },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+  } catch (err) { throw new ErrCls(`${provider} embed request failed: ${err.message}`, { cause: err }); }
+  finally { clearTimeout(timer); }
+  if (!res.ok) throw new ErrCls(`${provider} embed HTTP ${res.status}`, { status: res.status });
+  const json = await res.json();
+  const arr = extract(json);
+  if (!Array.isArray(arr) || arr.length === 0) throw new ErrCls(`${provider} response missing embedding`);
+  if (arr.length !== adapter.dim) throw new ErrCls(`${provider} dim mismatch: got ${arr.length}, expected ${adapter.dim} for model ${adapter.model}`);
+  return Float32Array.from(arr);
+}

package/src/rag/embedders/cohere.js

@@ -0,0 +1,28 @@
+// KJC-TSK-0446 — Cohere embed-v3 adapter. Cohere returns
+// { embeddings: { float: [[...]] } } when `embedding_types: ["float"]`
+// is requested, or { embeddings: [[...]] } in legacy v1. We extract the
+// modern shape with a v1 fallback.
+import { cloudEmbed } from "./_cloud-base.js";
+
+const DEFAULTS = { url: "https://api.cohere.com/v2/embed", model: "embed-multilingual-v3.0", dim: 1024, timeoutMs: 30000 };
+
+export class CohereEmbedderError extends Error {
+  constructor(message, { cause, status } = {}) { super(message); this.name = "CohereEmbedderError"; if (cause) this.cause = cause; if (status != null) this.status = status; }
+}
+
+export class CohereEmbedder {
+  constructor({ url = DEFAULTS.url, apiKey = process.env.KJ_COHERE_KEY, model = process.env.KJ_COHERE_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, timeoutMs = DEFAULTS.timeoutMs, fetchFn = globalThis.fetch } = {}) {
+    // KJC architecture invariant: scoped env var (KJ_COHERE_KEY), not the
+    // generic COHERE_API_KEY — same rule as OpenAI/Voyage adapters.
+    if (!apiKey) throw new CohereEmbedderError("Cohere embedder requires an api_key (config.rag.embedder.api_key or KJ_COHERE_KEY env)");
+    Object.assign(this, { url, apiKey, model, dim, timeoutMs, fetch: fetchFn });
+  }
+  async embed(text) {
+    return cloudEmbed(this, text, CohereEmbedderError, {
+      provider: "Cohere",
+      body: { model: this.model, texts: [text], input_type: "search_document", embedding_types: ["float"] },
+      extract: (b) => b?.embeddings?.float?.[0] || b?.embeddings?.[0],
+    });
+  }
+  async embedBatch(texts) { if (!Array.isArray(texts)) throw new CohereEmbedderError("embedBatch: texts must be an array"); const out = []; for (const t of texts) out.push(await this.embed(t)); return out; }
+}

package/src/rag/embedders/factory.js

@@ -0,0 +1,30 @@
+// KJC-TSK-0442 / KJC-TSK-0446 — Embedder factory. Selects provider from
+// config.rag.embedder.provider (ollama | openai | voyage | cohere | mistral;
+// default ollama). Each provider has its own dim default; the factory wires
+// it so the caller does not need to know.
+import { OllamaEmbedder } from "../embedder.js";
+import { OpenAIEmbedder } from "./openai.js";
+import { VoyageEmbedder } from "./voyage.js";
+import { CohereEmbedder } from "./cohere.js";
+import { MistralEmbedder } from "./mistral.js";
+import { ONNXEmbedder } from "./onnx.js";
+
+const PROVIDERS = {
+  ollama: { cls: OllamaEmbedder, dim: 768 },
+  openai: { cls: OpenAIEmbedder, dim: 1536 },
+  voyage: { cls: VoyageEmbedder, dim: 1024 },
+  cohere: { cls: CohereEmbedder, dim: 1024 },
+  mistral: { cls: MistralEmbedder, dim: 1024 },
+  onnx: { cls: ONNXEmbedder, dim: 384 },
+};
+
+export function makeEmbedder(config = {}) {
+  const cfg = config?.rag?.embedder || {};
+  const provider = cfg.provider || "ollama";
+  const spec = PROVIDERS[provider];
+  if (!spec) throw new Error(`Unknown embedder provider: ${provider}. Supported: ${Object.keys(PROVIDERS).join(", ")}`);
+  const dim = cfg.dim || spec.dim;
+  return new spec.cls({ url: cfg.url, apiKey: cfg.api_key, model: cfg.model, dim, timeoutMs: cfg.timeout_ms });
+}
+
+export { PROVIDERS };

package/src/rag/embedders/mistral.js

@@ -0,0 +1,26 @@
+// KJC-TSK-0446 — Mistral AI embeddings adapter. EU-hosted, useful for
+// users with GDPR constraints that prefer not to send chunks to US
+// endpoints. Single model today (`mistral-embed`, 1024 dim).
+import { cloudEmbed } from "./_cloud-base.js";
+
+const DEFAULTS = { url: "https://api.mistral.ai/v1/embeddings", model: "mistral-embed", dim: 1024, timeoutMs: 30000 };
+
+export class MistralEmbedderError extends Error {
+  constructor(message, { cause, status } = {}) { super(message); this.name = "MistralEmbedderError"; if (cause) this.cause = cause; if (status != null) this.status = status; }
+}
+
+export class MistralEmbedder {
+  constructor({ url = DEFAULTS.url, apiKey = process.env.KJ_MISTRAL_KEY, model = process.env.KJ_MISTRAL_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, timeoutMs = DEFAULTS.timeoutMs, fetchFn = globalThis.fetch } = {}) {
+    // KJC architecture invariant: scoped env var (KJ_MISTRAL_KEY).
+    if (!apiKey) throw new MistralEmbedderError("Mistral embedder requires an api_key (config.rag.embedder.api_key or KJ_MISTRAL_KEY env)");
+    Object.assign(this, { url, apiKey, model, dim, timeoutMs, fetch: fetchFn });
+  }
+  async embed(text) {
+    return cloudEmbed(this, text, MistralEmbedderError, {
+      provider: "Mistral",
+      body: { model: this.model, input: [text] },
+      extract: (b) => b?.data?.[0]?.embedding,
+    });
+  }
+  async embedBatch(texts) { if (!Array.isArray(texts)) throw new MistralEmbedderError("embedBatch: texts must be an array"); const out = []; for (const t of texts) out.push(await this.embed(t)); return out; }
+}

package/src/rag/embedders/onnx.js

@@ -0,0 +1,63 @@
+// KJC-TSK-0447 — ONNX local embedder via @huggingface/transformers
+// (formerly @xenova/transformers). Runs sentence-transformer models
+// directly in Node — no API key, no Docker, no Ollama.
+//
+// First call downloads the model weights to ~/.cache/huggingface/ (~80 MB
+// for the default MiniLM). Subsequent calls reuse the cache, so the steady
+// state is fully offline.
+//
+// Default model: `Xenova/all-MiniLM-L6-v2` (384 dim, ~80 MB, fast).
+// Higher-quality alternative: `Xenova/jina-embeddings-v2-base-en`
+// (768 dim, ~260 MB, slower but better for retrieval).
+
+const DEFAULTS = { model: "Xenova/all-MiniLM-L6-v2", dim: 384, pooling: "mean", normalize: true };
+
+export class ONNXEmbedderError extends Error {
+  constructor(message, { cause } = {}) { super(message); this.name = "ONNXEmbedderError"; if (cause) this.cause = cause; }
+}
+
+async function loadTransformers() {
+  // Prefer the modern @huggingface/transformers (post-2024 rebrand);
+  // fall back to @xenova/transformers for users still on the legacy package.
+  // Both are optional peer deps — Karajan does not ship them by default to
+  // keep the install size small (~500 MB with WASM + weights). The user
+  // installs whichever they prefer when they opt into provider: onnx.
+  /* eslint-disable import-x/no-unresolved */
+  try { return await import("@huggingface/transformers"); }
+  catch (e1) {
+    try { return await import("@xenova/transformers"); }
+    catch (e2) {
+      throw new ONNXEmbedderError(
+        "ONNX embedder requires @huggingface/transformers (or legacy @xenova/transformers). Install with `npm install @huggingface/transformers`.",
+        { cause: e2 },
+      );
+    }
+  }
+  /* eslint-enable import-x/no-unresolved */
+}
+
+export class ONNXEmbedder {
+  constructor({ model = process.env.KJ_ONNX_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, pooling = DEFAULTS.pooling, normalize = DEFAULTS.normalize } = {}) {
+    Object.assign(this, { model, dim, pooling, normalize, _pipe: null });
+  }
+  async _ensurePipeline() {
+    if (this._pipe) return this._pipe;
+    const transformers = await loadTransformers();
+    this._pipe = await transformers.pipeline("feature-extraction", this.model);
+    return this._pipe;
+  }
+  async embed(text) {
+    if (typeof text !== "string" || text.length === 0) throw new ONNXEmbedderError("embed: text must be a non-empty string");
+    const pipe = await this._ensurePipeline();
+    const out = await pipe(text, { pooling: this.pooling, normalize: this.normalize });
+    const arr = Array.from(out.data || []);
+    if (arr.length !== this.dim) throw new ONNXEmbedderError(`ONNX dim mismatch: got ${arr.length}, expected ${this.dim} for model ${this.model}`);
+    return Float32Array.from(arr);
+  }
+  async embedBatch(texts) {
+    if (!Array.isArray(texts)) throw new ONNXEmbedderError("embedBatch: texts must be an array");
+    const out = [];
+    for (const t of texts) out.push(await this.embed(t));
+    return out;
+  }
+}

package/src/rag/embedders/openai.js

@@ -0,0 +1,22 @@
+// KJC-TSK-0442 — OpenAI text-embeddings adapter.
+import { cloudEmbed } from "./_cloud-base.js";
+
+const DEFAULTS = { url: "https://api.openai.com/v1/embeddings", model: "text-embedding-3-small", dim: 1536, timeoutMs: 30000 };
+
+export class OpenAIEmbedderError extends Error {
+  constructor(message, { cause, status } = {}) { super(message); this.name = "OpenAIEmbedderError"; if (cause) this.cause = cause; if (status != null) this.status = status; }
+}
+
+export class OpenAIEmbedder {
+  constructor({ url = DEFAULTS.url, apiKey = process.env.KJ_OPENAI_KEY, model = process.env.KJ_OPENAI_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, timeoutMs = DEFAULTS.timeoutMs, fetchFn = globalThis.fetch } = {}) {
+    // KJC architecture invariant: Karajan does not read provider API keys
+    // (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) — those belong to the CLI
+    // agents Karajan spawns. RAG embedders are the one exception: they
+    // call the OpenAI endpoint directly, but use a Karajan-scoped env var
+    // (KJ_OPENAI_KEY) so the invariant stays clean.
+    if (!apiKey) throw new OpenAIEmbedderError("OpenAI embedder requires an api_key (config.rag.embedder.api_key or KJ_OPENAI_KEY env)");
+    Object.assign(this, { url, apiKey, model, dim, timeoutMs, fetch: fetchFn });
+  }
+  async embed(text) { return cloudEmbed(this, text, OpenAIEmbedderError, { provider: "OpenAI", body: { model: this.model, input: text }, extract: (b) => b?.data?.[0]?.embedding }); }
+  async embedBatch(texts) { if (!Array.isArray(texts)) throw new OpenAIEmbedderError("embedBatch: texts must be an array"); const out = []; for (const t of texts) out.push(await this.embed(t)); return out; }
+}

package/src/rag/embedders/voyage.js

@@ -0,0 +1,18 @@
+// KJC-TSK-0442 — Voyage AI embeddings adapter.
+import { cloudEmbed } from "./_cloud-base.js";
+
+const DEFAULTS = { url: "https://api.voyageai.com/v1/embeddings", model: "voyage-code-3", dim: 1024, timeoutMs: 30000 };
+
+export class VoyageEmbedderError extends Error {
+  constructor(message, { cause, status } = {}) { super(message); this.name = "VoyageEmbedderError"; if (cause) this.cause = cause; if (status != null) this.status = status; }
+}
+
+export class VoyageEmbedder {
+  constructor({ url = DEFAULTS.url, apiKey = process.env.KJ_VOYAGE_KEY, model = process.env.KJ_VOYAGE_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, timeoutMs = DEFAULTS.timeoutMs, fetchFn = globalThis.fetch } = {}) {
+    // Same invariant as OpenAIEmbedder: Karajan-scoped env var.
+    if (!apiKey) throw new VoyageEmbedderError("Voyage embedder requires an api_key (config.rag.embedder.api_key or KJ_VOYAGE_KEY env)");
+    Object.assign(this, { url, apiKey, model, dim, timeoutMs, fetch: fetchFn });
+  }
+  async embed(text) { return cloudEmbed(this, text, VoyageEmbedderError, { provider: "Voyage", body: { model: this.model, input: [text], input_type: "document" }, extract: (b) => b?.data?.[0]?.embedding }); }
+  async embedBatch(texts) { if (!Array.isArray(texts)) throw new VoyageEmbedderError("embedBatch: texts must be an array"); const out = []; for (const t of texts) out.push(await this.embed(t)); return out; }
+}

package/src/rag/rerank.js

@@ -0,0 +1,74 @@
+// KJC-TSK-0449 — Cross-encoder rerank stage. Re-scores the top-N hits
+// from the hybrid retriever using a (query, passage) cross-encoder.
+//
+// Cross-encoders are slower than the bi-encoder embedders (they jointly
+// encode query + passage instead of caching the passage), but they are
+// substantially more precise for the final top-K ranking. Karajan calls
+// the reranker only on the post-fusion candidates (≤topK*2), so the
+// added latency is bounded.
+//
+// Model is loaded dynamically via @huggingface/transformers (same dep as
+// the ONNX embedder, KJC-TSK-0447). Default: `Xenova/ms-marco-MiniLM-L-6-v2`,
+// the de-facto standard sentence-transformers reranker.
+
+const DEFAULT_MODEL = "Xenova/ms-marco-MiniLM-L-6-v2";
+
+export class RerankError extends Error {
+  constructor(message, { cause } = {}) { super(message); this.name = "RerankError"; if (cause) this.cause = cause; }
+}
+
+async function loadTransformers() {
+  /* eslint-disable import-x/no-unresolved */
+  try { return await import("@huggingface/transformers"); }
+  catch (e1) {
+    try { return await import("@xenova/transformers"); }
+    catch (e2) {
+      throw new RerankError(
+        "rerank requires @huggingface/transformers (or legacy @xenova/transformers). Install with `npm install @huggingface/transformers`.",
+        { cause: e2 },
+      );
+    }
+  }
+  /* eslint-enable import-x/no-unresolved */
+}
+
+/**
+ * Lazy singleton — first call downloads weights (~80 MB), every subsequent
+ * call reuses the same pipeline instance.
+ */
+let _pipelinePromise = null;
+function getPipeline(modelName) {
+  if (!_pipelinePromise) _pipelinePromise = (async () => {
+    const t = await loadTransformers();
+    // text-classification pipeline returns the cross-encoder relevance score
+    // for a `[query, passage]` text pair when applied to a CE model.
+    return t.pipeline("text-classification", modelName);
+  })();
+  return _pipelinePromise;
+}
+
+/** Reset for tests. */
+export function _resetPipeline() { _pipelinePromise = null; }
+
+/**
+ * Rerank `hits` against `queryText` using the cross-encoder. Returns a NEW
+ * array sorted by descending rerank score (best first), `score` mutated
+ * so the existing downstream code (kindBoost, slicing) keeps working.
+ *
+ * Each input hit is treated as a [query, hit.text] pair. Truncates the
+ * passage to `maxChars` to avoid blowing past the CE model's context
+ * window — most CE models handle 512 tokens, ~2000 chars is safe.
+ *
+ * If `pipelineFn` is injected (tests), it bypasses model loading.
+ */
+export async function rerank(queryText, hits, { model = process.env.KJ_RERANK_MODEL || DEFAULT_MODEL, maxChars = 2000, pipelineFn = null } = {}) {
+  if (!queryText || typeof queryText !== "string") throw new RerankError("rerank: queryText must be a non-empty string");
+  if (!Array.isArray(hits)) throw new RerankError("rerank: hits must be an array");
+  if (hits.length === 0) return hits;
+  const pipe = pipelineFn || await getPipeline(model);
+  const pairs = hits.map((h) => ({ text: queryText, text_pair: String(h.text || "").slice(0, maxChars) }));
+  const results = await pipe(pairs);
+  return hits
+    .map((h, i) => ({ ...h, _rerank: Number(results[i]?.score) || 0, score: -Number(results[i]?.score) || 0 }))
+    .sort((a, b) => a.score - b.score);
+}

package/src/rag/retriever.js

@@ -1,77 +1,75 @@
-// KJC-PCS-0049 Step 5 — Retriever for the RAG pipeline. Composes the
-// embedder (Step 2) + vec store (Step 1) into a one-call query API.
-// The CLI (Step 6) and the future MCP tool are the only consumers.
+// KJC-PCS-0049 Step 5 — Retriever for the RAG pipeline.
+import { searchSimilar, searchBM25 } from "./vec-store.js";
+import { parseWhere, buildWhereSql } from "./where-parser.js";
+import { rerank } from "./rerank.js";
 
-import { searchSimilar } from "./vec-store.js";
-
-// Kind boosts for rerank: a plan chunk is more "intentional" than a
-// raw code chunk, an onboarding brief sits between them. Tunable via
-// the third argument; the defaults are conservative — they break ties
-// between equidistant chunks but won't reorder by big distance gaps.
 const DEFAULT_KIND_BOOST = { plan: 0.05, onboarding: 0.03, code: 0 };
 
-// KJC-TSK-0440 — asymmetric source/test boost. v2.26 smoke caught a
-// systematic bias: queries in natural language ("how does X work") return
-// tests/X.test.js ahead of src/X.js because tests carry more descriptive
-// prose. When the query itself does NOT mention test-flavoured terms,
-// give code chunks +0.05 — but only chunks whose source path is NOT a
-// test file. Tests keep the baseline boost.
+// KJC-TSK-0440 — asymmetric source/test boost.
 const SOURCE_BOOST_NON_TEST = 0.05;
 const TEST_TERMS_RE = /\b(test|tests|spec|specs|expect|describe|it\(|jest|vitest|mocha)\b/i;
 const TEST_PATH_RE = /[\\/](tests?|specs?|__tests__)[\\/]|\.test\.[jt]sx?$|\.spec\.[jt]sx?$/i;
 
-function shouldBoostSources(queryText) {
-  return !TEST_TERMS_RE.test(queryText);
-}
+function shouldBoostSources(queryText) { return !TEST_TERMS_RE.test(queryText); }
+function isTestPath(source) { return TEST_PATH_RE.test(source || ""); }
 
-function isTestPath(source) {
-  return TEST_PATH_RE.test(source || "");
+// KJC-TSK-0443 — fuse semantic + keyword hits into a unified candidate set.
+// For 'semantic'/'keyword' modes we surface that side. For 'hybrid' (default)
+// we min-max normalise both scores to [0,1] (lower=better) and linear-combine
+// via alpha * semantic + (1-alpha) * keyword. Result written back to
+// `distance` so the kind+source boost pipeline keeps working unchanged.
+function fuseHits(semantic, keyword, alpha, mode) {
+  if (mode === "semantic") return semantic;
+  if (mode === "keyword") return keyword.map((h) => ({ ...h, distance: h.bm25 }));
+  const byId = new Map();
+  for (const h of semantic) byId.set(h.id, { ...h, _sem: h.distance });
+  for (const h of keyword) {
+    const prev = byId.get(h.id);
+    if (prev) prev._kw = h.bm25;
+    else byId.set(h.id, { ...h, _kw: h.bm25, distance: h.bm25 });
+  }
+  const list = [...byId.values()];
+  const norm = (vals) => {
+    const xs = vals.filter((v) => Number.isFinite(v));
+    if (xs.length === 0) return () => 0.5;
+    const min = Math.min(...xs); const max = Math.max(...xs); const span = max - min || 1;
+    return (v) => Number.isFinite(v) ? (v - min) / span : 1;
+  };
+  const nSem = norm(list.map((h) => h._sem));
+  const nKw = norm(list.map((h) => h._kw));
+  for (const h of list) h.distance = alpha * nSem(h._sem) + (1 - alpha) * nKw(h._kw);
+  return list;
 }
 
-/**
- * Run a natural-language query against the indexed RAG corpus. Returns
- * the top-K chunks ranked by adjusted distance (lower = closer).
- *
- *   query(db, embedder, "how did I handle auth in module X?",
- *         { topK: 5, scope: 'plans' })
- *
- * @param {Database} db           — opened via openVecStore()
- * @param {OllamaEmbedder} embedder
- * @param {string} text           — the query
- * @param {Object} [opts]
- * @param {number} [opts.topK=5]
- * @param {'plans'|'code'|'onboarding'|'all'} [opts.scope='all']
- * @param {Object} [opts.kindBoost]
- */
-export async function query(db, embedder, text, { topK = 5, scope = "all", kindBoost = DEFAULT_KIND_BOOST, project = null } = {}) {
+export async function query(db, embedder, text, { topK = 5, scope = "all", kindBoost = DEFAULT_KIND_BOOST, project = null, mode = "hybrid", alpha = 0.6, where = null, rerankOpts = null } = {}) {
   if (!text || typeof text !== "string") throw new Error("query: text must be a non-empty string");
-  const queryEmbedding = await embedder.embed(text);
-  // Over-fetch (topK * 2) so the rerank step has room to reshuffle
-  // without dropping a relevant chunk past the cut. Clamped at 50 to
-  // avoid loading the entire store on tiny topK calls.
   const fetchK = Math.min(50, topK * 2);
   const scopeKind = scope === "plans" ? "plan" : scope === "code" ? "code" : scope === "onboarding" ? "onboarding" : null;
-  // KJC-TSK-0438 — `project` filters by chunks.project_slug. null means
-  // no filter (pre-v2.27 behaviour). Caller's CLI defaults this to the
-  // basename of cwd; pass "all" through commands/rag.js to disable.
-  const raw = searchSimilar(db, queryEmbedding, fetchK, { kind: scopeKind, project });
+  // KJC-TSK-0448 — metadata filter. `where` is a string like "symbol=Foo AND
+  // hu_id=HU-003"; we parse once and reuse the SQL fragment across both
+  // semantic and keyword searches.
+  const parsed = parseWhere(where);
+  if (!parsed.ok) throw new Error(`query: ${parsed.error}`);
+  const { sql: whereSql, params: whereParams } = buildWhereSql(parsed.clauses);
+  const opts = { kind: scopeKind, project, whereSql, whereParams };
+  const wantSemantic = mode !== "keyword";
+  const wantKeyword = mode !== "semantic";
+  const semanticHits = wantSemantic ? searchSimilar(db, await embedder.embed(text), fetchK, opts) : [];
+  const keywordHits = wantKeyword ? searchBM25(db, text, fetchK, opts) : [];
+  const raw = fuseHits(semanticHits, keywordHits, alpha, mode);
   if (raw.length === 0) return [];
-  // Adjust each chunk's distance by its kind boost. The vec store returns
-  // cosine distance (smaller = closer); subtracting the boost makes
-  // higher-priority kinds appear "closer" without altering the source
-  // truth in the DB.
-  // KJC-TSK-0440 — apply the source-vs-test asymmetric boost only when
-  // the query itself is not test-flavoured. Test-flavoured queries keep
-  // the symmetric baseline so e.g. "vitest mock setup" still surfaces
-  // test files.
   const boostSources = shouldBoostSources(text);
   const reranked = raw.map((r) => {
     const kindB = kindBoost[r.kind] || 0;
     const sourceB = (boostSources && r.kind === "code" && !isTestPath(r.source)) ? SOURCE_BOOST_NON_TEST : 0;
     return { ...r, score: r.distance - kindB - sourceB };
   }).sort((a, b) => a.score - b.score).slice(0, topK);
+  // KJC-TSK-0449 — optional cross-encoder rerank. When `rerankOpts` is set,
+  // we re-score the topK survivors with a (query, passage) cross-encoder;
+  // the kind+source boost has already been applied, so the rerank acts as
+  // a finer-grained quality lever on top.
+  if (rerankOpts) return await rerank(text, reranked, rerankOpts);
   return reranked;
 }
 
-// Exported for tests.
-export { shouldBoostSources, isTestPath };
+export { shouldBoostSources, isTestPath, fuseHits };

package/src/rag/vec-store.js

@@ -54,6 +54,29 @@ export function openVecStore({ dim = DEFAULT_DIM, path = dbPath() } = {}) {
     db.exec("CREATE INDEX IF NOT EXISTS chunks_by_project ON chunks(project_slug);");
   }
   db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0(embedding float[${dim}]);`);
+  // KJC-TSK-0443 — FTS5 keyword index for BM25 hybrid scoring. content='chunks'
+  // makes it a contentless mirror linked by id (no double storage); triggers
+  // sync the FTS5 rows on insert/update/delete. Rebuilds idempotently when
+  // the FTS5 table exists but is empty (e.g. created post-migration on a
+  // DB with pre-v2.28 chunks).
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(text, content='chunks', content_rowid='id');
+    CREATE TRIGGER IF NOT EXISTS chunks_ai AFTER INSERT ON chunks BEGIN
+      INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
+    END;
+    CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
+      INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES ('delete', old.id, old.text);
+    END;
+    CREATE TRIGGER IF NOT EXISTS chunks_au AFTER UPDATE ON chunks BEGIN
+      INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES ('delete', old.id, old.text);
+      INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
+    END;
+  `);
+  const ftsCount = db.prepare("SELECT COUNT(*) AS n FROM chunks_fts").get().n;
+  const chunksCount = db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
+  if (ftsCount === 0 && chunksCount > 0) {
+    db.exec("INSERT INTO chunks_fts(chunks_fts) VALUES('rebuild');");
+  }
   return db;
 }
 
@@ -83,7 +106,7 @@ export function insertChunk(db, { source, kind, text, metadata = null, embedding
  * text, metadata, distance }]` for the topK best matches; lower
  * distance = closer. Returns `[]` when the store is empty.
  */
-export function searchSimilar(db, embedding, topK = 5, { kind = null, project = null } = {}) {
+export function searchSimilar(db, embedding, topK = 5, { kind = null, project = null, whereSql = "", whereParams = [] } = {}) {
   const buf = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
   const kindClause = kind ? "AND c.kind = ?" : "";
   const projectClause = project ? "AND c.project_slug = ?" : "";
@@ -91,12 +114,13 @@ export function searchSimilar(db, embedding, topK = 5, { kind = null, project =
     SELECT c.id, c.source, c.kind, c.text, c.metadata, c.project_slug, v.distance
     FROM vec_chunks v
     JOIN chunks c ON c.id = v.rowid
-    WHERE v.embedding MATCH ? AND k = ? ${kindClause} ${projectClause}
+    WHERE v.embedding MATCH ? AND k = ? ${kindClause} ${projectClause}${whereSql}
     ORDER BY v.distance
   `;
   const params = [Buffer.from(buf.buffer), topK];
   if (kind) params.push(kind);
   if (project) params.push(project);
+  if (whereParams.length) params.push(...whereParams);
   const rows = db.prepare(sql).all(...params);
   return rows.map((r) => ({ ...r, metadata: r.metadata ? safeParse(r.metadata) : null }));
 }
@@ -133,3 +157,31 @@ export function countChunks(db, { kind = null } = {}) {
   if (kind) return db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE kind = ?").get(kind).n;
   return db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
 }
+
+/**
+ * KJC-TSK-0443 — BM25 keyword search over chunks_fts. Returns
+ * [{ id, source, kind, text, metadata, project_slug, bm25 }] ordered by
+ * relevance (lower bm25 = better in SQLite FTS5). `query` is sanitized for
+ * the FTS5 grammar: special chars are stripped, words split on whitespace.
+ */
+export function searchBM25(db, queryText, topK = 10, { kind = null, project = null, whereSql = "", whereParams = [] } = {}) {
+  const cleaned = String(queryText || "").replace(/["'()]/g, " ").split(/\s+/).filter(Boolean).join(" OR ");
+  if (!cleaned) return [];
+  const kindClause = kind ? "AND c.kind = ?" : "";
+  const projectClause = project ? "AND c.project_slug = ?" : "";
+  const sql = `
+    SELECT c.id, c.source, c.kind, c.text, c.metadata, c.project_slug, bm25(chunks_fts) AS bm25
+    FROM chunks_fts JOIN chunks c ON c.id = chunks_fts.rowid
+    WHERE chunks_fts MATCH ? ${kindClause} ${projectClause}${whereSql}
+    ORDER BY bm25 LIMIT ?
+  `;
+  const params = [cleaned];
+  if (kind) params.push(kind);
+  if (project) params.push(project);
+  if (whereParams.length) params.push(...whereParams);
+  params.push(topK);
+  try {
+    const rows = db.prepare(sql).all(...params);
+    return rows.map((r) => ({ ...r, metadata: r.metadata ? safeParse(r.metadata) : null }));
+  } catch { return []; }
+}

package/src/rag/watcher.js

@@ -0,0 +1,60 @@
+// KJC-TSK-0441 (RAG v2.28.0 PR1) — chokidar watcher. Live re-index of plans
+// + onboarding + (opt) sources, debounced. PID file arbitrates a single daemon.
+import { writeFileSync, readFileSync, existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import chokidar from "chokidar";
+import { openVecStore, deleteChunksBySource, projectSlug } from "./vec-store.js";
+import { makeEmbedder } from "./embedders/factory.js";
+import { indexFile } from "./indexer.js";
+import { getKarajanHome } from "../utils/paths.js";
+
+const PIDFILE = () => join(getKarajanHome(), "watcher.pid");
+const DEFAULT_DEBOUNCE_MS = 1000;
+const SKIP_SEGMENTS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".next", ".kj", "_diet"]);
+const SOURCE_RE = /\.(js|mjs|cjs|ts|tsx|jsx)$/;
+
+function isWatchable(path) {
+  if (path.includes("/.karajan/onboarding/")) return /\.md$/.test(path);
+  if (path.includes("/.karajan/plans/")) return /\.json$/.test(path);
+  if (path.split("/").some((seg) => SKIP_SEGMENTS.has(seg))) return false;
+  return SOURCE_RE.test(path);
+}
+
+export function startWatcher({ projectDir, config, logger = console, debounceMs = DEFAULT_DEBOUNCE_MS, withSources = false } = {}) {
+  if (!projectDir) throw new Error("startWatcher: projectDir is required");
+  const slug = projectSlug(projectDir);
+  const dim = config?.rag?.embedder?.dim || 768;
+  const db = openVecStore({ dim });
+  const embedder = makeEmbedder(config);
+  const paths = [join(getKarajanHome(), "onboarding"), join(getKarajanHome(), "plans")];
+  if (withSources) paths.push(projectDir);
+  const watcher = chokidar.watch(paths, { ignoreInitial: true, persistent: true });
+  const pending = new Map();
+  const flush = async (p) => {
+    pending.delete(p);
+    if (!existsSync(p)) { deleteChunksBySource(db, p); logger.info?.(`[rag-watcher] removed → ${p}`); return; }
+    if (!isWatchable(p)) return;
+    try { const r = await indexFile(p, { db, embedder, logger, project: slug }); logger.info?.(`[rag-watcher] reindexed ${p} → ${r.indexed} chunk(s)`); }
+    catch (err) { logger.warn?.(`[rag-watcher] reindex failed for ${p}: ${err.message}`); }
+  };
+  const schedule = (p) => { if (pending.has(p)) clearTimeout(pending.get(p)); pending.set(p, setTimeout(() => flush(p), debounceMs)); };
+  watcher.on("add", schedule).on("change", schedule).on("unlink", schedule).on("error", (err) => logger.warn?.(`[rag-watcher] ${err.message}`));
+  return async function stop() {
+    for (const t of pending.values()) clearTimeout(t);
+    pending.clear();
+    await watcher.close();
+    try { db.close(); } catch { /* already closed */ }
+  };
+}
+
+export function writePidFile(pid = process.pid) { writeFileSync(PIDFILE(), String(pid), "utf8"); }
+export function clearPidFile() { if (existsSync(PIDFILE())) unlinkSync(PIDFILE()); }
+export function readPidFile() {
+  if (!existsSync(PIDFILE())) return null;
+  const pid = Number(readFileSync(PIDFILE(), "utf8").trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+export function isPidAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}

package/src/rag/where-parser.js

@@ -0,0 +1,54 @@
+// KJC-TSK-0448 — minimal --where filter parser for metadata-aware RAG
+// queries. Grammar (intentionally small):
+//
+//   clause     := pair ( "AND" pair )*
+//   pair       := IDENT "=" VALUE
+//   IDENT      := [A-Za-z_][A-Za-z0-9_.-]*
+//   VALUE      := unquoted token  | "quoted string"
+//
+// Examples:
+//   symbol=loadConfig
+//   hu_id=HU-003 AND kind=plan
+//   "headingPath.0"=Architecture
+//
+// Returns { ok: true, clauses: [["symbol","loadConfig"], ...] } or
+// { ok: false, error: "...explanation..." }. The retriever turns each
+// clause into a `json_extract(c.metadata, '$.<key>') = ?` SQL fragment;
+// the `kind` key is special-cased to filter the column directly.
+
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+
+export function parseWhere(input) {
+  if (input == null) return { ok: true, clauses: [] };
+  if (typeof input !== "string") return { ok: false, error: "where: input must be a string" };
+  const s = input.trim();
+  if (!s) return { ok: true, clauses: [] };
+  const parts = s.split(/\s+AND\s+/i);
+  const clauses = [];
+  for (const p of parts) {
+    const eq = p.indexOf("=");
+    if (eq <= 0) return { ok: false, error: `where: bad pair "${p}" — expected key=value` };
+    const key = p.slice(0, eq).trim().replace(/^"|"$/g, "");
+    let val = p.slice(eq + 1).trim();
+    if (!IDENT_RE.test(key)) return { ok: false, error: `where: invalid key "${key}"` };
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) val = val.slice(1, -1);
+    if (val.length === 0) return { ok: false, error: `where: empty value for key "${key}"` };
+    clauses.push([key, val]);
+  }
+  return { ok: true, clauses };
+}
+
+/**
+ * Build a `(sqlFragment, params)` pair to append to a chunks-table query.
+ * `kind` filters the column directly; everything else goes through json_extract.
+ */
+export function buildWhereSql(clauses) {
+  if (!clauses?.length) return { sql: "", params: [] };
+  const fragments = [];
+  const params = [];
+  for (const [k, v] of clauses) {
+    if (k === "kind") { fragments.push("c.kind = ?"); params.push(v); }
+    else { fragments.push(`json_extract(c.metadata, '$.${k}') = ?`); params.push(v); }
+  }
+  return { sql: ` AND ${fragments.join(" AND ")}`, params };
+}

package/src/utils/rate-limit-detector.js

@@ -39,23 +39,21 @@ export function parseCooldown(message) {
     }
   }
 
-  // 5. Claude Code session / weekly limit: "resets 10:10pm" / "resets 4am"
-  //    (12-hour clock, no date). Resolve to the next wall-clock occurrence
-  //    of that time in the machine's local timezone. Claude Code reports
-  //    the reset in the user's local TZ and kj runs on the same machine,
-  //    so the parenthesised "(Europe/Madrid)" hint is ignored on purpose.
-  const ampmMatch = /reset(?:s|ting)?\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*([ap]m)\b/i.exec(
-    message
-  );
+  // 5. Claude Code session / weekly limit: "resets 10:10pm (Europe/Madrid)" / "resets 4am"
+  //    KJC-BUG-0064: prefer the parenthesised IANA TZ when present so the
+  //    same stderr resolves to the same instant regardless of where kj runs
+  //    (CI in TZ=UTC was misclassifying Madrid 10:10pm as already past).
+  //    No TZ literal → fall back to the host's local TZ.
+  const ampmMatch = /reset(?:s|ting)?\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*([ap]m)\b/i.exec(message);
   if (ampmMatch) {
     let hour = Number.parseInt(ampmMatch[1], 10) % 12;
     if (/pm/i.test(ampmMatch[3])) hour += 12;
     const minute = ampmMatch[2] ? Number.parseInt(ampmMatch[2], 10) : 0;
     if (hour < 24 && minute < 60) {
-      const target = new Date();
-      target.setHours(hour, minute, 0, 0);
-      if (target.getTime() <= Date.now()) target.setDate(target.getDate() + 1);
-      return { cooldownUntil: target.toISOString(), cooldownMs: target.getTime() - Date.now() };
+      const tzMatch = /\(([A-Za-z]+\/[A-Za-z_/+\-0-9]+)\)/.exec(message);
+      const tz = tzMatch ? tzMatch[1] : null;
+      const target = tz ? nextOccurrenceInTZ(hour, minute, tz) : nextOccurrenceLocal(hour, minute);
+      if (target) return { cooldownUntil: target.toISOString(), cooldownMs: Math.max(0, target.getTime() - Date.now()) };
     }
   }
 
@@ -84,6 +82,50 @@ export function parseCooldown(message) {
   return { cooldownUntil: null, cooldownMs: null };
 }
 
+// KJC-BUG-0064 — TZ-aware "next occurrence of hour:minute" resolver.
+// Walks today + tomorrow in the given IANA TZ; returns the first instant
+// > now. Uses Intl.DateTimeFormat as the source of truth so it works on
+// any host TZ (CI runs UTC, dev runs Europe/Madrid, etc.).
+function nextOccurrenceInTZ(hour, minute, tz) {
+  try {
+    const now = new Date();
+    for (let dayOffset = 0; dayOffset <= 1; dayOffset++) {
+      const probe = new Date(now.getTime() + dayOffset * 86400000);
+      const parts = new Intl.DateTimeFormat("en-CA", {
+        timeZone: tz, year: "numeric", month: "2-digit", day: "2-digit",
+      }).formatToParts(probe).reduce((acc, p) => (p.type !== "literal" ? { ...acc, [p.type]: p.value } : acc), {});
+      if (!parts.year) return null;
+      const candidate = zonedTimeToUTC(Number(parts.year), Number(parts.month), Number(parts.day), hour, minute, tz);
+      if (candidate && candidate.getTime() > now.getTime()) return candidate;
+    }
+    return null;
+  } catch { return null; }
+}
+
+// Converts a wall-clock date + time in `tz` to a UTC Date.
+// Strategy: interpret year/month/day/hour/minute as naive UTC, see what
+// wall-clock that maps to in `tz`, derive the offset (tz - UTC at that
+// moment) and subtract it from the naive value to land on the true UTC.
+// One step suffices except at DST transitions (within ±1h, acceptable
+// for cooldown timing).
+function zonedTimeToUTC(year, month, day, hour, minute, tz) {
+  const naiveUTC = Date.UTC(year, month - 1, day, hour, minute);
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: tz, year: "numeric", month: "2-digit", day: "2-digit",
+    hour: "2-digit", minute: "2-digit", hour12: false,
+  }).formatToParts(new Date(naiveUTC)).reduce((acc, p) => (p.type !== "literal" ? { ...acc, [p.type]: p.value } : acc), {});
+  const wallInTZ = Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour) % 24, Number(parts.minute));
+  const tzOffset = wallInTZ - naiveUTC; // positive when tz is ahead of UTC
+  return new Date(naiveUTC - tzOffset);
+}
+
+function nextOccurrenceLocal(hour, minute) {
+  const target = new Date();
+  target.setHours(hour, minute, 0, 0);
+  if (target.getTime() <= Date.now()) target.setDate(target.getDate() + 1);
+  return target;
+}
+
 const RATE_LIMIT_PATTERNS = [
   // Claude CLI
   { pattern: /usage limit/i, agent: "claude" },