karajan-code 4.70.3 → 5.0.0

package/scripts/dual-publish.mjs

@@ -7,6 +7,7 @@
  * Uso:
  *   node scripts/dual-publish.mjs --pack-only          # genera+verifica el tarball scoped
  *   node scripts/dual-publish.mjs --publish --otp=XXX  # publica el scoped (tras publicar el legacy)
+ *   node scripts/dual-publish.mjs --publish --provenance --no-verify  # desde CI (ADR 0035), tras --pack-only en otro job
  *
  * El swap del name es EN SITIO con restauración en finally: un crash a mitad
  * no deja el manifest renombrado. La verificación es el MISMO verify-pack
@@ -43,6 +44,22 @@ export async function withScopedName(repoRoot, fn) {
   }
 }
 
+/** KJC-TSK-1359 (ADR 0035): npm publish arguments; from CI, provenance and no OTP. */
+export function publishArgs(args) {
+  const otp = args.find((a) => a.startsWith("--otp="))?.slice(6);
+  return ["publish", "--ignore-scripts", ...(args.includes("--provenance") ? ["--provenance"] : []), ...(otp ? [`--otp=${otp}`] : [])];
+}
+
+/**
+ * KJC-TSK-1359: the CI publish job holds the OIDC token and installs nothing, so it skips
+ * verify-pack (which installs the tarball and runs its scripts); the verify job ran --pack-only.
+ */
+export function shouldVerify(args) {
+  if (!args.includes("--no-verify")) return true;
+  if (!args.includes("--publish")) throw new Error("dual-publish: --no-verify only goes with --publish; --pack-only always verifies");
+  return false;
+}
+
 // argv[1] normalizado (catch de codex): node lo absolutiza hoy, pero el
 // guard no debe depender de ese detalle de implementación.
 const isMain = process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
@@ -50,13 +67,12 @@ if (isMain) {
   const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
   const args = process.argv.slice(2);
   const publish = args.includes("--publish");
-  const otp = args.find((a) => a.startsWith("--otp="))?.slice(6);
   await withScopedName(repoRoot, async () => {
     console.log(`dual-publish: manifest → ${SCOPED_NAME} (temporal)`);
     // La E2E real: empaqueta el scoped, instálalo aislado y corre kj.
-    execFileSync("node", [join(repoRoot, "scripts", "verify-pack.mjs")], { cwd: repoRoot, stdio: "inherit" });
+    if (shouldVerify(args)) execFileSync("node", [join(repoRoot, "scripts", "verify-pack.mjs")], { cwd: repoRoot, stdio: "inherit" });
     if (publish) {
-      const pubArgs = ["publish", "--ignore-scripts", ...(otp ? [`--otp=${otp}`] : [])];
+      const pubArgs = publishArgs(args);
       console.log(`dual-publish: npm ${pubArgs.join(" ").replace(/--otp=\S+/, "--otp=***")}`);
       execFileSync("npm", pubArgs, { cwd: repoRoot, stdio: "inherit" });
     } else {

package/scripts/postinstall.js

@@ -7,6 +7,7 @@
  * - Idempotent: safe to run many times.
  * - Never fails hard (exits 0 even on error) so `npm install` is not blocked.
  */
+import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -38,10 +39,22 @@ const CLAUDE_JSON_PATH = path.join(os.homedir(), ".claude.json");
 const isPackageDirHome = (home) => /node_modules[\\/]karajan-code[\\/]\.karajan[\\/]?$/.test(home)
   || path.resolve(home) === path.join(ROOT_DIR, ".karajan");
 
+// KJC-BUG-0404: the .karajan of a git working tree is a project's own state (ADR 0032). Taken as
+// the home, every project's home data (audits, stories, board) landed in that repo.
+function isProjectKarajanDir(home) {
+  const dir = path.resolve(home);
+  if (path.basename(dir) !== ".karajan" || path.dirname(dir) === os.homedir()) return false;
+  if (!existsSync(path.join(path.dirname(dir), ".git"))) return false;
+  process.stderr.write(`karajan-mcp: ${dir} is a project's .karajan, not a Karajan home; ignoring it\n`);
+  return true;
+}
+
+const usableHome = (home) => Boolean(home) && !isPackageDirHome(home) && !isProjectKarajanDir(home);
+
 /** The home a previous registration carried, if the user (not this script) set it. */
 function homeFromExistingEntry(entry) {
   const previous = entry?.env?.KARAJAN_HOME || entry?.env?.KJ_HOME;
-  return previous && !isPackageDirHome(previous) ? previous : null;
+  return usableHome(previous) ? previous : null;
 }
 
 /**
@@ -58,7 +71,7 @@ async function resolveKjHome(existingEntry) {
     const names = Object.keys(registry.instances || {});
     if (names.length > 0) {
       const first = registry.instances[names.includes("default") ? "default" : names[0]];
-      if (first?.kjHome) return first.kjHome;
+      if (usableHome(first?.kjHome)) return first.kjHome;
     }
   } catch {
     // No registry yet — use default

package/scripts/verify-pack-mcp.mjs

@@ -1,7 +1,8 @@
 /**
  * MCP smoke for verify-pack (KJC-TSK-0844) — the karajan-mcp server of the
  * INSTALLED tarball is started over stdio with the SDK client and exercised
- * with kj_status, kj_config and kj_review, no LLM involved. The MCP surface
+ * with kj_config and kj_code, no LLM involved; kj_run, retired in 5.0
+ * (KJC-TSK-1318), must answer with its retirement notice. The MCP surface
  * was only proved by tests with every seam mocked and dogfooded by no
  * development session; KJC-BUG-0175 (taskFile promised, never read) and
  * KJC-BUG-0176 (kjHome declared, ignored) both shipped through that gap.
@@ -17,7 +18,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 
 const FATAL = [/Missing required field/i, /Config file not found/i, /taskFile read failed/i, /Unknown tool/i];
-const TOOLS = ["kj_status", "kj_config", "kj_review"];
+const TOOLS = ["kj_config", "kj_code"];
 
 /** The text of a tool answer, and whether it is a failure of the contract (not of the environment). */
 export function classifyAnswer(tool, text) {
@@ -58,15 +59,18 @@ export async function mcpSmoke({ serverPath, kjHome, projectDir, taskFile, env =
     const listed = new Set((await client.listTools()).tools.map((t) => t.name));
     for (const t of TOOLS) if (!listed.has(t)) findings.push(`${t} is not listed by the server`);
     if (findings.length > 0) return { ok: false, findings, answers };
-    // A project that never ran has no run log: that answer is the contract, not a refusal.
-    const status = await call("kj_status", { kjHome, projectDir, lines: 5 });
-    if (status.gated && !/no active run log/i.test(status.reason)) findings.push(`kj_status refused: ${status.reason}`);
     const config = await call("kj_config", { kjHome, json: true });
     if (config.gated) findings.push(`kj_config refused: ${config.reason}`);
     // The task travels ONLY as a file: the handler must read it before any
-    // gate. The reviewer is a name no machine has, so the gate stops the call
+    // gate. The coder is a name no machine has, so the gate stops the call
     // before a single LLM token, on a laptop with real agents as much as in CI.
-    await call("kj_review", { kjHome, projectDir, taskFile, reviewer: "kj-verify-stub" });
+    const code = await call("kj_code", { kjHome, projectDir, taskFile, coder: "kj-verify-stub" });
+    // Its gate: the bootstrap on a runner with no agent CLI (CI), the unknown coder anywhere else.
+    // Both come after the taskFile is read; an answer that is not a refusal ran something.
+    if (!code.gated || !/Unsupported agent: kj-verify-stub|BOOTSTRAP FAILED/.test(code.reason)) findings.push(`kj_code did not stop at its gate with the stub coder: ${code.reason ?? "it answered ok"}`);
+    // KJC-TSK-1318: a retired tool says so and points at the migration guide.
+    const retired = await call("kj_run", { kjHome, projectDir, task: "x" });
+    if (!/^kj run was retired in 5\.0/.test(retired.reason ?? "")) findings.push(`kj_run did not answer with its retirement notice: ${retired.reason}`);
   } catch (err) {
     findings.push(`MCP session failed: ${err.message}`);
   } finally {

package/scripts/verify-pack.mjs

@@ -253,10 +253,10 @@ try {
   // (a symlinked virtual store), so it can break resolution of the bundled
   // karajan-core the way npm packaging breakage did before (KJC-BUG-0082/0086).
   // Verify a pnpm install resolves the JS tree and `kj --version` boots — every
-  // release catches a pnpm packaging regression. (pnpm also blocks
-  // better-sqlite3's native build by default, so DB-backed commands need
-  // `pnpm approve-builds`; that's surfaced as a doctor warning, KJC-BUG-0092 —
-  // not a gate failure, since it's inherent to pnpm.) Auto-skips without pnpm.
+  // release catches a pnpm packaging regression. (pnpm also blocks node-pty's
+  // native build by default, so the HU Board terminal needs `pnpm approve-builds`;
+  // that's surfaced as a doctor warning, KJC-BUG-0092 / KJC-TSK-1353 — not a gate
+  // failure, since it's inherent to pnpm.) Auto-skips without pnpm.
   // KJC-BUG-0135: `npm run` leaks npm_config_* into the child env, and pnpm
   // maps those variables onto its own config — which can re-anchor it to THIS
   // repo (7-aug incident: the repo's node_modules converted to pnpm layout,

package/src/audit/audit-history.js

@@ -1,7 +1,8 @@
 // KJC-TSK-0472 — Per-project audit history (sqlite at .karajan/audit-history.db).
 import path from "node:path";
 import fs from "node:fs";
-import Database from "better-sqlite3";
+// KJC-TSK-0618 (SQL-D): karajan-core's adapter over node:sqlite, built into Node.
+import { openDatabase } from "karajan-core/db";
 
 const SCHEMA_VERSION = 1;
 
@@ -12,7 +13,7 @@ export function getAuditHistoryDbPath(projectDir) {
 export function openAuditHistoryDb(projectDir) {
   const dbPath = getAuditHistoryDbPath(projectDir);
   fs.mkdirSync(path.dirname(dbPath), { recursive: true });
-  const db = new Database(dbPath);
+  const db = openDatabase(dbPath);
   db.pragma("journal_mode = WAL");
   migrate(db);
   return db;

package/src/audit/dead-exports.js

@@ -93,6 +93,68 @@ function resolveKnipBin() {
   return path.join(knipRoot, "bin", "knip.js");
 }
 
+// The ephemeral knip config for the entrypoints kj can vouch for. A project with
+// its OWN knip config already decided — it is respected. Declaring is
+// best-effort: on any error the default scan still runs.
+async function declareEntrypoints(projectDir, config) {
+  try {
+    const eps = await resolveProjectEntrypoints(projectDir, config);
+    if (eps && !(await hasOwnKnipConfig(projectDir))) {
+      const cfgPath = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "kj-knip-")), "knip.json");
+      await fs.writeFile(cfgPath, JSON.stringify(buildEphemeralKnipConfig(eps)));
+      return { configArgs: ["--config", cfgPath], declaredEntrypoints: eps };
+    }
+  } catch { /* declaring is best-effort; the default scan still runs */ }
+  return { configArgs: [], declaredEntrypoints: null };
+}
+
+async function runKnip(args, projectDir, logger) {
+  try {
+    const { stdout } = await execFileAsync(
+      process.execPath,
+      args,
+      { cwd: projectDir, timeout: SCAN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 },
+    );
+    return { raw: stdout };
+  } catch (err) {
+    // knip exits non-zero when issues are found; with --no-exit-code that
+    // should not happen, but old configs might still trigger it. If the
+    // process produced JSON on stdout we still try to parse it.
+    const raw = err?.stdout || "";
+    if (raw) return { raw };
+    logger?.warn?.(`audit/dead-exports: knip failed (${err?.message || err})`);
+    return { failure: { available: false, reason: `knip run failed: ${err?.shortMessage || err?.message || err}` } };
+  }
+}
+
+// One knip file entry → its unused exports, then its unused types.
+function deadExportIssuesOf(fi) {
+  const file = fi.file || fi.filePath || "";
+  if (!file) return [];
+  const exportIssues = (fi.exports || []).map((ex) => ({
+    tool: "knip",
+    rule: "unused-exports",
+    component: file,
+    path: file,
+    line: ex.line || 1,
+    col: ex.col,
+    name: ex.name,
+    severity: "MINOR",
+    message: `Unused export \`${ex.name}\` in ${file}`,
+  }));
+  const typeIssues = (fi.types || []).map((t) => ({
+    tool: "knip",
+    rule: "unused-types",
+    component: file,
+    path: file,
+    line: t.line || 1,
+    name: t.name,
+    severity: "MINOR",
+    message: `Unused type \`${t.name}\` in ${file}`,
+  }));
+  return [...exportIssues, ...typeIssues];
+}
+
 /**
  * Collect dead-exports findings for a project.
  *
@@ -116,36 +178,12 @@ export async function collectDeadExports(projectDir, stack, config = {}, logger
   }
 
   const args = [knipBin, "--reporter", "json", "--no-progress", "--no-exit-code"];
-  let declaredEntrypoints = null;
-  try {
-    const eps = await resolveProjectEntrypoints(projectDir, config);
-    // a project with its OWN knip config already decided — it is respected
-    if (eps && !(await hasOwnKnipConfig(projectDir))) {
-      const cfgPath = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "kj-knip-")), "knip.json");
-      await fs.writeFile(cfgPath, JSON.stringify(buildEphemeralKnipConfig(eps)));
-      args.push("--config", cfgPath);
-      declaredEntrypoints = eps;
-    }
-  } catch { /* declaring is best-effort; the default scan still runs */ }
+  const { configArgs, declaredEntrypoints } = await declareEntrypoints(projectDir, config);
+  args.push(...configArgs);
 
-  let raw;
-  try {
-    const { stdout } = await execFileAsync(
-      process.execPath,
-      args,
-      { cwd: projectDir, timeout: SCAN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 },
-    );
-    raw = stdout;
-  } catch (err) {
-    // knip exits non-zero when issues are found; with --no-exit-code that
-    // should not happen, but old configs might still trigger it. If the
-    // process produced JSON on stdout we still try to parse it.
-    raw = err?.stdout || "";
-    if (!raw) {
-      logger?.warn?.(`audit/dead-exports: knip failed (${err?.message || err})`);
-      return { available: false, reason: `knip run failed: ${err?.shortMessage || err?.message || err}` };
-    }
-  }
+  const run = await runKnip(args, projectDir, logger);
+  if (run.failure) return run.failure;
+  const { raw } = run;
 
   let report;
   try {
@@ -158,36 +196,7 @@ export async function collectDeadExports(projectDir, stack, config = {}, logger
   const unusedFiles = Array.isArray(report.files) ? report.files : [];
   const fileIssues = Array.isArray(report.issues) ? report.issues : [];
 
-  const deadExportIssues = [];
-  for (const fi of fileIssues) {
-    const file = fi.file || fi.filePath || "";
-    if (!file) continue;
-    for (const ex of fi.exports || []) {
-      deadExportIssues.push({
-        tool: "knip",
-        rule: "unused-exports",
-        component: file,
-        path: file,
-        line: ex.line || 1,
-        col: ex.col,
-        name: ex.name,
-        severity: "MINOR",
-        message: `Unused export \`${ex.name}\` in ${file}`,
-      });
-    }
-    for (const t of fi.types || []) {
-      deadExportIssues.push({
-        tool: "knip",
-        rule: "unused-types",
-        component: file,
-        path: file,
-        line: t.line || 1,
-        name: t.name,
-        severity: "MINOR",
-        message: `Unused type \`${t.name}\` in ${file}`,
-      });
-    }
-  }
+  const deadExportIssues = fileIssues.flatMap(deadExportIssuesOf);
 
   const unusedFileIssues = unusedFiles.map((f) => ({
     tool: "knip",

package/src/audit/deterministic-summary.js

@@ -40,6 +40,7 @@ export function formatDeterministicSummary(ctx) {
   if (ctx.osvFindings) lines.push(...formatOsvBlock(ctx.osvFindings));
   if (ctx.semgrepFindings) lines.push(...formatSemgrepBlock(ctx.semgrepFindings));
   if (ctx.infraFindings) lines.push(...formatInfraBlock(ctx.infraFindings));
+  if (ctx.npmSignatures) lines.push(...formatNpmSignaturesBlock(ctx.npmSignatures));
   if (ctx.circularDeps) lines.push(...formatCircularDepsBlock(ctx.circularDeps));
   if (ctx.deadExports) lines.push(...formatDeadExportsBlock(ctx.deadExports));
   if (ctx.injectionFindings) lines.push(...formatInjectionBlock(ctx.injectionFindings));
@@ -159,6 +160,22 @@ function formatSemgrepBlock(semgrepFindings) {
 
 // INF-C (KJC-TSK-0760): checkov misconfigs — same shape as the semgrep
 // block; a not-applicable repo (no infra markers) declares it in one line.
+// KJC-TSK-1253: an invalid signature is a tampered package; a missing one, a package the registry cannot vouch for.
+function formatNpmSignaturesBlock(sigs) {
+  if (!sigs.available) return ["### npm signatures", `- Status: not available — ${sigs.reason}`, ""];
+  const lines = ["### npm signatures"];
+  const list = (title, pkgs) => {
+    if (!pkgs.length) return;
+    lines.push(`  - ${title} (${pkgs.length}):`);
+    for (const p of pkgs.slice(0, MAX_SAMPLE_SEMGREP_PER_SEVERITY * 3)) lines.push(`    - ${p.name}@${p.version}`);
+  };
+  if (!sigs.invalid.length && !sigs.missing.length) lines.push("- Every installed dependency has a valid registry signature");
+  list("Invalid signature", sigs.invalid);
+  list("No signature", sigs.missing);
+  lines.push("");
+  return lines;
+}
+
 function formatInfraBlock(infraFindings) {
   if (!infraFindings.available) {
     return ["### Infra misconfigurations (checkov)", `- Status: not available — ${infraFindings.reason || "checkov not installed"}`, ""];
@@ -350,17 +367,20 @@ function formatWebperfBlock(webperf) {
  */
 export function deterministicContextHasFindings(ctx) {
   if (!ctx) return false;
-  if (ctx.basalCost?.deadExports?.length > 0) return true;
-  if (ctx.basalCost?.unusedDependencies?.unused?.length > 0) return true;
-  if (ctx.sonarFindings?.available && (ctx.sonarFindings.total ?? 0) > 0) return true;
-  if (ctx.sonarFindings?.qualityGate?.status === "ERROR") return true;
-  if (ctx.osvFindings?.available && (ctx.osvFindings.total ?? 0) > 0) return true;
-  if (ctx.semgrepFindings?.available && (ctx.semgrepFindings.total ?? 0) > 0) return true;
-  if (ctx.infraFindings?.available && (ctx.infraFindings.total ?? 0) > 0) return true;
-  if (ctx.circularDeps?.available && (ctx.circularDeps.total ?? 0) > 0) return true;
-  if (ctx.deadExports?.available && (ctx.deadExports.total ?? 0) > 0) return true;
-  if (ctx.growthDelta && (Math.abs(ctx.growthDelta.lines || 0) > 100 || Math.abs(ctx.growthDelta.deps || 0) > 0)) return true;
-  if (ctx.aiSlop?.available && (ctx.aiSlop.total ?? 0) > 0) return true;
-  if (ctx.envKeys?.available && ((ctx.envKeys.divergent?.length ?? 0) + (ctx.envKeys.incomplete?.length ?? 0)) > 0) return true;
-  return false;
+  return FINDING_SIGNALS.some((signal) => signal(ctx));
 }
+
+// Sections that report a `total` once collected.
+const COUNTED_SECTIONS = ["sonarFindings", "osvFindings", "semgrepFindings", "infraFindings", "circularDeps", "deadExports", "aiSlop"];
+const hasCount = (section) => Boolean(section?.available) && (section.total ?? 0) > 0;
+const grewNoticeably = (delta) => Boolean(delta) && (Math.abs(delta.lines || 0) > 100 || Math.abs(delta.deps || 0) > 0);
+const envKeysDiverge = (envKeys) => Boolean(envKeys?.available) && ((envKeys.divergent?.length ?? 0) + (envKeys.incomplete?.length ?? 0)) > 0;
+
+const FINDING_SIGNALS = [
+  (ctx) => ctx.basalCost?.deadExports?.length > 0,
+  (ctx) => ctx.basalCost?.unusedDependencies?.unused?.length > 0,
+  (ctx) => ctx.sonarFindings?.qualityGate?.status === "ERROR",
+  (ctx) => COUNTED_SECTIONS.some((key) => hasCount(ctx[key])),
+  (ctx) => grewNoticeably(ctx.growthDelta),
+  (ctx) => envKeysDiverge(ctx.envKeys),
+];

package/src/audit/npm-signatures.js

@@ -0,0 +1,41 @@
+/**
+ * KJC-TSK-1253: npm registry signatures and provenance of the installed dependencies, for
+ * `kj audit` and `kj audit --security`. `npm audit signatures` checks every installed package
+ * against the registry's signing keys (and its Sigstore provenance when published with it):
+ * an invalid signature means a tampered package, a missing one a package the registry cannot
+ * vouch for. Same best-effort shape as osv-findings: when it does not apply or cannot run, the
+ * section says why and the audit goes on.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { runGoverned } from "../utils/tool-governor.js";
+
+const TIMEOUT_MS = 60_000;
+const pick = (list) => (Array.isArray(list) ? list.map((p) => ({ name: p?.name ?? "?", version: p?.version ?? "?" })) : []);
+
+/** @returns {Promise<{available: boolean, reason?: string, invalid?: {name, version}[], missing?: {name, version}[]}>} */
+export async function collectNpmSignatures(projectDir, logger = null) {
+  if (!existsSync(join(projectDir, "package-lock.json")) || !existsSync(join(projectDir, "node_modules"))) {
+    return { available: false, reason: "not an installed npm project (needs package-lock.json and node_modules)" };
+  }
+  // Same kill-switch as the other scanners: never from the unit suite without the opt-in.
+  if (process.env.VITEST && process.env.KJ_ALLOW_REAL_SCANS !== "1") {
+    return { available: false, reason: "real scans disabled under the test runner (set KJ_ALLOW_REAL_SCANS=1 to opt in)" };
+  }
+  let stdout;
+  try {
+    ({ stdout } = await runGoverned("npm", ["audit", "signatures", "--json"], { cwd: projectDir, timeout: TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }));
+  } catch (err) {
+    // npm exits non-zero when a signature is invalid or missing: its JSON is still the answer.
+    if (err.code === "ENOENT") return { available: false, reason: "npm not found in PATH" };
+    if (err.killed) return { available: false, reason: `npm audit signatures timed out after ${TIMEOUT_MS}ms` };
+    stdout = err.stdout;
+  }
+  try {
+    const parsed = JSON.parse(stdout);
+    return { available: true, invalid: pick(parsed.invalid), missing: pick(parsed.missing) };
+  } catch {
+    logger?.warn?.("npm audit signatures: output not parseable as JSON");
+    return { available: false, reason: "npm audit signatures output not parseable as JSON" };
+  }
+}

package/src/audit/sbom.js

@@ -0,0 +1,35 @@
+/**
+ * KJC-TSK-1255: kj audit --sbom <file>. The CycloneDX SBOM of an npm project's production
+ * dependencies, as npm itself builds it from the lockfile (no node_modules needed). Written
+ * atomically: a failed run leaves no file, never a half one.
+ */
+import { existsSync } from "node:fs";
+import { rename, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { runGoverned } from "../utils/tool-governor.js";
+
+const TIMEOUT_MS = 60_000;
+const firstLine = (text) => String(text ?? "").trim().split("\n")[0];
+
+/** @returns {Promise<{file: string, components: number}>} */
+export async function writeSbom({ projectDir, file, run = runGoverned }) {
+  if (!existsSync(join(projectDir, "package-lock.json"))) {
+    throw new Error("--sbom needs an npm project with package-lock.json; other ecosystems are not covered yet");
+  }
+  let stdout;
+  try {
+    ({ stdout } = await run("npm", ["sbom", "--sbom-format", "cyclonedx", "--omit", "dev", "--package-lock-only"], { cwd: projectDir, timeout: TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024 }));
+  } catch (err) {
+    let why = firstLine(err.stderr) || err.message;
+    if (err.code === "ENOENT") why = "npm not found in PATH";
+    else if (err.killed) why = `timed out after ${TIMEOUT_MS}ms`;
+    throw new Error(`npm sbom failed: ${why}`, { cause: err });
+  }
+  let doc;
+  try { doc = JSON.parse(stdout); } catch { doc = null; }
+  if (doc?.bomFormat !== "CycloneDX") throw new Error("npm sbom output is not a CycloneDX document");
+  const target = resolve(projectDir, file);
+  await writeFile(`${target}.tmp`, stdout);
+  await rename(`${target}.tmp`, target);
+  return { file: target, components: Array.isArray(doc.components) ? doc.components.length : 0 };
+}

package/src/checks/agent-token.js

@@ -0,0 +1,112 @@
+/**
+ * Agent token check (KJC-TSK-1268, ADR 0037).
+ *
+ * The agent works with whatever token `gh` uses. ADR 0037 asks for a fine-grained token without
+ * Administration or Deployments, so the agent can neither change branch protection nor approve
+ * a protected environment such as npm-publish. Two probes that change nothing tell:
+ * - reading the default branch's protection needs Administration;
+ * - reviewing pending deployments of a run that does not exist is refused (403) without
+ *   Deployments write, and answers 404/422 with it.
+ */
+
+import { execFileSync } from "node:child_process";
+
+import { STRATEGY } from "./types.js";
+
+const FIX = "Give the agent a fine-grained token with no Administration, Environments, Secrets, Variables or Deployments "
+  + "(github.com/settings/personal-access-tokens/new), load it with `gh auth login --with-token`, revoke the old one "
+  + "and do admin acts in the browser (ADR 0037)";
+
+const OWNER_REPO = /^\/?([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/;
+
+/** owner/repo of a GitHub remote, or null: exact host github.com, or an ssh alias github.com-<name>. */
+export function parseGithubRepo(url) {
+  const text = String(url ?? "").trim();
+  const scp = /^[\w.-]+@github\.com(?:-[\w.-]+)?:(.+)$/.exec(text);
+  let path = scp?.[1];
+  if (!path) {
+    try {
+      const parsed = new URL(text);
+      if (!["https:", "ssh:"].includes(parsed.protocol) || !/^github\.com(?:-[\w.-]+)?$/.test(parsed.hostname)) return null;
+      if (parsed.protocol === "https:" && parsed.hostname !== "github.com") return null;
+      path = parsed.pathname;
+    } catch {
+      return null;
+    }
+  }
+  const match = OWNER_REPO.exec(path);
+  return match ? `${match[1]}/${match[2]}` : null;
+}
+
+function defaultOriginUrl(projectDir) {
+  try {
+    return execFileSync("git", ["remote", "get-url", "origin"], { cwd: projectDir, encoding: "utf8", timeout: 10_000 });
+  } catch {
+    return null;
+  }
+}
+
+/** `gh api` as data: the HTTP status gh reports and the JSON body, success or not. */
+async function defaultGh(args) {
+  try {
+    return { status: 200, body: JSON.parse(execFileSync("gh", ["api", ...args], { encoding: "utf8", timeout: 20_000, stdio: "pipe" }) || "{}") };
+  } catch (err) {
+    const status = Number(/\(HTTP (\d{3})\)/.exec(String(err.stderr ?? ""))?.[1]);
+    if (!status) throw err;
+    let body = {};
+    try { body = JSON.parse(String(err.stdout ?? "") || "{}"); } catch { /* gh printed no JSON body */ }
+    return { status, body };
+  }
+}
+
+/** true/false for the answers each probe expects; anything else (401, 5xx...) cannot be read. */
+function hasAdmin({ status, body }) {
+  if (status === 200) return true;
+  if (status === 404) return /not protected/i.test(body?.message ?? "");
+  if (status === 403) return false;
+  throw new Error(`branch protection probe answered HTTP ${status}`);
+}
+
+function canApprove({ status }) {
+  if (status === 404 || status === 422) return true;
+  if (status === 403) return false;
+  throw new Error(`deployment review probe answered HTTP ${status}`);
+}
+
+async function defaultBranchOf(gh, repo) {
+  const { status, body } = await gh([`repos/${repo}`]);
+  if (status !== 200 || !body?.default_branch) throw new Error(`reading ${repo} answered HTTP ${status}`);
+  return body.default_branch;
+}
+
+export function createAgentTokenCheck({ projectDir = process.cwd(), originUrl = () => defaultOriginUrl(projectDir), gh = defaultGh } = {}) {
+  return {
+    name: "agent-token",
+    label: "agent's GitHub token (no admin power)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const repo = parseGithubRepo(originUrl());
+      if (!repo) return { ok: true, severity: "info", detail: "no GitHub origin: nothing to check" };
+      try {
+        const branch = await defaultBranchOf(gh, repo);
+        const powers = [];
+        if (hasAdmin(await gh([`repos/${repo}/branches/${encodeURIComponent(branch)}/protection`]))) {
+          powers.push("it holds the Administration permission (it reads branch protection; ADR 0037 allows it at no level, since write changes protection and settings)");
+        }
+        const probe = ["-X", "POST", `repos/${repo}/actions/runs/1/pending_deployments`, "-F", "environment_ids[]=0", "-f", "state=rejected", "-f", "comment=kj doctor probe"];
+        if (canApprove(await gh(probe))) powers.push("it can approve protected environments (Deployments write)");
+        if (powers.length === 0) return { ok: true, severity: "info", detail: `the token gh uses has no admin power over ${repo}` };
+        return { ok: false, severity: "warn", detail: `the token gh uses on ${repo}: ${powers.join("; ")}`, fix: FIX };
+      } catch (err) {
+        const reason = `${err?.code ?? ""} ${err?.stderr ?? ""} ${err?.message ?? err}`;
+        // No gh, or gh with no token: the agent holds no GitHub power to check.
+        if (/ENOENT|gh auth login|not logged in/i.test(reason)) return { ok: true, severity: "info", detail: "gh has no GitHub token here: nothing to check" };
+        return { ok: false, severity: "warn", detail: `could not check the token gh uses: ${String(err?.message || err).split("\n")[0]}`, fix: FIX };
+      }
+    },
+  };
+}
+
+export function getAgentTokenChecks({ projectDir } = {}) {
+  return [createAgentTokenCheck({ projectDir })];
+}

package/src/checks/ai-surface.js

@@ -11,11 +11,13 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { claudeConfigFile, codexHome } from "../utils/agent-home.js";
 
-const sources = (projectDir, home) => [
+// KJC-TSK-1344: claude and codex configs of the account CLAUDE_CONFIG_DIR / CODEX_HOME select.
+const sources = (projectDir, home, env = process.env) => [
   { file: path.join(projectDir, ".mcp.json"), format: "json" },
-  { file: path.join(home, ".claude.json"), format: "json" },
-  { file: path.join(home, ".codex", "config.toml"), format: "toml" },
+  { file: claudeConfigFile({ home, env }), format: "json" },
+  { file: path.join(codexHome({ home, env }), "config.toml"), format: "toml" },
   { file: path.join(home, ".gemini", "settings.json"), format: "json" },
 ];
 
@@ -34,9 +36,9 @@ const tomlServerNames = (text) =>
   new Set([...text.matchAll(/^\s*\[mcp_servers\.["']?([^\]"']+)["']?\]/gm)].map((m) => m[1]));
 
 /** Sorted `name (config-file)` entries for every MCP reachable in this project. */
-export function collectAiSurface({ projectDir = process.cwd(), home = os.homedir() } = {}) {
+export function collectAiSurface({ projectDir = process.cwd(), home = os.homedir(), env = process.env } = {}) {
   const surface = new Set();
-  for (const { file, format } of sources(projectDir, home)) {
+  for (const { file, format } of sources(projectDir, home, env)) {
     if (!existsSync(file)) continue;
     let text;
     try { text = readFileSync(file, "utf8"); } catch { continue; }
@@ -50,11 +52,11 @@ export function collectAiSurface({ projectDir = process.cwd(), home = os.homedir
  * Diff the current surface against the last-seen snapshot and persist the
  * new state. First run records the baseline silently.
  */
-export function checkAiSurface({ projectDir = process.cwd(), home = os.homedir(), statePath = path.join(os.homedir(), ".karajan", "ai-surface.json"), extraSurface = [] } = {}) {
+export function checkAiSurface({ projectDir = process.cwd(), home = os.homedir(), env = process.env, statePath = path.join(os.homedir(), ".karajan", "ai-surface.json"), extraSurface = [] } = {}) {
   // KJC-TSK-0728: extraSurface carries entries the (async) caller collected
   // outside config files — e.g. observed agent CLIs as "grok (cli)" — so
   // they ride the same snapshot and the same "NEW since last check" drift.
-  const surface = [...new Set([...collectAiSurface({ projectDir, home }), ...extraSurface])].sort();
+  const surface = [...new Set([...collectAiSurface({ projectDir, home, env }), ...extraSurface])].sort();
   let state = {};
   try { state = JSON.parse(readFileSync(statePath, "utf8")); } catch { /* first run or corrupt → baseline */ }
   const prev = Array.isArray(state[projectDir]) ? state[projectDir] : null;