karajan-code 3.14.1 → 3.15.0

package/README.md

@@ -383,6 +383,16 @@ Each AI role is executed by the agent you choose:
 >
 > Full per-stage reference: [Pipeline roles](https://karajan-code.web.app/docs/handbook/pipeline-roles/) (handbook).
 
+## Step mode and parallel lanes (v3.14+)
+
+Two ways to control how a plan executes:
+
+**`kj run --step`** — supervise the orchestra iteration by iteration. After every iteration the pipeline pauses with a compact report (what happened, the reviewer's must-fix list, what the next iteration will do, spend vs cap) and asks: press Enter to continue, type `stop` to halt (resumable with `kj resume`), or **type instructions** — free text is injected into the feedback the coder reads next iteration, without clobbering the reviewer's own findings. Also offered as a question in the `kj init` wizard (`session.iteration_gate`).
+
+**`kj run --plan <id> --parallel <n>`** — run a plan's independent HUs concurrently, each in its own **git worktree** under `.kj/worktrees/<huId>` on branch `kj-hu-<huId>`. The scheduler walks the `blocked_by` graph and only pairs HUs with disjoint `scope` paths (scopeless HUs run alone); the whole lane — coder, acceptance tests, diffs, sonar, final commit — runs inside its worktree while the main working tree stays parked. Governance is built in: default is `1` (fully sequential), a plan-level budget ceiling (`n × max_budget_usd`) stops the batch loudly when exhausted, and SonarQube serializes across lanes. Each fresh worktree is bootstrapped automatically (submodules + `npm ci`, or your `session.worktree_setup` command) and receives `KJ_LANE_SLOT` / `KJ_PORT_OFFSET` env vars so services started by tests don't collide on ports.
+
+Full guide: [`docs/parallel-hus.md`](docs/parallel-hus.md).
+
 ## 5 AI agents supported
 
 | Agent | CLI | Install |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.14.1",
+  "version": "3.15.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

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

@@ -76,7 +76,9 @@ router.get('/version', (_req, res) => {
  */
 router.get('/standby', async (_req, res) => {
   try {
-    const { listPendingStandby } = await import('../../../../src/brain/standby-store.js');
+    // KJC-TSK-0632: resolve from karajan-core directly — the CLI's
+    // src/brain/standby-store.js is just a re-export shim of this.
+    const { listPendingStandby } = await import('karajan-core/standby-store');
     const sessions = listPendingStandby();
     res.set('Cache-Control', 'no-store');
     res.json({ sessions });
@@ -1362,8 +1364,10 @@ router.post('/rag/query', async (req, res) => {
   }
   try {
     const { openVecStore, countChunks } = await import('karajan-core/vec-store');
-    const { makeEmbedder } = await import('../../../../src/rag/embedders/factory.js');
-    const { query } = await import('../../../../src/rag/retriever.js');
+    // KJC-TSK-0632: resolved from karajan-core — the board carries zero
+    // relative imports into the CLI src tree (see no-cli-imports test).
+    const { makeEmbedder } = await import('karajan-core/rag/embedders/factory');
+    const { query } = await import('karajan-core/rag/retriever');
     const db = openVecStore({ dim: 768 });
     try {
       if (countChunks(db) === 0) return res.json({ hits: [], empty: true, topK, scope });

package/scripts/verify-pack.mjs

@@ -166,7 +166,11 @@ try {
     console.log(`verify-pack: installing the tarball with pnpm into ${pnpmTmp}…`);
     // pnpm exits non-zero on ERR_PNPM_IGNORED_BUILDS (it skips native build
     // scripts by default) — expected here, so don't treat the exit as failure.
-    spawnSync("pnpm", ["add", tgzPath, "--store-dir", path.join(pnpmTmp, ".store")], {
+    // minimum-release-age=0: modern pnpm quarantines freshly published
+    // versions (supply-chain protection), so right after publishing
+    // karajan-core it silently resolves an OLD one and this smoke fails on
+    // missing subpaths. The gate verifies packaging, not release-age policy.
+    spawnSync("pnpm", ["add", tgzPath, "--store-dir", path.join(pnpmTmp, ".store"), "--config.minimum-release-age=0"], {
       encoding: "utf8",
       env: childEnv,
       cwd: pnpmTmp,

package/src/agents/claude-agent.js

@@ -300,7 +300,10 @@ export function createStreamJsonFilter(onOutput) {
  */
 function cleanExecaOpts(extra = {}) {
   const { CLAUDECODE: _CLAUDECODE, ...env } = process.env;
-  return { env, stdin: "ignore", ...extra };
+  // PAR-H (KJC-TSK-0631): extra.env ADDS to the inherited env (lane slot
+  // vars) instead of replacing it wholesale.
+  const { env: extraEnv, ...rest } = extra;
+  return { env: extraEnv ? { ...env, ...extraEnv } : env, stdin: "ignore", ...rest };
 }
 
 /**
@@ -370,7 +373,8 @@ export class ClaudeAgent extends BaseAgent {
       const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({
         onOutput: streamFilter,
         silenceTimeoutMs: task.silenceTimeoutMs,
-        timeout: task.timeoutMs
+        timeout: task.timeoutMs,
+        env: task.env
       }));
       const raw = pickOutput(res);
       const output = extractTextFromStreamJson(raw);
@@ -380,7 +384,7 @@ export class ClaudeAgent extends BaseAgent {
 
     // Without streaming, use json output to get structured response via stderr
     args.push("--output-format", "json");
-    const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts());
+    const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({ env: task.env }));
     const raw = pickOutput(res);
     const output = extractTextFromStreamJson(raw);
     const usage = extractUsageFromStreamJson(raw);
@@ -393,7 +397,8 @@ export class ClaudeAgent extends BaseAgent {
     const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
-      timeout: task.timeoutMs
+      timeout: task.timeoutMs,
+      env: task.env
     }));
     const raw = pickOutput(res);
     const usage = extractUsageFromStreamJson(raw);

package/src/agents/model-registry.js

@@ -108,6 +108,29 @@ registerModelAlias("gemini", "gemini-2.5-pro");
 registerModel("aider", { provider: "aider", pricing: { input_per_million: 3, output_per_million: 15 } });
 registerModel("opencode", { provider: "opencode", pricing: { input_per_million: 0, output_per_million: 0 } });
 
+/**
+ * Moonshot Kimi Family (KJC-TSK-0633) — consumed through OpenCode as an
+ * OpenAI-compatible provider (docs/providers-via-opencode.md).
+ * Pricing: https://platform.moonshot.ai/docs/pricing — verify before
+ * trusting for billing decisions; ids/prices move fast.
+ */
+registerModel("kimi-k2", { provider: "moonshot", pricing: { input_per_million: 0.6, output_per_million: 2.5 } });
+registerModel("kimi-k2-thinking", { provider: "moonshot", pricing: { input_per_million: 0.6, output_per_million: 2.5 } });
+registerModelAlias("kimi", "kimi-k2");
+// Prefixed ids as the documented opencode.json snippet produces them.
+registerModelAlias("kimi/kimi-k2", "kimi-k2");
+registerModelAlias("kimi/kimi-k2-thinking", "kimi-k2-thinking");
+
+/**
+ * DeepSeek Family (KJC-TSK-0633) — same OpenCode route.
+ * Pricing: https://api-docs.deepseek.com/quick_start/pricing
+ */
+registerModel("deepseek-chat", { provider: "deepseek", pricing: { input_per_million: 0.28, output_per_million: 0.42 } });
+registerModel("deepseek-reasoner", { provider: "deepseek", pricing: { input_per_million: 0.28, output_per_million: 0.42 } });
+registerModelAlias("deepseek", "deepseek-chat");
+registerModelAlias("deepseek/deepseek-chat", "deepseek-chat");
+registerModelAlias("deepseek/deepseek-reasoner", "deepseek-reasoner");
+
 // Common CLI Aliases (with provider overrides)
 registerModelAlias("aider/claude-3-7-sonnet", "claude-sonnet-4.6", { provider: "aider" });
 registerModelAlias("aider/gpt-4o", "gpt-5.4-standard", { provider: "aider" });

package/src/config/defaults.js

@@ -182,6 +182,10 @@ const DEFAULTS = {
     // Concurrent HU lanes per plan run (KJC-TSK-0626). 1 = sequential.
     // Raising it multiplies token burn rate — the plan budget scales with it.
     max_parallel_hus: 1,
+    // Command run inside each fresh lane worktree before the coder starts
+    // (KJC-TSK-0630). null = auto-detect: `npm ci` when package-lock.json
+    // exists, nothing otherwise. Submodules are always initialized first.
+    worktree_setup: null,
     max_iteration_minutes: 30,
     max_total_minutes: 120,
     max_planner_minutes: 60,

package/src/hu/acceptance-runner.js

@@ -12,11 +12,15 @@ import { runCommand } from "../utils/process.js";
  * @param {number} [timeoutMs=30000] - Timeout per test
  * @returns {Promise<{cmd: string, passed: boolean, output: string, exitCode: number}>}
  */
-async function runSingleTest(cmd, cwd, timeoutMs = 30000) {
+async function runSingleTest(cmd, cwd, timeoutMs = 30000, env = null) {
   try {
     const result = await runCommand("bash", ["-c", cmd], {
       timeout: timeoutMs,
-      cwd
+      cwd,
+      // PAR-H (KJC-TSK-0631): lane env (KJ_LANE_SLOT / KJ_PORT_OFFSET) so
+      // tests that start services can offset their ports. execa merges
+      // this on top of process.env.
+      ...(env ? { env } : {})
     });
     const output = (result.stdout || "") + (result.stderr || "");
     return {
@@ -51,7 +55,7 @@ async function runSingleTest(cmd, cwd, timeoutMs = 30000) {
  * @param {string} cwd - Working directory
  * @returns {Promise<{allPassed: boolean, results: object[], summary: string, diagnostics: string|null, pending: number}>}
  */
-export async function runAcceptanceTests(tests, cwd) {
+export async function runAcceptanceTests(tests, cwd, { env = null } = {}) {
   if (!tests || tests.length === 0) {
     return { allPassed: false, results: [], summary: "No acceptance tests defined", diagnostics: null, pending: 0 };
   }
@@ -86,7 +90,7 @@ export async function runAcceptanceTests(tests, cwd) {
       });
       continue;
     }
-    const result = await runSingleTest(cmd, cwd);
+    const result = await runSingleTest(cmd, cwd, 30000, env);
     results.push({ ...result, type: "shell" });
   }
 

package/src/hu/worktree-bootstrap.js

@@ -0,0 +1,59 @@
+/**
+ * PAR-G (KJC-TSK-0630): make a freshly created lane worktree operative.
+ *
+ * `git worktree add` produces a clean checkout: no node_modules, no
+ * initialized submodules — and a container/bind-mounted process cannot
+ * init them itself because the worktree's real .git lives in the parent
+ * repo (gotcha reported by Jorge del Casar's worktree-docker-envs skill).
+ * Without this step, --parallel lanes die on the first `npm test` in any
+ * real project.
+ *
+ * Best-effort by contract: a failed or slow bootstrap warns and the lane
+ * continues — the acceptance tests deliver the real verdict.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { runCommand } from "../utils/process.js";
+
+const STEP_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * @param {object} params
+ * @param {string} params.worktreePath  Absolute path of the lane worktree.
+ * @param {string|null} [params.setupCommand]  session.worktree_setup — wins over auto-detect.
+ * @param {object|null} [params.logger]
+ * @param {number} [params.timeoutMs]
+ * @param {Function} [params.run]  Injectable runner (tests).
+ * @returns {Promise<{ok: boolean, steps: string[], warnings: string[]}>}
+ */
+export async function bootstrapWorktree({ worktreePath, setupCommand = null, logger = null, timeoutMs = STEP_TIMEOUT_MS, run = runCommand }) {
+  const warnings = [];
+  const steps = [];
+
+  if (existsSync(join(worktreePath, ".gitmodules"))) {
+    steps.push({ name: "submodules", cmd: "git", args: ["submodule", "update", "--init", "--recursive"] });
+  }
+
+  const explicit = typeof setupCommand === "string" && setupCommand.trim() ? setupCommand.trim() : null;
+  if (explicit) {
+    steps.push({ name: "setup", cmd: "sh", args: ["-c", explicit] });
+  } else if (existsSync(join(worktreePath, "package-lock.json"))) {
+    steps.push({ name: "deps", cmd: "npm", args: ["ci", "--no-audit", "--no-fund"] });
+  }
+
+  for (const step of steps) {
+    try {
+      const res = await run(step.cmd, step.args, { cwd: worktreePath, timeout: timeoutMs });
+      if (res.exitCode !== 0) {
+        warnings.push(`${step.name} failed (exit ${res.exitCode}): ${String(res.stderr || res.stdout || "").slice(0, 200)}`);
+      } else {
+        logger?.info?.(`worktree bootstrap: ${step.name} ok`);
+      }
+    } catch (err) {
+      warnings.push(`${step.name} threw: ${err.message}`);
+    }
+  }
+
+  for (const w of warnings) logger?.warn?.(`worktree bootstrap: ${w} — lane continues`);
+  return { ok: warnings.length === 0, steps: steps.map((s) => s.name), warnings };
+}

package/src/orchestrator/drivers/run-hu-batch.js

@@ -104,7 +104,13 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
       // left it clamped to hu_max_iterations for the rest of the run.
       const worktreePath = laneOpts?.worktreePath || null;
       const projectDir = worktreePath || ctx.config.projectDir || process.cwd();
-      const laneConfig = { ...ctx.config, projectDir, max_iterations: huMaxIterations };
+      // PAR-H (KJC-TSK-0631): the lane's slot travels as env vars so any
+      // service the coder or the acceptance tests start can offset its
+      // ports (offset = slot × 100; the project applies its own base).
+      const laneEnv = Number.isInteger(laneOpts?.laneSlot)
+        ? { KJ_LANE_SLOT: String(laneOpts.laneSlot), KJ_PORT_OFFSET: String(laneOpts.laneSlot * 100) }
+        : null;
+      const laneConfig = { ...ctx.config, projectDir, max_iterations: huMaxIterations, lane_env: laneEnv };
       if (!huPolicies.tdd) laneConfig.development = { ...laneConfig.development, methodology: "standard", require_test_changes: false };
       if (!huPolicies.sonar) laneConfig.sonarqube = { ...laneConfig.sonarqube, enabled: false };
       const laneFlags = { ...ctx.pipelineFlags };
@@ -233,7 +239,7 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
             detail: { huId: story.id, testCount: story.acceptance_tests.length }
           }));
 
-          const testResult = await runAcceptanceTests(story.acceptance_tests, projectDir);
+          const testResult = await runAcceptanceTests(story.acceptance_tests, projectDir, { env: laneEnv });
           emitProgress(emitter, makeEvent("hu:acceptance-end", { ...ctx.eventBase, stage: "acceptance" }, {
             status: testResult.allPassed ? "ok" : "fail",
             message: testResult.summary,

package/src/orchestrator/hu-sub-pipeline.js

@@ -6,7 +6,11 @@ import { topologicalSort } from "../hu/graph.js";
 import { updateStoryStatus, loadHuBatch, saveHuBatch, HU_STATUS } from "../hu/store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { refineHuWithContext } from "../hu/lazy-planner.js";
+import { join } from "node:path";
+import { acquireSlot, releaseSlot } from "karajan-core/slot-registry";
+import { getKarajanHome } from "karajan-core/paths";
 import { findParallelGroups, createWorktree, mergeWorktree, removeWorktree } from "../hu/parallel-executor.js";
+import { bootstrapWorktree } from "../hu/worktree-bootstrap.js";
 import { partitionConflictFree } from "./hu-scheduler.js";
 import { createParallelLimiter, planBudgetUsd } from "./parallel-limiter.js";
 
@@ -200,7 +204,7 @@ function buildHuOutcome({ story: _story, iterResult, status, startedAt, huBudget
  * @param {object} params
  * @returns {Promise<{huId: string, approved: boolean, result?: object, error?: string, blockedDependents?: string[]}>}
  */
-async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emitter, eventBase, logger, config, results, worktreePath, onStatusChange = null, onOutcome = null, budgetTracker = null }) {
+async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emitter, eventBase, logger, config, results, worktreePath, laneSlot = null, onStatusChange = null, onOutcome = null, budgetTracker = null }) {
   // PR1 (live HU status): every saveHuBatch should also notify the
   // plan JSON so the board reflects state in real time. Defined as a
   // local helper so we don't repeat the try/null-check boilerplate.
@@ -287,7 +291,7 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
   try {
     // PAR-E2 (KJC-TSK-0629): lanes handed a worktree must aim every git and
     // filesystem touchpoint at it — laneOpts carries that path to the runner.
-    const iterResult = await runIterationFn(huTask, story, { worktreePath: worktreePath || null });
+    const iterResult = await runIterationFn(huTask, story, { worktreePath: worktreePath || null, laneSlot });
     const approved = Boolean(iterResult?.approved);
 
     // --- Transition to reviewing (post-coder, pre-reviewer evaluation) ---
@@ -527,12 +531,27 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
       // Multiple HUs: create worktrees, run in parallel
       const projectDir = config?.projectDir || process.cwd();
       const worktrees = new Map();
+      // PAR-H (KJC-TSK-0631): every lane gets a stable numeric slot so
+      // services it starts can offset their ports (KJ_LANE_SLOT /
+      // KJ_PORT_OFFSET reach the coder and the acceptance tests).
+      const slotRegistryPath = join(getKarajanHome(), "worktree-slots.json");
+      const laneSlots = new Map();
 
       // Create worktrees for each HU in the batch
       for (const id of runnableIds) {
         try {
           const wtPath = await createWorktree(projectDir, id);
           worktrees.set(id, wtPath);
+          // PAR-G (KJC-TSK-0630): a fresh worktree has no node_modules and
+          // no initialized submodules — make the lane operative before the
+          // coder lands. Best-effort: warnings never block the lane.
+          await bootstrapWorktree({ worktreePath: wtPath, setupCommand: config?.session?.worktree_setup || null, logger });
+          try {
+            const { slot } = await acquireSlot({ registryPath: slotRegistryPath, id: `${projectDir}::${id}` });
+            laneSlots.set(id, slot);
+          } catch (err) {
+            logger.warn(`Failed to acquire lane slot for HU ${id}: ${err.message} — lane runs without port offset`);
+          }
         } catch (err) {
           logger.warn(`Failed to create worktree for HU ${id}: ${err.message} — will run sequentially`);
         }
@@ -547,6 +566,7 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
             storyId, batch, batchSessionId, runIterationFn,
             emitter, eventBase, logger, config, results,
             worktreePath: worktrees.get(storyId),
+            laneSlot: laneSlots.get(storyId) ?? null,
             onStatusChange, onOutcome, budgetTracker
           });
         } finally {
@@ -562,6 +582,7 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
         if (res.approved && worktrees.has(res.huId)) {
           try {
             await mergeWorktree(projectDir, res.huId);
+            await releaseSlot({ registryPath: slotRegistryPath, id: `${projectDir}::${res.huId}` }).catch(() => {});
           } catch (err) {
             logger.warn(`Failed to merge worktree for HU ${res.huId}: ${err.message}`);
           }
@@ -581,6 +602,7 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
           // Clean up failed worktree
           if (worktrees.has(res.huId)) {
             try { await removeWorktree(projectDir, res.huId); } catch { /* ignore */ }
+            await releaseSlot({ registryPath: slotRegistryPath, id: `${projectDir}::${res.huId}` }).catch(() => {});
           }
         }
       }

package/src/orchestrator/stages/coder-stage.js

@@ -71,6 +71,9 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
       // PAR-E2 (KJC-TSK-0629): the stage's config wins over the role's own —
       // worktree lanes pass a laneConfig whose projectDir is the worktree.
       projectDir: config?.projectDir || null,
+      // PAR-H (KJC-TSK-0631): lane env (KJ_LANE_SLOT / KJ_PORT_OFFSET)
+      // reaches the coder subprocess so services it starts don't collide.
+      env: config?.lane_env || null,
       onOutput: coderStall.onOutput,
       // Lets Brain Recovery persist a standby snapshot if the coder's
       // provider hits a quota cap mid-run (KJC hibernation wiring).

package/src/rag/embedder.js

@@ -1,81 +1,2 @@
-// KJC-PCS-0049 Step 2 — Ollama embedder adapter for the RAG pipeline.
-// Talks to a local Ollama server (POST /api/embeddings) and returns
-// Float32Array vectors. Cero deps externas; usa fetch global.
-//
-// Defaults:
-//   url       = process.env.KJ_OLLAMA_URL or "http://localhost:11434"
-//   model     = process.env.KJ_OLLAMA_EMBED_MODEL or "nomic-embed-text"
-//   dim       = 768  (matches nomic-embed-text)
-//   timeoutMs = 30000
-
-const DEFAULT_URL = "http://localhost:11434";
-const DEFAULT_MODEL = "nomic-embed-text";
-const DEFAULT_DIM = 768;
-const DEFAULT_TIMEOUT_MS = 30000;
-
-export class OllamaEmbedderError extends Error {
-  constructor(message, { cause, status } = {}) {
-    super(message);
-    this.name = "OllamaEmbedderError";
-    if (cause) this.cause = cause;
-    if (status != null) this.status = status;
-  }
-}
-
-export class OllamaEmbedder {
-  constructor({
-    url = process.env.KJ_OLLAMA_URL || DEFAULT_URL,
-    model = process.env.KJ_OLLAMA_EMBED_MODEL || DEFAULT_MODEL,
-    dim = DEFAULT_DIM,
-    timeoutMs = DEFAULT_TIMEOUT_MS,
-    fetchFn = globalThis.fetch,
-  } = {}) {
-    this.url = url.replace(/\/$/, "");
-    this.model = model;
-    this.dim = dim;
-    this.timeoutMs = timeoutMs;
-    this.fetch = fetchFn;
-  }
-
-  /** Single-text embedding. Returns Float32Array(dim). */
-  async embed(text) {
-    if (typeof text !== "string" || text.length === 0) {
-      throw new OllamaEmbedderError("embed: text must be a non-empty string");
-    }
-    const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
-    let res;
-    try {
-      res = await this.fetch(`${this.url}/api/embeddings`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ model: this.model, prompt: text }),
-        signal: ctrl.signal,
-      });
-    } catch (err) {
-      throw new OllamaEmbedderError(`Ollama embed request failed (${this.url}): ${err.message}`, { cause: err });
-    } finally {
-      clearTimeout(timer);
-    }
-    if (!res.ok) {
-      throw new OllamaEmbedderError(`Ollama embed HTTP ${res.status} from ${this.url}`, { status: res.status });
-    }
-    const body = await res.json();
-    const arr = body?.embedding;
-    if (!Array.isArray(arr) || arr.length === 0) {
-      throw new OllamaEmbedderError("Ollama response missing 'embedding' array");
-    }
-    if (arr.length !== this.dim) {
-      throw new OllamaEmbedderError(`Ollama dim mismatch: got ${arr.length}, expected ${this.dim} for model ${this.model}`);
-    }
-    return Float32Array.from(arr);
-  }
-
-  /** Batch embedding (sequential — Ollama /api/embeddings is single-text). */
-  async embedBatch(texts) {
-    if (!Array.isArray(texts)) throw new OllamaEmbedderError("embedBatch: texts must be an array");
-    const out = [];
-    for (const t of texts) out.push(await this.embed(t));
-    return out;
-  }
-}
+// Shim: embedder now lives in karajan-core/rag (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedder";

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

@@ -1,24 +1,2 @@
-// 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);
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/_cloud-base";

package/src/rag/embedders/cohere.js

@@ -1,28 +1,2 @@
-// 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; }
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/cohere";

package/src/rag/embedders/factory.js

@@ -1,29 +1,2 @@
-// 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 });
-}
-
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/factory";

package/src/rag/embedders/mistral.js

@@ -1,26 +1,2 @@
-// 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; }
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/mistral";

package/src/rag/embedders/onnx.js

@@ -1,63 +1,2 @@
-// 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;
-  }
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/onnx";

package/src/rag/embedders/openai.js

@@ -1,22 +1,2 @@
-// 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; }
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/openai";

package/src/rag/embedders/voyage.js

@@ -1,18 +1,2 @@
-// 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; }
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/voyage";

package/src/rag/rerank.js

@@ -1,74 +1,4 @@
-// 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);
-}
+// Shim: rerank now lives in karajan-core/rag so the hu-board workspace
+// can consume it without a relative dep on the CLI src tree.
+// KJC-TSK-0632 PR2.
+export { RerankError, _resetPipeline, rerank } from "karajan-core/rag/rerank";

package/src/rag/retriever.js

@@ -1,127 +1,2 @@
-// KJC-PCS-0049 Step 5 — Retriever for the RAG pipeline.
-import { searchSimilar, searchBM25, getEmbeddingsByIds } from "./vec-store.js";
-import { parseWhere, buildWhereSql } from "./where-parser.js";
-import { rerank } from "./rerank.js";
-
-const DEFAULT_KIND_BOOST = { plan: 0.05, onboarding: 0.03, code: 0 };
-
-// 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;
-}
-
-// KJC-TSK-0484 PR-B — Maximal Marginal Relevance. Given an ordered list of
-// candidates (best-first by `score`), pick `topK` that balance relevance
-// against intra-result diversity. `lambda=1` collapses to plain relevance;
-// `lambda=0` maximises diversity. Cosine sim between candidate embeddings
-// drives the redundancy penalty. Candidates without an embedding are kept
-// at the end (no penalty applies).
-function cosineSim(a, b) {
-  if (!a || !b || a.length !== b.length) return 0;
-  let dot = 0; let na = 0; let nb = 0;
-  for (let i = 0; i < a.length; i += 1) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
-  const denom = Math.sqrt(na) * Math.sqrt(nb);
-  return denom === 0 ? 0 : dot / denom;
-}
-
-export function mmrRerank(candidates, embeddings, { topK, lambda = 0.7 }) {
-  const remaining = candidates.slice();
-  const picked = [];
-  const relevance = (c) => 1 / (1 + Math.max(0, c.score ?? c.distance ?? 0));
-  while (picked.length < topK && remaining.length > 0) {
-    let bestIdx = 0; let bestVal = -Infinity;
-    for (let i = 0; i < remaining.length; i += 1) {
-      const c = remaining[i];
-      const rel = relevance(c);
-      let maxSim = 0;
-      const ce = embeddings.get(c.id);
-      if (ce && picked.length > 0) {
-        for (const p of picked) {
-          const pe = embeddings.get(p.id);
-          if (pe) maxSim = Math.max(maxSim, cosineSim(ce, pe));
-        }
-      }
-      const score = lambda * rel - (1 - lambda) * maxSim;
-      if (score > bestVal) { bestVal = score; bestIdx = i; }
-    }
-    picked.push(remaining.splice(bestIdx, 1)[0]);
-  }
-  return picked;
-}
-
-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, diversify = false, mmrLambda = 0.7 } = {}) {
-  if (!text || typeof text !== "string") throw new Error("query: text must be a non-empty string");
-  const fetchK = Math.min(50, topK * 2);
-  const scopeKind = scope === "plans" ? "plan" : scope === "code" ? "code" : scope === "onboarding" ? "onboarding" : null;
-  // 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 [];
-  const boostSources = shouldBoostSources(text);
-  const scored = 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);
-  // KJC-TSK-0484 PR-B — MMR diversification over topK*2 candidates. Fetches
-  // embeddings only when requested; cosine between candidate vectors drives
-  // the redundancy penalty so near-duplicates that survived dedup (e.g. a
-  // boilerplate chunk repeated under slightly different wording) get pushed
-  // down. Skipped entirely when `diversify=false` (default).
-  let reranked;
-  if (diversify) {
-    const pool = scored.slice(0, Math.min(scored.length, topK * 2));
-    const embeddings = getEmbeddingsByIds(db, pool.map((c) => c.id));
-    reranked = mmrRerank(pool, embeddings, { topK, lambda: mmrLambda });
-  } else {
-    reranked = scored.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;
-}
-
-export { fuseHits, cosineSim };
+// Shim: retriever now lives in karajan-core/rag (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/retriever";

package/src/rag/where-parser.js

@@ -1,54 +1,4 @@
-// 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 };
-}
+// Shim: where-parser now lives in karajan-core/rag so the hu-board
+// workspace can consume it without a relative dep on the CLI src tree.
+// KJC-TSK-0632 PR2.
+export { parseWhere, buildWhereSql } from "karajan-core/rag/where-parser";

package/src/roles/agent-role.js

@@ -129,6 +129,10 @@ export class AgentRole extends BaseRole {
 
     const runArgs = { prompt, role: this.name };
     if (onOutput) runArgs.onOutput = onOutput;
+    // PAR-H (KJC-TSK-0631): per-call env additions for the agent
+    // subprocess (lane slot vars). Agents that ignore task.env simply
+    // run without them.
+    if (extracted.env) runArgs.env = extracted.env;
     // Φ1-D (KJC-PCS-0057): roles that build their prompt as a
     // stable/volatile layout forward both buckets so cache-aware agents
     // (ClaudeAgent) can ship the stable block as system prompt. Agents

package/src/roles/coder-role.js

@@ -56,6 +56,8 @@ export class CoderRole extends AgentRole {
       // PAR-E2 (KJC-TSK-0629): per-call project root. Worktree lanes pass
       // their lane dir here; the shared role instance keeps its own config.
       projectDir: input?.projectDir || null,
+      // PAR-H (KJC-TSK-0631): per-call subprocess env (lane slot vars).
+      env: input?.env || null,
       onOutput: input?.onOutput || null
     };
   }