@karajan-family/code 4.70.1 → 4.70.3

package/package.json

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

package/src/checks/native-build.js

@@ -9,8 +9,43 @@
  * WARN in `kj doctor` with the exact remedy instead of a cryptic runtime crash.
  */
 
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { STRATEGY } from "./types.js";
 
+// kj's own package root: where npm keeps its dependencies' approvals and builds.
+const OWN_PKG_DIR = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+
+/** npm's major version, or null when npm is not there to ask. */
+function defaultNpmMajor() {
+  try {
+    return Number.parseInt(execFileSync("npm", ["--version"], { encoding: "utf8", timeout: 10_000 }), 10) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * KJC-BUG-0426 (issue #2670): npm 12 runs a dependency's install script only when
+ * allowScripts covers it; reinstalling blocks it again. Approve, then rebuild, in kj's dir.
+ */
+export const npmAllowScriptsRemedy = (pkgDir = OWN_PKG_DIR) =>
+  `cd "${pkgDir}" && npm install-scripts approve better-sqlite3 && npm install-scripts approve node-pty && npm rebuild better-sqlite3 node-pty`;
+
+// The addon is installed but its native build is missing (a missing package needs a reinstall, not this).
+const UNBUILT_ADDON = /bindings file|better_sqlite3\.node/;
+
+/** A missing better-sqlite3 addon becomes an error that says how to build it; any other error passes as it is. */
+export function explainNativeLoadError(err, { npmMajor = defaultNpmMajor, pkgDir = OWN_PKG_DIR } = {}) {
+  if (!UNBUILT_ADDON.test(String(err?.message ?? err))) return err;
+  const remedy = (npmMajor() ?? 0) >= 12
+    ? `npm 12 skipped its install script (allowScripts); build it with: ${npmAllowScriptsRemedy(pkgDir)}`
+    : "run kj doctor for the exact fix on this install";
+  return new Error(`better-sqlite3 native addon is not built, so the RAG cannot open its index — ${remedy}`, { cause: err });
+}
+
 /** pnpm lays packages out under a `.pnpm` virtual store and symlinks them in. */
 function isPnpmInstall() {
   return (
@@ -25,7 +60,7 @@ async function defaultLoadDb() {
   new Database(":memory:").close();
 }
 
-export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpmInstall } = {}) {
+export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpmInstall, npmMajor = defaultNpmMajor, pkgDir = OWN_PKG_DIR } = {}) {
   return {
     name: "native-build",
     label: "native modules (better-sqlite3)",
@@ -48,6 +83,14 @@ export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpm
             fix: "Approve the build then reinstall: `pnpm approve-builds better-sqlite3` — or install with npm: `npm i -g @karajan-family/code`",
           };
         }
+        if ((npmMajor() ?? 0) >= 12) {
+          return {
+            ok: false,
+            severity: "warn",
+            detail: `better-sqlite3 failed to load: ${firstLine} — npm 12 skips dependency install scripts that allowScripts does not cover, so the native build never ran`,
+            fix: npmAllowScriptsRemedy(pkgDir),
+          };
+        }
         return {
           ok: false,
           severity: "warn",

package/src/cli/register-pipeline.js

@@ -292,6 +292,7 @@ export function registerPipeline(program, { pkgVersion }) {
           const r = await verifyPrReview({ projectDir: config.projectDir || process.cwd(), pr: flags.verifyPr });
           if (r.ok) logger.info(`✓ PR #${flags.verifyPr}: ${r.commits} commit(s), each with its cross-AI verdict`);
           else logger.error(`✗ PR #${flags.verifyPr}:\n  - ${r.problems.join("\n  - ")}`);
+          if (r.sealCommits) logger.info(`  seal commit(s) signed by the roster, a human act with no AI verdict: ${r.sealCommits.join(", ")}`);
           process.exitCode = r.ok ? 0 : 1;
           return;
         }

package/src/commands/harden.js

@@ -25,7 +25,7 @@ import { installHarnessHooks } from "../harden/harness-hooks.js";
 import { installSentinelHooks } from "../harden/sentinel-hooks.js";
 import { installSandbox } from "../harden/sandbox.js";
 import { detectStackRoots } from "../harden/stack-roots.js";
-import { installWorkflows } from "../harden/workflow-engine.js";
+import { installWorkflows, resolveKjPin } from "../harden/workflow-engine.js";
 import { adviseBranchProtection } from "../harden/branch-protection.js";
 import { detectTestFramework } from "../utils/project-detect.js";
 import { ensureIdentity } from "../identity/bootstrap.js";
@@ -97,6 +97,7 @@ export async function hardenCommand({
   // KJC-BUG-0289: the contract files already dirty before anything was generated
   // (kj init captures them before writing its own). What is dirty NOW is the person's.
   contractBefore = null,
+  fetchFn = fetch,
   logger = console,
 } = {}) {
   const dirtyBefore = contractBefore ?? contractChanges(projectDir);
@@ -177,8 +178,11 @@ export async function hardenCommand({
   const withConfig = config && profile !== "minimal";
   const cfg = withConfig ? installConfigsForRoots({ projectDir, roots, dryRun }) : null;
   const withCi = ci && profile !== "minimal";
+  // KJC-BUG-0420: consumer CI installs kj from npm, so the workflows pin a published version.
+  const pin = withCi ? await resolveKjPin({ projectDir, fetchFn }) : null;
+  if (pin?.note) logger.warn?.(`⚠ ${pin.note}`);
   const wf = withCi
-    ? installWorkflows({ projectDir, language: roots[0]?.language ?? null, root: roots[0]?.dir ?? ".", profile, mutation, dryRun })
+    ? installWorkflows({ projectDir, language: roots[0]?.language ?? null, root: roots[0]?.dir ?? ".", profile, mutation, dryRun, kjVersion: pin?.version ?? null })
     : null;
   const withGuidelines = guidelines && profile !== "minimal";
   // KJC-BUG-0199 (issue #1773): the same detected language the workflows and
@@ -219,7 +223,10 @@ export async function hardenCommand({
     const note = c.note ? ` (${c.note})` : "";
     logger.info?.(`  • ${c.file}: ${c.action}${note}`);
   }
-  for (const w of out.workflows) logger.info?.(`  • ${w.file}: ${w.action}`);
+  for (const w of out.workflows) {
+    logger.info?.(`  • ${w.file}: ${w.action}`);
+    if (w.note) logger.warn?.(`⚠ ${w.note}`);
+  }
   for (const g of out.guidelines) {
     logger.info?.(`  • ${g.file}: ${g.action}`);
     // KJC-BUG-0206: quitar reglas no puede leerse como "updated" y nada más.

package/src/commands/pr-size.js

@@ -8,7 +8,7 @@ import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { budgetedAdded } from "../review/loc-budget.js";
+import { budgetedAdded, budgetedNet } from "../review/loc-budget.js";
 
 const git = (projectDir, args) =>
   execFileSync("git", ["-C", projectDir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
@@ -40,12 +40,13 @@ export async function branchSize({ projectDir = process.cwd(), base = "main", ex
     const n = text === "" ? 0 : text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
     numstat += `${n}\t0\t${file}\n`;
   }
-  return { ...budgetedAdded(numstat), base };
+  // KJC-BUG-0434: `net` is what the CI gate and the policy measure; `added` stays for its readers.
+  return { ...budgetedAdded(numstat), net: budgetedNet(numstat).net, base };
 }
 
 export async function prSizeCommand({ config, logger = console, flags = {} }) {
   const s = await branchSize({ projectDir: config?.projectDir || process.cwd(), base: config?.base_branch || "main" });
   if (flags.json) process.stdout.write(`${JSON.stringify(s)}\n`);
-  else logger.info(`pr-size: ${s.added} line(s) added against ${s.base} (${s.testAdded} in tests, ${s.exempt} exempt)`);
+  else logger.info(`pr-size: ${s.net} net line(s) against ${s.base}, as the CI gate counts them (${s.added} added, ${s.testAdded} in tests, ${s.exempt} exempt)`);
   return s;
 }

package/src/commands/review-gate.js

@@ -268,26 +268,28 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     // documentation are exempt — the same rule CI applies. Counting everything
     // here warned 234 lines on a doc-only PR that CI counted at 104, and two
     // implementations of one rule that disagree teach people to trust neither.
-    const { added, exempt, testAdded } = budgetedAdded(numstat);
+    // KJC-BUG-0434: measured NET, as CI and the policy's net_lines_added do — a rewrite in place is not growth.
+    const { added, testAdded } = budgetedAdded(numstat);
+    const { net, exempt } = budgetedNet(numstat);
     // Said out loud: an exemption nobody sees is indistinguishable from a gate
     // that is not looking.
     if (exempt > 0) console.log(`ℓ pr-size: ${exempt} line(s) exempt from the budget (generated output and human docs; AI-rule files always count)`);
-    if (added > sizeIdeal && added <= sizeWarn) {
-      console.log(`ℓ pr-size: ${added} lines added, over the ~${sizeIdeal} ideal, within the ${sizeWarn} limit: allowed, nothing to ask`);
+    if (net > sizeIdeal && net <= sizeWarn) {
+      console.log(`ℓ pr-size: ${net} net lines, over the ~${sizeIdeal} ideal, within the ${sizeWarn} limit: allowed, nothing to ask`);
     }
-    if (added > sizeWarn) {
+    if (net > sizeWarn) {
       // KJC-TSK-0795 AC5: say how much of the weight is the module's OWN tests —
       // partitioning is a decision, and it must never split code from its tests.
-      const split = testAdded > 0 ? ` (${added - testAdded} source + ${testAdded} accompanying tests — partition by feature, never code from its tests)` : "";
+      const split = testAdded > 0 ? ` (${added - testAdded} source + ${testAdded} test lines added — partition by feature, never code from its tests)` : "";
       const sizePolicy = config?.method_gates?.pr_size || "warn";
       // ADR 0015: no env escape — an exception is the user's label on the PR, judged in CI.
       if (sizePolicy === "block") {
-        const reason = `${added} lines added${split} is over the ${sizeWarn}-line limit (${sizeSource}; method_gates.pr_size: block) — partition the work; an exception is your user's large-pr-justified label on the PR`;
+        const reason = `${net} net lines${split} is over the ${sizeWarn}-line limit (${sizeSource}; method_gates.pr_size: block) — partition the work; an exception is your user's large-pr-justified label on the PR`;
         console.log(`✗ pr-size gate: ${reason}`);
         process.exitCode = 1;
         return { verdict: "rejected", reviewer: "pr-size", issues: [{ severity: "high", description: reason }] };
       } else {
-        console.log(`⚠ pr-size: ${added} lines added${split}, over the ${sizeWarn}-line limit (ideal ~${sizeIdeal}, source: ${sizeSource}) — partition the work before committing (method_gates.pr_size: block to harden)`);
+        console.log(`⚠ pr-size: ${net} net lines${split}, over the ${sizeWarn}-line limit (ideal ~${sizeIdeal}, source: ${sizeSource}) — partition the work before committing (method_gates.pr_size: block to harden)`);
       }
     }
   }

package/src/config/loader.js

@@ -119,7 +119,9 @@ export async function loadConfig(projectDir) {
   // a .karajan dir from another repo, edited the wrong file, etc.) and
   // would silently behave like a global config without the defaults
   // people expect. Refuse with an actionable message.
-  if (projectConfig && !globalExists) {
+  // KJC-BUG-0428 (issue #2694): a CI runner never has a global config; there the
+  // team's committed project config sits on the defaults instead.
+  if (projectConfig && !globalExists && !process.env.CI) {
     throw new Error(
       `Local config found at ${getProjectConfigPath(projectDir)} but no global config exists.\n` +
       "Local configs are merged ON TOP of the global one — run `kj init --global` first to create the base."

package/src/git/automation.js

@@ -348,10 +348,11 @@ export async function finalizeGitAutomation({ config, gitCtx, task, logger, sess
     } catch (err) {
       logger.warn(`pr-size: the branch could not be measured (${err.message}); the budget is not checked for this commit`);
     }
-    if (size && size.added > limit) {
-      logger.warn(`pr-size: ${size.added} line(s) added against ${gitCtx.baseBranch}, over the budget of ${limit}: nothing committed. Split the step (several commits, several HUs); the changes stay in the tree`);
-      await addCheckpoint(session, { stage: "git-commit", committed: false, skipped: "over-budget", added: size.added, limit });
-      return { committed: false, branch: gitCtx.branch, prUrl: null, pr: null, commits: [], overBudget: { added: size.added, limit } };
+    // KJC-BUG-0434: net, as the CI gate counts it.
+    if (size && size.net > limit) {
+      logger.warn(`pr-size: ${size.net} net line(s) against ${gitCtx.baseBranch}, over the budget of ${limit}: nothing committed. Split the step (several commits, several HUs); the changes stay in the tree`);
+      await addCheckpoint(session, { stage: "git-commit", committed: false, skipped: "over-budget", added: size.added, net: size.net, limit });
+      return { committed: false, branch: gitCtx.branch, prUrl: null, pr: null, commits: [], overBudget: { added: size.added, net: size.net, limit } };
     }
     // ENV-F1: this path only runs after the pipeline's reviewer approved,
     // so stamp that verdict for the staged diff — the v4 pre-commit gate

package/src/harden/harden-engine.js

@@ -12,7 +12,7 @@ import { join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
 import { runCommand } from "../utils/process.js";
-import { hookBody, PROFILE_HOOKS, SHEBANG, toPortableHooksDir } from "./hook-templates.js";
+import { hookBody, PROFILE_HOOKS, SHEBANG } from "./hook-templates.js";
 
 const BLOCK_VERSION = 1;
 const HOOKS_DIR = join(".karajan", "hooks");
@@ -29,12 +29,12 @@ export function isGitRepo(projectDir) {
  * compara por hash: un fichero con una sola coma manual ya no coincide.
  */
 export function renderCanonicalHook(hook, generation = {}) {
-  const { cmds = {}, baseBranch = null, globalHooksDir = null } = generation;
+  const { cmds = {}, baseBranch = null } = generation;
   const { content } = upsertManagedBlock({
     source: HOOK_PREAMBLE,
     blockId: `hook:${hook}`,
     version: BLOCK_VERSION,
-    body: hookBody(hook, cmds, { globalHooksDir, baseBranch }),
+    body: hookBody(hook, cmds, { baseBranch }),
     style: "hash",
   });
   return content;
@@ -57,22 +57,6 @@ export async function installHooks({
   const hooks = PROFILE_HOOKS[profile];
   if (!hooks) throw new Error(`Unknown harden profile: ${profile}`);
 
-  // KJC-TSK-0645: setting a repo-local hooksPath ECLIPSES the machine's
-  // global hooks dir — personal guards (AI-attribution commit-msg, protected
-  // branch pre-push) would silently stop applying here. Detect the previous
-  // global dir and have every generated hook chain to it. `~` is emitted as
-  // `$HOME` so the committed hook stays portable across machines (the -x
-  // guard silences it where the dir doesn't exist).
-  let globalHooksDir = null;
-  const globalCfg = await runCommand("git", ["config", "--global", "core.hooksPath"], { cwd: projectDir });
-  const rawGlobal = globalCfg.exitCode === 0 ? globalCfg.stdout.trim() : "";
-  if (rawGlobal && rawGlobal !== HOOKS_DIR) {
-    // KJC-BUG-0169: normalize to a machine-independent form HERE (generation,
-    // on the human's machine) so the provenance stores the portable dir and CI
-    // recomputes the SAME bytes — an absolute home path is not verifiable there.
-    globalHooksDir = toPortableHooksDir(rawGlobal);
-  }
-
   const absHooksDir = join(projectDir, HOOKS_DIR);
   const results = [];
   for (const hook of hooks) {
@@ -82,7 +66,7 @@ export async function installHooks({
       source,
       blockId: `hook:${hook}`,
       version: BLOCK_VERSION,
-      body: hookBody(hook, cmds, { globalHooksDir, baseBranch }),
+      body: hookBody(hook, cmds, { baseBranch }),
       style: "hash",
     });
     results.push({ hook, target, action });
@@ -99,5 +83,5 @@ export async function installHooks({
 
   // KJC-BUG-0161: los parámetros con los que SE GENERÓ — lo que la
   // provenance necesita registrar para que CI pueda recomputar y comparar.
-  return { profile, hooksPath: HOOKS_DIR, dryRun, hooks: results, generation: { profile, cmds, baseBranch, globalHooksDir } };
+  return { profile, hooksPath: HOOKS_DIR, dryRun, hooks: results, generation: { profile, cmds, baseBranch } };
 }

package/src/harden/hook-templates.js

@@ -8,8 +8,6 @@
  * is imposed on non-JS repos. See docs/specs/quality-harness.md §5.
  */
 
-import { homedir } from "node:os";
-
 // KJC-TSK-1076: exported so the third-party PR checks apply the same rules.
 export const CONVENTIONAL_TYPES = "feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert";
 export const AI_ATTRIBUTION = "co-authored-by:.*(claude|gpt|copilot|gemini)|(generated|written) (by|with) .*(claude|gpt|copilot)";
@@ -25,32 +23,21 @@ export const PROFILE_HOOKS = {
 
 /** Build the managed body for a single hook. */
 // KJC-TSK-0645: `core.hooksPath .karajan/hooks` eclipses the user's global
-// hooks dir, silently disabling personal guards. When a previous global dir
-// is known, every generated hook ends by chaining its namesake there —
-// guarded, so machines without it are unaffected.
-// KJC-BUG-0161 / 0169 (ADR 0009): a committed hook must not bake a machine's
-// absolute home path — a dir under the home resolves through $HOME so the same
-// generated content is valid on every machine and its provenance stays
-// verifiable IN CI (a different home), with no local filesystem layout leaking
-// into a public repo. Normalization happens ONCE, at generation, on the human's
-// machine; the stored/rendered value is already portable, so a render on any
-// other home (CI) reproduces identical bytes. `home` is injectable for tests.
-export function toPortableHooksDir(dir, home = homedir()) {
-  if (!dir) return dir;
-  if (dir.startsWith("$HOME")) return dir;
-  if (dir.startsWith("~")) return `$HOME${dir.slice(1)}`;
-  if (dir === home || dir.startsWith(`${home}/`)) return `$HOME${dir.slice(home.length)}`;
-  return dir;
-}
-
-function chainToGlobal(hook, globalHooksDir) {
-  if (!globalHooksDir) return [];
-  const dir = toPortableHooksDir(globalHooksDir);
+// hooks dir, silently disabling personal guards. Every generated hook ends by
+// chaining its namesake in the machine's global dir.
+// KJC-BUG-0161 / 0169 (ADR 0009), HU-2762: the dir is looked up when the hook
+// RUNS, never when kj harden ran — so the generated bytes do not depend on the
+// machine (HOME, GIT_CONFIG_GLOBAL), the provenance verifies in CI, and no
+// local filesystem layout leaks into a public repo. `|| true`: the preamble
+// sets `set -e`. `--type=path` expands `~`; the pwd -P test stops a hook from
+// calling itself when the global setting is this repo's own hooks dir.
+function chainToGlobal(hook) {
   // KJC-TSK-1085: pre-push already read the refs from stdin; the chained hook gets them back.
-  const call = hook === "pre-push" ? `printf '%s\\n' "$kj_push_refs" | "${dir}/${hook}" "$@"; rc=$?` : `"${dir}/${hook}" "$@"; rc=$?`;
+  const call = hook === "pre-push" ? `printf '%s\\n' "$kj_push_refs" | "$kj_global/${hook}" "$@"; rc=$?` : `"$kj_global/${hook}" "$@"; rc=$?`;
   return [
-    "# Chain the machine's previous global hook (kj harden keeps it active).",
-    `if [ -x "${dir}/${hook}" ]; then`,
+    "# Chain the machine's global hook, looked up when the hook runs, not when kj harden ran (KJC-TSK-0645, HU-2762).",
+    "kj_global=$(git config --global --type=path --get core.hooksPath 2>/dev/null || true)",
+    `if [ -n "$kj_global" ] && [ -x "$kj_global/${hook}" ] && [ "$(cd "$kj_global" 2>/dev/null && pwd -P)" != "$(cd "$(dirname "$0")" && pwd -P)" ]; then`,
     `  ${call}`,
     '  [ "$rc" -eq 0 ] || exit "$rc"',
     "fi",
@@ -109,8 +96,9 @@ function identityGuard(hook) {
     '  if [ -n "$kj_declared_email" ]; then',
     '    printf "%s\\n" "$kj_push_refs" | while read -r kj_lref kj_lsha kj_rref kj_rsha; do',
     '      case "$kj_lsha" in *[!0]*) ;; *) continue ;; esac',
-    // A new ref: what the PUSH TARGET ($1, the remote git hands the hook) does not have yet.
-    '      case "$kj_rsha" in *[!0]*) kj_new=$(git rev-list "$kj_rsha..$kj_lsha") ;; *) kj_new=$(git rev-list "$kj_lsha" --not --remotes="${1:-origin}") ;; esac',
+    // What the PUSH TARGET ($1, the remote git hands the hook) does not have yet. KJC-BUG-0436:
+    // an existing ref too, or merging main into a pushed branch judges main's own merges.
+    '      case "$kj_rsha" in *[!0]*) kj_new=$(git rev-list "$kj_lsha" --not "$kj_rsha" --remotes="${1:-origin}") ;; *) kj_new=$(git rev-list "$kj_lsha" --not --remotes="${1:-origin}") ;; esac',
     "      for kj_c in $kj_new; do",
     '        kj_who=$(git log -1 --format="%ae %ce" "$kj_c")',
     '        if [ "$kj_who" != "$kj_declared_email $kj_declared_email" ]; then',
@@ -129,8 +117,8 @@ function identityGuard(hook) {
   ];
 }
 
-export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch = null } = {}) {
-  const chain = chainToGlobal(hook, globalHooksDir);
+export function hookBody(hook, cmds = {}, { baseBranch = null } = {}) {
+  const chain = chainToGlobal(hook);
   switch (hook) {
     case "pre-commit": {
       const lines = [...baseBranchGuard(baseBranch), ...identityGuard("pre-commit"), "# Lint + format the working tree with the project's native tools."];

package/src/harden/phone-sign.js

@@ -36,7 +36,9 @@ async function relayConfig(fetchFn) {
 }
 const SIGN_PAGE = "https://karajancode.com/sign";
 const POLL_INTERVAL_MS = 2000;
-const TTL_MS = 60000;
+// KJC-BUG-0432: 60 s was too short to scan, read the files and sign, and the page still said
+// "signed" after kj had given up. 150 s leaves time and stays under the relay's 3 min window.
+const TTL_MS = 150000;
 
 /** Spinner en su sitio (una línea, con \r) solo en TTY; no-op fuera de TTY o en tests. */
 function makeSpinner() {

package/src/harden/published-pin.js

@@ -0,0 +1,34 @@
+/**
+ * published-pin — the karajan-code version a seeded workflow may pin (KJC-BUG-0420).
+ *
+ * A consumer repo's CI installs kj from npm, so the pin must be a published
+ * version. A checkout ahead of npm pins the newest published version that is
+ * not newer than itself; when the registry cannot confirm anything, the
+ * running version stays and the note says so.
+ */
+
+import { isNewerVersion } from "../utils/update-check.js";
+
+const packumentUrl = (name) => `https://registry.npmjs.org/${encodeURIComponent(name)}`;
+
+async function publishedVersions(name, fetchFn) {
+  const res = await fetchFn(packumentUrl(name), { headers: { Accept: "application/vnd.npm.install-v1+json" } });
+  if (!res.ok) throw new Error(`registry responded ${res.status}`);
+  return Object.keys((await res.json()).versions ?? {});
+}
+
+/** @returns {Promise<{version: string, note?: string}>} */
+export async function publishedPin({ name, version, fetchFn = fetch }) {
+  const unconfirmed = (why) => ({ version, note: `could not confirm on npm that ${name}@${version} is published (${why}); the workflow pins it as is` });
+  let published;
+  try {
+    published = await publishedVersions(name, fetchFn);
+  } catch (err) {
+    return unconfirmed(err.message);
+  }
+  if (published.includes(version)) return { version };
+  const older = published.filter((v) => !v.includes("-") && !isNewerVersion(v, version));
+  const newest = older.reduce((best, v) => (best && !isNewerVersion(v, best) ? best : v), null);
+  if (!newest) return unconfirmed("no published version at or below it");
+  return { version: newest, note: `${name}@${version} is not on npm yet; the workflow pins ${newest}, the newest published one` };
+}

package/src/harden/sentinel/posttooluse.mjs

@@ -196,10 +196,12 @@ process.stdin.on("end", () => {
       const ps = spawnSync("kj", ["pr-size", "--json"], { cwd: ROOT, encoding: "utf8", timeout: 5000 });
       let size = null;
       try { size = JSON.parse(String(ps.stdout || "").trim().split(String.fromCharCode(10)).pop()); } catch { size = null; }
-      const crossed = size ? [200, 150].find((t) => size.added > t) : undefined;
+      // KJC-BUG-0435: net lines, as the CI gate counts them; a kj older than 0434 reports only added.
+      const lines = size ? (size.net ?? size.added) : 0;
+      const crossed = size ? [200, 150].find((t) => lines > t) : undefined;
       if (crossed && (s.size_warned || 0) < crossed) {
         s.size_warned = crossed;
-        sizeNote = "karajan sentinel: la rama ya suma " + size.added + " lineas contables (" + size.testAdded + " de tests); " + (crossed >= 200 ? "pasa el limite de 200 del CI: parte antes de seguir" : "pasa de 150: planea la particion ahora, no en el stage");
+        sizeNote = "karajan sentinel: la rama ya suma " + lines + " lineas netas contables (" + size.testAdded + " de tests); " + (crossed >= 200 ? "pasa el limite de 200 del CI: parte antes de seguir" : "pasa de 150: planea la particion ahora, no en el stage");
       }
     }
     const ids = Object.keys(state.sessions);

package/src/harden/sentinel/pretooluse-sentinel.mjs

@@ -13,7 +13,7 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, STATE, branchOf, foreignLane, load, save, session, boardGate, pendingMoves, pendingText } from "./sentinel-lib.mjs";
 // KJC-TSK-0915 (ADR 0014): the shell reader is a real, unit-tested module copied here as is.
-import { isGhIssueCreate, isPublishCommand, optionValues, shellSegments, stripInertQuotes, stripTextOptionValues, stripTextOnlyCommandValues } from "./sentinel-shell.mjs";
+import { isGhIssueCreate, isPublishCommand, isReadOnlyCommand, optionValues, shellSegments, stripInertQuotes, stripTextOptionValues, stripTextOnlyCommandValues } from "./sentinel-shell.mjs";
 import { DISCARD_VERBS, discardOf, foreignLost, removedFiles } from "./sentinel-discard.mjs";
 import { sandboxCovers, shellWrites, writesRepo } from "./sentinel-bash-write.mjs";
 const EDIT_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
@@ -84,8 +84,10 @@ process.stdin.on("end", () => {
     // substitution) cannot be resolved from command text: that vector is
     // caught by the Stop gate's checksum verification, which blocks the turn.
     // KJC-TSK-1114: where the host sandbox denies writing them, the sandbox guards them instead.
+    // KJC-BUG-0425 (ADR 0036): text a command only publishes or stores (a PR description) is not a write.
+    // KJC-BUG-0429: nor is a command made only of known readers (an allow-list, not a write blocklist).
     const SUPERVISOR_PATHS = [".claude/settings.json", ".karajan/hooks", ".karajan/harness"];
-    if (tool === "Bash" && PROTECTED.test(String(input.command || "").replaceAll("\\", "/")) && !sandboxCovers(ROOT, SUPERVISOR_PATHS)) {
+    if (tool === "Bash" && !isReadOnlyCommand(String(input.command || "")) && PROTECTED.test(stripTextOnlyCommandValues(String(input.command || "")).replaceAll("\\", "/")) && !sandboxCovers(ROOT, SUPERVISOR_PATHS)) {
       console.error("karajan sentinel: los ficheros del supervisor no se tocan desde Bash — consultalos con la tool Read/Grep; solo el humano los modifica, fuera de la sesion." + doc("supervisor"));
       process.exit(2);
     }

package/src/harden/sentinel/sentinel-shell.mjs

@@ -174,7 +174,22 @@ const isGitCommit = (words) => {
   return words[0] === "git" && words[i] === "commit";
 };
 
-const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr|handoff)\s+add\b/.test(seg) || isGitCommit(seg.split(/\s+/));
+// KJC-BUG-0425: gh pr/issue/release commands only publish their text to GitHub.
+const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr|handoff)\s+add\b/.test(seg) || /^gh\s+(?:pr|issue|release)\s+(?:create|edit|comment|review)\b/.test(seg) || isGitCommit(seg.split(/\s+/));
+
+// KJC-BUG-0425: a heredoc whose delimiter is quoted expands nothing; read from stdin
+// by a text-only command, it is the text stored or published. The FIRST line equal to
+// the delimiter must be the last one, or the shell would run what follows it.
+const HEREDOC_HEAD = /^([^\n]*?)[ \t]*<<(-?)[ \t]*(['"])([A-Za-z_]\w*)\3[ \t]*$/;
+const READS_STDIN = /(^|\s)(?:--body-file|--notes-file|--file|-F)(?:=|\s+)-(?=\s|$)/;
+const quotedHeredocHead = (cmd) => {
+  const lines = cmd.replace(/\n$/, "").split("\n");
+  const m = lines.length > 1 ? HEREDOC_HEAD.exec(lines[0]) : null;
+  if (!m) return null;
+  const [, head, dash, , delim] = m;
+  const end = lines.findIndex((l, i) => i > 0 && (dash ? l.replace(/^\t+/, "") : l) === delim);
+  return end === lines.length - 1 && READS_STDIN.test(head) ? head : null;
+};
 
 /**
  * KJC-BUG-0354: blank the quoted text values (stripTextOptionValues) only when the
@@ -185,9 +200,10 @@ const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr|handoff)\s+add\b/.test(seg) ||
 export const stripTextOnlyCommandValues = (cmd) => {
   // Only a whole input that is ONE simple text-storage command: a chained
   // segment could follow a shell function that turns the stored text into code.
-  const bare = stripInertQuotes(cmd);
-  if (splitOutsideQuotes(cmd).length !== 1 || /[(){}<>`$\n]/.test(bare) || !isTextOnlyHead(cmd.trim())) return cmd;
-  return stripTextOptionValues(cmd);
+  const line = quotedHeredocHead(cmd) ?? cmd;
+  const bare = stripInertQuotes(line);
+  if (splitOutsideQuotes(line).length !== 1 || /[(){}<>`$\n]/.test(bare) || !isTextOnlyHead(line.trim())) return cmd;
+  return stripTextOptionValues(line);
 };
 
 /** Segments and the ; && || | between them, cut only outside quotes (the pieces join back to cmd). */
@@ -248,5 +264,39 @@ export const withoutRedirections = (words) => {
   return rest;
 };
 
+// KJC-BUG-0429 (ADR 0036): the guards decide by write verb. These readers were picked
+// because no option of theirs writes a file or runs a program; a command made only of
+// them, with output to the session, /dev/null or another descriptor, writes nothing.
+// KJC-BUG-0437: never git, whose reads run what its config names (filters, textconv,
+// diff.external, fsmonitor); the Read tool reads those files instead.
+const READERS = new Set(["cat", "head", "tail", "grep", "egrep", "fgrep", "ls", "wc", "diff", "cmp", "stat", "jq", "sha256sum", "sha1sum", "md5sum"]);
+
+const REDIRECTION = /^(\d*)(>>|>&|>\||>|<)(.*)$/;
+const quietRedirections = (words) => words.every((w, i) => {
+  const m = REDIRECTION.exec(w);
+  if (!m) return true;
+  const [, , op, glued] = m;
+  const target = glued || words[i + 1] || "";
+  if (op === "<") return target !== "";
+  if (op === ">&") return /^\d$/.test(target);
+  return (op === ">" || op === ">>") && target === "/dev/null";
+});
+
+/**
+ * Whether the command only reads: every simple command is a known reader and no
+ * output goes to a file. Substitution, subshells, heredocs, expansion, newlines
+ * or assignments are not provably that.
+ * @param {string} cmd
+ */
+export const isReadOnlyCommand = (cmd) => {
+  const bare = stripInertQuotes(String(cmd));
+  if (/[(){}`\n]|<</.test(bare) || LIVE_EXPANSION.test(bare)) return false;
+  const segs = shellSegments(cmd);
+  return segs.length > 0 && segs.every((words) => {
+    const rest = withoutRedirections(words);
+    return quietRedirections(words) && READERS.has(rest[0]);
+  });
+};
+
 /** Short flags of a cluster stop at "e": the rest is -e's value (-fen = -f -e n). */
 export const shortOpts = (a) => (/^-[a-zA-Z]/.test(a) ? a.slice(1).split("e")[0] : "");

package/src/harden/workflow-engine.js

@@ -14,8 +14,16 @@ import { dirname } from "node:path";
 
 import { parse as parseYaml } from "yaml";
 import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { publishedPin } from "./published-pin.js";
 import { extraWorkflowsFor, mutationWorkflowFor, qualityWorkflowFor, policyWorkflowFor, stewardWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
 
+// KJC-BUG-0424: on the PR that brings this change GitHub runs neither YAML (the base's
+// listens to pull_request, the new one to pull_request_target), so policy-check never reports.
+export const POLICY_TRIGGER_MOVE_NOTE =
+  "kj-policy.yml moves from pull_request to pull_request_target (judged from the base branch). " +
+  "The PR that brings this change gets no policy-check run: if policy-check is a required check, " +
+  "merge that one PR as an admin after the other checks pass; from then on the base runs the judge.";
+
 // La versión del kj que corre harden — es la que se pinea en el fallback
 // npx del workflow de policy (jamás @latest en CI). Lectura LAZY: en el
 // bundle SEA no hay package.json junto al módulo y una lectura eager a
@@ -66,6 +74,25 @@ function hasLintScript(projectDir) {
   }
 }
 
+const policyDeclared = (projectDir) => existsSync(join(projectDir, ".karajan", "policy.yml"));
+
+// STW-E (KJC-TSK-0793): the scheduled sweep is OPT-IN — the project says
+// steward.action: true in its config; nothing is imposed by default.
+function stewardActionOn(projectDir) {
+  try {
+    return parseYaml(readFileSync(join(projectDir, ".karajan", "kj.config.yml"), "utf8"))?.steward?.action === true;
+  } catch {
+    return false; // no config — no action
+  }
+}
+
+/** KJC-BUG-0420: the published kj version the policy and steward workflows pin; null when neither is seeded. */
+export async function resolveKjPin({ projectDir, fetchFn } = {}) {
+  const own = ownPkg();
+  if (!own || !(policyDeclared(projectDir) || stewardActionOn(projectDir))) return null;
+  return publishedPin({ name: own.name, version: own.version, fetchFn });
+}
+
 export function installWorkflows({
   projectDir = process.cwd(),
   language = null,
@@ -87,14 +114,10 @@ export function installWorkflows({
   // pinear: la plumbeada por el CLI (SEA) o la propia; "latest" es último
   // recurso inalcanzable en los caminos reales.
   const pinned = kjVersion ?? ownPkg()?.version ?? "latest";
-  const policy = existsSync(join(projectDir, ".karajan", "policy.yml"))
+  const policy = policyDeclared(projectDir)
     ? { file: "kj-policy.yml", blockId: "wf-policy", body: policyWorkflowFor(pinned, ownPkg()?.name ?? "karajan-code") }
     : null;
-  // STW-E (KJC-TSK-0793): the scheduled sweep is OPT-IN — the project says
-  // steward.action: true in its config; nothing is imposed by default.
-  let stewardOn = false;
-  try { stewardOn = parseYaml(readFileSync(join(projectDir, ".karajan", "kj.config.yml"), "utf8"))?.steward?.action === true; } catch { /* no config — no action */ }
-  const steward = stewardOn ? { file: "kj-steward.yml", blockId: "wf-steward", body: stewardWorkflowFor(pinned, ownPkg()?.name ?? "karajan-code") } : null;
+  const steward = stewardActionOn(projectDir) ?{ file: "kj-steward.yml", blockId: "wf-steward", body: stewardWorkflowFor(pinned, ownPkg()?.name ?? "karajan-code") } : null;
   const all = [...WORKFLOWS, ...(quality ? [quality] : []), ...extras, ...(mut ? [mut] : []), ...(policy ? [policy] : []), ...(steward ? [steward] : [])];
   const results = [];
   for (const wf of all) {
@@ -125,7 +148,9 @@ export function installWorkflows({
       // pre-commit rechaza el fichero recién generado.
       writeFileSync(target, content.endsWith("\n") ? content : `${content}\n`);
     }
-    results.push({ file: label, action });
+    // KJC-BUG-0424: the PR that moves the trigger cannot report policy-check.
+    const movesTrigger = wf.blockId === "wf-policy" && action !== "unchanged" && /^\s*pull_request:\s*$/m.test(source);
+    results.push({ file: label, action, ...(movesTrigger ? { note: POLICY_TRIGGER_MOVE_NOTE } : {}) });
   }
   return { dryRun, workflows: results };
 }

package/src/orchestrator/stages/suite-green-stage.js

@@ -39,7 +39,9 @@ export async function runSuiteGreenStage({ config, logger, emitter, eventBase, s
   }
   const timeout = Number(config?.development?.test_timeout_ms) > 0 ? Number(config.development.test_timeout_ms) : DEFAULT_TIMEOUT_MS;
   const run = runTestsImpl || (async () => {
-    const res = await runCommand("bash", ["-lc", command], { cwd: projectDir, timeout });
+    // KJC-BUG-0427: never a login shell, which re-reads the person's profile and may rewrite
+    // PATH (nvm drops node when npm_config_prefix is set): the suite runs in kj's own environment.
+    const res = await runCommand("bash", ["-c", command], { cwd: projectDir, timeout });
     return { exitCode: res.exitCode ?? 1, output: `${res.stdout || ""}\n${res.stderr || ""}` };
   });
   const res = await run(command);

package/src/policy/add.js

@@ -11,6 +11,7 @@ import yaml from "js-yaml";
 import { parsePolicy } from "@karajan-family/governance";
 import { createAgent } from "../agents/index.js";
 import { resolveRole } from "../config/role-resolver.js";
+import { agentAnswerText } from "../review/parser.js";
 
 const PROMPT = (text) => `Traduce esta regla de proyecto hablada a un FRAGMENTO YAML del vocabulario
 cerrado v1 de policy de Karajan. Vocabulario COMPLETO (nada fuera de esto):
@@ -27,7 +28,8 @@ async function defaultTranslate({ text, config, logger }) {
   const role = resolveRole(config, "reviewer");
   const res = await createAgent(role.provider, config, logger).reviewTask({ prompt: PROMPT(text), role: "reviewer" });
   if (!res?.ok) throw new Error(`el agente traductor (${role.provider}) falló: ${res?.error || "sin salida"}`);
-  return String(res.output || "").replace(/^```[a-z]*\n?|```\s*$/g, "").trim();
+  // KJC-BUG-0430 (issue #2695): claude answers with its stream-json; the answer is its final result.
+  return String(agentAnswerText(res.output) || "").replace(/^```[a-z]*\n?|```\s*$/g, "").trim();
 }
 
 // Merge conservador: las listas se CONCATENAN (añadir jamás borra), los

package/src/policy/engine.js

@@ -9,7 +9,7 @@
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { stripTextOptionValues } from "../harden/sentinel/sentinel-shell.mjs";
+import { isReadOnlyCommand, stripTextOptionValues } from "../harden/sentinel/sentinel-shell.mjs";
 import {
   ALLOW_VERDICT,
   checkArtifacts,
@@ -36,7 +36,8 @@ export const SUPERVISOR_DEFAULTS = [
     // it is USED (commit, CI, release), whatever wrote it: only the human's seal lifts it.
     id: "defaults.governance.write",
     // KJC-BUG-0400: the CI workflows too; a PR could rewrite the check that judges it.
-    pattern: /(^|\/)\.karajan\/(policy|rules)\.yml\b|(^|\/)\.github\/workflows\/[^/\s]+\.ya?ml\b/,
+    // KJC-BUG-0429: in shell text a relative path follows a blank or a quote, not a slash.
+    pattern: /(^|[^\w.-])\.karajan\/(policy|rules)\.yml\b|(^|[^\w.-])\.github\/workflows\/[^/\s]+\.ya?ml\b/,
     message: "es configuración de gobierno: solo entra sellada por la persona (kj harden --commit, firmado desde su móvil)",
   },
 ];
@@ -84,7 +85,12 @@ export function evalToolCall(policy, { role = "coder", tool, input = {}, root =
   // KJC-BUG-0343: the inert prose of a text option (--title, --error, -m...) is
   // not a target: a report naming a supervisor path is not a write to it. A path
   // anywhere else, or a value that can expand, is still judged.
-  if (tool === "Bash") return evalShell(policy, role, stripTextOptionValues(String(input.command ?? "")));
+  if (tool === "Bash") {
+    const command = stripTextOptionValues(String(input.command ?? ""));
+    // KJC-BUG-0429 (ADR 0036): a command that only reads may name the guarded files;
+    // the role's own shell rules still judge it.
+    return evalShell(isReadOnlyCommand(command) ? { ...policy, defaults: [] } : policy, role, command);
+  }
   if (READONLY_TOOLS.has(tool) || !policy.roles?.[role]) return ALLOW_VERDICT;
   return denyVerdict(`roles.${role}.tools`, `tool "${tool}" fuera del registro de la policy — no verificable para el rol declarado ${role}`);
 }

package/src/policy/supervisor-verify.js

@@ -15,8 +15,8 @@ import { HOST_SETTINGS, isSealedConfig, PROVENANCE_FILE } from "../harden/superv
 
 const HOOKS_PREFIX = ".karajan/hooks/";
 const HARNESS_PREFIX = ".karajan/harness/";
-// globalHooksDir es el único texto libre que se interpola en el render:
-// vocabulario cerrado de ruta o la provenance no verifica NADA.
+// HU-2762: el render ya no interpola globalHooksDir; se conserva el guard para
+// provenances antiguas, donde era texto libre: vocabulario cerrado o no verifica NADA.
 const SAFE_DIR = /^(\$HOME)?(\/[\w.@%+~-]+)+$/;
 
 const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");

package/src/rag/migrate.js

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

package/src/rag/project-store.js

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

package/src/review/pr-requirements.js

@@ -9,7 +9,7 @@ import { join } from "node:path";
 import { AI_ATTRIBUTION, CONVENTIONAL_TYPES } from "../harden/hook-templates.js";
 import { loadPolicy } from "../policy/engine.js";
 import { runCommand } from "../utils/process.js";
-import { budgetedAdded } from "./loc-budget.js";
+import { budgetedNet } from "./loc-budget.js";
 import { checkTestsWithCode } from "./tests-with-code.js";
 
 const HEADER_MAX = 100;
@@ -37,13 +37,13 @@ export function prSizeLimit({ projectDir, config }) {
   };
 }
 
-/** Lines added that count against the budget (generated output and human docs exempt). */
+/** Net lines that count against the budget, as the CI gate counts them (generated output and human docs exempt). */
 export function sizeCheck({ numstat, limit }) {
-  const { added, exempt } = budgetedAdded(numstat);
+  const { net, exempt } = budgetedNet(numstat);
   const exemptNote = exempt > 0 ? ` (${exempt} exempt)` : "";
-  return added > limit
-    ? { id: "size", ok: false, detail: `${added} lines added${exemptNote}, over the ${limit}-line limit: partition the PR` }
-    : { id: "size", ok: true, detail: `${added} lines added${exemptNote}, within the ${limit}-line limit` };
+  return net > limit
+    ? { id: "size", ok: false, detail: `${net} net lines${exemptNote}, over the ${limit}-line limit: partition the PR` }
+    : { id: "size", ok: true, detail: `${net} net lines${exemptNote}, within the ${limit}-line limit` };
 }
 
 /** Conventional Commits headers (at most 100 characters) and no AI attribution in base..head. */

package/src/review/verify-pr.js

@@ -9,6 +9,8 @@ import { runCommand } from "../utils/process.js";
 import { diffHash } from "./verdict-store.js";
 import { MARKER } from "./publish-pr.js";
 import { isCleanMerge } from "./clean-merge.js";
+import { verifiedSupervisorFiles } from "../policy/supervisor-verify.js";
+import { PROVENANCE_FILE } from "../harden/supervisor-commit.js";
 
 const TRUSTED = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
 // The marker of a kj review for any head: what MARKER writes up to the head itself.
@@ -38,10 +40,33 @@ async function hashesOf(projectDir, sha, run) {
   return hashes;
 }
 
+// KJC-BUG-0388: kj harden --commit is the human's act, signed from the phone, and no AI
+// reviews it. The proof is the signature, never the message: a commit that only touches
+// files the roster-signed seal vouches for at the head is that act.
+async function isSealCommit(projectDir, sha, run, sealed) {
+  if (sealed.signed !== true) return false;
+  const res = await run("git", ["-C", projectDir, "diff", "--name-only", `${sha}^`, sha]);
+  if (res.exitCode !== 0) throw new Error(`git diff --name-only ${sha.slice(0, 7)} failed: ${(res.stderr || "").trim()}`);
+  const files = (res.stdout || "").split("\n").filter(Boolean);
+  // KJC-BUG-0438: the seal act writes the signed provenance; a commit without it only touched files.
+  if (!files.includes(PROVENANCE_FILE)) return false;
+  if (!files.every((f) => sealed.files.has(f) || (f === PROVENANCE_FILE && sealed.complete === true))) return false;
+  // What the commit leaves is byte for byte what the signed seal vouches for at the head: a
+  // precursor whose provenance or hooks a later commit replaced is not the seal act.
+  for (const f of files) if ((await blobAt(projectDir, sha, f, run)) !== (await blobAt(projectDir, "HEAD", f, run))) return false;
+  return true;
+}
+
+/** The blob id of a file at a revision, or null when the file is absent there. */
+async function blobAt(projectDir, rev, file, run) {
+  const res = await run("git", ["-C", projectDir, "rev-parse", "--verify", "--quiet", `${rev}:${file}`]);
+  return res.exitCode === 0 ? String(res.stdout || "").trim() : null;
+}
+
 /**
- * @returns {Promise<{ok: boolean, commits: number, problems: string[]}>}
+ * @returns {Promise<{ok: boolean, commits: number, problems: string[], sealCommits?: string[]}>}
  */
-export async function verifyPrReview({ projectDir, pr, run = runCommand }) {
+export async function verifyPrReview({ projectDir, pr, run = runCommand, sealed = null }) {
   const info = await json(run, ["pr", "view", String(pr), "--json", "headRefOid,commits"], projectDir);
   const commits = info.commits ?? [];
   // One review per line, every page: --slurp is missing from the gh that distros ship.
@@ -52,15 +77,21 @@ export async function verifyPrReview({ projectDir, pr, run = runCommand }) {
   // today's head: the diff hash of each commit is what proves it, and a commit pushed after
   // the review is simply not listed. "Update branch" no longer leaves the check red.
   const kjReviews = reviews.filter((r) => TRUSTED.has(r.author_association) && String(r.body ?? "").includes(MARKER_PREFIX));
-  if (kjReviews.length === 0) {
-    return { ok: false, commits: commits.length, problems: [`no kj review published by a member: run kj review --publish-pr ${pr}`] };
-  }
   const listed = new Map(kjReviews.flatMap((r) => [...r.body.matchAll(LISTED)].map((m) => [m[1], m[2]])));
   const problems = [];
+  const sealCommits = [];
+  let seal = sealed;
   for (const c of commits) {
     if (await isCleanMerge(projectDir, c.oid, run)) continue;
     const hash = listed.get(c.oid.slice(0, 7));
-    if (!hash || !(await hashesOf(projectDir, c.oid, run)).has(hash)) problems.push(`${c.oid.slice(0, 7)} (${c.messageHeadline}): no approved verdict for the diff it brings`);
+    if (hash && (await hashesOf(projectDir, c.oid, run)).has(hash)) continue;
+    seal ??= verifiedSupervisorFiles({ projectDir, trackedOnly: true });
+    if (await isSealCommit(projectDir, c.oid, run, seal)) sealCommits.push(c.oid.slice(0, 7));
+    else problems.push(`${c.oid.slice(0, 7)} (${c.messageHeadline}): no approved verdict for the diff it brings`);
   }
-  return { ok: problems.length === 0, commits: commits.length, problems };
+  // A PR that only brings the seal needs no review; anything else without one (a clean merge
+  // included, KJC-BUG-0438) is told to publish it.
+  const onlySeals = sealCommits.length > 0 && sealCommits.length === commits.length;
+  if (kjReviews.length === 0 && !onlySeals) problems.splice(0, problems.length, `no kj review published by a member: run kj review --publish-pr ${pr}`);
+  return { ok: problems.length === 0, commits: commits.length, problems, ...(sealCommits.length > 0 ? { sealCommits } : {}) };
 }

package/src/sonar/scanner.js

@@ -198,7 +198,8 @@ async function maybeRunCoverage(config) {
 
   const command = String(coverage.command || "").trim();
   const timeout = Number(coverage.timeout_ms) > 0 ? Number(coverage.timeout_ms) : 5 * 60 * 1000;
-  const run = await runCommand("bash", ["-lc", command], { timeout });
+  // KJC-BUG-0427: a plain shell in kj's environment; a login one may rewrite PATH.
+  const run = await runCommand("bash", ["-c", command], { timeout });
 
   if (run.exitCode !== 0) {
     if (blockOnFailure) {