karajan-code 5.0.0 → 5.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -99,7 +99,7 @@
   },
   "dependencies": {
     "@babel/parser": "^7.29.7",
-    "@karajan-family/atril": "^1.1.0",
+    "@karajan-family/atril": "^1.3.0",
     "@karajan-family/governance": "^0.1.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@xterm/xterm": "^6.0.0",

package/src/cli/register-roles-skills.js

@@ -10,7 +10,7 @@ import { withConfig } from "./_shared.js";
 export function registerRolesSkills(program, { pkgVersion }) {
   program
     .command("skills [action] [args...]")
-    .description("Manage the skill cache (list | clear-cache | sync-addyosmani | list-addyosmani) and, through atril, the .karajan store (search | route | scan | install | remove | graph | enrich | config)")
+    .description("Manage the skill cache (list | clear-cache | sync-addyosmani | list-addyosmani) and, through atril, the .karajan store (search, which translates a non-English query first | route | scan | install | remove | graph | enrich | config)")
     // KJC-TSK-1193: atril's options (--json, --kind, --role, --root) travel to atril untouched.
     .allowUnknownOption()
     .action(async (action, args) => {

package/src/commands/rag.js

@@ -12,6 +12,8 @@ import { fileIndexState } from "../rag/coverage.js";
 import { query } from "../rag/retriever.js";
 import { pathNamedHits, withPathNamedHits } from "../rag/path-hits.js";
 import { installPostMergeHook, maybeAutoUpdate } from "../rag/auto-update.js";
+import { noteDeadline } from "../rag/bootstrap-index.js";
+import { claimLease, indexLeasePath, releaseLease } from "../rag/pid-lease.js";
 import { indexLibrary, LIBRARY_PROJECT } from "../rag/library.js";
 import { compareToBaseline, loadGoldenQueries, runEval } from "../rag/eval.js";
 import { getKarajanHome } from "../utils/paths.js";
@@ -47,8 +49,35 @@ async function indexFiles({ files, projectDir, db, embedder, slug, logger, json,
   return totals;
 }
 
-export async function ragIndexCommand({ config, logger, flags = {} }) {
+// HU-3092: the background indexer is given the time it may stop at; unset, non-numeric or <= 0 means none.
+const deadlineFromEnv = () => { const n = Number(process.env.KJ_RAG_DEADLINE); return Number.isFinite(n) && n > 0 ? n : null; };
+
+// The partial index keeps its chunks but not its commit: the marker says why it stopped, the warning how to finish.
+function reportDeadline({ totals, projectDir, logger, json }) {
+  noteDeadline(projectDir);
+  logger.warn?.(`[rag] KJ_RAG_DEADLINE reached after ${totals.files} file(s): the index is partial and its commit is not recorded; run kj rag index --with-sources by hand`);
+  if (json) process.stdout.write(`${JSON.stringify(totals)}\n`);
+  return totals;
+}
+
+// HU-3116: the cooperative stop only looks between files; a hung embed call is ended this long after the deadline.
+// It stays inside DEADLINE_MARGIN_MS (60 s), so the child is gone before its lease reads as expired.
+export const BACKSTOP_GRACE_MS = 30 * 1000;
+
+export async function ragIndexCommand({ config, logger, flags = {}, backstop = {} }) {
+  const { setTimer = setTimeout, clearTimer = clearTimeout, exit = process.exit } = backstop;
   const projectDir = config?.projectDir || process.cwd();
+  const deadline = deadlineFromEnv();
+  // Past already (a queued start, a slow machine): nothing is opened, claimed or embedded.
+  if (deadline !== null && Date.now() >= deadline) return reportDeadline({ totals: { indexed: 0, failed: 0, files: 0, stopped: "deadline" }, projectDir, logger, json: flags.json });
+  let heldLease = null;
+  const timer = deadline === null ? null : setTimer(() => {
+    if (heldLease) releaseLease(heldLease);
+    noteDeadline(projectDir);
+    logger.warn?.("[rag] KJ_RAG_DEADLINE passed with an embed call still hung: the index is partial and its commit is not recorded; run kj rag index --with-sources by hand");
+    exit(0);
+  }, Math.max(0, deadline + BACKSTOP_GRACE_MS - Date.now()));
+  timer?.unref?.();
   const db = openDb(config);
   try {
     const slug = projectSlug(projectDir);
@@ -76,13 +105,22 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
       }
     }
     if (!totals) {
-      totals = await indexProject(projectDir, {
-        db, embedder,
-        karajanHome: getKarajanHome(), logger,
-        withSources: Boolean(flags.withSources),
-        exclude: ragExclude(config),
-      });
+      // HU-2907: a full foreground index holds the machine lease, so background lanes defer to it.
+      // The bootstrap child finds its spawning parent in the lease (it names itself first): kin.
+      const lease = indexLeasePath();
+      const claim = claimLease(lease, { projectDir, slug }, { kin: [process.ppid] });
+      if (claim.holder) logger.warn?.(`[rag] another index is running (${claim.holder.slug ?? "?"}, pid ${claim.holder.pid}); indexing anyway`);
+      if (claim.claimed) heldLease = lease;
+      try {
+        totals = await indexProject(projectDir, {
+          db, embedder,
+          karajanHome: getKarajanHome(), logger,
+          withSources: Boolean(flags.withSources),
+          exclude: ragExclude(config), deadline,
+        });
+      } finally { if (claim.claimed) releaseLease(lease); }
     }
+    if (totals.stopped) return reportDeadline({ totals, projectDir, logger, json: flags.json });
     if (totals.head) setLastIndexedCommit(db, slug, totals.head);
     // KJC-TSK-0697 — the library corpus refreshes on every index run.
     // Best-effort and cheap: a handful of cards, content-hash dedup.
@@ -101,6 +139,7 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
     }
     return totals;
   } finally {
+    if (timer) clearTimer(timer);
     db.close();
   }
 }

package/src/commands/skills.js

@@ -13,6 +13,7 @@
 import { listCached, clearCache, getCacheRoot, DEFAULT_TTL_MS } from "../skills/skills-cache.js";
 import { refreshIfStale, listAvailableSlugs, getCatalogRoot, loadSkillBySlug } from "../skills/addyosmani-catalog.js";
 import { ATRIL_COMMANDS, runAtril } from "../skills/atril-cli.js";
+import { skillsSearch } from "../skills/skills-search.js";
 
 function humanAge(cachedAt) {
   const ms = Date.now() - Date.parse(cachedAt);
@@ -22,7 +23,9 @@ function humanAge(cachedAt) {
   return `${days.toFixed(1)}d ago`;
 }
 
-export async function skillsCommand({ action = "list", args = [], deps = { atril: runAtril } } = {}) {
+export async function skillsCommand({ action = "list", args = [], deps = { atril: runAtril, skillsSearch } } = {}) {
+  // HU-2782: search is kj's own, so the query can be translated into English first.
+  if (action === "search") return deps.skillsSearch({ args });
   // KJC-TSK-1193: atril's own commands go to atril, on the .karajan store.
   if (ATRIL_COMMANDS.includes(action)) return deps.atril({ action, args });
   switch (action) {

package/src/commands/worktree.js

@@ -13,13 +13,17 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { bootstrapWorktree } from "../hu/worktree-bootstrap.js";
 import { laneWork, setupLane } from "../hu/lane-setup.js";
-import { classifyLanes, commitsNotIn, liveProcesses, looseLaneBranches, resolveBase } from "../hu/lane-prune.js";
+import { classifyLanes, commitsNotIn, liveProcesses, looseLaneBranches, resolveBase, stopLaneIndexers } from "../hu/lane-prune.js";
+import { stopBootstrap } from "../rag/bootstrap-index.js";
 import { recordGateDecision } from "../policy/decisions.js";
 import { mainCheckout } from "../utils/main-checkout.js";
 import { cardsOfLane, parseLanes, prsByBranch } from "../hu/lanes.js";
 import { listPlans, loadPlan } from "../plan/plan-store.js";
 
-const REF_SEPARATOR = " · "; // external_ref joins a tracker card and an issue (src/commands/hu.js)
+// The pid itself, not the marker's expiry: an indexer past MAX_RUN_MS still runs. EPERM is a process too.
+const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (err) { return err.code === "EPERM"; } };
+
+const REF_SEPARATOR =" · "; // external_ref joins a tracker card and an issue (src/commands/hu.js)
 
 // KJC-TSK-1316: ONE gh call for every lane, open and merged PRs alike.
 const listPrs = async (cwd) => JSON.parse((await execFileAsync("gh", ["pr", "list", "--state", "all", "--limit", "200", "--json", "number,url,state,headRefName"], { cwd })).stdout);
@@ -121,6 +125,12 @@ export async function worktreeCommand({ config = null, action, args = [], flags
     if (dirty && !flags.force) {
       throw new Error(`lane "${slug}" has uncommitted changes — commit them (through the gate) or discard with --force`);
     }
+    // HU-3114: the lane's background indexer must not outlive it (any age); a failure never blocks the removal.
+    const stopIndexer = deps.stopBootstrap ?? stopBootstrap;
+    const indexerStopped = await stopIndexer(wtPath, { force: true }).catch((err) => {
+      console.warn(`warning: could not stop the background indexer of "${slug}": ${err.message}`);
+      return null;
+    });
     // The lane's real branch (headless kj-hu-* lanes share the folder); detached HEAD → null.
     // symbolic-ref -q exits 1 on a detached HEAD; any other failure is a real error.
     const branch = await git(["symbolic-ref", "--short", "-q", "HEAD"], wtPath).then((r) => r.stdout.trim() || null, (err) => {
@@ -140,13 +150,15 @@ export async function worktreeCommand({ config = null, action, args = [], flags
         : ahead === null ? `branch ${branch} kept: base "${base}" not found, cannot tell if it is merged (git branch -D ${branch} to delete it)`
           : `branch ${branch} kept: ${ahead} commit(s) not in ${base} (squash-merged or not fetched? git fetch, then git branch -D ${branch})`;
     console.log(`✓ lane "${slug}" removed; ${note}`);
-    return { removed: true, slug, branch, branchDeleted, merged: branch ? ahead === 0 : null };
+    return { removed: true, slug, branch, branchDeleted, merged: branch ? ahead === 0 : null, indexerStopped };
   }
 
   if (action === "prune") {
     const { processes = liveProcesses() } = deps;
     const base = await resolveBase({ git, base: baseName });
     const lanes = await classifyLanes({ git, laneRoot: lanesDir, base, processes, now: deps.now });
+    // HU-3092: a removable lane's own background indexer is stopped first (never in a dry run); one that survives keeps the lane.
+    if (!flags.dryRun) await stopLaneIndexers(lanes, { stop: deps.stopIndexer ?? ((l) => stopBootstrap(l.path, { force: true })), stillRunning: deps.indexerRunning ?? ((l) => pidAlive(l.indexer.pid)) });
     const abandoned = lanes.filter((l) => l.reasons.length === 0);
     const kept = lanes.filter((l) => l.reasons.length > 0);
     for (const l of kept) console.log(`kept    ${l.slug.padEnd(24)} ${l.reasons.join("; ")}`);
@@ -155,7 +167,7 @@ export async function worktreeCommand({ config = null, action, args = [], flags
     const { empty: branches, withWork } = await looseLaneBranches({ git, base });
     for (const b of withWork) console.log(`kept    branch ${b.branch.padEnd(17)} ${b.reason}`);
     if (flags.dryRun) {
-      for (const l of abandoned) console.log(`would retire ${l.slug} (${l.branch ?? "detached"})`);
+      for (const l of abandoned) console.log(`would retire ${l.slug} (${l.branch ?? "detached"})${l.indexer ? ` (stopping its background index, pid ${l.indexer.pid})` : ""}`);
       for (const b of branches) console.log(`would delete branch ${b}`);
       return { wouldRemove: abandoned, kept, wouldRemoveBranches: branches, branchesKept: withWork };
     }

package/src/config/defaults.js

@@ -28,6 +28,7 @@ const DEFAULTS = {
     discover: { provider: null, model: null },
     architect: { provider: null, model: null },
     hu_reviewer: { provider: null, model: null },
+    translator: { provider: null, model: null },
     start: { provider: null, model: "haiku" }
   },
   pipeline: {

package/src/config/role-resolver.js

@@ -65,6 +65,7 @@ const CODER_INHERITED_ROLES = new Set([
   "impeccable", "triage", "discover", "architect", "audit",
   "hu_reviewer", "hu-reviewer",
   "spec_reviewer", "spec-reviewer",
+  "translator",
 ]);
 
 function resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer) {

package/src/config/schema.js

@@ -90,6 +90,7 @@ const RolesMap = v.optional(v.looseObject({
   discover: v.optional(RoleEntry),
   architect: v.optional(RoleEntry),
   hu_reviewer: v.optional(RoleEntry),
+  translator: v.optional(RoleEntry),
   start: v.optional(RoleEntry),
 }));
 

package/src/hu/lane-prune.js

@@ -5,31 +5,61 @@
  * touched, so a session may run this without risking anyone's work.
  */
 import fs from "node:fs";
+import { spawnSync } from "node:child_process";
 import path from "node:path";
-import { laneWork } from "./lane-setup.js";
+import { isLaneSetupPath, laneWork } from "./lane-setup.js";
+import { readBootstrap } from "../rag/bootstrap-index.js";
 
 const IDLE_HOURS = 24;
+// HU-3092: the lane's index and what rides along it (-wal, -shm, .bootstrap, .embed-schema) is regenerable state.
+const RAG_STATE = /^\.karajan\/rag\.db([.-]|$)/;
 const REGENERABLE = new Set(["node_modules", "dist", "build", "coverage", ".venv", "venv", "__pycache__", ".cache", "target"]);
 
+const LSOF = "/usr/sbin/lsof";
+const LSOF_TIMEOUT_MS = 10_000;
+
+/** HU-3117: `lsof -Fpn` output is `p<pid>` then `n<path>` lines; a pid with no path line is skipped. */
+export function parseLsofCwds(out) {
+  const procs = [];
+  let pid = null;
+  for (const line of out.split("\n")) {
+    if (line.startsWith("p") && /^\d+$/.test(line.slice(1))) pid = Number(line.slice(1));
+    else if (line.startsWith("n") && pid !== null) { procs.push({ pid, cwd: line.slice(1) }); pid = null; }
+  }
+  return procs;
+}
+
+/** darwin has no /proc: lsof lists this user's cwds. null when it is missing, fails or times out (never "no processes"). */
+function lsofProcesses({ run, uid }) {
+  const r = run(LSOF, ["-a", "-d", "cwd", "-u", String(uid), "-Fpn"], { encoding: "utf8", timeout: LSOF_TIMEOUT_MS });
+  if (r.error || r.status !== 0 || typeof r.stdout !== "string") return null;
+  const procs = parseLsofCwds(r.stdout);
+  return { cwds: new Set(procs.map((p) => p.cwd)), unseen: 0, procs };
+}
+
 /**
  * This user's live processes (another user's cannot write in our worktrees): the
  * cwds that can be read and how many cannot (non-dumpable ones: ssh-agent, systemd,
- * some JVMs). null when the platform has no /proc.
+ * some JVMs). null when the platform's listing is unavailable (no /proc, no lsof).
  */
-export function liveProcesses() {
+export function liveProcesses({ platform = process.platform, run = spawnSync, uid = process.getuid() } = {}) {
+  if (platform === "darwin") return lsofProcesses({ run, uid });
   let pids;
   try { pids = fs.readdirSync("/proc").filter((p) => /^\d+$/.test(p)); } catch { return null; }
   const cwds = new Set();
+  const procs = [];
   let unseen = 0;
   for (const pid of pids) {
     try {
       if (fs.statSync(`/proc/${pid}`).uid !== process.getuid()) continue;
-      cwds.add(fs.readlinkSync(`/proc/${pid}/cwd`));
+      const cwd = fs.readlinkSync(`/proc/${pid}/cwd`);
+      cwds.add(cwd);
+      procs.push({ pid: Number(pid), cwd });
     } catch (err) {
       if (err.code !== "ENOENT" && err.code !== "ESRCH") unseen += 1;
     }
   }
-  return { cwds, unseen };
+  return { cwds, unseen, procs };
 }
 
 /** Hours since anything in the lane moved: its dir, and its git index and HEAD. */
@@ -43,6 +73,32 @@ async function idleHours(git, lanePath, now) {
 
 const inside = (cwd, dir) => cwd === dir || cwd.startsWith(dir + path.sep);
 
+/** A folder git lists whole (an ignored `.karajan/`) holds only index state and setup when every file in it does. */
+function onlyRagState(lanePath, dir) {
+  try {
+    return fs.readdirSync(path.join(lanePath, dir), { recursive: true, withFileTypes: true }).filter((d) => !d.isDirectory()) // symlinks and the like are the user's, never state
+      .every((d) => { const rel = path.relative(lanePath, path.join(d.parentPath, d.name)); return RAG_STATE.test(rel) || isLaneSetupPath(rel); });
+  } catch { return false; }
+}
+const ragOnly = (lanePath, p) => RAG_STATE.test(p) || (p.endsWith("/") && onlyRagState(lanePath, p));
+
+/**
+ * The pid of the lane's background indexer: the one its marker names, while the marker notes no stop.
+ * null when KJ_RAG_DB puts the index elsewhere: the marker read is then not this lane's.
+ */
+function indexerOf(lanePath) {
+  if (process.env.KJ_RAG_DB) return null;
+  const marker = readBootstrap(lanePath);
+  return Number.isInteger(marker?.pid) && !marker.stoppedAt ? marker.pid : null;
+}
+
+/** D6: stops each removable lane's indexer; a lane whose indexer survives (marker still running) is kept, saying so. */
+export async function stopLaneIndexers(lanes, { stop, stillRunning }) {
+  for (const l of lanes.filter((x) => x.indexer && x.reasons.length === 0)) {
+    if (!(await stop(l)) && (await stillRunning(l))) l.reasons.push(`its background index (pid ${l.indexer.pid}) could not be stopped`);
+  }
+}
+
 /** @returns {Promise<{slug: string, path: string, branch: string|null, reasons: string[]}[]>} */
 export async function classifyLanes({ git, laneRoot, base, processes, now = Date.now() }) {
   const { stdout } = await git(["worktree", "list", "--porcelain"]);
@@ -58,7 +114,7 @@ export async function classifyLanes({ git, laneRoot, base, processes, now = Date
     const reasons = [];
     // KJC-TSK-1371: the identity and Sentinel files lane setup wrote are not the lane's work.
     const { stdout: status } = await git(["status", "--porcelain", "--ignored=matching", "--untracked-files=all"], lane.path);
-    const entries = laneWork(status, lane.path);
+    const entries = laneWork(status, lane.path).filter((e) => !ragOnly(lane.path, e.slice(3)));
     if (entries.some((e) => !e.startsWith("!! "))) reasons.push("uncommitted changes");
     // Ignored files can be valuable (.env, local artifacts); only regenerable dirs are not.
     const precious = entries.filter((e) => e.startsWith("!! ") && !REGENERABLE.has(e.slice(3).split("/")[0]));
@@ -66,12 +122,18 @@ export async function classifyLanes({ git, laneRoot, base, processes, now = Date
     // The lane's HEAD, branch or detached: a detached lane's commits have no other name.
     const ahead = await commitsNotIn({ git, base, cwd: lane.path });
     if (ahead > 0) reasons.push(`${ahead} commit(s) not in ${base}`);
+    // The lane's own indexer alone is no reason to keep it (HU-3092); without pids (older callers) any process still is.
+    const inLane = (processes?.procs ?? []).filter((p) => inside(p.cwd, lane.path));
+    const indexer = processes?.procs ? indexerOf(lane.path) : null;
+    const busy = processes !== null && [...processes.cwds].some((cwd) => inside(cwd, lane.path));
+    const owned = busy && indexer !== null && inLane.every((p) => p.pid === indexer) ? { pid: indexer } : null;
     if (processes === null) reasons.push("cannot check for live processes on this platform");
-    else if ([...processes.cwds].some((cwd) => inside(cwd, lane.path))) reasons.push("a live process works in it");
+    else if (busy && !owned) reasons.push("a live process works in it");
+    // The owned indexer excluded, processes that cannot be inspected still protect a recently active lane.
     else if (processes.unseen > 0 && (await idleHours(git, lane.path, now)) < IDLE_HOURS) {
       reasons.push(`${processes.unseen} process(es) of yours cannot be inspected and the lane changed in the last ${IDLE_HOURS} h`);
     }
-    return { slug: path.basename(lane.path), path: lane.path, branch: lane.branch, reasons };
+    return { slug: path.basename(lane.path), path: lane.path, branch: lane.branch, reasons, indexer: owned };
   }));
 }
 

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

@@ -10,6 +10,7 @@ import { indexProject } from "../../rag/indexer.js";
 import { ragExclude } from "../../rag/indexable.js";
 import { query } from "../../rag/retriever.js";
 import { pathNamedHits, withPathNamedHits } from "../../rag/path-hits.js";
+import { claimLease, indexLeasePath, releaseLease } from "../../rag/pid-lease.js";
 import { getKarajanHome } from "../../utils/paths.js";
 import { resolveProjectDir, buildConfig, responseText, failPayload } from "../shared-helpers.js";
 
@@ -56,7 +57,11 @@ export async function handleRagIndex(args, server) {
     const projectDir = await resolveProjectDir(server, args?.projectDir);
     const config = await buildConfig({ ...args, projectDir }, "rag-index");
     const db = openProjectStore({ projectDir, dim: config?.rag?.embedder?.dim || 768 });
+    // HU-2907: the long-lived host holds the machine lease for the walk and releases it in the finally.
+    const lease = indexLeasePath();
+    let claim;
     try {
+      claim = claimLease(lease, { projectDir, slug: projectSlug(projectDir) });
       const totals = await indexProject(projectDir, {
         db, embedder: makeGovernedEmbedder(config),
         karajanHome: getKarajanHome(), logger: silentLogger,
@@ -64,7 +69,10 @@ export async function handleRagIndex(args, server) {
         exclude: ragExclude(config), // KJC-TSK-0891
       });
       return responseText(totals);
-    } finally { db.close(); }
+    } finally {
+      if (claim?.claimed) releaseLease(lease);
+      db.close();
+    }
   } catch (err) {
     return failPayload(`kj_rag_index failed: ${err.message}`);
   }

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";
@@ -33,8 +34,21 @@ const HOOK_SRC = resolve(fileURLToPath(import.meta.url), "../../../scripts/git-h
 
 // 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.
-function bootstrapInBackground({ projectDir, slug, head, logger }) {
+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 };
@@ -93,7 +107,7 @@ 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) return bootstrapInBackground({ projectDir, slug, head, logger });
+    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.

package/src/rag/bootstrap-index.js

@@ -6,12 +6,14 @@ 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, readLease, takeLock, unlessGone, withMutex, writeLease } from "./pid-lease.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;
 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`;
 
 /** What the marker says of the last attempt: `{ pid, at, running }`, or null when none was ever made. */
@@ -33,7 +35,10 @@ 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 };
+    // 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);
@@ -42,10 +47,11 @@ export function startBootstrap(projectDir, { spawnFn = spawn, bin = KJ_BIN, 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 note = (pid) => { writeLease(file, { pid, at: now }); writeLease(lease, { pid, at: now, projectDir, slug }); };
+      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" });
+        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 };
@@ -58,3 +64,15 @@ export function startBootstrap(projectDir, { spawnFn = spawn, bin = KJ_BIN, now
     return res.busy === true ? { started: false, busy: {} } : res;
   } finally { unlessGone(() => rmdirSync(lock)); }
 }
+
+/** 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/pid-lease.js

@@ -1,6 +1,8 @@
-// HU-2757: a lease names the pid that holds a resource and when it took it. Nobody releases it:
-// a dead pid, or an age of MAX_RUN_MS, means free. A mkdir mutex makes the decision atomic.
-import { mkdirSync, readFileSync, renameSync, rmdirSync, statSync, writeFileSync } from "node:fs";
+// 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";
 
@@ -29,7 +31,7 @@ export function readLease(file, { now = Date.now() } = {}) {
   if (raw === null) return null;
   try {
     const note = JSON.parse(raw);
-    return { ...note, running: alive(note.pid) && now - note.at < MAX_RUN_MS };
+    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));
@@ -68,3 +70,112 @@ export function withMutex(file, now, fn) {
   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/skills/atril-cli.js

@@ -4,9 +4,10 @@
  * contract between them stays narrow. The store is the project's `.karajan/`
  * unless the user names another root.
  */
-import { spawnSync } from "node:child_process";
+import { execFile, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
 import { ATRIL_ROOT } from "./atril-skills.js";
 
 export const ATRIL_COMMANDS = ["search", "route", "scan", "install", "remove", "graph", "enrich", "config"];
@@ -32,6 +33,23 @@ export function atrilBin(resolveFn = (spec) => import.meta.resolve(spec)) {
   return fileURLToPath(new URL("../bin/atril.js", entry));
 }
 
+/** `atril search --json` through atril's own CLI (KJC-TSK-1193): `{ mode, hits }`, or an error carrying atril's stderr. */
+export async function atrilSearch(query, { kind, root = ATRIL_ROOT } = {}, { exec = promisify(execFile), bin = atrilBin() } = {}) {
+  // `--` keeps a query that starts with a dash from being read as an atril option.
+  const args = [bin, "search", ...(kind ? ["--kind", kind] : []), "--root", root, "--json", "--", query];
+  let stdout;
+  try {
+    ({ stdout } = await exec(process.execPath, args));
+  } catch (err) {
+    throw new Error(`atril search failed: ${String(err.stderr || err.message).trim()}`, { cause: err });
+  }
+  try {
+    return JSON.parse(stdout);
+  } catch (err) {
+    throw new Error(`atril search printed invalid JSON: ${err.message}`, { cause: err });
+  }
+}
+
 /** Runs atril with this node; its output is the user's, its exit code is kj's. */
 export function runAtril({ action, args = [], spawn = spawnSync, bin = atrilBin(), exists = existsSync }) {
   if (spawn === spawnSync && !exists(bin)) throw new Error(`the atril CLI is not at ${bin}: ${INSTALL_HINT}`);

package/src/skills/skills-search.js

@@ -0,0 +1,72 @@
+/**
+ * HU-2782: `kj skills search` asks atril in English. kj prints the results itself
+ * (atril's line format), so the translation step can sit between query and search.
+ */
+import { parseArgs } from "node:util";
+import { loadConfig } from "../config/loader.js";
+import { createLogger } from "../utils/logger.js";
+import { ATRIL_ROOT } from "./atril-skills.js";
+import { atrilSearch } from "./atril-cli.js";
+import { looksNonEnglish, panelAsk, translateDescriptions, translateQuery } from "./translate.js";
+
+// Text from an artifact author or an agent must not drive the terminal.
+const printable = (text) => [...String(text)]
+  .map((ch) => { const code = ch.codePointAt(0); return code < 32 || (code >= 127 && code < 160) ? " " : ch; })
+  .join("").replaceAll(/\s+/g, " ").trim();
+
+// Errors only, to stderr: the agent's progress lines must never mix into the results on stdout.
+const lazyAsk = async (prompt) => panelAsk({ config: (await loadConfig()).config, logger: createLogger("error") })(prompt);
+
+const TOP_HITS = 10;
+
+// The top hits' descriptions back into the asker's language, in one call; never the name, kind, source or score.
+async function describeIn(hits, lang, { ask, err, translation }) {
+  const top = hits.slice(0, TOP_HITS);
+  if (top.length === 0) return hits;
+  try {
+    const texts = await translateDescriptions({ texts: top.map((h) => h.description), lang, ask });
+    return hits.map((h, i) => (i < TOP_HITS ? { ...h, description: texts[i], description_en: h.description } : h));
+  } catch (cause) {
+    translation.error = cause.message;
+    err(`kj: translation unavailable (${cause.message}); showing the original descriptions`);
+    return hits;
+  }
+}
+
+export async function skillsSearch({ args, deps = {} }) {
+  const { search = atrilSearch, ask = lazyAsk, out = (line) => process.stdout.write(`${line}\n`), err = (line) => process.stderr.write(`${line}\n`) } = deps;
+  const { values, positionals } = parseArgs({
+    args, allowPositionals: true, strict: false,
+    options: { kind: { type: "string" }, root: { type: "string" }, json: { type: "boolean" }, "no-translate": { type: "boolean" } },
+  });
+  const query = positionals.join(" ");
+  const opts = { kind: values.kind, root: values.root ?? ATRIL_ROOT };
+  try {
+    let found = await search(query, opts);
+    const translation = { english: query, lang: null, translated: false };
+    if (!values["no-translate"] && (found.hits.length === 0 || looksNonEnglish(query))) {
+      try {
+        const { english, lang } = await translateQuery({ query, ask });
+        if (english !== query) {
+          found = await search(english, opts);
+          err(`kj: searched in English: ${JSON.stringify(english)}`);
+        }
+        Object.assign(translation, { english, lang, translated: true });
+        if (lang && lang !== "en") found = { ...found, hits: await describeIn(found.hits, lang, { ask, err, translation }) };
+      } catch (cause) {
+        translation.error = cause.message;
+        err(`kj: translation unavailable (${cause.message}); showing results for the untranslated query`);
+      }
+    }
+    err(`kj: search mode ${found.mode}`);
+    if (values.json) {
+      const { english, lang, translated, error } = translation;
+      out(JSON.stringify({ mode: found.mode, query: { original: query, english, lang }, translated, hits: found.hits, ...(error && { translation_error: error }) }, null, 2));
+    } else if (found.hits.length === 0) out(`no results for ${JSON.stringify(translation.english)}`);
+    else for (const h of found.hits) out(`${h.score}\t${h.kind}\t${printable(h.name)}\t${h.source}\t${printable(h.description)}`);
+    return 0;
+  } catch (failure) {
+    err(`kj: ${failure.message}`);
+    return 1;
+  }
+}

package/src/skills/translate.js

@@ -0,0 +1,62 @@
+/**
+ * HU-2782 (ADR 0039, decision 2): atril indexes English, so a query in another
+ * language is translated first, by the `translator` role (it inherits the coder).
+ */
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { resolveRole } from "../config/role-resolver.js";
+import { agentAnswerText } from "../review/parser.js";
+
+// The same Spanish stopword list as packages/atril/src/lang.js (HU-2781); copied, not imported from atril's internals.
+const SPANISH_STOPWORDS = new Set("de del la las el los para por con sin una unos unas que como cuando donde este esta estos estas pero sobre entre segun mas muy tambien hacer usar y o en es son al su sus lo se".split(" "));
+const stripAccents = (text) => text.normalize("NFD").replaceAll(/\p{Diacritic}/gu, "");
+
+/** Deterministic gate, no model needed: text outside ASCII or a Spanish stopword means not English. */
+export const looksNonEnglish = (query) => /[^\u0000-\u007F]/.test(query)
+  || stripAccents(query.toLowerCase()).split(/[^a-z]+/).some((token) => SPANISH_STOPWORDS.has(token));
+
+const PROMPT = (query) => `Detect the language of this skill-search query and translate it to English.
+Answer ONLY a JSON object {"lang":"<ISO 639-1 code>","english":"<the query in English>"}, no fences, no explanation.
+
+Query: ${JSON.stringify(query)}`;
+
+const DESCRIPTIONS_PROMPT = (texts, lang) => `Translate each of these skill descriptions from English into the language with ISO 639-1 code ${JSON.stringify(lang)}.
+Answer ONLY a JSON array of ${texts.length} strings, in the same order, no fences, no explanation.
+
+Descriptions: ${JSON.stringify(texts)}`;
+
+async function askJson(ask, prompt) {
+  const text = String(await ask(prompt)).replace(/^```[a-z]*\n?|```\s*$/g, "").trim();
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new Error(`the translator answer is not valid JSON (${err.message})`, { cause: err });
+  }
+}
+
+/** One batched agent call back into the asker's language. Throws unless the answer is one string per text. */
+export async function translateDescriptions({ texts, lang, ask }) {
+  const parsed = await askJson(ask, DESCRIPTIONS_PROMPT(texts, lang));
+  if (!Array.isArray(parsed) || parsed.length !== texts.length || !parsed.every((t) => typeof t === "string")) {
+    throw new Error(`the translator answer is not a JSON array of ${texts.length} strings`);
+  }
+  return parsed;
+}
+
+/** One agent call: `ask(prompt)` returns the agent's text. Throws when the answer is unusable. */
+export async function translateQuery({ query, ask }) {
+  const parsed = await askJson(ask, PROMPT(query));
+  if (typeof parsed?.english !== "string" || !parsed.english.trim()) throw new Error("the translator answer has no english text");
+  return { lang: typeof parsed.lang === "string" ? parsed.lang : null, english: parsed.english.trim() };
+}
+
+/** The panel's translator, as `ask(prompt) => text`; never a silent fallback to another agent. */
+export function panelAsk({ config, logger, create = createAgent, check = assertAgentsAvailable }) {
+  return async (prompt) => {
+    const { provider } = resolveRole(config, "translator");
+    await check([provider]);
+    const res = await create(provider, config, logger).runTask({ prompt, role: "translator" });
+    if (!res?.ok) throw new Error(`${provider}: ${res?.error || "no output"}`);
+    return agentAnswerText(res.output);
+  };
+}