karajan-code 4.70.4 → 5.0.1

package/src/config/loader.js

@@ -27,6 +27,7 @@ import { getKarajanHome } from "../utils/paths.js";
 import { safeParseConfig, formatConfigIssues } from "./schema.js";
 import { DEFAULTS } from "./defaults.js";
 import { resolveTestHarness } from "./test-harness.js";
+import { SECRET_PATHS } from "./secrets.js";
 
 /**
  * Parse a YAML config file with an actionable error message.
@@ -74,13 +75,18 @@ export function getProjectConfigPath(projectDir = process.cwd()) {
   return path.join(projectDir, ".karajan", "kj.config.yml");
 }
 
+/** ADR 0032: a member's own preferences, ignored by git, on top of the team's project config. */
+export function getLocalConfigPath(projectDir = process.cwd()) {
+  return path.join(projectDir, ".karajan", "kj.config.local.yml");
+}
+
+async function readYamlIfPresent(filePath) {
+  if (!(await exists(filePath))) return null;
+  return parseYamlOrThrow(await fs.readFile(filePath, "utf8"), filePath);
+}
+
 export async function loadProjectConfig(projectDir = process.cwd()) {
-  const projectConfigPath = getProjectConfigPath(projectDir);
-  if (!(await exists(projectConfigPath))) {
-    return null;
-  }
-  const raw = await fs.readFile(projectConfigPath, "utf8");
-  return parseYamlOrThrow(raw, projectConfigPath);
+  return readYamlIfPresent(getProjectConfigPath(projectDir));
 }
 
 async function loadProjectPricingOverrides(projectDir = process.cwd()) {
@@ -113,6 +119,7 @@ export async function loadConfig(projectDir) {
 
   // Load project config (.karajan/kj.config.yml)
   const projectConfig = await loadProjectConfig(projectDir);
+  const localConfig = await readYamlIfPresent(getLocalConfigPath(projectDir));
 
   // KJC-TSK-0395: enforce the local-overrides-global hierarchy. A project
   // config with no global counterpart is almost always user error (copied
@@ -120,19 +127,24 @@ export async function loadConfig(projectDir) {
   // would silently behave like a global config without the defaults
   // people expect. Refuse with an actionable message.
   // 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) {
+  // team's committed project config sits on the defaults instead. A member's local
+  // config is never committed, so without a global it is still refused, in CI too.
+  if (!globalExists && (localConfig || (projectConfig && !process.env.CI))) {
+    const found = projectConfig ? getProjectConfigPath(projectDir) : getLocalConfigPath(projectDir);
     throw new Error(
-      `Local config found at ${getProjectConfigPath(projectDir)} but no global config exists.\n` +
+      `Local config found at ${found} 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."
     );
   }
 
-  // Merge: DEFAULTS < global < project
+  // Merge: DEFAULTS < global < project (the team's) < local (the member's, ADR 0032)
   let merged = mergeDeep(DEFAULTS, globalConfig);
   if (projectConfig) {
     merged = mergeDeep(merged, projectConfig);
   }
+  if (localConfig) {
+    merged = mergeDeep(merged, localConfig);
+  }
 
   if (projectPricing) {
     merged.budget = mergeDeep(merged.budget || {}, { pricing: projectPricing });
@@ -199,19 +211,24 @@ function stripRuntimeOnlyKeys(config) {
 // KJC-BUG-0253: a project's .karajan/kj.config.yml is versioned with the repo,
 // so the SonarQube credentials never go there; they live in the global config
 // (~/.karajan), where the token bootstrap already saves them.
-const SECRET_KEYS = ["token", "admin_password"];
 const isProjectConfig = (configPath) =>
   path.basename(configPath) === "kj.config.yml"
   && path.basename(path.dirname(configPath)) === ".karajan"
   && path.resolve(configPath) !== path.resolve(getConfigPath());
 
+// KJC-TSK-1234 (ADR 0032): the same secret paths the pre-commit check refuses (SonarCloud's token
+// included), one list for both, so writing never keeps what committing would reject.
 function stripSecrets(config) {
-  if (!config?.sonarqube || typeof config.sonarqube !== "object") return { out: config, stripped: [] };
-  const stripped = SECRET_KEYS.filter((k) => config.sonarqube[k] != null);
-  if (!stripped.length) return { out: config, stripped };
-  const sonarqube = { ...config.sonarqube };
-  for (const k of stripped) delete sonarqube[k];
-  return { out: { ...config, sonarqube }, stripped: stripped.map((k) => `sonarqube.${k}`) };
+  let out = config;
+  const stripped = [];
+  for (const [section, key] of SECRET_PATHS) {
+    const block = out?.[section];
+    if (!block || typeof block !== "object" || block[key] == null) continue;
+    const { [key]: _secret, ...kept } = block;
+    out = { ...out, [section]: kept };
+    stripped.push(`${section}.${key}`);
+  }
+  return { out, stripped };
 }
 
 /** @returns {Promise<{strippedSecrets: string[]}>} the secret keys kept out of a project config */

package/src/config/role-resolver.js

@@ -65,6 +65,7 @@ const CODER_INHERITED_ROLES = new Set([
   "impeccable", "triage", "discover", "architect", "audit",
   "hu_reviewer", "hu-reviewer",
   "spec_reviewer", "spec-reviewer",
+  "translator",
 ]);
 
 function resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer) {

package/src/config/schema.js

@@ -90,6 +90,7 @@ const RolesMap = v.optional(v.looseObject({
   discover: v.optional(RoleEntry),
   architect: v.optional(RoleEntry),
   hu_reviewer: v.optional(RoleEntry),
+  translator: v.optional(RoleEntry),
   start: v.optional(RoleEntry),
 }));
 

package/src/config/secrets.js

@@ -0,0 +1,36 @@
+/**
+ * KJC-TSK-1234 (ADR 0032): the project's kj.config.yml travels with the repo, so it must never
+ * hold a secret. It is judged by its parsed YAML (escaped keys, flow mappings, anchors and merge
+ * keys all resolved), never by its raw text. The parse is strict: a duplicated key fails, since a
+ * second empty value could hide a secret written before it.
+ */
+import fs from "node:fs";
+import yaml from "js-yaml";
+
+export const SECRET_PATHS = [["sonarqube", "token"], ["sonarqube", "admin_password"], ["sonarcloud", "token"]];
+
+/** @returns {string[]} the secret paths that hold a value (empty, null and absent are fine) */
+export function configSecrets(text) {
+  const doc = yaml.load(text) ?? {};
+  return SECRET_PATHS
+    .filter(([section, key]) => {
+      const value = doc?.[section]?.[key];
+      return value !== undefined && value !== null && value !== "";
+    })
+    .map((path) => path.join("."));
+}
+
+/** `kj config --check-secrets <file|->`: exit 1 naming each secret, or when the file cannot be read. */
+export function checkSecretsCommand(file, { logger = console } = {}) {
+  let found;
+  try {
+    found = configSecrets(fs.readFileSync(file === "-" ? 0 : file, "utf8"));
+  } catch (err) {
+    logger.error(`kj: cannot check ${file} for secrets (${err.message})`);
+    process.exitCode = 1;
+    return;
+  }
+  if (found.length === 0) return;
+  logger.error(`kj: ${file} holds a secret (${found.join(", ")}): move it to .karajan/kj.config.local.yml or ~/.karajan`);
+  process.exitCode = 1;
+}

package/src/config.js

@@ -25,6 +25,7 @@ export { DEFAULTS } from "./config/defaults.js";
 export {
   getConfigPath,
   getProjectConfigPath,
+  getLocalConfigPath,
   loadProjectConfig,
   loadConfig,
   writeConfig,

package/src/environment/adr.js

@@ -6,6 +6,8 @@
  */
 import fs from "node:fs/promises";
 import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 
 const ADR_DIR = path.join(".karajan", "adrs");
 // KJC-BUG-0272: whoever records a decision proposes it. Accepting is the user's:
@@ -28,12 +30,24 @@ export async function listAdrs(projectDir) {
   return adrs;
 }
 
-export async function addAdr(projectDir, { title, decision, context = "", consequences = "" }) {
+const realGit = (cwd) => async (args) => (await promisify(execFile)("git", args, { cwd })).stdout;
+
+// HU-2792: numbers that open branches hold, read from the local origin/* refs
+// (no network). Not a git repo, or no remotes: nothing taken, as before.
+async function remoteAdrNumbers(run) {
+  try {
+    const refs = (await run(["for-each-ref", "--format=%(refname)", "refs/remotes/origin"])).split("\n").filter(Boolean);
+    const trees = await Promise.all(refs.map((ref) => run(["ls-tree", "--name-only", ref, `${ADR_DIR}/`]).catch(() => "")));
+    return trees.flatMap((t) => t.split("\n")).map((f) => /\/(\d{4})-[^/]*\.md$/.exec(f)?.[1]).filter(Boolean).map(Number);
+  } catch { return []; }
+}
+
+export async function addAdr(projectDir, { title, decision, context = "", consequences = "" }, run = realGit(projectDir)) {
   if (!title?.trim() || !decision?.trim()) {
     throw new Error("kj adr add requires a title and --decision");
   }
   const existing = await listAdrs(projectDir);
-  const number = (existing.at(-1)?.number || 0) + 1;
+  const number = Math.max(0, ...existing.map((a) => a.number), ...await remoteAdrNumbers(run)) + 1;
   const file = path.join(ADR_DIR, `${String(number).padStart(4, "0")}-${slugify(title)}.md`);
   const body = [
     `# ${title}`, "",

package/src/git/karajan-label.js

@@ -1,10 +1,11 @@
 /**
- * KJC-TSK-1123 (#2315): every PR Karajan opens carries the «Karajan» label, so
+ * KJC-TSK-1123 (#2315): every PR Karajan governs carries the «Karajan» label, so
  * a team can measure how much of its change goes through the governor. It means
  * "went through Karajan", never "written by an AI": Karajan governs AIs, and the
  * PR may be a person's work it reviewed. The signal lives only in the PR's
  * metadata, never in commits or the PR body. Labelling never costs the PR: a
- * failure is logged and the work goes on.
+ * failure is logged and the work goes on. KJC-BUG-0461: since 5.0 (no kj run opening PRs)
+ * kj review --publish-pr adds it, the step of the method that runs on every PR.
  */
 import { runCommand } from "../utils/process.js";
 
@@ -12,20 +13,31 @@ export const KARAJAN_LABEL = "Karajan";
 const LABEL_COLOR = "1f6feb";
 const LABEL_DESCRIPTION = "Went through Karajan (governed and reviewed); not a claim that an AI wrote it";
 
-/** owner/repo of a GitHub PR URL, or null when the URL has another shape. */
-const repoOf = (url) => /^https:\/\/[^/]+\/([^/]+\/[^/]+)\/pull\/\d+/.exec(url)?.[1] ?? null;
+/** The PR a URL or a bare number names: { repo: "owner/repo" or null for the repo gh runs in, number }. */
+function prOf(ref) {
+  const url = /^https:\/\/[^/]+\/([^/]+\/[^/]+)\/pull\/(\d+)/.exec(String(ref ?? ""));
+  if (url) return { repo: url[1], number: url[2] };
+  return /^\d+$/.test(String(ref ?? "")) ? { repo: null, number: String(ref) } : null;
+}
 
 /**
  * Add the label to the PR, creating it first when the repo lacks it.
+ * @param {{url: string|number}} args a PR URL, or its number in the repo gh runs in
  * @returns {Promise<boolean>} true when the PR carries the label.
  */
 export async function labelKarajanPr({ url, cwd = null, run = runCommand, warn = (msg) => process.stderr.write(`${msg}\n`) }) {
   const opts = cwd ? { cwd } : {};
-  const repo = repoOf(url);
+  const pr = prOf(url);
+  if (!pr) {
+    warn(`kj: could not add the Karajan label to ${url}: not a pull request URL or number`);
+    return false;
+  }
   try {
-    // Fails when the label exists; the edit below says whether the PR got it.
-    await run("gh", ["label", "create", KARAJAN_LABEL, "--color", LABEL_COLOR, "--description", LABEL_DESCRIPTION, ...(repo ? ["--repo", repo] : [])], opts);
-    const res = await run("gh", ["pr", "edit", url, "--add-label", KARAJAN_LABEL], opts);
+    // Fails when the label exists; the call below says whether the PR got it.
+    await run("gh", ["label", "create", KARAJAN_LABEL, "--color", LABEL_COLOR, "--description", LABEL_DESCRIPTION, ...(pr.repo ? ["--repo", pr.repo] : [])], opts);
+    // KJC-BUG-0462: REST. `gh pr edit --add-label` asks GraphQL for the PR's classic project
+    // cards and fails since GitHub sunset Projects (classic), so no PR got the label.
+    const res = await run("gh", ["api", "-X", "POST", `repos/${pr.repo ?? "{owner}/{repo}"}/issues/${pr.number}/labels`, "-f", `labels[]=${KARAJAN_LABEL}`], opts);
     if (res.exitCode === 0) return true;
     warn(`kj: could not add the Karajan label to ${url}: ${(res.stderr || res.stdout || "").trim()}`);
   } catch (err) {

package/src/guards/main-guard.js

@@ -0,0 +1,54 @@
+/**
+ * main-guard (KJC-TSK-1368, ADR 0037 layer 2): after a push to the protected branch, what
+ * reached it without its required checks, and whether the protection still enforces them on
+ * admins. It cannot prevent an abuse by someone holding the maintainer's credentials; it makes
+ * it visible. GitHub is reached through an injected api, so the logic runs without network.
+ *
+ * api.pullsOf(sha)   → pull requests associated with a commit (GitHub's commits/{sha}/pulls)
+ * api.checksOf(sha)  → [{ name, conclusion }] for a commit (check runs and statuses)
+ * api.protection()   → the branch protection, or null when the branch is not protected
+ */
+
+// GitHub counts these as passing for a required check.
+const PASSING = new Set(["success", "neutral", "skipped"]);
+
+/** The pull request that merged this commit into the branch, if any. */
+function mergedInto(pulls, branch) {
+  return pulls.find((p) => p.merged_at && p.base?.ref === branch) ?? null;
+}
+
+async function auditCommit(sha, { branch, requiredChecks, api }) {
+  const pull = mergedInto(await api.pullsOf(sha), branch);
+  if (!pull) return { sha, kind: "direct-push", detail: `no pull request merged into ${branch}` };
+  const results = await api.checksOf(pull.head.sha);
+  const passed = new Set(results.filter((c) => PASSING.has(c.conclusion)).map((c) => c.name));
+  const missing = requiredChecks.filter((name) => !passed.has(name));
+  if (missing.length === 0) return null;
+  return { sha, kind: "checks-skipped", pr: pull.number, mergedBy: pull.merged_by?.login ?? "unknown", missing };
+}
+
+/** What changed in the protection against what is declared. */
+function auditProtection(protection, { branch, requiredChecks }) {
+  if (!protection) return [`${branch} is not protected`];
+  const changes = [];
+  if (!protection.enforce_admins?.enabled) changes.push("enforce_admins is off: admins can merge past the required checks");
+  const rules = protection.required_status_checks ?? {};
+  const enforced = new Set([...(rules.contexts ?? []), ...(rules.checks ?? []).map((c) => c.context)]);
+  for (const name of requiredChecks) if (!enforced.has(name)) changes.push(`required check removed: ${name}`);
+  return changes;
+}
+
+/**
+ * @param {{ branch: string, commits: string[], requiredChecks: string[], api: object }} opts
+ * @returns {Promise<{ ok: boolean, merges: object[], protection: string[] }>}
+ */
+export async function auditMain({ branch, commits, requiredChecks, api }) {
+  if (!requiredChecks?.length) throw new Error("main-guard: declare at least one required check to audit against");
+  const merges = [];
+  for (const sha of commits) {
+    const finding = await auditCommit(sha, { branch, requiredChecks, api });
+    if (finding) merges.push(finding);
+  }
+  const protection = auditProtection(await api.protection(), { branch, requiredChecks });
+  return { ok: merges.length === 0 && protection.length === 0, merges, protection };
+}

package/src/harden/hook-templates.js

@@ -109,9 +109,17 @@ function identityGuard(hook) {
     "  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"',
+    // KJC-BUG-0459: a per-account gh (gh-tribbu, ADR 0040) as the credential helper is the account
+    // git pushes as. The accounts guide makes gh-<account> use ~/.config/gh-<account>: read it.
+    "  kj_helper=$(git config --get-urlmatch credential.helper https://github.com 2>/dev/null)",
+    '  case "$kj_helper" in',
+    "    '!'*/gh-*' auth git-credential'*|'!'gh-*' auth git-credential'*)",
+    '      kj_ghbin=${kj_helper#!}; kj_ghbin=${kj_ghbin%% *}',
+    '      kj_hosts="${XDG_CONFIG_HOME:-$HOME/.config}/${kj_ghbin##*/}/hosts.yml" ;;',
+    "  esac",
     "  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)",
     '  if [ -n "$kj_declared_gh" ] && [ "$kj_active_gh" != "$kj_declared_gh" ]; then',
-    '    echo "kj harden: identity lock — gh session is ${kj_active_gh:-none} but this clone is declared as $kj_declared_gh — run: gh auth switch --user $kj_declared_gh"; exit 1',
+    '    echo "kj harden: identity lock — gh session is ${kj_active_gh:-none} but this clone is declared as $kj_declared_gh — run: gh auth switch --user $kj_declared_gh (or set the gh of that account, e.g. gh-<account>, as the credential helper)"; exit 1',
     "  fi",
     ...tail,
   ];
@@ -147,6 +155,13 @@ export function hookBody(hook, cmds = {}, { baseBranch = null } = {}) {
         "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",
+        "# KJC-TSK-1234 (ADR 0032): the project's kj.config.yml travels with the repo, so its staged",
+        "# version is checked for secrets by kj, which parses the YAML (raw text can spell a key in",
+        "# too many ways). Without kj nothing can check it, so it does not enter.",
+        "if git diff --cached --name-only --diff-filter=d | grep -qx '.karajan/kj.config.yml'; then",
+        "  command -v kj >/dev/null 2>&1 || { echo 'kj harden: .karajan/kj.config.yml is staged but kj is not installed to check it holds no secret'; exit 1; }",
+        "  git show ':.karajan/kj.config.yml' | kj config --check-secrets - || { echo 'kj harden: keep tokens and passwords out of the shared kj.config.yml'; exit 1; }",
+        "fi",
         "# KJC-TSK-1205 (ADR 0030): a tampered Sentinel is caught before each commit,",
         "# not only when the turn ends. Only where it is installed; no kj, no check.",
         "if [ -d .karajan/harness ] && command -v kj >/dev/null 2>&1; then",

package/src/harden/sentinel/posttooluse.mjs

@@ -7,13 +7,14 @@ import process from "node:process";
 import { realpathSync } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
 import { spawnSync } from "node:child_process";
-import { CODE, TESTS, ROOT, CARD, branchOf, load, save, session } from "./sentinel-lib.mjs";
+import { CODE, TESTS, ROOT, CARD, branchOf, enterLane, laneFor, laneTop, load, save, session } from "./sentinel-lib.mjs";
 import { remindersFor } from "./sentinel-reminders.mjs";
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
   try {
-    const { session_id: sid = "default", tool_name: tool, tool_input: input = {}, tool_response: response = {} } = JSON.parse(raw);
+    const { session_id: sid = "default", tool_name: tool, tool_input: input = {}, tool_response: response = {}, cwd = null } = JSON.parse(raw);
+    enterLane(load(), sid, cwd);
     // KJC-TSK-0765 board-sync: a merge that gh CONFIRMS leaves its card pending
     // in the tracker (the PreToolUse gate then refuses to advance until it is
     // moved). Recorded here, after the fact, so a failed merge never blocks.
@@ -76,7 +77,10 @@ process.stdin.on("end", () => {
     // Sources are read STRUCTURALLY, never through the stringified response:
     // a JSON document (the MCP {content:[{text}]} parts, the CLI --json array)
     // is parsed and its hits[].source / [].source collected.
-    const sourcesOf = (doc) => {
+    // KJC-BUG-0440 (#2830): the MCP tool may wrap its answer again (the part's
+    // text is itself {content:[parts]}); unwrapped up to three levels.
+    const sourcesOf = (doc, depth = 0) => {
+      if (Array.isArray(doc?.content) && depth < 3) return doc.content.flatMap((p) => sourcesOf(parseJson(String(p?.text || "")), depth + 1));
       const list = Array.isArray(doc) ? doc : Array.isArray(doc?.hits) ? doc.hits : [];
       return list.map((h) => h?.source).filter((x) => typeof x === "string");
     };
@@ -88,7 +92,7 @@ process.stdin.on("end", () => {
       let found = parts.flatMap((p) => sourcesOf(parseJson(String(p?.text || ""))));
       // KJC-BUG-0365 (#2208): an answer cut short (whole code chunks) is no
       // longer valid JSON, but every "source" it carries still names a hit.
-      if (found.length === 0) found = [...text.matchAll(/\\?"source\\?"\s*:\s*\\?"([^"\\]+)\\?"/g)].map((m) => m[1]);
+      if (found.length === 0) found = [...text.matchAll(/\\*"source\\*"\s*:\s*\\*"([^"\\]+)\\*"/g)].map((m) => m[1]);
       recordRag(input.text, found, parts.map((p) => String(p?.text || "")).join(String.fromCharCode(10)));
       process.exit(0);
     }
@@ -184,10 +188,18 @@ process.stdin.on("end", () => {
     const state = load();
     const s = session(state, sid);
     s.at = Date.now();
-    const rel = relative(ROOT, file).replaceAll("\\", "/");
+    // ADR 0034 (KJC-TSK-1245): a write in another lane is recorded under that lane, relative to it,
+    // so the Stop gate judges it with that lane's branch and tree.
+    const top = laneFor(file);
+    const rec = top === laneTop() ? s : (((s.lanes ||= {})[top]) ||= { edited_sources: [], edited_tests: [] });
+    const rel = relative(top, file).replaceAll("\\", "/");
     // KJC-BUG-0279 (#1981): a file outside the repository is not one of its sources.
     const inside = rel && rel !== ".." && !rel.startsWith("../") && !rel.startsWith("/");
-    const bucket = !inside ? null : TESTS.test(rel) ? s.edited_tests : CODE.test(rel) ? s.edited_sources : null;
+    const bucketOf = () => {
+      if (TESTS.test(rel)) return rec.edited_tests;
+      return CODE.test(rel) ? rec.edited_sources : null;
+    };
+    const bucket = inside ? bucketOf() : null;
     if (bucket && !bucket.includes(rel)) bucket.push(rel);
     // KJC-TSK-0910: the branch size while it is written, with the CI budget
     // (kj pr-size), said once per threshold crossed. Context, never a block.

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

@@ -7,11 +7,11 @@
 import console from "node:console";
 import process from "node:process";
 import { dirname, join, relative, resolve } from "node:path";
-import { appendFileSync, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync } 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, STATE, branchOf, foreignLane, load, save, session, boardGate, pendingMoves, pendingText, stagedVerdict } from "./sentinel-lib.mjs";
+import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, STATE, branchOf, enterLane, holdLane, laneFor, laneRefusal, laneTop, load, save, session, boardGate, pendingMoves, pendingText, stagedVerdict } from "./sentinel-lib.mjs";
 // KJC-TSK-0915 (ADR 0014): the shell reader is a real, unit-tested module copied here as is.
 import { commitStaging, isGhIssueCreate, isPublishCommand, isReadOnlyCommand, optionValues, shellSegments, stripInertQuotes, stripTextOptionValues, stripTextOnlyCommandValues } from "./sentinel-shell.mjs";
 import { DISCARD_VERBS, discardOf, foreignLost, removedFiles } from "./sentinel-discard.mjs";
@@ -26,7 +26,8 @@ let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
   try {
-    const { session_id: sid = "default", tool_name: tool, tool_input: input = {}, transcript_path: transcript = null } = JSON.parse(raw);
+    const { session_id: sid = "default", tool_name: tool, tool_input: input = {}, transcript_path: transcript = null, cwd = null } = JSON.parse(raw);
+    enterLane(load(), sid, cwd);
     // 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.
@@ -50,7 +51,7 @@ process.stdin.on("end", () => {
       // hasOwn + defineProperty: a file named __proto__ or toString is a path, not a prototype key.
       if (Object.hasOwn(touch, relT)) return;
       // --ignored: a user's ignored .env is theirs too (git clean -x deletes it).
-      const gs = spawnSync("git", ["-C", ROOT, "status", "--porcelain", "--ignored", "--", relT], { encoding: "utf8" });
+      const gs = spawnSync("git", ["-C", laneTop(), "status", "--porcelain", "--ignored", "--", relT], { encoding: "utf8" });
       const value = gs.status === 0 && String(gs.stdout).trim() === "" ? "clean" : "dirty";
       Object.defineProperty(touch, relT, { value, enumerable: true, writable: true, configurable: true });
       save(st);
@@ -60,7 +61,9 @@ process.stdin.on("end", () => {
     // only the human, editing outside it.
     if (EDIT_TOOLS.includes(tool)) {
       const target = input.file_path || input.notebook_path;
-      const relT = target ? relative(ROOT, String(target)).replaceAll("\\", "/") : "";
+      // ADR 0034: judged in the lane the write lands in (its supervisor, its config).
+      const targetTop = target ? laneFor(target) : laneTop();
+      const relT = target ? relative(targetTop, String(target)).replaceAll("\\", "/") : "";
       if (relT && PROTECTED.test(relT)) {
         console.error("karajan sentinel: ese fichero es parte del supervisor (" + relT + ") — solo el humano desmonta el sentinel, editalo fuera de la sesion." + doc("supervisor"));
         process.exit(2);
@@ -74,7 +77,8 @@ process.stdin.on("end", () => {
         console.error("karajan sentinel: " + relT + " es configuracion de gobierno (politicas, gates, exclusiones): la cambia tu usuario, no la sesion. Si un gate te parece injusto, proponselo a tu usuario o usa kj report-issue." + doc("governance"));
         process.exit(2);
       }
-      if (relT && !relT.startsWith("..") && !relT.startsWith("/")) noteFirstTouch(relT);
+      // The ledger is keyed by path in the session's lane: a write the lane guard will deny records nothing.
+      if (targetTop === laneTop() && relT && !relT.startsWith("..") && !relT.startsWith("/")) noteFirstTouch(relT);
     }
     // KJC-BUG-0261: rm / git rm is the session touching those files, noted before they go.
     if (tool === "Bash") for (const words of shellSegments(String(input.command || ""))) for (const f of removedFiles(words, ROOT)) noteFirstTouch(f);
@@ -202,9 +206,9 @@ process.stdin.on("end", () => {
       };
       const declaredGh = idLine("gh_user");
       const ghHostsPath = join(process.env.GH_CONFIG_DIR || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "gh"), "hosts.yml");
-      const activeGh = () => {
-        if (!existsSync(ghHostsPath)) return null;
-        const lines = readFileSync(ghHostsPath, "utf8").split(ESC_NL);
+      const activeGh = (hostsPath = ghHostsPath) => {
+        if (!existsSync(hostsPath)) return null;
+        const lines = readFileSync(hostsPath, "utf8").split(ESC_NL);
         const start = lines.findIndex((l) => l.startsWith("github.com:"));
         if (start < 0) return null;
         for (let k = start + 1; k < lines.length; k += 1) {
@@ -216,6 +220,19 @@ process.stdin.on("end", () => {
       };
       const words = (seg) => seg.trim().split(" ").filter((w) => w.length > 0 && w !== ESC_TAB);
       const headOf = (ws) => { let k = 0; while (k < ws.length && ws[k].indexOf("=") > 0 && ws[k].indexOf("=") < ws[k].length) k += 1; return ws.slice(k); };
+      // KJC-BUG-0459: `GH_CONFIG_DIR=<dir> gh ...` reads <dir>, not the hook's config.
+      const hostsOf = (ws) => {
+        const a = ws.slice(0, ws.length - headOf(ws).length).findLast((w) => w.startsWith("GH_CONFIG_DIR="));
+        if (!a) return null; // no assignment of its own (not the same as one naming the default dir)
+        const d = bare(a.slice("GH_CONFIG_DIR=".length)).replace(/^(~|\$HOME|\$\{HOME\})(?=\/|$)/, homedir());
+        return join(d, "hosts.yml");
+      };
+      // KJC-BUG-0459: a per-account gh (gh-tribbu, gh-ox: ADR 0040). The accounts guide makes
+      // gh-<account> run gh with GH_CONFIG_DIR=~/.config/gh-<account>: its config is READ, the
+      // wrapper is never executed by the hook.
+      const wrapperName = (w) => w.slice(w.lastIndexOf("/") + 1);
+      const isGhWrapper = (w) => /^gh-[A-Za-z0-9_.-]+$/.test(wrapperName(w));
+      const wrapperHosts = (w) => join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), wrapperName(w), "hosts.yml");
       // Wrapper shells hide the payload in a string (review catch): scan inside.
       const WRAPPERS =["sh", "bash", "zsh", "dash", "eval", "env", "xargs", "sudo", "nohup", "time", "exec"];
       let switchedTo = null;
@@ -223,12 +240,21 @@ process.stdin.on("end", () => {
       // $( and backticks are separators too (review catch): their payload is its own segment.
       const SEPS = [";", "&&", "||", "|", "$(", String.fromCharCode(96), "(", ")"];
       const bare = (w) => w.replaceAll(String.fromCharCode(39), "").replaceAll(String.fromCharCode(34), "");
-      const scan = (text, depth) => { if (depth > 3) return; for (const seg of SEPS.reduce((acc, s) => acc.flatMap((l) => l.split(s)), text.split(ESC_NL))) checkSeg(headOf(words(seg)), depth); };
-      const checkSeg = (ws, depth) => {
+      // A rescanned payload inherits the config resolved outside it (`GH_CONFIG_DIR=<dir> env gh ...`).
+      const scan = (text, depth, inherited = null) => {
+        if (depth > 3) return;
+        for (const seg of SEPS.reduce((acc, s) => acc.flatMap((l) => l.split(s)), text.split(ESC_NL))) {
+          checkSeg(headOf(words(seg)), depth, hostsOf(words(seg)) ?? inherited);
+        }
+      };
+      // hostsPath: the config an explicit GH_CONFIG_DIR assignment selects, or null without one.
+      const checkSeg = (ws, depth, hostsPath = null) => {
         if (ws.length === 0) return;
         if (WRAPPERS.includes(ws[0])) { // wrapper args have arity (sudo -u bob): scan from the first gh/wrapper token (review catch)
-          const j = ws.findIndex((w, i) => i > 0 && ["gh", ...WRAPPERS].includes(bare(w)));
-          if (j > 0) scan(ws.slice(j).map(bare).join(" "), depth + 1);
+          const j = ws.findIndex((w, i) => i > 0 && (["gh", ...WRAPPERS].includes(bare(w)) || isGhWrapper(bare(w))));
+          // `env GH_CONFIG_DIR=<dir> gh ...`: the assignments before the command go with it (review catch).
+          const assigns = ws.slice(1, Math.max(j, 1)).map(bare).filter((w) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(w));
+          if (j > 0) scan([...assigns, ...ws.slice(j).map(bare)].join(" "), depth + 1, hostsPath);
           return;
         }
         if (ws[0] === "gh") {
@@ -237,8 +263,15 @@ process.stdin.on("end", () => {
             return; // session commands ARE the remedy — never blocked
           }
           if (!declaredGh) { problems.push("gh without a declared identity for this clone — run: kj identity set"); return; }
-          const eff = switchedTo || activeGh();
-          if (eff !== declaredGh) problems.push("gh as '" + (eff || "no session") + "' but this clone is declared as '" + declaredGh + "' — prefix the command: gh auth switch --user " + declaredGh + " && ...");
+          const eff = hostsPath ? activeGh(hostsPath) : (switchedTo || activeGh());
+          if (eff !== declaredGh) problems.push("gh as '" + (eff || "no session") + "' but this clone is declared as '" + declaredGh + "' — prefix the command: gh auth switch --user " + declaredGh + " && ... (or use the gh of that account, e.g. gh-<account>)");
+        }
+        if (isGhWrapper(ws[0])) {
+          if (ws[1] === "auth") return; // its session commands are the remedy too
+          if (!declaredGh) { problems.push(ws[0] + " without a declared identity for this clone — run: kj identity set"); return; }
+          // Its own config even with an inline GH_CONFIG_DIR: the wrapper sets that variable itself.
+          const eff = activeGh(wrapperHosts(ws[0]));
+          if (eff !== declaredGh) problems.push(wrapperName(ws[0]) + " runs as '" + (eff || "no session") + "' (" + wrapperHosts(ws[0]) + ") but this clone is declared as '" + declaredGh + "' — use the gh of that account");
         }
         // KJC-TSK-1085 (ADR 0015): git commit/tag/rebase/push are no longer read here:
         // pre-commit checks the author, pre-push every pushed commit and the gh session.
@@ -249,24 +282,18 @@ process.stdin.on("end", () => {
         process.exit(2);
       }
     }
-    // MONO-0 (KJC-TSK-0737, ADR 0002): cada sesion muta solo SU worktree;
-    // otro carril del MISMO repo se deniega ANTES del dano. Lectura libre.
+    // MONO-0 (ADR 0002) under ADR 0034 (KJC-TSK-1244): a write in another lane of the SAME
+    // repo is allowed while no other live session holds that lane; the session then holds it.
+    // A held lane is denied BEFORE the damage. Reads are free.
+    // Another lane of this repo => its toplevel; the session's own lane or no repo => null.
     const laneOf = (p) => {
-      // Sube al primer ancestro EXISTENTE (un subdir aun no creado escapaba).
-      let d = String(p);
-      if (!(existsSync(d) && statSync(d).isDirectory())) d = dirname(d);
-      while (d && !existsSync(d)) {
-        const up = dirname(d);
-        if (up === d) return null;
-        d = up;
-      }
-      // Canonicaliza (reviewer catch: un symlink local hacia otro carril
-      // esquivaba la clasificacion por ruta literal).
-      try { d = realpathSync(d); } catch { /* se clasifica tal cual */ }
-      return d ? foreignLane(d) : null;
+      const top = laneFor(p);
+      return top === laneTop() ? null : top;
     };
     const laneDeny = (what, lane) => {
-      console.error("karajan sentinel: " + what + " vive en otro carril (" + lane + ") de este repo — cada sesion muta solo SU worktree (MONO-0). Sin escape (ADR 0015): un cruce deliberado lo hace tu usuario en su terminal." + doc("cross-lane"));
+      const why = holdLane(lane);
+      if (!why) return false;
+      console.error("karajan sentinel: " + what + " vive en otro carril (" + lane + ") de este repo " + why + (laneRefusal() ? " " + laneRefusal() : "") + ". Sin escape (ADR 0015): un cruce deliberado lo hace tu usuario en su terminal." + doc("cross-lane"));
       return true;
     };
     if (EDIT_TOOLS.includes(tool)) {
@@ -523,10 +550,12 @@ process.stdin.on("end", () => {
         }
       } catch { /* no report or unreadable — the Steward is not adopted here */ }
       const file = input.file_path || input.notebook_path;
-      const rel = file ? relative(ROOT, String(file)).replaceAll("\\", "/") : "";
+      // ADR 0034: the card, the branch and the RAG of the lane the write lands in.
+      const top = file ? laneFor(file) : laneTop();
+      const rel = file ? relative(top, String(file)).replaceAll("\\", "/") : "";
       // KJC-BUG-0279 (#1981): outside the repository there is no source to govern.
       if (rel && rel !== ".." && !rel.startsWith("../") && !rel.startsWith("/") && CODE.test(rel) && !TESTS.test(rel)) {
-        const branch = branchOf();
+        const branch = branchOf(top);
         const why = !branch ? null : BASE_BRANCHES.has(branch) ? "base" : !CARD.test(branch) ? "nocard" : null;
         // ADR 0015 (KJC-TSK-0925): no escape. Without a card there is no work.
         if (why) {
@@ -549,7 +578,7 @@ process.stdin.on("end", () => {
         // Solo se pregunta a git en el camino lento, cuando el gate iba a
         // denegar: exit 1 = git responde que no lo conoce; cualquier otro
         // resultado se comporta como hasta ahora y bloquea.
-        const fresh = () => !existsSync(String(file)) || spawnSync("git", ["-C", ROOT, "ls-files", "--error-unmatch", "--", rel], { encoding: "utf8" }).status === 1;
+        const fresh = () => !existsSync(String(file)) || spawnSync("git", ["-C", top, "ls-files", "--error-unmatch", "--", rel], { encoding: "utf8" }).status === 1;
         // A path outside this tree is another lane's business (the lane guard
         // above rules on it) and the ledger only holds in-repo paths.
         // KJC-BUG-0190: with nothing indexed, no query can cover anything —
@@ -570,7 +599,7 @@ process.stdin.on("end", () => {
             // esa: un indice vacio o por detras si tiene arreglo (kj rag index)
             // y sigue bloqueando, porque si no el gate desapareceria en
             // cualquier proyecto sin indexar. Nada legible = se bloquea.
-            const cov = spawnSync("kj", ["rag", "covers", rel, "--json"], { cwd: ROOT, encoding: "utf8" });
+            const cov = spawnSync("kj", ["rag", "covers", rel, "--json"], { cwd: top, encoding: "utf8" });
             let blind = null;
             let absent = null;
             try {
@@ -640,8 +669,7 @@ process.stdin.on("end", () => {
       // tail that hid its failure, let a commit through with no verdict at all.
       const plan = commitStaging(cmd);
       if (plan.commits) {
-        // 4.x: the hook payload carries no cwd; the session works in the project root.
-        const verdict = stagedVerdict(plan.dir ? resolve(ROOT, plan.dir) : ROOT);
+        const verdict = stagedVerdict(plan.dir ? resolve(cwd || ROOT, plan.dir) : (cwd || ROOT));
         if (verdict.gate && plan.stages) {
           console.error("karajan sentinel: stagea y commitea en comandos separados — el veredicto se comprueba sobre lo que ya esta stageado, y este comando stagea a la vez que commitea (git add/rm/mv, -a o rutas en git commit). Stagea por nombre, pasa kj review --staged y luego git commit." + doc("commit-verdict"));
           process.exit(2);