karajan-code 4.54.0 → 4.56.0

package/package.json

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

package/src/agents/claude-agent.js

@@ -366,6 +366,9 @@ export class ClaudeAgent extends BaseAgent {
   async _runTaskExec(task, model, _role) {
     const { args, input } = buildPromptArgs(task);
     if (model) args.push("--model", model);
+    // KJC-TSK-1070 (MR-D2): the effort the HU's route gives the coder.
+    const effort = this.config?.roles?.[_role]?.effort;
+    if (effort) args.push("--effort", effort);
     // PL-C (KJC-TSK-0735): el rol del subproceso viaja en KJ_POLICY_ROLE —
     // si su harness corre hooks (claude -p), el tier A evalúa la policy con
     // el rol que ACTÚA. El rol del ORQUESTADOR es autoritativo: task.env no

package/src/cli/register-pipeline.js

@@ -15,6 +15,7 @@ import { statusCommand } from "../commands/status.js";
 import { loadPlan } from "../plan/plan-store.js";
 import { withConfig } from "./_shared.js";
 import { publishPrReview } from "../review/publish-pr.js";
+import { thirdPartyReviewCommand } from "../review/third-party-review.js";
 
 /**
  * Register the "core pipeline" commands: everything the user runs day-to-day
@@ -257,8 +258,15 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--walked <route>", "Recorrido comprobado como lo haría una persona (repetible) — queda en el veredicto", (v, prev) => [...(prev || []), v], [])
     .option("--walked-with <tool>", "Con qué se comprobó el recorrido (por ejemplo chrome-devtools)")
     .option("--publish-pr <n>", "Publish the cross-AI verdicts of a PR's commits on it as one GitHub review")
+    .option("--third-party", "Review someone else's PR (--range base...head): reviewer only, no own-work gates, no verdict stored")
+    .option("--json", "With --third-party: print the review as one JSON document on stdout")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "review", flags, async ({ config, logger }) => {
+        // KJC-TSK-1075 (#2227): a third-party PR, for reviewer agents; own work keeps every gate.
+        if (flags.thirdParty) {
+          process.exitCode = await thirdPartyReviewCommand({ flags: { ...flags, task: task ?? null }, config });
+          return;
+        }
         // KJC-TSK-0913: the verdicts kj already holds, published on the PR as one review.
         if (flags.publishPr) {
           const r = await publishPrReview({ projectDir: config.projectDir || process.cwd(), pr: flags.publishPr });

package/src/commands/harden.js

@@ -16,6 +16,7 @@ import { interactiveHarden } from "../harden/interactive.js";
 import { createWizard, isTTY } from "../utils/wizard.js";
 import { commitSupervisorRegeneration } from "../harden/supervisor-commit.js";
 import { installConfigsForRoots } from "../harden/config-engine.js";
+import { readHardenConfig } from "../harden/harden-scope.js";
 import { installGuidelines } from "../harden/guidelines-engine.js";
 import { maybeRulesyncGenerate } from "../utils/rulesync.js";
 import { commandsForLanguage } from "../harden/hook-commands.js";
@@ -35,21 +36,6 @@ const JS_TEST_CMD = {
   mocha: "npx mocha",
 };
 
-/**
- * Per-repo harden scope, persisted in package.json `kj.harden` so a repo with
- * sub-tools (e.g. a python wrapper) excludes them once instead of on every
- * invocation (KJC-TSK-0564). CLI flags are merged on top.
- */
-function readHardenConfig(projectDir) {
-  const pkgPath = join(projectDir, "package.json");
-  if (!existsSync(pkgPath)) return {};
-  try {
-    return JSON.parse(readFileSync(pkgPath, "utf8")).kj?.harden ?? {};
-  } catch {
-    return {};
-  }
-}
-
 /**
  * Resolve the hook's lint/format/test commands for the primary language.
  * Non-JS stacks use their native toolchain (go/ruff/…); JS/TS is built from

package/src/commands/plan/generate.js

@@ -9,7 +9,7 @@ import { promptProjectName } from "../../utils/prompt-project-name.js";
 import { deriveProjectNameFromCwd } from "../../utils/derive-project-name-from-cwd.js";
 import { applyReviewerFeedback, applyFixerPatch, patchChanged } from "../../plan/plan-fixer.js";
 import { runStructuralPass } from "../../plan/plan-structural-pass.js";
-import { recommendModelsForHu, complexityFromTaskType } from "../../hu/model-router.js";
+import { planHuModels } from "../../hu/model-router.js";
 import { withBrainRecovery } from "../../brain/with-brain-recovery.js";
 import { buildStandbyState } from "../../brain/standby-store.js";
 import { printResumeHint } from "../../utils/display/resume-hint.js";
@@ -206,16 +206,15 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     const symbolicId = typeof step === "object" && typeof step.id === "string" && step.id.trim()
       ? step.id.trim() : null;
     const taskType = classifyTaskType(desc);
-    // KJC-TSK-0405 step 2: asigna coder_model + reviewer_model
-    // automáticamente según complexity inferido del task_type. El
-    // planner puede emitir `step.complexity` (trivial/simple/medium/complex
-    // o score 1-5) para override más fino. Cross-provider reviewer
-    // (claude↔codex) por defecto.
-    const coderProvider = config?.roles?.coder?.provider || config?.coder || "claude";
-    const complexity = (typeof step === "object" && step.complexity)
-      ? step.complexity
-      : complexityFromTaskType(taskType);
-    const models = recommendModelsForHu({ complexity, coderProvider, config });
+    // KJC-TSK-1072 (MR-D4): coder_model comes from the HU's tier (MR-A), the
+    // criterion the run uses; the board can change it. Cross-provider reviewer.
+    const models = planHuModels({
+      title: desc, goal: desc,
+      acceptanceCriteria: tests.map((t) => (typeof t === "object" ? String(t.content ?? "") : String(t))),
+      tier: typeof step === "object" ? step.tier ?? null : null,
+      tierReason: typeof step === "object" ? step.tierReason ?? null : null,
+      config: config ?? {},
+    });
     const hu = addHu(plan, {
       title: desc.slice(0, 80),
       task_type: taskType,
@@ -232,6 +231,8 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     // KJC-TSK-0661: provenance stamp (addHu builds its object explicitly,
     // so this goes on the returned reference, not in huData).
     hu.created_by = "planner";
+    // KJC-TSK-1072: the tier rides on the HU, so the run gives its coder the tier's effort.
+    hu.complexity = models.complexity;
     // KJC-TSK-1061: the classification travels to the HU; validatePlan judges it (KJC-TSK-0717).
     for (const key of ["change_class", "change_criterion", "hardens"]) {
       const value = typeof step === "object" ? step[key] : null;

package/src/commands/rag.js

@@ -38,7 +38,7 @@ async function indexFiles({ files, projectDir, db, embedder, slug, logger, json,
       logger.warn?.(`[rag] ${out}: not indexed`);
       continue;
     }
-    const r = await indexFile(abs, { db, embedder, logger, project: slug, kind: sourceKind(abs) });
+    const r = await indexFile(abs, { db, embedder, logger, project: slug, kind: sourceKind() });
     totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
   }
   const deleted = totals.deleted ? `, ${totals.deleted} chunks deleted` : "";

package/src/commands/review-gate.js

@@ -26,6 +26,8 @@ import { loadPrivacyList, scanText } from "../privacy/scan.js";
 import { isGeneratedPath, splitAddedByFile } from "../privacy/diff-scope.js";
 import { budgetedAdded, budgetedNet } from "../review/loc-budget.js";
 import { checkStagedDiff, loadPolicy } from "../policy/engine.js";
+import { prSizeLimit } from "../review/pr-requirements.js";
+import { stewardBlocking } from "../steward/gate.js";
 import { loadStandingExceptions, recordPolicyException } from "../policy/exceptions.js";
 import { policyFileHash, recordGateDecision } from "../policy/decisions.js";
 import { evaluatePolicyGate } from "../review/policy-gate.js";
@@ -227,6 +229,14 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   const card = await enforceCardFirst({ config, projectDir });
   if (!card.ok) return { verdict: "rejected", reviewer: "card-first", issues: [{ severity: "high", description: card.reason }] };
 
+  // KJC-TSK-1086: the Steward's block at commit too, not only where Edit starts work.
+  const steward = stewardBlocking({ projectDir, config });
+  if (steward) {
+    console.log(`✗ ${steward.reason}`);
+    process.exitCode = 1;
+    return { verdict: "rejected", reviewer: "steward", issues: [{ severity: "high", description: steward.reason }] };
+  }
+
   // KJC-TSK-0687 (MG-B): the verifiable half of TDD — sources without a
   // single test change warn (block via method_gates.tests_with_code).
   const changedFiles = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
@@ -246,16 +256,12 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // PL-C (KJC-TSK-0735), fuente única de umbrales: si la policy declara el
   // invariante net_lines_added, SU max es el umbral — el mismo número que
   // aplican kj policy check y el tier C de CI; method_gates queda de fallback.
-  const pol = loadPolicy({ projectDir });
-  const locInv = pol.errors.length === 0
-    ? (pol.policy.invariants || []).find((i) => i.kind === "diff-threshold" && i.metric === "net_lines_added")
-    : null;
   // KJC-BUG-0326 (#2085): two tiers. ~150 is the ideal (method_gates.pr_size_warn);
   // up to the limit (the policy's net_lines_added max, else method_gates.pr_size_max,
-  // 200) is allowed without asking; above the limit, partition.
-  const sizeIdeal = config?.method_gates?.pr_size_warn ?? 150;
-  const sizeWarn = locInv?.max ?? config?.method_gates?.pr_size_max ?? 200;
-  const sizeSource = locInv ? `policy [${locInv.id}]` : "method_gates";
+  // 200) is allowed without asking; above the limit, partition. KJC-TSK-1076: one
+  // source, shared with the third-party PR checks.
+  const pol = loadPolicy({ projectDir });
+  const { ideal: sizeIdeal, limit: sizeWarn, source: sizeSource } = prSizeLimit({ projectDir, config });
   if (sizeWarn > 0) {
     const numstat = await rawDiff(flags.range, ["--numstat"]);
     // KJC-BUG-0205: the budget caps CODE growth, so generated output and human

package/src/config/defaults.js

@@ -134,6 +134,8 @@ const DEFAULTS = {
   },
   sonarqube: {
     enabled: true,
+    // KJC-BUG-0368 (#2216): sonar-scanner runs this many reviews at once per machine.
+    max_parallel_scans: 2,
     host: "http://localhost:9000",
     external: false,
     container_name: "karajan-sonarqube",

package/src/config/schema.js

@@ -208,6 +208,8 @@ const Skills = v.optional(v.looseObject({
  *     forzar Sonnet en todo el proyecto, por ejemplo.
  */
 const ModelRouting = v.optional(v.looseObject({
+  // KJC-TSK-0701 (MR-D): the coder of each HU runs on its tier's model; false turns it off.
+  enabled: v.optional(v.boolean("model_routing.enabled must be true or false")),
   by_provider: v.optional(v.record(
     v.string(),
     v.looseObject({
@@ -257,6 +259,10 @@ export const ConfigSchema = v.looseObject({
     every_commits: v.optional(PositiveInt),
   })),
   coder_rules: v.optional(v.string()),
+  // KJC-BUG-0368 (#2216): how many sonar-scanner reviews run at once per machine.
+  sonarqube: v.optional(v.looseObject({
+    max_parallel_scans: v.optional(PositiveInt),
+  })),
   base_branch: v.optional(v.string()),
   coder_options: CoderOptions,
   reviewer_options: ReviewerOptions,

package/src/harden/check.js

@@ -11,8 +11,9 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 import { runCommand } from "../utils/process.js";
-import { artifactIdForConfig, findAlternative } from "./alternatives.js";
+import { configLeftAlone } from "./config-engine.js";
 import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
+import { readHardenConfig } from "./harden-scope.js";
 import { PROFILE_HOOKS } from "./hook-templates.js";
 import { detectStackRoots } from "./stack-roots.js";
 import { qualityWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
@@ -49,24 +50,24 @@ export async function checkHarden({ projectDir = process.cwd(), profile = "stand
   // Config + workflows ship with standard+ — and surface the greenfield gap:
   // a language now present but never hardened ⇒ its config shows as missing.
   if (profile !== "minimal") {
-    const roots = detectStackRoots(projectDir);
+    // KJC-BUG-0370: the same scope (package.json kj.harden) and the same verdict on a
+    // missing config as kj harden, so check never calls drift what harden leaves alone.
+    const { only = [], exclude = [] } = readHardenConfig(projectDir);
+    const roots = detectStackRoots(projectDir, { only, exclude });
+    const configCheck = (cfg, rel, altDirs, missing) => {
+      const leftAlone = existsSync(join(projectDir, rel)) ? null : configLeftAlone(cfg, altDirs);
+      if (!leftAlone) return presence(projectDir, rel, `config:${rel}`, missing);
+      const detail = leftAlone.action === "covered" ? `covered by ${leftAlone.by}` : `omitted: ${leftAlone.note}`;
+      return { id: `config:${rel}`, ok: true, detail };
+    };
     for (const cfg of UNIVERSAL_CONFIGS) {
-      checks.push(presence(projectDir, cfg.file, `config:${cfg.file}`, "missing — run kj harden"));
+      checks.push(configCheck(cfg, cfg.file, [projectDir], "missing — run kj harden"));
     }
     for (const { dir, language } of roots) {
       const rootDir = dir === "." ? projectDir : join(projectDir, dir);
       for (const cfg of CONFIGS_BY_LANGUAGE[language] ?? []) {
         const rel = dir === "." ? cfg.file : join(dir, cfg.file);
-        // A config covered by the user's own tool (biome.json ⇒ eslint+prettier)
-        // is not drift — kj must not demand a second linter/formatter (KJC-TSK-0614).
-        if (!existsSync(join(projectDir, rel))) {
-          const alt = findAlternative([rootDir, projectDir], artifactIdForConfig(cfg));
-          if (alt) {
-            checks.push({ id: `config:${rel}`, ok: true, detail: `covered by ${alt.foundAt} (${alt.tool})` });
-            continue;
-          }
-        }
-        checks.push(presence(projectDir, rel, `config:${rel}`, `missing for ${language} — run kj harden`));
+        checks.push(configCheck(cfg, rel, [rootDir, projectDir], `missing for ${language} — run kj harden`));
       }
     }
     const expectedWf = [...WORKFLOWS];

package/src/harden/config-engine.js

@@ -33,6 +33,27 @@ function hasTool(dirs, tool) {
   return false;
 }
 
+/**
+ * Why kj leaves a missing config alone, or null when it seeds it. KJC-BUG-0370:
+ * kj check reads the same answer, so it never calls drift what harden skips.
+ */
+export function configLeftAlone(cfg, altDirs) {
+  const id = artifactIdForConfig(cfg);
+  const alt = findAlternative(altDirs, id);
+  if (alt) return { action: "covered", by: alt.foundAt };
+  // KJC-BUG-0119: a same-tool variant (eslint.config.mjs, .eslintrc.json,
+  // package.json#eslintConfig…) means the config already EXISTS — seeding
+  // kj's default filename next to it would silently ECLIPSE the user's
+  // real config (eslint resolves eslint.config.js before .mjs).
+  const variant = findEquivalentIn(altDirs, id);
+  if (variant) return { action: "covered", by: variant };
+  // KJC-BUG-0137: no tool ⇒ no config — report the actionable gap instead.
+  if (cfg.requires && !hasTool(altDirs, cfg.requires)) {
+    return { action: "omitted", note: `${cfg.requires} is not installed — npm i -D ${cfg.requires}, then re-run kj harden` };
+  }
+  return null;
+}
+
 function writeFile(target, content) {
   mkdirSync(dirname(target), { recursive: true });
   writeFileSync(target, content);
@@ -50,30 +71,10 @@ function seedInto(targetDir, configs, dryRun, prefix, results, altDirs = [target
     const exists = existsSync(target);
     const file = prefix === "." ? cfg.file : join(prefix, cfg.file);
 
-    if (!exists) {
-      const alt = findAlternative(altDirs, artifactIdForConfig(cfg));
-      if (alt) {
-        results.push({ file, action: "covered", by: alt.foundAt });
-        continue;
-      }
-      // KJC-BUG-0119: a same-tool variant (eslint.config.mjs, .eslintrc.json,
-      // package.json#eslintConfig…) means the config already EXISTS — seeding
-      // kj's default filename next to it would silently ECLIPSE the user's
-      // real config (eslint resolves eslint.config.js before .mjs).
-      const variant = findEquivalentIn(altDirs, artifactIdForConfig(cfg));
-      if (variant) {
-        results.push({ file, action: "covered", by: variant });
-        continue;
-      }
-      // KJC-BUG-0137: no tool ⇒ no config — report the actionable gap instead.
-      if (cfg.requires && !hasTool(altDirs, cfg.requires)) {
-        results.push({
-          file,
-          action: "omitted",
-          note: `${cfg.requires} is not installed — npm i -D ${cfg.requires}, then re-run kj harden`,
-        });
-        continue;
-      }
+    const leftAlone = exists ? null : configLeftAlone(cfg, altDirs);
+    if (leftAlone) {
+      results.push({ file, ...leftAlone });
+      continue;
     }
 
     if (cfg.json) {

package/src/harden/harden-scope.js

@@ -0,0 +1,18 @@
+/**
+ * Per-repo harden scope, persisted in package.json `kj.harden` so a repo with
+ * sub-tools (e.g. a python wrapper) excludes them once instead of on every
+ * invocation (KJC-TSK-0564). KJC-BUG-0370: kj harden and kj check read it from
+ * here, so check never asks for configs harden was told to leave out.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function readHardenConfig(projectDir) {
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(pkgPath)) return {};
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf8")).kj?.harden ?? {};
+  } catch {
+    return {};
+  }
+}

package/src/harden/hook-templates.js

@@ -10,8 +10,9 @@
 
 import { homedir } from "node:os";
 
-const CONVENTIONAL_TYPES = "feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert";
-const AI_ATTRIBUTION = "co-authored-by:.*(claude|gpt|copilot|gemini)|(generated|written) (by|with) .*(claude|gpt|copilot)";
+// 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)";
 
 export const SHEBANG = "#!/usr/bin/env sh";
 
@@ -45,10 +46,12 @@ export function toPortableHooksDir(dir, home = homedir()) {
 function chainToGlobal(hook, globalHooksDir) {
   if (!globalHooksDir) return [];
   const dir = toPortableHooksDir(globalHooksDir);
+  // 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=$?`;
   return [
     "# Chain the machine's previous global hook (kj harden keeps it active).",
     `if [ -x "${dir}/${hook}" ]; then`,
-    `  "${dir}/${hook}" "$@"; rc=$?`,
+    `  ${call}`,
     '  [ "$rc" -eq 0 ] || exit "$rc"',
     "fi",
   ];
@@ -100,6 +103,22 @@ function identityGuard(hook) {
   }
   return [
     ...head,
+    // KJC-TSK-1085: every commit the push brings carries the declared identity
+    // (a rebase, cherry-pick, merge or tag never ran pre-commit).
+    "  kj_declared_email=$(sed -n 's/^git_email:[[:space:]]*//p' .karajan/identity.local.yml | head -n1)",
+    '  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',
+    "      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',
+    '          echo "kj harden: identity lock — commit $(git log -1 --format=%h "$kj_c") is authored/committed as $kj_who but this clone is declared as $kj_declared_email"; exit 1',
+    "        fi",
+    "      done",
+    "    done || exit 1",
+    "  fi",
     "  kj_declared_gh=$(sed -n 's/^gh_user:[[:space:]]*//p' .karajan/identity.local.yml | head -n1)",
     '  kj_hosts="${GH_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/gh}/hosts.yml"',
     "  kj_active_gh=$(awk '/^github.com:/{f=1;next} f&&/^[^[:space:]]/{f=0} f&&/^[[:space:]]*user:/{sub(/^[[:space:]]*user:[[:space:]]*/,\"\");print;exit}' \"$kj_hosts\" 2>/dev/null)",
@@ -178,6 +197,8 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
       ].join("\n");
     case "pre-push": {
       const lines = [
+        // KJC-TSK-1085: git hands the pushed refs on stdin; kept for the identity check and the chained hook.
+        "[ -t 0 ] || kj_push_refs=$(cat)",
         "# Identity guard — never push without a configured git identity.",
         'if [ -z "$(git config user.email)" ] || [ -z "$(git config user.name)" ]; then',
         "  echo 'kj harden: git user.name/user.email not set — refusing to push'; exit 1",

package/src/harden/human-act.js

@@ -8,18 +8,36 @@
  *  4.   a random nonce typed back, read from the real controlling terminal.
  */
 import { randomBytes } from "node:crypto";
-import { closeSync, openSync, readFileSync, readSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, openSync, readFileSync, readSync } from "node:fs";
 
 const AGENT_PROC = /claude|codex|copilot|gemini|opencode|\bagy\b/i;
 
-export function agentAncestry({ pid = process.pid, readProc = null, maxDepth = 40 } = {}) {
-  const read = readProc || ((p) => {
-    const stat = readFileSync(`/proc/${p}/stat`, "utf8");
-    const ppid = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
-    let cmd = "";
-    try { cmd = readFileSync(`/proc/${p}/cmdline`).toString("utf8").replaceAll("\0", " "); } catch { /* gone */ }
-    return { ppid, cmd };
-  });
+const procRead = (p) => {
+  const stat = readFileSync(`/proc/${p}/stat`, "utf8");
+  const ppid = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
+  let cmd = "";
+  try { cmd = readFileSync(`/proc/${p}/cmdline`).toString("utf8").replaceAll("\0", " "); } catch { /* gone */ }
+  return { ppid, cmd };
+};
+
+// KJC-TSK-1084: without /proc (macOS) the chain comes from ps, so a human
+// there is not refused for an ancestry nobody could read.
+// The system binary by absolute path: a ps resolved through PATH could be the
+// agent's own forgery prepended to it.
+const PS_BIN = ["/bin/ps", "/usr/bin/ps"].find((p) => existsSync(p)) ?? null;
+const psOutput = (p) => {
+  if (!PS_BIN) throw new Error("no system ps (/bin/ps, /usr/bin/ps)");
+  return execFileSync(PS_BIN, ["-o", "ppid=", "-o", "command=", "-p", String(p)], { encoding: "utf8", env: {} });
+};
+const psRead = (ps) => (p) => {
+  const m = /^\s*(\d+)\s+(.*)$/s.exec(String(ps(p) ?? ""));
+  if (!m) throw new Error(`ps gave nothing for pid ${p}`);
+  return { ppid: Number(m[1]), cmd: m[2].trim() };
+};
+
+export function agentAncestry({ pid = process.pid, readProc = null, maxDepth = 40, hasProc = existsSync("/proc/self/stat"), ps = psOutput } = {}) {
+  const read = readProc || (hasProc ? procRead : psRead(ps));
   let cur = pid;
   for (let i = 0; i < maxDepth && cur > 1; i += 1) {
     let info;
@@ -37,6 +55,11 @@ export function refuseAgentSession(what, { env = process.env, tty = process.stdo
     throw new Error(`${what} es un acto humano: córrelo desde TU terminal, fuera de una sesión de agente (ADR 0009)`);
   }
   const anc = agentAncestry(ancestry);
+  // KJC-TSK-1084: fail closed. Nothing else stops a human act any more (the
+  // Sentinel does not read its text), so an ancestry that cannot be read is no pass.
+  if (anc.unknown) {
+    throw new Error(`${what} es un acto humano y no se pudo comprobar la ascendencia de procesos — córrelo desde TU terminal (ADR 0009)`);
+  }
   if (anc.agent) {
     throw new Error(`${what} es un acto humano y este proceso desciende de un agente (${anc.match}) — ni con pty falso ni con el entorno limpio (ADR 0009)`);
   }

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

@@ -145,10 +145,12 @@ export const stripInertQuotes = (cmd) => {
 
 // Options whose value is prose, never a path (gh, git, kj).
 // KJC-BUG-0306: --error and --command of kj report-issue, --scope and --tests of kj hu add.
-const TEXT_OPTIONS = new Set(["--title", "--body", "--message", "-m", "--notes", "--description", "--ac", "--criteria", "--reason", "--decision", "--context", "--consequences", "--position", "--error", "--command", "--scope", "--tests"]);
+// KJC-BUG-0366: --why of kj handoff add.
+const TEXT_OPTIONS = new Set(["--title", "--body", "--message", "-m", "--notes", "--description", "--ac", "--criteria", "--reason", "--decision", "--context", "--consequences", "--position", "--error", "--command", "--scope", "--tests", "--why"]);
 const QUOTED_OPTION_VALUE = /(^|\s)(--?[a-z]+)(=|\s+)("[^"$`\\]*"|'[^']*')/g;
 // KJC-BUG-0306: the title kj hu add and kj adr add take as their first argument, at the start of a segment.
-const KJ_TITLE = /(^|[;&|]\s*)(kj\s+(?:hu|adr)\s+add\s+)("[^"$`\\]*"|'[^']*')/g;
+// KJC-BUG-0366: and the command kj handoff add stores for the human.
+const KJ_TITLE = /(^|[;&|]\s*)(kj\s+(?:hu|adr|handoff)\s+add\s+)("[^"$`\\]*"|'[^']*')/g;
 
 /** KJC-BUG-0243: blank the inert quoted value of a text option (--title "a/b c"): prose, not a path. */
 export const stripTextOptionValues = (cmd) => cmd
@@ -171,7 +173,7 @@ const isGitCommit = (words) => {
   return words[0] === "git" && words[i] === "commit";
 };
 
-const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr)\s+add\b/.test(seg) || isGitCommit(seg.split(/\s+/));
+const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr|handoff)\s+add\b/.test(seg) || isGitCommit(seg.split(/\s+/));
 
 /**
  * KJC-BUG-0354: blank the quoted text values (stripTextOptionValues) only when the