karajan-code 4.47.0 → 4.48.0

package/package.json

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

package/src/cli/advanced-commands.js

@@ -35,7 +35,7 @@ export const ADVANCED_GROUPS = [
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
   { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "rules", "claims", "steward", "pr-size"] },
-  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity", "security"] },
+  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity", "security", "handoff"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },
 ];

package/src/cli/register-meta.js

@@ -9,6 +9,7 @@ import { bootstrapCommand } from "../commands/bootstrap.js";
 import { PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
 import { identityCommand } from "../commands/identity.js";
 import { securityCommand } from "../commands/security.js";
+import { handoffCommand } from "../commands/handoff.js";
 import { policyCommand } from "../commands/policy.js";
 import { claimsCommand, claimsGateCommand } from "../commands/claims.js";
 import { stewardSweepCommand } from "../commands/steward.js";
@@ -193,6 +194,16 @@ export function registerMeta(program, { pkgVersion }) {
       });
   }
 
+  // KJC-TSK-0968 (HUM-E, ADR 0018): the agent's handoff to the human goes through kj.
+  const handoffCmd = program.command("handoff").description("Handoffs: what a gate denied the agent, registered with the gate's why, for the human to read and run by id");
+  const handoff = (action, flags) => withConfig(pkgVersion, `handoff-${action}`, flags, async ({ config }) => { process.exitCode = await handoffCommand({ action, config, flags }); });
+  handoffCmd.command("add").description("Register the EXACT command a gate denied (the why comes from the Sentinel's record, not from you)")
+    .argument("<command...>", "the denied command, as it was run").option("--cwd <dir>", "Directory the command runs in (default: the project)")
+    .action((parts, flags) => handoff("add", { ...flags, command: parts.join(" ") }));
+  handoffCmd.command("list", { isDefault: true }).description("The handoffs registered in this project").action((flags) => handoff("list", flags));
+  handoffCmd.command("show").description("A handoff: the exact command, its sha256 and why the gate denied it")
+    .argument("<id>", "handoff id (8 hex)").option("--json", "Output the record as JSON").action((id, flags) => handoff("show", { ...flags, id }));
+
   // KJC-TSK-0986 (HUM-F): the invitation to enroll the phone, once per version.
   identityCmd
     .command("phone-invite")

package/src/commands/handoff.js

@@ -0,0 +1,38 @@
+/**
+ * kj handoff add|list|show (KJC-TSK-0968, HUM-E, ADR 0018): the agent registers
+ * what a gate denied it, with the gate's why; the human reads it by id.
+ */
+import { addHandoff, listHandoffs, readHandoff } from "../harden/handoff.js";
+
+const line = (h) => `${h.id}  ${h.status.padEnd(8)}  ${h.createdAt}  ${h.command}`;
+
+/** @returns {Promise<0|1>} */
+export async function handoffCommand({ action = "list", config, flags = {}, log = console.log }) {
+  const projectDir = config?.projectDir || process.cwd();
+  try {
+    if (action === "add") {
+      const record = addHandoff({ projectDir, command: flags.command, cwd: flags.cwd ?? projectDir });
+      log(`encargo ${record.id} registrado: ${record.command}`);
+      log(`por qué lo negó el gate (${record.denial.at}):\n${record.denial.why}`);
+      log(`tu usuario lo revisa con kj handoff show ${record.id}; nadie copia y pega el comando.`);
+      return 0;
+    }
+    if (action === "show") {
+      const h = readHandoff({ projectDir, id: flags.id });
+      if (flags.json) { log(JSON.stringify(h)); return 0; }
+      log(`encargo   ${h.id} (${h.status}, ${h.createdAt})`);
+      log(`comando   ${h.command}`);
+      log(`sha256    ${h.sha256}`);
+      log(`cwd       ${h.cwd}`);
+      log(`gate      ${h.denial.tool} negó el ${h.denial.at}:\n${h.denial.why}`);
+      return 0;
+    }
+    const all = listHandoffs({ projectDir });
+    if (all.length === 0) log("kj handoff: ningún encargo registrado");
+    for (const h of all) log(line(h));
+    return 0;
+  } catch (err) {
+    log(err.message);
+    return 1;
+  }
+}

package/src/harden/handoff.js

@@ -0,0 +1,60 @@
+/**
+ * KJC-TSK-0968 (HUM-E, ADR 0018): the agent's handoff to the human goes through
+ * kj. When a gate denies the agent a command, the agent registers a HANDOFF with
+ * the exact command; the why is what the gate said, read from the Sentinel's
+ * record of denials, never a text of the agent. The human later reads and runs
+ * it by id (E2, E3). Handoffs live in .karajan/handoffs/<id>.json, local.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const HANDOFFS_DIR = ".karajan/handoffs";
+export const DENIALS_FILE = ".karajan/harness/denials.jsonl";
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+
+/** The Sentinel's denials, oldest first; a line that is not JSON is skipped. */
+export function readDenials({ projectDir }) {
+  let text;
+  try { text = readFileSync(join(projectDir, DENIALS_FILE), "utf8"); } catch { return []; }
+  return text.split("\n").filter(Boolean).flatMap((line) => { try { return [JSON.parse(line)]; } catch { return []; } });
+}
+
+/** The latest denial of this EXACT Bash command, or null. */
+export function findDenial({ projectDir, command }) {
+  return readDenials({ projectDir }).findLast((d) => d?.tool === "Bash" && d?.input?.command === command) ?? null;
+}
+
+/**
+ * Registers a handoff for a command a gate denied. Without a denial of those
+ * exact bytes there is nothing to hand off: the agent does not write the why.
+ * @returns {{id: string, command: string, sha256: string, why: string}}
+ */
+export function addHandoff({ projectDir, command, cwd = projectDir }) {
+  if (typeof command !== "string" || !command.trim()) throw new Error("kj handoff add: falta el comando exacto que el gate negó");
+  const denial = findDenial({ projectDir, command });
+  if (!denial) throw new Error("kj handoff add: kj no tiene registrado ningún deny para ese comando exacto; el porqué de un encargo lo escribe el gate, no el agente (ADR 0018)");
+  const createdAt = new Date().toISOString();
+  const digest = sha256(command);
+  const id = sha256(`${digest}:${createdAt}`).slice(0, 8);
+  const record = { id, command, sha256: digest, cwd, createdAt, status: "pending", denial: { at: denial.at, tool: denial.tool, why: denial.why } };
+  mkdirSync(join(projectDir, HANDOFFS_DIR), { recursive: true });
+  writeFileSync(join(projectDir, HANDOFFS_DIR, `${id}.json`), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  return record;
+}
+
+export function readHandoff({ projectDir, id }) {
+  if (!/^[0-9a-f]{8}$/.test(id ?? "")) throw new Error(`kj handoff: "${id}" no es un identificador de encargo (8 hex)`);
+  const path = join(projectDir, HANDOFFS_DIR, `${id}.json`);
+  if (!existsSync(path)) throw new Error(`kj handoff: no hay ningún encargo ${id}`);
+  const record = JSON.parse(readFileSync(path, "utf8"));
+  // The bytes the human will run are the bytes that were registered, or nothing.
+  if (sha256(record.command ?? "") !== record.sha256) throw new Error(`kj handoff: el encargo ${id} no coincide con su sha256: alguien lo tocó, no se ejecuta`);
+  return record;
+}
+
+export function listHandoffs({ projectDir }) {
+  let names;
+  try { names = readdirSync(join(projectDir, HANDOFFS_DIR)).filter((n) => /^[0-9a-f]{8}\.json$/.test(n)); } catch { return []; }
+  return names.map((n) => readHandoff({ projectDir, id: n.slice(0, 8) })).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}

package/src/harden/hook-templates.js

@@ -135,8 +135,9 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
         "fi",
         "# KJC-BUG-0296 (issue #1989): the host agent's runtime and local state never",
         "# enter a commit, however they were staged (a blanket `git add -A` put a",
-        "# Claude scheduler lock into main). Checked on the staged list itself.",
-        "if git diff --cached --name-only | grep -qE '^(\\.claude/[^/]*\\.lock|\\.claude/scheduled_tasks\\.lock|\\.kj/|\\.karajan/identity\\.local\\.yml|\\.karajan/harness/sentinel-state\\.json)'; then",
+        "# Claude scheduler lock into main). Checked on the staged list itself,",
+        "# deletions left out: untracking a runtime file is the fix (KJC-BUG-0307).",
+        "if git diff --cached --name-only --diff-filter=d | grep -qE '^(\\.claude/[^/]*\\.lock|\\.claude/scheduled_tasks\\.lock|\\.kj/|\\.karajan/identity\\.local\\.yml|\\.karajan/harness/sentinel-state\\.json)'; then",
         "  echo 'kj harden: agent runtime files are staged (.claude/*.lock, .kj/, identity.local.yml, sentinel-state.json) — unstage them: git restore --staged <path>'; exit 1",
         "fi",
         "# v4 review gate (ENV-C1, opt-in via `kj review --install-gate`):",

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

@@ -64,6 +64,28 @@ export const headIndex = (words, heads) => {
   return k < 0 ? words.length : i + k;
 };
 
+/**
+ * KJC-BUG-0306: a simple command that runs `gh ... issue create`, read by words
+ * (quotes, escapes and newlines as the shell reads them), not by words anywhere.
+ * @param {string} cmd
+ */
+export const isGhIssueCreate = (cmd) => shellSegments(cmd).some((words) => {
+  const i = headIndex(words, ["gh"]);
+  if (words[i]?.split("/").at(-1) !== "gh") return false;
+  // The subcommand words, with every flag skipped together with a value that may
+  // follow it (--repo x, --hostname y): what is left is "issue", then "create".
+  const subcommand = [];
+  let afterFlag = false;
+  for (const w of words.slice(i + 1)) {
+    if (w.startsWith("-")) { afterFlag = !w.includes("="); continue; }
+    if (afterFlag && !["issue", "create"].includes(w)) { afterFlag = false; continue; }
+    afterFlag = false;
+    subcommand.push(w);
+    if (subcommand.length === 2) break;
+  }
+  return subcommand[0] === "issue" && subcommand[1] === "create";
+});
+
 // KJC-BUG-0286: a $ expands only when something expandable follows it ($x, ${x},
 // $(cmd), $1, $@...). A lone "$ " in a grep pattern is a literal dollar sign.
 const LIVE_EXPANSION = /\$(?=[A-Za-z0-9_{(@*#?$!-])|`/;
@@ -90,11 +112,16 @@ export const stripInertQuotes = (cmd) => {
 };
 
 // Options whose value is prose, never a path (gh, git, kj).
-const TEXT_OPTIONS = new Set(["--title", "--body", "--message", "-m", "--notes", "--description", "--ac", "--criteria", "--reason", "--decision", "--context", "--consequences", "--position"]);
+// 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"]);
 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-0243: blank the inert quoted value of a text option (--title "a/b c"): prose, not a path. */
-export const stripTextOptionValues = (cmd) => cmd.replace(QUOTED_OPTION_VALUE, (m, pre, opt, sep, val) => (TEXT_OPTIONS.has(opt) ? `${pre}${opt}${sep}${val[0]}${val[0]}` : m));
+export const stripTextOptionValues = (cmd) => cmd
+  .replace(KJ_TITLE, (m, pre, head, val) => `${pre}${head}${val[0]}${val[0]}`)
+  .replace(QUOTED_OPTION_VALUE, (m, pre, opt, sep, val) => (TEXT_OPTIONS.has(opt) ? `${pre}${opt}${sep}${val[0]}${val[0]}` : m));
 
 /**
  * KJC-BUG-0245: the values of the named options, read by the shell reader, so a

package/src/harden/sentinel-hooks.js

@@ -467,13 +467,13 @@ const PRETOOL_BODY = `#!/usr/bin/env node
 import console from "node:console";
 import process from "node:process";
 import { dirname, join, relative, resolve } from "node:path";
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, branchOf, foreignLane, load, save, session, violations, boardGate, pendingMoves, pendingText } from "./sentinel-lib.mjs";
+import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, STATE, branchOf, foreignLane, load, save, session, violations, 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 { optionValues, shellSegments, stripInertQuotes, stripTextOptionValues } from "./sentinel-shell.mjs";
+import { isGhIssueCreate, optionValues, shellSegments, stripInertQuotes, stripTextOptionValues } from "./sentinel-shell.mjs";
 import { DISCARD_VERBS, discardOf, foreignLost, removedFiles } from "./sentinel-discard.mjs";
 import { shellWrites, writesRepo } from "./sentinel-bash-write.mjs";
 const EDIT_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
@@ -495,8 +495,17 @@ process.stdin.on("end", () => {
   try {
     const { session_id: sid = "default", tool_name: tool, tool_input: input = {}, transcript_path: transcript = null } = JSON.parse(raw);
     // KJC-TSK-0920 (SNT-E): every deny ends with the same line, whatever gate it was.
+    // KJC-TSK-0968 (HUM-E, ADR 0018): and leaves a record next to the state, with the
+    // gate's own words: kj handoff takes the why from here, never from the agent.
+    const said = [];
+    const errOrig = console.error.bind(console);
+    console.error = (m) => { said.push(String(m)); errOrig(m); };
     process.on("exit", (code) => {
-      if (code === 2) console.error("karajan: Karajan gobierna y se le obedece. No rodees el gate ni cambies la politica para pasarlo; si te parece injusto, diselo a tu usuario o usa kj report-issue.");
+      if (code !== 2) return;
+      errOrig("karajan: Karajan gobierna y se le obedece. No rodees el gate ni cambies la politica para pasarlo; si te parece injusto, diselo a tu usuario o usa kj report-issue.");
+      // Only what a handoff needs: the exact Bash command, or the path an edit aimed at; never file contents.
+      const what = tool === "Bash" ? { command: input.command } : { file_path: input.file_path || input.notebook_path || null };
+      try { appendFileSync(join(dirname(STATE), "denials.jsonl"), JSON.stringify({ at: new Date().toISOString(), sid, tool, input: what, why: said.join("\\n") }) + "\\n"); } catch { /* the deny stands without its record */ }
     });
     // KJC-BUG-0238 (#1886): de quien es cada cambio. La primera vez que la
     // sesion toca un fichero se anota si estaba limpio: solo entonces un
@@ -574,7 +583,9 @@ process.stdin.on("end", () => {
     // (sanitiza y busca duplicados), nunca por gh issue create a mano.
     {
       const ghIssue = String(input.command || "");
-      if (tool === "Bash" && /(^|[^a-zA-Z])gh([^a-zA-Z]|$)/.test(ghIssue) && /(^|[^a-z])issue([^a-z]|$)/.test(ghIssue) && /(^|[^a-z])create([^a-z]|$)/.test(ghIssue)) {
+      // KJC-BUG-0306: the subcommand itself (gh, its flags, issue create), not three words
+      // anywhere: "gh pr create --title 'kj report-issue ...'" is not an issue.
+      if (tool === "Bash" && isGhIssueCreate(ghIssue)) {
         // The target: --repo/-R, an inline or inherited GH_REPO, else the
         // checkout's own origin, which is what gh takes (review catches).
         const inlineRepo = /(^|[^A-Z_])GH_REPO=([^ ]+)/.exec(ghIssue);
@@ -884,7 +895,7 @@ process.stdin.on("end", () => {
         // KJC-BUG-0243: inert quoted text is not a substitution, and the prose value
         // of a text option (--title, -m...) is not a path.
         if (/\\$\\(|\`/.test(stripInertQuotes(cmd)) || quotedPathWithSpaces(stripTextOptionValues(cmd))) {
-          console.error("karajan sentinel: sustitucion de comandos o ruta entrecomillada con espacios en un comando mutador — no verificable por el guard de carriles (MONO-0); usa valores/rutas LITERALES sin sustitucion." + doc("cross-lane"));
+          console.error("karajan sentinel: sustitucion de comandos o ruta entrecomillada con espacios en un comando mutador — no verificable por el guard de carriles (MONO-0); usa valores/rutas LITERALES sin sustitucion. Si es texto (titulo, descripcion, error) con comillas de codigo o dolar, ponlo entre comillas SIMPLES: entre dobles la shell lo ejecuta." + doc("cross-lane"));
           process.exit(2);
         }
         const SAFE_EXP_SEG = /^([A-Za-z_][A-Za-z0-9_]*=[^ \\t]*[ \\t]*)*((npm|pnpm|yarn|vitest|jest|kj|gh|echo|printf|true|test)\\b|git[ \\t](?![^\\n]*(-C[ \\t]|--git-dir|--work-tree)))[^;|&\\n]*$|^[A-Za-z_][A-Za-z0-9_]*=[^;|&\\n]*$/;