karajan-code 4.70.4 → 5.0.1

package/src/roles/audit-role.js

@@ -13,6 +13,7 @@ import { collectWebPerfInput } from "../audit/webperf-input.js";
 import { collectOsvFindings } from "../audit/osv-findings.js";
 import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
 import { collectInfraFindings } from "../audit/infra-findings.js";
+import { collectNpmSignatures } from "../audit/npm-signatures.js";
 import { collectCircularDeps } from "../audit/circular-deps.js";
 import { collectDeadExports } from "../audit/dead-exports.js";
 import { collectInjectionFindings } from "../audit/injection-findings.js";
@@ -38,6 +39,86 @@ function buildSummary(parsed) {
   return `Overall health: ${summary.overallHealth}. ${summary.totalFindings} findings (${findingsStr})`;
 }
 
+/** A deterministic collector's result, or null when it fails: every section is best-effort. */
+async function bestEffort(collect) {
+  try { return await collect(); } catch { return null; }
+}
+
+/** Basal cost and its growth against the last audit; a failure on the way leaves what was measured. */
+async function basalWithGrowth(projectDir) {
+  let basalCost = null;
+  let growthDelta = null;
+  try {
+    basalCost = await measureBasalCost(projectDir);
+    const previous = await loadPreviousAudit(projectDir);
+    growthDelta = computeGrowthDelta(basalCost, previous);
+  } catch { /* basal cost is best-effort */ }
+  return { basalCost, growthDelta };
+}
+
+/**
+ * Knip dead-exports — KJC-TSK v2.17. Stack-aware, JS/TS only, needs
+ * package.json. Best-effort: any failure returns available:false and
+ * the audit continues without the section.
+ * AC8 (KJC-TSK-0794): the report leads with the derivative — hand the
+ * block its previous measurement, if one was ever recorded.
+ */
+async function deadExportsWithPrevious(projectDir, stack, config, logger) {
+  const deadExports = await collectDeadExports(projectDir, stack, config, logger);
+  if (deadExports?.available) {
+    try {
+      const prev = await loadPreviousAudit(projectDir);
+      deadExports.previous = prev?.knipDeadExports ? { ...prev.knipDeadExports, timestamp: prev.timestamp || null } : null;
+    } catch { /* the findings stand without their previous measurement */ }
+  }
+  return deadExports;
+}
+
+/**
+ * STW-A (KJC-TSK-0789 AC5): record that the security surface was looked
+ * at, so the Steward can age it — GREBLA went 79 days with "never".
+ */
+function recordSecurityAudit(projectDir, securityOnly) {
+  try {
+    mkdirSync(dirname(securityAuditMarkerPath(projectDir)), { recursive: true });
+    writeFileSync(securityAuditMarkerPath(projectDir), JSON.stringify({ at: new Date().toISOString(), mode: securityOnly ? "security" : "full" }));
+  } catch { /* recording is best-effort — the audit itself already ran */ }
+}
+
+/** The LLM phase's input, from a task string or the options object. */
+function auditInput(input, fallbackTask) {
+  if (typeof input === "string") return { task: input, onOutput: null, dimensions: null, context: null };
+  const rawDimensions = input?.dimensions || null;
+  return {
+    task: input?.task || fallbackTask,
+    onOutput: input?.onOutput || null,
+    dimensions: typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions,
+    context: input?.context || null,
+  };
+}
+
+const ifAvailable = (section) => (section?.available ? section : undefined);
+
+/** The structured result: the parsed audit plus every deterministic section that ran. */
+function structuredResult(parsed, ctx, provider) {
+  const { basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, envKeys } = ctx;
+  return {
+    summary: parsed.summary, dimensions: parsed.dimensions,
+    topRecommendations: parsed.topRecommendations,
+    textSummary: parsed.textSummary || undefined,
+    basalCost: basalCost || undefined, growthDelta: growthDelta || undefined,
+    stack: stack || undefined,
+    sonarFindings: ifAvailable(sonarFindings),
+    webperf: ifAvailable(webperf),
+    osvFindings: ifAvailable(osvFindings),
+    semgrepFindings: ifAvailable(semgrepFindings),
+    circularDeps: ifAvailable(circularDeps),
+    deadExports: ifAvailable(deadExports),
+    envKeys: ifAvailable(envKeys),
+    provider,
+  };
+}
+
 export class AuditRole extends AgentRole {
   constructor(opts) {
     super({ ...opts, name: "audit" });
@@ -56,123 +137,47 @@ export class AuditRole extends AgentRole {
    *   execute() would gather internally)
    */
   async collectDeterministic(input) {
+    const opts = (typeof input === "object" && input) || {};
     // KJC-TSK-0695: securityOnly = the focused pass an agent self-invokes
     // when a task touches sensitive surface. Only the security collectors
     // run (sonar, osv, semgrep, injection) — zero tokens, fast.
-    const securityOnly = typeof input === "object" ? Boolean(input?.securityOnly) : false;
-    const noSonar = typeof input === "object" ? Boolean(input?.noSonar) : false;
-    const noOsv = typeof input === "object" ? Boolean(input?.noOsv) : false;
-    const noSemgrep = typeof input === "object" ? Boolean(input?.noSemgrep) : false;
-    const noMadge = (typeof input === "object" ? Boolean(input?.noMadge) : false) || securityOnly;
-    const noKnip = (typeof input === "object" ? Boolean(input?.noKnip) : false) || securityOnly;
-    const noInjectionScan = typeof input === "object" ? Boolean(input?.noInjectionScan) : false;
-    const noInfraScan = typeof input === "object" ? Boolean(input?.noInfraScan) : false;
-    const noAiSlop = (typeof input === "object" ? Boolean(input?.noAiSlop) : false) || securityOnly;
+    const securityOnly = Boolean(opts.securityOnly);
+    const skip = (flag) => Boolean(opts[flag]);
     const projectDir = this.config?.projectDir || process.cwd();
-    let basalCost = null;
-    let growthDelta = null;
-    let stack = null;
-    let sonarFindings = null;
-    let webperf = null;
-    let osvFindings = null;
-    let semgrepFindings = null;
-    let circularDeps = null;
-    let deadExports = null;
-    let injectionFindings = null;
-    let infraFindings = null;
-    let aiSlop = null;
-    let envKeys = null;
-    if (!securityOnly) {
-      try {
-        basalCost = await measureBasalCost(projectDir);
-        const previous = await loadPreviousAudit(projectDir);
-        growthDelta = computeGrowthDelta(basalCost, previous);
-      } catch { /* basal cost is best-effort */ }
-    }
-    try {
-      stack = await detectProjectStack(projectDir);
-    } catch { /* stack detect is best-effort */ }
-    if (!noSonar) {
-      try {
-        sonarFindings = await collectSonarFindings(this.config, this.logger);
-      } catch { /* sonar fetch is best-effort */ }
-    }
-    if (!securityOnly) {
-      try {
-        webperf = collectWebPerfInput(stack, this.config);
-      } catch { /* webperf input is best-effort */ }
-    }
+    const { config, logger } = this;
+    // KJC-TSK-1257: every collector is best-effort — a failure leaves its section out (null).
+    const { basalCost, growthDelta } = securityOnly ? { basalCost: null, growthDelta: null } : await basalWithGrowth(projectDir);
+    const stack = await bestEffort(() => detectProjectStack(projectDir));
+    const sonarFindings = skip("noSonar") ? null : await bestEffort(() => collectSonarFindings(config, logger));
+    const webperf = securityOnly ? null : await bestEffort(() => collectWebPerfInput(stack, config));
     // OSV vulnerabilities — KJC-TSK-0365. Best-effort: missing
     // osv-scanner binary returns available:false and the audit
     // continues without the section.
-    if (!noOsv) {
-      try {
-        osvFindings = await collectOsvFindings(projectDir, this.logger);
-      } catch { /* osv-scanner is best-effort */ }
-    }
+    const osvFindings = skip("noOsv") ? null : await bestEffort(() => collectOsvFindings(projectDir, logger));
     // Semgrep SAST — KJC-TSK-0366. Best-effort: missing semgrep binary
     // returns available:false and the audit continues without the section.
-    if (!noSemgrep) {
-      try {
-        semgrepFindings = await collectSemgrepFindings(projectDir, this.logger);
-      } catch { /* semgrep is best-effort */ }
-    }
+    const semgrepFindings = skip("noSemgrep") ? null : await bestEffort(() => collectSemgrepFindings(projectDir, logger));
     // Madge circular-import deps — KJC-TSK v2.17. Stack-aware: skipped for
     // non-JS/TS projects. Best-effort: any failure returns available:false
     // and the audit continues without the section.
-    if (!noMadge) {
-      try {
-        circularDeps = await collectCircularDeps(projectDir, stack, this.config, this.logger);
-      } catch { /* madge is best-effort */ }
-    }
-    // Knip dead-exports — KJC-TSK v2.17. Stack-aware, JS/TS only, needs
-    // package.json. Best-effort: any failure returns available:false and
-    // the audit continues without the section.
-    if (!noKnip) {
-      try {
-        deadExports = await collectDeadExports(projectDir, stack, this.config, this.logger);
-        // AC8 (KJC-TSK-0794): the report leads with the derivative — hand the
-        // block its previous measurement, if one was ever recorded.
-        if (deadExports?.available) {
-          const prev = await loadPreviousAudit(projectDir);
-          deadExports.previous = prev?.knipDeadExports ? { ...prev.knipDeadExports, timestamp: prev.timestamp || null } : null;
-        }
-      } catch { /* knip is best-effort */ }
-    }
-    if (!noInjectionScan) {
-      try {
-        injectionFindings = await collectInjectionFindings(projectDir, this.logger);
-      } catch { /* injection scan is best-effort (KJC-TSK-0498) */ }
-    }
+    const circularDeps = skip("noMadge") || securityOnly ? null : await bestEffort(() => collectCircularDeps(projectDir, stack, config, logger));
+    const deadExports = skip("noKnip") || securityOnly ? null : await bestEffort(() => deadExportsWithPrevious(projectDir, stack, config, logger));
+    const injectionFindings = skip("noInjectionScan") ? null : await bestEffort(() => collectInjectionFindings(projectDir, logger));
     // Checkov infra misconfigs — INF-C (KJC-TSK-0760). Security surface, so
     // it ALSO runs in securityOnly. Best-effort: no infra markers or missing
     // checkov return available:false declaring why.
-    if (!noInfraScan) {
-      try {
-        infraFindings = await collectInfraFindings(projectDir, this.logger);
-      } catch { /* checkov is best-effort */ }
-    }
+    const infraFindings = skip("noInfraScan") ? null : await bestEffort(() => collectInfraFindings(projectDir, logger));
+    // KJC-TSK-1253: npm registry signatures and provenance. Supply-chain security, so it
+    // also runs in securityOnly; the collector says when it does not apply or cannot run.
+    const npmSignatures = skip("noNpmSignatures") ? null : await bestEffort(() => collectNpmSignatures(projectDir, logger));
     // AI-slop tells (KJC-TSK-0503). Deterministic, offline, regex-based.
     // Local equivalent of Deslopify-style review. Best-effort.
-    if (!noAiSlop) {
-      try {
-        aiSlop = await collectAiSlop(projectDir);
-      } catch { /* ai-slop scan is best-effort */ }
-    }
+    const aiSlop = skip("noAiSlop") || securityOnly ? null : await bestEffort(() => collectAiSlop(projectDir));
     // KJC-TSK-0845: one key, two resolution rules = a migration left half-way
     // (KJ_HOME → KARAJAN_HOME). Deterministic, offline, best-effort.
-    if (!securityOnly) {
-      try {
-        envKeys = await collectEnvKeyFindings(projectDir);
-      } catch { /* env-key scan is best-effort */ }
-    }
-    // STW-A (KJC-TSK-0789 AC5): record that the security surface was looked
-    // at, so the Steward can age it — GREBLA went 79 days with "never".
-    try {
-      mkdirSync(dirname(securityAuditMarkerPath(projectDir)), { recursive: true });
-      writeFileSync(securityAuditMarkerPath(projectDir), JSON.stringify({ at: new Date().toISOString(), mode: securityOnly ? "security" : "full" }));
-    } catch { /* recording is best-effort — the audit itself already ran */ }
-    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings, infraFindings, aiSlop, envKeys };
+    const envKeys = securityOnly ? null : await bestEffort(() => collectEnvKeyFindings(projectDir));
+    recordSecurityAudit(projectDir, securityOnly);
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings, infraFindings, npmSignatures, aiSlop, envKeys };
   }
 
   /**
@@ -182,13 +187,8 @@ export class AuditRole extends AgentRole {
    * call this if the user wants to spend tokens.
    */
   async executeWithDeterministic(input, deterministicCtx) {
-    const task = typeof input === "string" ? input : input?.task || this.context?.task || "";
-    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
-    const rawDimensions = typeof input === "object" ? input?.dimensions || null : null;
-    const context = typeof input === "object" ? input?.context || null : null;
-    const dimensions = typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions;
-
-    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, envKeys } = deterministicCtx;
+    const { task, onOutput, dimensions, context } = auditInput(input, this.context?.task || "");
+    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports } = deterministicCtx;
 
     const provider = this.resolveProvider();
     const agent = this.createAgentInstance(provider);
@@ -238,26 +238,7 @@ export class AuditRole extends AgentRole {
         try { await saveAuditSnapshot(projectDir, { ...basalCost, knipDeadExports }); } catch { /* best-effort */ }
       }
 
-      return {
-        ok: true,
-        result: {
-          summary: parsed.summary, dimensions: parsed.dimensions,
-          topRecommendations: parsed.topRecommendations,
-          textSummary: parsed.textSummary || undefined,
-          basalCost: basalCost || undefined, growthDelta: growthDelta || undefined,
-          stack: stack || undefined,
-          sonarFindings: sonarFindings?.available ? sonarFindings : undefined,
-          webperf: webperf?.available ? webperf : undefined,
-          osvFindings: osvFindings?.available ? osvFindings : undefined,
-          semgrepFindings: semgrepFindings?.available ? semgrepFindings : undefined,
-          circularDeps: circularDeps?.available ? circularDeps : undefined,
-          deadExports: deadExports?.available ? deadExports : undefined,
-          envKeys: envKeys?.available ? envKeys : undefined,
-          provider
-        },
-        summary: buildSummary(parsed),
-        usage
-      };
+      return { ok: true, result: structuredResult(parsed, deterministicCtx, provider), summary: buildSummary(parsed), usage };
     } catch {
       return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage };
     }

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/atril-skills.js

@@ -10,10 +10,11 @@ import { join } from "node:path";
 import { resolve as atrilResolve } from "@karajan-family/atril";
 
 export const ATRIL_ROOT = ".karajan";
-const KIND_DIRS = ["skills", "commands", "agents"];
-
-/** A project has a store when any kind directory exists under `.karajan/`. */
-export const hasAtrilStore = (projectDir, root = ATRIL_ROOT) => KIND_DIRS.some((dir) => existsSync(join(projectDir, root, dir)));
+/**
+ * The roles ask atril for their skills once the store holds skills: Karajan's own commands
+ * (installed there by kj init, step 15d) must not switch the roles off their usual skills.
+ */
+export const hasAtrilStore = (projectDir, root = ATRIL_ROOT) => existsSync(join(projectDir, root, "skills"));
 
 /**
  * The block atril resolves for this role and task, in the shape the prompts

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);
+  };
+}