karajan-code 4.70.4 → 5.0.1

package/src/prompts/card-context.js

@@ -12,7 +12,7 @@
  * and says so: the coder learns the card exists and where to ask for it,
  * instead of receiving a silently empty context.
  */
-import { getHu } from "../hu/store.js";
+import { findBoardHu } from "../hu/board-lookup.js";
 
 /** Ids minted by the HU Board; anything else belongs to an external board. */
 const LOCAL_HU = /^HU-/i;
@@ -25,9 +25,14 @@ const externalSection = (ref) =>
     "Treat the task below as the card's statement, and if something the card should answer is missing, ASK instead of guessing.",
   ].join("\n");
 
+// KJC-BUG-0454: a board card keeps its criteria as a list; older HUs as one string.
+const criteriaOf = (hu) => (Array.isArray(hu.acceptance_criteria) ? hu.acceptance_criteria.join("\n") : hu.acceptanceCriteria ?? "").trim();
+const idOf = (hu) => hu.short_id || hu.id;
+
 const localSection = (hu) => {
-  const lines = [`## Card ${hu.id} — ${hu.title}`, ""];
+  const lines = [`## Card ${idOf(hu)} — ${hu.title}`, ""];
   if (hu.description?.trim()) lines.push(hu.description.trim(), "");
+  if (hu.scope?.trim()) lines.push(`Scope: ${hu.scope.trim()}`, "");
   lines.push(`Status on the board: ${hu.status}. The card is the contract: done means its statement is literally true.`);
   return lines.join("\n");
 };
@@ -45,10 +50,10 @@ export async function resolveCardContext({ projectDir, ref, deps = {} }) {
   }
   // A missing local HU is an error, never an empty context: the caller asked
   // for a card by id and kj either delivers it or says it does not exist.
-  const hu = await (deps.getHu || getHu)(projectDir, id);
-  const criteria = hu.acceptanceCriteria?.trim();
+  const hu = await (deps.getHu || findBoardHu)(projectDir, id);
+  const criteria = criteriaOf(hu);
   return {
-    huId: hu.id,
+    huId: idOf(hu),
     title: hu.title,
     section: localSection(hu),
     acceptanceTests: criteria ? [{ type: "gherkin", content: criteria }] : null,

package/src/prompts/reviewer.js

@@ -35,7 +35,7 @@ const SERENA_INSTRUCTIONS = [
  * on it; the per-review content (task context + git diff, up to 12 KB
  * and always different) goes last.
  */
-export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
+export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null, roleSkillBlock = null }) {
   const { body: clippedDiff, note: clipNote } = clipDiff(diff);
   // KJC-BUG-0138: full diff on purpose — the moved-to side survives clipping.
   const splitSignal = buildSplitSignal(diff);
@@ -44,7 +44,10 @@ export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode,
   const rtkSnippet = buildRtkInstructions({ rtkAvailable });
   // KJC-TSK-1065: the reviewer gets the skills of its role and of the task, up to 3.
   let skillSection = null;
-  if (projectDir) {
+  // KJC-TSK-1272: a block the caller resolved (a third-party repo's stack) wins over the project's.
+  if (roleSkillBlock) {
+    skillSection = buildRoleSkillSection(roleSkillBlock, { provider }) || null;
+  } else if (projectDir) {
     skillSection = buildRoleSkillSection(await roleSkills({ role: "reviewer", task, projectDir }), { provider }) || null;
   }
 

package/src/rag/auto-update.js

@@ -9,7 +9,8 @@ import { execa } from "execa";
 import { projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
 import { indexProject, indexProjectDelta } from "./indexer.js";
 import { readRefreshedPaths, untrackedFiles, writeRefreshedPaths } from "./worktree-files.js";
-import { startBootstrap } from "./bootstrap-index.js";
+import { startBootstrap, stopBootstrap } from "./bootstrap-index.js";
+import { indexLeasePath, stopLeaseHolder } from "./pid-lease.js";
 import { ragExclude } from "./indexable.js";
 import { makeGovernedEmbedder } from "./governed-embedder.js";
 import { openProjectStore } from "./project-store.js";
@@ -31,6 +32,70 @@ const countSources = (db, slug, projectDir) => {
 export const DEFAULT_MAX_DRIFT_FILES = 25;
 const HOOK_SRC = resolve(fileURLToPath(import.meta.url), "../../../scripts/git-hooks/post-merge");
 
+// KJC-TSK-1174 (RAG-A2): no index yet. It is built in the background, once; the session
+// does not wait. A recent attempt that died (no Ollama) is not retried blindly.
+async function bootstrapInBackground({ projectDir, slug, head, logger }) {
+  // HU-2758: an indexer past MAX_RUN_MS is stopped first: this project's, then whichever holds the machine lease
+  // (an orphan of an older build that no marker names). A failure here never keeps the bootstrap from happening.
+  for (const stopped of [await stopBootstrap(projectDir).catch(() => null), await stopLeaseHolder(indexLeasePath()).catch(() => null)]) {
+    if (!stopped) continue;
+    logger.info?.(`[rag] stopped the background index of ${stopped.slug ?? slug} (pid ${stopped.pid}): it ran past 60 min`);
+    // The stop never reached the marker (busy mutex): nothing on file says it was stopped, so it may start again.
+    if (stopped.marked === false) warnOnce(logger, `bootstrap-unmarked:${projectDir}`, `[rag] the stop of the background index of ${stopped.slug ?? slug} (pid ${stopped.pid}) could not be noted: it may be started again on the next command; run kj rag index --with-sources by hand`);
+  }
+  const boot = startBootstrap(projectDir);
+  if (boot.stopped) {
+    const why = boot.stopped === "deadline" ? "reached its deadline and left a partial index" : "ran past 60 min and was stopped";
+    warnOnce(logger, `bootstrap-stopped:${projectDir}`, `[rag] the background index of ${slug} ${why}: run kj rag index --with-sources by hand`);
+    return { skipped: true, reason: "bootstrap-failed", head };
+  }
+  if (boot.busy) {
+    warnOnce(logger, `bootstrap-busy:${projectDir}`, `[rag] ${slug} has no index yet: another background index is running (${boot.busy.slug ?? "?"}, pid ${boot.busy.pid ?? "?"}); it is tried again on the next command`);
+    return { skipped: true, reason: "bootstrap-queued", holder: boot.busy, head };
+  }
+  if (boot.recent) {
+    warnOnce(logger, `bootstrap:${projectDir}`, `[rag] ${slug} has no index and the background indexing did not finish: run kj rag index --with-sources`);
+    return { skipped: true, reason: "bootstrap-failed", head };
+  }
+  warnOnce(logger, `bootstrap:${projectDir}`, `[rag] ${slug} has no index yet: indexing it in the background (pid ${boot.pid}); queries answer from it once it is done`);
+  return { skipped: true, reason: "bootstrapping", pid: boot.pid, head };
+}
+
+// KJC-TSK-1171 (RAG-B): an index built before the embedded header holds vectors a
+// query by file or symbol name cannot reach. Small, it is rebuilt here; large, the
+// query answers from it and says once how to rebuild.
+async function rebuildOldSchema({ db, slug, projectDir, config, logger, head, maxFiles }, schema) {
+  const sources = countSources(db, slug, projectDir);
+  if (sources > maxFiles) {
+    warnOnce(logger, projectDir, `[rag] the index of ${slug} predates the embedded header (schema ${schema} < ${EMBED_SCHEMA}): answering from it as it is; rebuild it with kj rag index --with-sources`);
+    return { skipped: true, reason: "embed-schema-old", sources, head };
+  }
+  logger.info?.(`[rag] the index of ${slug} predates the embedded header (schema ${schema} < ${EMBED_SCHEMA}); rebuilding ${sources} source(s)`);
+  const totals = await indexProject(projectDir, { db, embedder: makeGovernedEmbedder(config), karajanHome: getKarajanHome(), logger, withSources: true, exclude: ragExclude(config) });
+  if (totals.head) setLastIndexedCommit(db, slug, totals.head);
+  return { ran: true, rebuilt: true, totals };
+}
+
+// KJC-TSK-1174 (RAG-A1): the drift is measured up to the files on disk, untracked ones
+// included, so a query sees what the session is writing before it is committed.
+// The dirty paths of the last refresh count too: reverted or deleted since, they hold stale chunks.
+async function deltaUpdate({ db, slug, projectDir, config, logger, head, maxFiles }, since) {
+  const { stdout } = await execa("git", ["-C", projectDir, "diff", "--name-only", "-z", since]);
+  const dirty = [...stdout.split("\0").filter(Boolean), ...(await untrackedFiles(projectDir))];
+  const reconcile = readRefreshedPaths(projectDir).filter((p) => !dirty.includes(p));
+  const changed = dirty.length + reconcile.length;
+  if (changed === 0) return { skipped: true, head };
+  if (changed > maxFiles) {
+    logger.warn?.(`[rag] ${changed} file(s) changed since the last index (more than ${maxFiles}): answering from the index as it is; bring it up to date with kj rag index --since auto`);
+    return { skipped: true, reason: "drift-too-large", changed, head };
+  }
+  logger.info?.(`[rag] drift detected (${since.slice(0, 7)} → ${head.slice(0, 7)}, ${changed} file(s)); running delta update`);
+  const totals = await indexProjectDelta(projectDir, { db, embedder: makeGovernedEmbedder(config), since, logger, exclude: ragExclude(config), worktree: true, reconcile });
+  if (totals.head) setLastIndexedCommit(db, slug, totals.head);
+  writeRefreshedPaths(projectDir, dirty);
+  return { ran: true, totals };
+}
+
 export async function maybeAutoUpdate({ projectDir, config, logger = console, flags = {} } = {}) {
   // commander turns `--no-rag-update` into flags.ragUpdate === false.
   if (flags?.ragUpdate === false || config?.rag?.autoUpdate?.onRun === false) return { skipped: true };
@@ -42,53 +107,15 @@ export async function maybeAutoUpdate({ projectDir, config, logger = console, fl
   const db = openProjectStore({ projectDir, dim: config?.rag?.embedder?.dim || 768 });
   try {
     const since = getLastIndexedCommit(db, slug);
-    if (!since) {
-      // KJC-TSK-1174 (RAG-A2): no index yet. It is built in the background, once; the session
-      // does not wait. A recent attempt that died (no Ollama) is not retried blindly.
-      const boot = startBootstrap(projectDir);
-      if (boot.recent) {
-        warnOnce(logger, `bootstrap:${projectDir}`, `[rag] ${slug} has no index and the background indexing did not finish: run kj rag index --with-sources`);
-        return { skipped: true, reason: "bootstrap-failed", head };
-      }
-      warnOnce(logger, `bootstrap:${projectDir}`, `[rag] ${slug} has no index yet: indexing it in the background (pid ${boot.pid}); queries answer from it once it is done`);
-      return { skipped: true, reason: "bootstrapping", pid: boot.pid, head };
-    }
+    if (!since) return await bootstrapInBackground({ projectDir, slug, head, logger });
     // KJC-BUG-0304: a drift of hundreds of files (an index weeks old) reindexed the
     // repo for half an hour before the query answered. Past the bound the query
     // answers from the index as it is, and says how to bring it up to date.
-    const maxFiles = config?.rag?.autoUpdate?.maxFiles ?? DEFAULT_MAX_DRIFT_FILES;
-    // KJC-TSK-1171 (RAG-B): an index built before the embedded header holds vectors a
-    // query by file or symbol name cannot reach. Small, it is rebuilt here; large, the
-    // query answers from it and says once how to rebuild.
+    const ctx = { db, slug, projectDir, config, logger, head, maxFiles: config?.rag?.autoUpdate?.maxFiles ?? DEFAULT_MAX_DRIFT_FILES };
     const schema = readEmbedSchema(projectDir);
-    if (schema < EMBED_SCHEMA) {
-      const sources = countSources(db, slug, projectDir);
-      if (sources > maxFiles) {
-        warnOnce(logger, projectDir, `[rag] the index of ${slug} predates the embedded header (schema ${schema} < ${EMBED_SCHEMA}): answering from it as it is; rebuild it with kj rag index --with-sources`);
-        return { skipped: true, reason: "embed-schema-old", sources, head };
-      }
-      logger.info?.(`[rag] the index of ${slug} predates the embedded header (schema ${schema} < ${EMBED_SCHEMA}); rebuilding ${sources} source(s)`);
-      const totals = await indexProject(projectDir, { db, embedder: makeGovernedEmbedder(config), karajanHome: getKarajanHome(), logger, withSources: true, exclude: ragExclude(config) });
-      if (totals.head) setLastIndexedCommit(db, slug, totals.head);
-      return { ran: true, rebuilt: true, totals };
-    }
-    // KJC-TSK-1174 (RAG-A1): the drift is measured up to the files on disk, untracked ones
-    // included, so a query sees what the session is writing before it is committed.
-    // The dirty paths of the last refresh count too: reverted or deleted since, they hold stale chunks.
-    const { stdout } = await execa("git", ["-C", projectDir, "diff", "--name-only", "-z", since]);
-    const dirty = [...stdout.split("\0").filter(Boolean), ...(await untrackedFiles(projectDir))];
-    const reconcile = readRefreshedPaths(projectDir).filter((p) => !dirty.includes(p));
-    const changed = dirty.length + reconcile.length;
-    if (changed === 0) return { skipped: true, head };
-    if (changed > maxFiles) {
-      logger.warn?.(`[rag] ${changed} file(s) changed since the last index (more than ${maxFiles}): answering from the index as it is; bring it up to date with kj rag index --since auto`);
-      return { skipped: true, reason: "drift-too-large", changed, head };
-    }
-    logger.info?.(`[rag] drift detected (${since.slice(0, 7)} → ${head.slice(0, 7)}, ${changed} file(s)); running delta update`);
-    const totals = await indexProjectDelta(projectDir, { db, embedder: makeGovernedEmbedder(config), since, logger, exclude: ragExclude(config), worktree: true, reconcile });
-    if (totals.head) setLastIndexedCommit(db, slug, totals.head);
-    writeRefreshedPaths(projectDir, dirty);
-    return { ran: true, totals };
+    // Awaited here, inside the try: the catch must see their errors and the finally must not close the store under them.
+    if (schema < EMBED_SCHEMA) return await rebuildOldSchema(ctx, schema);
+    return await deltaUpdate(ctx, since);
   } catch (err) {
     // Said once per process: an embedder that is down would repeat it on every query otherwise.
     warnOnce(logger, `failed:${projectDir}`, `[rag] auto-update failed (${err.message}); continuing without refresh`);

package/src/rag/bootstrap-index.js

@@ -1,52 +1,30 @@
 // KJC-TSK-1174 (RAG-A2): a project with no index gets one in the background, once, at the first
 // command that needs it. The session goes on; queries answer from the index when it is done.
 import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, renameSync, rmdirSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, rmdirSync, unlinkSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { projectDbPath } from "./project-store.js";
+import { projectSlug } from "./vec-store.js";
+import { GRACE_MS, MAX_RUN_MS, indexLeasePath, noteStopped, readLease, stopLeaseHolder, takeLock, unlessGone, withMutex, writeLease } from "./pid-lease.js";
 
 const KJ_BIN = resolve(fileURLToPath(import.meta.url), "../../../bin/kj.js");
 // An attempt that died (no Ollama, no model) is not repeated on every command: this long apart.
 export const RETRY_MS = 10 * 60 * 1000;
-// A marker that does not parse, or a lock, older than this was left by a crashed command: taken over.
-export const GRACE_MS = 30 * 1000;
-// An indexer is not trusted to run longer than this: past it, its pid may belong to someone else.
-export const MAX_RUN_MS = 60 * 60 * 1000;
+export { GRACE_MS, MAX_RUN_MS };
+// HU-3092: the child stops itself this long before MAX_RUN_MS, so it ends before the lease reads as expired.
+export const DEADLINE_MARGIN_MS = 60 * 1000;
 const markerPath = (projectDir) => `${projectDbPath(projectDir)}.bootstrap`;
 
-const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
-
 /** What the marker says of the last attempt: `{ pid, at, running }`, or null when none was ever made. */
-const unlessGone = (fn) => {
-  try { return fn(); }
-  catch (err) {
-    if (err.code === "ENOENT") { return null; }
-    throw err;
-  }
-};
-
-export function readBootstrap(projectDir, { now = Date.now() } = {}) {
-  const file = markerPath(projectDir);
-  // Read first, never check-then-read: another command may set the marker aside in between.
-  const raw = unlessGone(() => readFileSync(file, "utf8"));
-  if (raw === null) return null;
-  try {
-    const note = JSON.parse(raw);
-    return { ...note, running: alive(note.pid) && now - note.at < MAX_RUN_MS };
-  } catch {
-    // Another command is writing it this very moment: running for a moment; past the grace, a crash.
-    const stat = unlessGone(() => statSync(file));
-    return stat === null ? null : { pid: null, at: 0, running: now - stat.mtimeMs < GRACE_MS };
-  }
-}
+export const readBootstrap = (projectDir, o) => readLease(markerPath(projectDir), o);
 
 /**
  * Starts `kj rag index --with-sources` detached, or reuses the one running. Returns
  * `{ started, pid }`, or `{ started: false, recent: true }` when the last attempt died less
  * than RETRY_MS ago: the index is then asked for by hand instead of being retried blindly.
  */
-export function startBootstrap(projectDir, { spawnFn = spawn, bin = KJ_BIN, now = Date.now() } = {}) {
+export function startBootstrap(projectDir, { spawnFn = spawn, bin = KJ_BIN, now = Date.now(), lease = indexLeasePath() } = {}) {
   const file = markerPath(projectDir);
   mkdirSync(dirname(file), { recursive: true });
   // One claimant at a time: the lock directory is created atomically, so of two commands arriving
@@ -57,30 +35,44 @@ export function startBootstrap(projectDir, { spawnFn = spawn, bin = KJ_BIN, now
   try {
     const last = readBootstrap(projectDir, { now });
     if (last?.running) return { started: false, pid: last.pid };
-    if (last && now - last.at < RETRY_MS) return { started: false, recent: true, pid: null };
-    // The marker lands whole each time (written apart, then renamed): first with the claimant's
-    // pid, so it reads as running meanwhile, then with the indexer's.
-    const note = (pid) => { const tmp = `${file}.${process.pid}.tmp`; writeFileSync(tmp, JSON.stringify({ pid, at: now }), "utf8"); renameSync(tmp, file); };
-    note(process.pid);
-    const child = spawnFn(process.execPath, [bin, "rag", "index", "--with-sources"], { cwd: projectDir, detached: true, stdio: "ignore" });
-    child.unref?.();
-    note(child.pid);
-    return { started: true, pid: child.pid };
+    // HU-2758: one stopped for running too long is not respawned in the background, at any age.
+    // HU-3092: so is one that stopped itself at its deadline.
+    if (last?.stoppedBy === "max-run" || last?.stoppedBy === "deadline") return { started: false, recent: true, stopped: last.stoppedBy };
+    if (last && now - (last.stoppedAt ?? last.at) < RETRY_MS) return { started: false, recent: true, pid: null };
+    // One indexer per machine: the lease is taken inside the project mutex, before the marker is
+    // written, so a queued project does not spend its RETRY_MS. Both mutexes yield, never wait.
+    const slug = projectSlug(projectDir);
+    const res = withMutex(lease, now, () => {
+      const holder = readLease(lease, { now });
+      if (holder?.running && holder.pid !== process.pid) return { started: false, busy: { projectDir: holder.projectDir, slug: holder.slug, pid: holder.pid } };
+      // Marker and lease land whole each time: first with the claimant's pid, so they read as
+      // running meanwhile, then with the indexer's.
+      const command = [process.execPath, bin, "rag", "index", "--with-sources"].join(" ");
+      const note = (pid) => { writeLease(file, { pid, at: now, command }); writeLease(lease, { pid, at: now, command, projectDir, slug }); };
+      note(process.pid);
+      try {
+        const child = spawnFn(process.execPath, [bin, "rag", "index", "--with-sources"], { cwd: projectDir, detached: true, stdio: "ignore", env: { ...process.env, KJ_RAG_DEADLINE: String(now + MAX_RUN_MS - DEADLINE_MARGIN_MS) } });
+        child.unref?.();
+        note(child.pid);
+        return { started: true, pid: child.pid };
+      } catch (err) {
+        // No indexer exists: neither the marker nor the lease may keep naming this (maybe long-lived) process.
+        unlessGone(() => unlinkSync(file)); unlessGone(() => unlinkSync(lease));
+        throw err;
+      }
+    });
+    return res.busy === true ? { started: false, busy: {} } : res;
   } finally { unlessGone(() => rmdirSync(lock)); }
 }
 
-const takeLock = (lock, now) => {
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try { mkdirSync(lock); return true; }
-    catch (err) {
-      if (err.code !== "EEXIST") throw err;
-      const held = unlessGone(() => statSync(lock));
-      if (held && now - held.mtimeMs < GRACE_MS) return false;
-      // The holder crashed. The lock is set aside under a unique name first: only the one caller
-      // whose rename succeeds removes it, so nobody removes a lock another caller has just taken.
-      const aside = `${lock}.${process.pid}.${now}.stale`;
-      if (unlessGone(() => renameSync(lock, aside)) !== null) rmdirSync(aside);
-    }
-  }
-  return false;
-};
+/** HU-3092: the indexer that reached its deadline notes it, only while the marker still names it. */
+export const noteDeadline = (projectDir, { pid = process.pid, now = Date.now(), wait } = {}) => noteStopped(markerPath(projectDir), pid, now, "deadline", wait);
+
+// HU-2758: stops the marker's indexer past MAX_RUN_MS (`force`: any age) and frees the lease naming it.
+export async function stopBootstrap(projectDir, { lease = indexLeasePath(), now = Date.now(), ...opts } = {}) {
+  const stopped = await stopLeaseHolder(markerPath(projectDir), { ...opts, now });
+  // `marked: false` (the stop never reached the marker): the lease is kept, naming a dead pid, which readLease
+  // already reads as free. The caller warns; nothing here pretends the stop is on file.
+  if (stopped?.marked) withMutex(lease, now, () => { if (readLease(lease, { now })?.pid === stopped.pid) unlessGone(() => unlinkSync(lease)); });
+  return stopped;
+}

package/src/rag/indexer.js

@@ -139,7 +139,7 @@ async function listFiles(dir, predicate) {
  * indexing tens of thousands of files is expensive — the CLI exposes
  * it as `--with-sources`.
  */
-export async function indexProject(projectDir, { db, embedder, karajanHome, logger = console, withSources = false, exclude = [] } = {}) {
+export async function indexProject(projectDir, { db, embedder, karajanHome, logger = console, withSources = false, exclude = [], deadline = null, now = Date.now } = {}) {
   // KJC-TSK-0640: a full index must stamp HEAD too — without it,
   // last_indexed_commit stayed null after the FIRST index, so the drift
   // delta-update (maybeAutoUpdate) never engaged until a manual --since.
@@ -150,20 +150,23 @@ export async function indexProject(projectDir, { db, embedder, karajanHome, logg
   } catch { /* not a git repo (or zero commits) — nothing to stamp */ }
   const slug = projectDir.split("/").pop()?.replace(/[^a-zA-Z0-9._-]/g, "-").toLowerCase() || "project";
   await prepareAdapters(detectAdaptersForProject(projectDir), { logger });
+  // HU-3092: past the deadline (a background indexer's) the walk stops between files; what it indexed stays.
+  const stop = () => { if (deadline != null && now() >= deadline) totals.stopped = "deadline"; return Boolean(totals.stopped); };
   const planRoot = join(karajanHome, PLANS_DIR, slug);
   if (existsSync(planRoot)) {
     const plans = await listFiles(planRoot, (p) => /plan-.*\.json$/.test(p));
     for (const p of plans) {
+      if (stop()) break;
       const r = await indexFile(p, { db, embedder, logger, project: slug, root: projectDir });
       totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
     }
   }
   const onboarding = join(karajanHome, ONBOARDING_DIR, `${slug}.md`);
-  if (existsSync(onboarding)) {
+  if (existsSync(onboarding) && !stop()) {
     const r = await indexFile(onboarding, { db, embedder, logger, project: slug, root: projectDir });
     totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
   }
-  if (withSources) {
+  if (withSources && !totals.stopped) {
     // 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
@@ -182,12 +185,14 @@ export async function indexProject(projectDir, { db, embedder, karajanHome, logg
       if (source.startsWith(prefix) && outOf(source) !== null) deleteChunksBySource(db, source);
     }
     for (const s of sources) {
+      if (stop()) break;
       const r = await indexFile(s, { db, embedder, logger, project: slug, kind: sourceKind(), root: projectDir });
       totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
     }
     // KJC-TSK-1171: only a COMPLETE index of the sources carries the embed schema; a file the
     // embedder failed on leaves the marker as it was, so the rebuild is asked for again.
-    if (totals.failed === 0) writeEmbedSchema(projectDir);
+    if (totals.stopped) logger.info?.("[rag-indexer] deadline reached: the index is partial, no embed schema recorded");
+    else if (totals.failed === 0) writeEmbedSchema(projectDir);
     else logger.warn?.(`[rag-indexer] ${totals.failed} chunk(s) failed: the embed schema is not recorded, the index will be rebuilt again`);
   }
   return totals;

package/src/rag/migrate.js

@@ -10,7 +10,7 @@ import { existsSync } from "node:fs";
 import { sep } from "node:path";
 
 import { insertChunk, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
-import { openVecStoreExplained as openVecStore } from "./project-store.js";
+import { openVecStore } from "./vec-store.js";
 
 export const countProjectChunks = (db, slug) => db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE project_slug = ?").get(slug).n;
 

package/src/rag/onnx-fallback.js

@@ -9,7 +9,7 @@
 import fs from "node:fs/promises";
 import { existsSync, rmSync } from "node:fs";
 import path from "node:path";
-import Database from "better-sqlite3";
+import { openDatabase } from "karajan-core/db";
 import { parseDocument } from "yaml";
 import { getProjectConfigPath } from "../config/loader.js";
 import { projectDbPath } from "./project-store.js";
@@ -31,7 +31,7 @@ export function resetEmptyStore(projectDir = process.cwd()) {
   if (!existsSync(storePath)) return true;
   // Read-only, schema-agnostic inspection: no DDL, no vec extension, no
   // dimension assumptions — the store is only ever OPENED to be counted.
-  const db = new Database(storePath, { readonly: true });
+  const db = openDatabase(storePath, { readOnly: true });
   try {
     const hasChunksTable = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='chunks'").get();
     if (hasChunksTable && db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n > 0) return false;

package/src/rag/pid-lease.js

@@ -0,0 +1,181 @@
+// HU-2757: a lease names the pid that holds a resource and when it took it. The background indexers
+// never release it (HU-2907: a foreground `kj rag index` releases its own): a dead pid, or an age
+// of MAX_RUN_MS, means free. A mkdir mutex makes the decision atomic.
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getKarajanHome } from "../utils/paths.js";
+
+// A lease that does not parse, or a lock, older than this was left by a crashed command: taken over.
+export const GRACE_MS = 30 * 1000;
+// An indexer is not trusted to run longer than this: past it, its pid may belong to someone else.
+export const MAX_RUN_MS = 60 * 60 * 1000;
+
+export const indexLeasePath = () => join(getKarajanHome(), "locks", "rag-index.json");
+
+// EPERM (a pid of another user) counts as dead: a single-user machine has no such indexer.
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+
+export const unlessGone = (fn) => {
+  try { return fn(); }
+  catch (err) {
+    if (err.code === "ENOENT") { return null; }
+    throw err;
+  }
+};
+
+/** What the lease says: `{ pid, at, running, ... }`, or null when none was ever written. */
+export function readLease(file, { now = Date.now() } = {}) {
+  // Read first, never check-then-read: another command may set the file aside in between.
+  const raw = unlessGone(() => readFileSync(file, "utf8"));
+  if (raw === null) return null;
+  try {
+    const note = JSON.parse(raw);
+    return { ...note, running: !note.stoppedAt && alive(note.pid) && now - note.at < MAX_RUN_MS };
+  } catch {
+    // Another command is writing it this very moment: running for a moment; past the grace, a crash.
+    const stat = unlessGone(() => statSync(file));
+    return stat === null ? null : { pid: null, at: 0, running: now - stat.mtimeMs < GRACE_MS };
+  }
+}
+
+/** The lease lands whole: written apart, then renamed. */
+export function writeLease(file, record) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(record), "utf8");
+  renameSync(tmp, file);
+}
+
+export const takeLock = (lock, now) => {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try { mkdirSync(lock); return true; }
+    catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      const held = unlessGone(() => statSync(lock));
+      if (held && now - held.mtimeMs < GRACE_MS) return false;
+      // The holder crashed. The lock is set aside under a unique name first: only the one caller
+      // whose rename succeeds removes it, so nobody removes a lock another caller has just taken.
+      const aside = `${lock}.${process.pid}.${now}.stale`;
+      if (unlessGone(() => renameSync(lock, aside)) !== null) rmdirSync(aside);
+    }
+  }
+  return false;
+};
+
+/** Runs `fn` under the mutex `${file}.lock`, or returns `{ busy: true }` when another command holds it. */
+export function withMutex(file, now, fn) {
+  const lock = `${file}.lock`;
+  mkdirSync(dirname(lock), { recursive: true });
+  if (!takeLock(lock, now)) return { busy: true };
+  try { return fn(); } finally { unlessGone(() => rmdirSync(lock)); }
+}
+
+// HU-2758: an indexer past MAX_RUN_MS is stopped from outside, once ps confirms the pid still runs it.
+export const KILL_AFTER_MS = 3000;
+const POLL_MS = 100;
+const START_SLACK_MS = 60 * 1000;
+// By absolute path: a ps found through PATH could be forged (as in harden/human-act.js).
+const PS_BIN = ["/bin/ps", "/usr/bin/ps"].find((p) => existsSync(p)) ?? null;
+
+export function parsePs(out) {
+  const text = String(out ?? "").trim();
+  const split = text.search(/\s/);
+  const m = /^(?:(?:(\d+)-)?(\d+):)?(\d+):(\d+)$/.exec(text.slice(0, split < 0 ? 0 : split));
+  const command = text.slice(split).trim();
+  if (!m || split < 0 || !command) return null;
+  const [d, h, min, s] = [m[1], m[2], m[3], m[4]].map((n) => Number(n ?? 0));
+  return { elapsedMs: (((d * 24 + h) * 60 + min) * 60 + s) * 1000, command };
+}
+
+const psInfo = (pid) => {
+  if (!PS_BIN) return null;
+  try { return parsePs(execFileSync(PS_BIN, ["-o", "etime=", "-o", "command=", "-p", String(pid)], { encoding: "utf8", env: {}, timeout: 2000 })); }
+  catch { return null; }
+};
+// ps flattens argv, so the identity is the exact command recorded at spawn; none recorded (older format): not ours.
+const isIndexer = (info, at, now, command) => Boolean(info && command) && info.command === command && info.elapsedMs >= Math.max(0, now - at - START_SLACK_MS);
+const isAliveVia = (kill, pid) => { try { kill(pid, 0); return true; } catch { return false; } };
+const signal = (kill, pid, sig) => {
+  try { kill(-pid, sig); } catch { try { kill(pid, sig); } catch (err) { if (err.code !== "ESRCH") throw err; } }
+};
+
+/** SIGTERM to a verified indexer, SIGKILL if it outlives `killAfterMs`. True only once it is confirmed gone. */
+export async function stopIndexer(pid, at, { command, now = Date.now(), ps = psInfo, kill = (p, s) => process.kill(p, s), sleep = (ms) => new Promise((r) => setTimeout(r, ms)), killAfterMs = KILL_AFTER_MS } = {}) {
+  if (!isIndexer(ps(pid), at, now, command)) return false;
+  signal(kill, pid, "SIGTERM");
+  for (let waited = 0; waited < killAfterMs; waited += POLL_MS) {
+    await sleep(POLL_MS);
+    if (!isAliveVia(kill, pid)) return true;
+  }
+  const again = ps(pid); // verified again: no answer is gone-or-unverified, never signalled blind
+  if (!again) return !isAliveVia(kill, pid);
+  if (!isIndexer(again, at, now, command)) return true; // the pid was reused: the indexer is gone
+  signal(kill, pid, "SIGKILL");
+  await sleep(POLL_MS);
+  return !isAliveVia(kill, pid);
+}
+
+const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+// Notes the stop while the file still names that pid: 5 tries at the mutex, 20 ms apart; false if never free.
+export const noteStopped = (file, pid, now, reason, wait = sleepSync) => {
+  const mark = () => withMutex(file, now, () => {
+    const { running: _running, ...note } = readLease(file, { now }) ?? {};
+    if (note.pid === pid && !note.stoppedAt) writeLease(file, { ...note, stoppedAt: now, stoppedBy: reason });
+    return true;
+  });
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    if (attempt > 0) wait(20);
+    if (mark() === true) return true;
+  }
+  return false;
+};
+
+// Stops the process `file` names past MAX_RUN_MS (or `force`) and notes it there: `{ pid, slug }` or null.
+export async function stopLeaseHolder(file, { force = false, now = Date.now(), ...io } = {}) {
+  const held = readLease(file, { now });
+  const kill = io.kill ?? ((p, s) => process.kill(p, s));
+  if (!Number.isInteger(held?.pid) || held.pid <= 1 || held.pid === process.pid || held.stoppedAt || !isAliveVia(kill, held.pid)) return null;
+  if (!force && now - held.at < MAX_RUN_MS) return null;
+  if (!(await stopIndexer(held.pid, held.at, { ...io, command: held.command, now, kill }))) return null;
+  const marked = noteStopped(file, held.pid, now, force ? "lane-done" : "max-run", io.wait ?? sleepSync);
+  return { pid: held.pid, slug: held.slug, marked };
+}
+
+// Overlapping claims of one process (two MCP requests in a host share its pid): the lease goes with the last.
+const claims = new Map();
+const RELEASE_TRIES = 5;
+const RELEASE_WAIT_MS = 20;
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+/**
+ * HU-2907: claims the lease for `pid` unless another live process holds it. Never waits. A holder
+ * in `kin` (the spawning parent, which names itself before the child's pid lands) is not "another".
+ */
+export function claimLease(file, record, { now = Date.now(), pid = process.pid, kin = [] } = {}) {
+  const res = withMutex(file, now, () => {
+    const holder = readLease(file, { now });
+    if (holder?.running && holder.pid !== pid && !kin.includes(holder.pid)) return { claimed: false, holder };
+    writeLease(file, { ...record, pid, at: now });
+    claims.set(file, (claims.get(file) ?? 0) + 1);
+    return { claimed: true };
+  });
+  return res.busy === true ? { claimed: false, busy: true } : res;
+}
+
+/** Removes the lease only while it still names `pid`: never another process's claim. */
+export function releaseLease(file, { pid = process.pid, now = Date.now(), sleep = pause } = {}) {
+  // This claim is over whatever the mutex says: counted down once, so a busy mutex never leaves it stale.
+  const left = (claims.get(file) ?? 1) - 1;
+  if (left > 0) { claims.set(file, left); return { released: false, shared: true }; }
+  claims.delete(file);
+  const release = () => withMutex(file, now, () => {
+    if (readLease(file, { now })?.pid !== pid) return { released: false };
+    unlessGone(() => unlinkSync(file));
+    return { released: true };
+  });
+  // Up to RELEASE_TRIES attempts while the mutex is busy; past that the lease expires on its own (dead pid, or MAX_RUN_MS).
+  let res = release();
+  for (let attempt = 1; res.busy === true && attempt < RELEASE_TRIES; attempt += 1) { sleep(RELEASE_WAIT_MS); res = release(); }
+  return res;
+}

package/src/rag/project-store.js

@@ -17,7 +17,6 @@ import { execFileSync } from "node:child_process";
 import path from "node:path";
 
 import { openVecStore } from "./vec-store.js";
-import { explainNativeLoadError } from "../checks/native-build.js";
 import { getKarajanHome } from "../utils/paths.js";
 
 function projectRoot(dir) {
@@ -40,20 +39,11 @@ export function libraryDbPath() {
   return process.env.KJ_LIBRARY_DB || path.join(getKarajanHome(), "library.db");
 }
 
-// KJC-BUG-0426: an unbuilt better-sqlite3 addon says how to build it, not "bindings file".
-// Every opening of a RAG store goes through here.
-export function openVecStoreExplained(opts) {
-  try {
-    return openVecStore(opts);
-  } catch (err) {
-    throw explainNativeLoadError(err);
-  }
-}
 
 export function openLibraryStore({ dim = 768 } = {}) {
-  return openVecStoreExplained({ dim, path: libraryDbPath() });
+  return openVecStore({ dim, path: libraryDbPath() });
 }
 
 export function openProjectStore({ projectDir = process.cwd(), dim = 768 } = {}) {
-  return openVecStoreExplained({ dim, path: projectDbPath(projectDir) });
+  return openVecStore({ dim, path: projectDbPath(projectDir) });
 }