karajan-code 2.26.0 → 2.28.0

package/README.md

@@ -345,13 +345,30 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
-> **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.
+> **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.
+> - **`docs/RAG.md` + `docs/es/RAG.md`** (PR #832): single unified guide covering architecture, install, six workflows, configuration, limitations and troubleshooting. Replaces the documentation spread across CHANGELOG / templates / landing.
+> - **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).
+>
+> **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)).
 >
 > Capability check (RAM + Docker) means the bootstrap never breaks init: on Windows without Docker Desktop, on hosts under 4 GB free, or with `--no-ollama`, the wizard logs a one-liner and continues. Where Ollama is already running on `:11434`, `kj init` reuses the external instance instead of spawning a second container.
 >
 > Bundles **KJC-BUG-0061** fix (caught during v2.25.0 smoke test): `kj onboard --no-synth` was ignored by Commander shape mapping, `OnboarderRole.run()` was called without `init()`, and `kj rag query --json` on empty store emitted just `[]` instead of the `{empty: true}` contract the MCP handler returns.
 >
-> **Coming in v2.27.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 next from v2.26.0**: addressed in v2.27.0 above.
 >
 > **v2.25.0 released** — Minor. **RAG Camino B + Camino D** (KJC-PCS-0049). Closes the consumer-surface plan. Skills hosts can now invoke RAG via `/kj-rag-query` without MCP, and the pre-loop retrieval stage from v2.24.0 only fires when triage signals make it worthwhile.
 >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.26.0",
+  "version": "2.28.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/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/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" }, () => ({
@@ -168,6 +168,14 @@ const ragStubPlugin = {
           // KJC-TSK-0436 — Ollama capability check + model pull.
           checkDockerAvailable: notAvailable, checkRamCapacity: notAvailable,
           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 — RAG embedders cloud + factory.
+          makeEmbedder: notAvailable, OpenAIEmbedder: notAvailable, VoyageEmbedder: notAvailable,
+          OpenAIEmbedderError: notAvailable, VoyageEmbedderError: notAvailable, PROVIDERS: 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";
@@ -113,6 +114,9 @@ export function registerMeta(program, { pkgVersion }) {
     .description("Run a semantic query against the indexed RAG corpus")
     .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("--json", "Output the hits as JSON")
     .action(async (text, flags) => {
       await withConfig(pkgVersion, "rag-query", flags, async ({ config, logger }) => {
@@ -120,6 +124,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

@@ -2,17 +2,12 @@
 //   kj rag index [--project <slug>] [--with-sources]
 //   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 } from "../rag/vec-store.js";
-import { OllamaEmbedder } from "../rag/embedder.js";
+import { openVecStore, countChunks, projectSlug } from "../rag/vec-store.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 });
 }
@@ -43,6 +38,12 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
   try {
     const topK = Math.max(1, Number(flags.topK) || 5);
     const scope = flags.scope || "all";
+    // KJC-TSK-0438 — project isolation. Auto-detect slug from projectDir
+    // (basename normalised); `--project all` disables the filter, `--project
+    // <slug>` overrides. Pre-v2.27 chunks with NULL slug are only visible
+    // when no filter is in effect.
+    const detected = projectSlug(config?.projectDir || process.cwd());
+    const project = flags.project === "all" ? null : (flags.project || detected || null);
     // KJC-BUG-0061 follow-up: align the CLI `--json` shape with the MCP
     // handler. The MCP tool responds `{ hits: [], empty: true, topK, scope }`
     // so agents (and the `/kj-rag-query` skill from Camino B) have a
@@ -54,7 +55,9 @@ 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 });
+    const mode = flags.mode || "hybrid";
+    const alpha = Math.max(0, Math.min(1, Number(flags.alpha) || 0.6));
+    const hits = await query(db, makeEmbedder(config), text, { topK, scope, project, mode, alpha });
     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/factory.js

@@ -0,0 +1,20 @@
+// KJC-TSK-0442 — Embedder factory. Selects provider from
+// config.rag.embedder.provider (ollama | openai | voyage; 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";
+
+const PROVIDERS = { ollama: { cls: OllamaEmbedder, dim: 768 }, openai: { cls: OpenAIEmbedder, dim: 1536 }, voyage: { cls: VoyageEmbedder, dim: 1024 } };
+
+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/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/indexer.js

@@ -41,7 +41,7 @@ function chunksFor(path, kind) {
  * fresh batch is written, so a second call against the same file
  * leaves the store with exactly the latest chunks (no duplicates).
  */
-export async function indexFile(path, { db, embedder, logger = console } = {}) {
+export async function indexFile(path, { db, embedder, logger = console, project = null } = {}) {
   if (!existsSync(path)) { logger.warn?.(`[rag-indexer] file not found: ${path}`); return { indexed: 0, failed: 0 }; }
   const kind = detectKind(path);
   if (!kind) { logger.warn?.(`[rag-indexer] unknown kind: ${path}`); return { indexed: 0, failed: 0 }; }
@@ -53,7 +53,7 @@ export async function indexFile(path, { db, embedder, logger = console } = {}) {
   for (const ch of chunks) {
     try {
       const embedding = await embedder.embed(ch.text);
-      insertChunk(db, { source: path, kind: ch.metadata.kind || kind, text: ch.text, metadata: ch.metadata, embedding });
+      insertChunk(db, { source: path, kind: ch.metadata.kind || kind, text: ch.text, metadata: ch.metadata, embedding, project });
       indexed += 1;
     } catch (err) {
       failed += 1;
@@ -95,20 +95,25 @@ export async function indexProject(projectDir, { db, embedder, karajanHome, logg
   if (existsSync(planRoot)) {
     const plans = await listFiles(planRoot, (p) => /plan-.*\.json$/.test(p));
     for (const p of plans) {
-      const r = await indexFile(p, { db, embedder, logger });
+      const r = await indexFile(p, { db, embedder, logger, project: slug });
       totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
     }
   }
   const onboarding = join(karajanHome, ONBOARDING_DIR, `${slug}.md`);
   if (existsSync(onboarding)) {
-    const r = await indexFile(onboarding, { db, embedder, logger });
+    const r = await indexFile(onboarding, { db, embedder, logger, project: slug });
     totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
   }
   if (withSources) {
-    const SKIP = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".next"]);
+    // KJC-BUG-0062: `.kj/worktrees/HU-*/` contains git worktrees Karajan spawns
+    // per HU during `kj run`; they hold complete copies of `src/` that
+    // duplicate every chunk and contaminate retrieval scores. `_diet` is the
+    // tests/_diet/ sandbox used by the test-diet audit harness — never user
+    // code. Skip both.
+    const SKIP = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".next", ".kj", "_diet"]);
     const sources = await listFiles(projectDir, (p) => /\.(js|mjs|cjs|ts|tsx|jsx)$/.test(p) && !p.split("/").some((seg) => SKIP.has(seg)));
     for (const s of sources) {
-      const r = await indexFile(s, { db, embedder, logger });
+      const r = await indexFile(s, { db, embedder, logger, project: slug });
       totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
     }
   }

package/src/rag/retriever.js

@@ -1,47 +1,61 @@
-// 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 { 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 };
 
-/**
- * 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 } = {}) {
+// 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 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;
+}
+
+export async function query(db, embedder, text, { topK = 5, scope = "all", kindBoost = DEFAULT_KIND_BOOST, project = null, mode = "hybrid", alpha = 0.6 } = {}) {
   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;
-  const raw = searchSimilar(db, queryEmbedding, fetchK, { kind: scopeKind });
+  const wantSemantic = mode !== "keyword";
+  const wantKeyword = mode !== "semantic";
+  const semanticHits = wantSemantic ? searchSimilar(db, await embedder.embed(text), fetchK, { kind: scopeKind, project }) : [];
+  const keywordHits = wantKeyword ? searchBM25(db, text, fetchK, { kind: scopeKind, project }) : [];
+  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.
-  const reranked = raw.map((r) => ({
-    ...r,
-    score: r.distance - (kindBoost[r.kind] || 0),
-  })).sort((a, b) => a.score - b.score).slice(0, topK);
+  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);
   return reranked;
 }
+
+export { shouldBoostSources, isTestPath, fuseHits };

package/src/rag/vec-store.js

@@ -45,7 +45,38 @@ export function openVecStore({ dim = DEFAULT_DIM, path = dbPath() } = {}) {
     CREATE INDEX IF NOT EXISTS chunks_by_source ON chunks(source);
     CREATE INDEX IF NOT EXISTS chunks_by_kind ON chunks(kind);
   `);
+  // KJC-TSK-0438 — Project isolation. project_slug = basename of projectDir
+  // normalized; chunks indexed before the migration carry NULL and remain
+  // queryable when `--project all` (or no slug detected at query time).
+  const cols = db.prepare("PRAGMA table_info(chunks)").all().map((c) => c.name);
+  if (!cols.includes("project_slug")) {
+    db.exec("ALTER TABLE chunks ADD COLUMN project_slug TEXT;");
+    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;
 }
 
@@ -54,13 +85,13 @@ export function openVecStore({ dim = DEFAULT_DIM, path = dbPath() } = {}) {
  * because the virtual table rowid is set explicitly to the freshly
  * minted chunks.id. Returns that id.
  */
-export function insertChunk(db, { source, kind, text, metadata = null, embedding }) {
+export function insertChunk(db, { source, kind, text, metadata = null, embedding, project = null }) {
   if (!Array.isArray(embedding) && !ArrayBuffer.isView(embedding)) {
     throw new Error("insertChunk: embedding must be an array or typed array of floats");
   }
   const meta = metadata == null ? null : (typeof metadata === "string" ? metadata : JSON.stringify(metadata));
-  const ins = db.prepare("INSERT INTO chunks (source, kind, text, metadata) VALUES (?, ?, ?, ?)");
-  const info = ins.run(source, kind, text, meta);
+  const ins = db.prepare("INSERT INTO chunks (source, kind, text, metadata, project_slug) VALUES (?, ?, ?, ?, ?)");
+  const info = ins.run(source, kind, text, meta, project);
   // sqlite-vec's vec0 virtual table requires the rowid to arrive as a BigInt
   // even for values that comfortably fit in a Number. Better-sqlite3 returns
   // lastInsertRowid as BigInt only when safeIntegers mode is on; force it.
@@ -75,22 +106,36 @@ 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 } = {}) {
+export function searchSimilar(db, embedding, topK = 5, { kind = null, project = null } = {}) {
   const buf = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
   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, v.distance
+    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}
+    WHERE v.embedding MATCH ? AND k = ? ${kindClause} ${projectClause}
     ORDER BY v.distance
   `;
   const params = [Buffer.from(buf.buffer), topK];
   if (kind) params.push(kind);
+  if (project) params.push(project);
   const rows = db.prepare(sql).all(...params);
   return rows.map((r) => ({ ...r, metadata: r.metadata ? safeParse(r.metadata) : null }));
 }
 
+/**
+ * Normalize a projectDir into a stable slug used for project isolation.
+ * Basename → lowercased → non-alphanumeric stripped to dashes.
+ * KJC-TSK-0438.
+ */
+export function projectSlug(projectDir) {
+  if (!projectDir) return null;
+  const base = String(projectDir).replace(/\/+$/, "").split("/").pop();
+  if (!base) return null;
+  return base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
 function safeParse(s) { try { return JSON.parse(s); } catch { return s; } }
 
 /**
@@ -111,3 +156,30 @@ 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 } = {}) {
+  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}
+    ORDER BY bm25 LIMIT ?
+  `;
+  const params = [cleaned];
+  if (kind) params.push(kind);
+  if (project) params.push(project);
+  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/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" },