karajan-code 4.70.4 → 5.0.1

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

@@ -2,9 +2,9 @@
 // Single source for every sentinel script: state, branch, classification,
 // and violations.
 import process from "node:process";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { execSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
+import { execSync, spawnSync } from "node:child_process";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const here = dirname(fileURLToPath(import.meta.url));
@@ -35,24 +35,124 @@ export const session = (state, sid) => {
   state.sessions ||= {};
   return (state.sessions[sid] ||= { edited_sources: [], edited_tests: [], escapes: [], errors: [], blocks: 0 });
 };
-export const branchOf = () => {
-  try { return execSync("git rev-parse --abbrev-ref HEAD", { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); }
-  catch { return null; }
-};
 const _git = (args, cwd) => {
   try { return execSync("git " + args, { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { return ""; }
 };
+// MONO-0 (ADR 0002, amended by #2566): lane identity = worktree toplevel; repo
+// identity = git-common-dir. The session's lane is where the HOST says it works
+// (the hook payload's cwd, which EnterWorktree moves) when that is a worktree of
+// this same repo; otherwise the dir the guard is installed in. ROOT keeps the
+// harness (state, config); laneTop() is the git tree the session works in.
+// ADR 0033 (KJC-TSK-1236): a session switches into a lane only when no other live session
+// is there. Each session keeps one presence mark (its lane and when it last resolved it) in
+// the repo's git common dir. Entering is intent first, then a look: the session writes the
+// new lane, then reads the others' marks and steps back if another live one is there. Two
+// sessions entering together never both stay: the later write is seen by the later look.
+const LANE_TTL_MS = 30 * 60 * 1000;
+let _cwd = null;
+let _sid = null;
 let _home;
-// MONO-0 (ADR 0002): lane identity = worktree toplevel; repo identity =
-// git-common-dir. Same repo but another toplevel than OUR root => foreign
-// lane (returns its toplevel); anything else => null.
-export const foreignLane = (targetDir) => {
-  const top = _git("rev-parse --show-toplevel", targetDir);
-  if (!top) return null;
-  _home ||= { top: _git("rev-parse --show-toplevel", ROOT), common: _git("rev-parse --path-format=absolute --git-common-dir", ROOT) };
-  if (!_home.top || top === _home.top) return null;
-  const common = _git("rev-parse --path-format=absolute --git-common-dir", targetDir);
-  return common && common === _home.common ? top : null;
+let _refusal = null;
+const homeOf = (dir) => {
+  const [top = "", common = ""] = _git("rev-parse --show-toplevel --path-format=absolute --git-common-dir", dir).split("\n");
+  return { top, common };
+};
+export const enterLane = (_state, sid, cwd) => {
+  _cwd = cwd;
+  _sid = sid;
+  _home = undefined;
+  _refusal = null;
+};
+/** Why the session was kept out of the lane its cwd is in, or null. */
+export const laneRefusal = () => _refusal;
+const laneKey = (s) => createHash("sha256").update(String(s)).digest("hex").slice(0, 16);
+const readJson = (f) => { try { return JSON.parse(readFileSync(f, "utf8")); } catch { return null; } };
+const live = (at, now) => typeof at === "number" && now - at < LANE_TTL_MS;
+// ADR 0034: a mark also lists the lanes the session wrote in (`held`); another session holds
+// a lane when it is in it or wrote there within the period. Another session's mark that cannot
+// be read or parsed throws: the caller refuses rather than read it as a free lane.
+const heldByOther = (dir, top, now) => readdirSync(dir).filter((f) => f.startsWith("session-"))
+  .map((f) => JSON.parse(readFileSync(join(dir, f), "utf8")))
+  .some((r) => r?.sid !== _sid && ((r?.lane === top && live(r.at, now)) || live(r?.held?.[top], now)));
+const liveHeld = (mark, now) => Object.fromEntries(Object.entries(mark?.held ?? {}).filter(([, at]) => live(at, now)));
+// The lane the session may take: `lane` when it is home, already its live lane, or free.
+const claimLane = (root, lane, now = Date.now()) => {
+  if (!_sid || !root.common) return lane;
+  const dir = join(root.common, "kj-lanes");
+  const mark = join(dir, "session-" + laneKey(_sid) + ".json");
+  const write = (top) => writeFileSync(mark, JSON.stringify({ sid: _sid, lane: top, at: now, held: liveHeld(readJson(mark), now) }));
+  try {
+    mkdirSync(dir, { recursive: true });
+    const prev = readJson(mark);
+    if (lane.top !== root.top && !(prev?.lane === lane.top && live(prev.at, now))) {
+      write(lane.top);
+      if (heldByOther(dir, lane.top, now)) {
+        _refusal = "(" + lane.top + " tiene otra sesión viva: un carril, una sesión, ADR 0033)";
+        lane = root;
+      }
+    }
+    write(lane.top);
+  } catch {
+    if (lane.top !== root.top) {
+      _refusal = "(no se pudo reclamar " + lane.top + ")";
+      lane = root;
+      // Best effort: a mark left in the refused lane would keep others out for 30 min.
+      try { write(root.top); } catch { /* the session stays home either way */ }
+    }
+  }
+  return lane;
+};
+// Resolved on first use: a hook that never asks git pays no spawn.
+const home = () => {
+  if (_home) return _home;
+  const root = homeOf(ROOT);
+  const here = _cwd ? homeOf(_cwd) : null;
+  // git that cannot answer ("" common dir) never matches: fail closed to the install lane.
+  return (_home = claimLane(root, here?.top && root.common && here.common === root.common ? here : root));
+};
+export const laneTop = () => home().top || ROOT;
+/**
+ * ADR 0034 (KJC-TSK-1244): why the session may not write in lane `top`, or null once it holds it.
+ * Intent first, then a look, as a switch does (ADR 0033): the hold is written, then another
+ * live session in that lane takes it back out. Anything unreadable refuses.
+ */
+export const holdLane = (top, now = Date.now()) => {
+  const own = home();
+  if (top === laneTop()) return null;
+  if (!_sid || !own.common) return "(sin sesión identificada no se reclama " + top + ")";
+  const dir = join(own.common, "kj-lanes");
+  const mark = join(dir, "session-" + laneKey(_sid) + ".json");
+  try {
+    mkdirSync(dir, { recursive: true });
+    const mine = { sid: _sid, lane: own.top, at: now, ...readJson(mark) };
+    const held = liveHeld(mine, now);
+    writeFileSync(mark, JSON.stringify({ ...mine, held: { ...held, [top]: now } }));
+    if (!heldByOther(dir, top, now)) return null;
+    writeFileSync(mark, JSON.stringify({ ...mine, held }));
+    return "(" + top + " tiene otra sesión viva: un carril, una sesión, ADR 0033/0034)";
+  } catch {
+    return "(no se pudo reclamar " + top + ")";
+  }
+};
+export const branchOf = (top = laneTop()) => {
+  try { return execSync("git rev-parse --abbrev-ref HEAD", { cwd: top, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); }
+  catch { return null; }
+};
+// ADR 0034 (KJC-TSK-1243): the lane a write lands in is the worktree holding its path when
+// that worktree is of this repo; any other path is judged in the session's lane. It walks up
+// to the first existing dir (a subdir not created yet escaped) and canonicalizes it (a local
+// symlink into another lane was classified by its literal path).
+export const laneFor = (p) => {
+  let d = String(p);
+  while (d && !(existsSync(d) && statSync(d).isDirectory())) {
+    const up = dirname(d);
+    if (up === d) return laneTop();
+    d = up;
+  }
+  try { d = realpathSync(d); } catch { /* classified as is */ }
+  const target = homeOf(d);
+  const own = home();
+  return target.top && own.top && target.common && target.common === own.common ? target.top : laneTop();
 };
 // KJC-TSK-0765 board-sync: cards merged in this session but not yet moved in
 // the tracker. The method does not advance until the board is true.
@@ -72,9 +172,8 @@ export const bootstrapPhase = () => {
 // state: approved | rejected | missing | empty (nothing staged) | unknown (git failed).
 export const stagedVerdict = (dir) => {
   const git = (args) => spawnSync("git", ["-C", dir, ...args], { encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
-  // No commit yet (or no repo): no committed marker can exist, as the hook reads it.
+  // No commit yet (or no repo): no committed marker exists. A git error fails closed.
   if (git(["rev-parse", "--verify", "-q", "HEAD"]).status !== 0) return { gate: false };
-  // A git error is not a missing marker: it fails closed.
   const marker = git(["ls-tree", "--name-only", "HEAD", ".karajan/review-gate"]);
   if (marker.status !== 0) return { gate: true, state: "unknown" };
   if (!marker.stdout.trim()) return { gate: false };
@@ -104,31 +203,35 @@ export const boardGate = (sid, pend) => {
 // files dirty, or local commits the remote does not have), not the ledger: after a
 // merged PR and a sync of main the ledger stays full while the base holds nothing.
 // Anything git cannot answer (no upstream, odd path) counts as work: fail closed.
-const baseHoldsWork = (files) => {
+const baseHoldsWork = (files, top) => {
   if (files.some((f) => !/^[A-Za-z0-9._/-]+$/.test(f))) return true;
   try {
-    if (execSync("git status --porcelain -- " + files.join(" "), { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim()) return true;
-    return execSync("git rev-list @{u}..HEAD", { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() !== "";
+    if (execSync("git status --porcelain -- " + files.join(" "), { cwd: top, stdio: ["ignore", "pipe", "ignore"] }).toString().trim()) return true;
+    return execSync("git rev-list @{u}..HEAD", { cwd: top, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() !== "";
   } catch { return true; }
 };
-export const violations = (s, branch, pending = pendingMoves(s)) => {
+// `top` is the tree the recorded paths are relative to: ROOT, or another lane (ADR 0034).
+// laneViolations: those of every other lane the session wrote in, each named by its lane.
+export const laneViolations = (s) => Object.entries(s?.lanes ?? {})
+  .flatMap(([top, rec]) => violations(rec, branchOf(top), [], top).map((x) => "[" + top + "] " + x));
+export const violations = (s, branch, pending = pendingMoves(s), top = ROOT) => {
   const v = pending.map(pendingText);
   if (!s || !(s.edited_sources || []).length) return v;
   if (bootstrapPhase()) return v;
-  if (BASE_BRANCHES.has(branch)) { if (baseHoldsWork(s.edited_sources)) v.push("Fuentes editadas en la rama base '" + branch + "' — crea una rama: git checkout -b feat/<CARD-ID>-descripcion"); }
+  if (BASE_BRANCHES.has(branch)) { if (baseHoldsWork(s.edited_sources, top)) v.push("Fuentes editadas en la rama base '" + branch + "' — crea una rama: git checkout -b feat/<CARD-ID>-descripcion"); }
   else if (branch && !CARD.test(branch)) v.push("La rama '" + branch + "' no referencia ninguna card — usa feat/<CARD-ID>-descripcion (y una card VIVA en el board)");
-  if (!(s.edited_tests || []).length && sessionAddsCode(s)) v.push("Fuentes editadas sin tocar un solo test (" + s.edited_sources.join(", ") + ") — escribe o actualiza el test que prueba el cambio");
+  if (!(s.edited_tests || []).length && sessionAddsCode(s, top)) v.push("Fuentes editadas sin tocar un solo test (" + s.edited_sources.join(", ") + ") — escribe o actualiza el test que prueba el cambio");
   return v;
 };
 // KJC-TSK-0795 AC1: deleting code adds no behavior to test — a session whose
 // source edits only REMOVED lines owes no test. Unreadable git = conservative
 // (the violation stands): a gate must never stand down on a shrug.
-const sessionAddsCode = (s) => {
+const sessionAddsCode = (s, top) => {
   const files = s.edited_sources || [];
   // _git builds a shell string: any path outside a strict charset stays out of
   // it — and the gate stays ARMED for it (conservative, and injection-proof).
   if (files.some((f) => !/^[A-Za-z0-9._/-]+$/.test(f))) return true;
-  const stat = _git("diff HEAD --numstat -- " + files.join(" "), ROOT);
+  const stat = _git("diff HEAD --numstat -- " + files.join(" "), top);
   if (!stat) return true;
   return stat.split(String.fromCharCode(10)).some((l) => {
     const a = l.trim().replaceAll(String.fromCharCode(9), " ").split(" ").filter(Boolean)[0];

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

@@ -301,8 +301,7 @@ export const isReadOnlyCommand = (cmd) => {
 /** 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] : "");
 
-// KJC-BUG-0455 (#2933): git commit's options that take a value, and the git verbs that
-// change the index. A commit that stages in the same command commits a diff nobody
+// KJC-BUG-0455 (#2933): a commit that stages in the same command commits a diff nobody
 // could have reviewed yet: the verdict is checked against what is staged BEFORE it runs.
 const COMMIT_VALUE_OPTS = new Set(["-m", "-F", "-C", "-c", "-t", "--message", "--file", "--reuse-message", "--reedit-message", "--template", "--author", "--date", "--cleanup", "--fixup", "--squash", "--trailer", "--pathspec-from-file"]);
 const COMMIT_VALUE_SHORT = new Set(["m", "F", "C", "c", "t"]);
@@ -316,9 +315,7 @@ const gitVerbOf = (words) => {
   while (i < words.length) {
     const w = words[i];
     if (GIT_GLOBAL_WITH_VALUE.has(w)) {
-      if (w === "-C") {
-        dir = words[i + 1] ?? null;
-      }
+      if (w === "-C") dir = words[i + 1] ?? null;
       i += 2; // the option and its value
     } else if (GIT_GLOBAL_FLAG.test(w)) {
       i += 1;
@@ -351,23 +348,15 @@ const commitArg = (a) => {
 const commitStagesItself = (args) => {
   let i = 0;
   while (i < args.length) {
-    if (args[i] === "--") {
-      return i + 1 < args.length;
-    }
+    if (args[i] === "--") return i + 1 < args.length;
     const { stages, words } = commitArg(args[i]);
-    if (stages) {
-      return true;
-    }
+    if (stages) return true;
     i += words;
   }
   return false;
 };
 
-/**
- * Does the command run git commit, and does it stage in the same command?
- * @param {string} cmd
- * @returns {{commits: boolean, stages: boolean, dir: string|null}}
- */
+/** Does the command run git commit, and does it stage in the same command? → { commits, stages, dir } */
 export const commitStaging = (cmd) => {
   const gits = shellSegments(cmd).map((words) => ({ words, g: gitVerbOf(words) })).filter((s) => s.g);
   const commits = gits.filter((s) => s.g.verb === "commit");

package/src/harden/sentinel/sessionstart.mjs

@@ -6,7 +6,7 @@
 // Copied byte for byte into .karajan/harness; never fails a session (exit 0).
 import process from "node:process";
 import { spawnSync } from "node:child_process";
-import { CARD, ROOT, branchOf, load, pendingMoves } from "./sentinel-lib.mjs";
+import { CARD, ROOT, branchOf, enterLane, load, pendingMoves } from "./sentinel-lib.mjs";
 import { rulesDriftNotice } from "./sentinel-rules.mjs";
 
 const RULES = [
@@ -25,7 +25,8 @@ let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
   try {
-    const { session_id: sid = "default", source } = JSON.parse(raw || "{}");
+    const { session_id: sid = "default", source, cwd = null } = JSON.parse(raw || "{}");
+    enterLane(load(), sid, cwd);
     // KJC-TSK-0949: an MD changed and its compiled rules fell behind. Said at
     // every start, a new session included: that one gets this line and nothing else.
     const drift = rulesDriftNotice({ root: ROOT, run: spawnSync });

package/src/harden/sentinel/stop.mjs

@@ -10,7 +10,7 @@ import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { doc, load, save, branchOf, violations, ROOT } from "./sentinel-lib.mjs";
+import { doc, load, save, branchOf, enterLane, laneViolations, violations, ROOT } from "./sentinel-lib.mjs";
 // KJC-TSK-0774: when the turn ends green with cards closed, remind the user
 // where to look — the board URL if it runs (pid file alive), else how to start it.
 const boardHint = () => {
@@ -27,7 +27,7 @@ if (process.argv.includes("--status")) {
   if (!sessions.length) console.log("sentinel: sin actividad registrada en esta sesion");
   for (const [sid, s] of sessions) {
     console.log("session " + sid + ": sources=[" + (s.edited_sources || []).join(", ") + "] tests=[" + (s.edited_tests || []).join(", ") + "] escapes=[" + (s.escapes || []).join(", ") + "] blocks=" + (s.blocks || 0) + ((s.errors || []).length ? " errors=" + s.errors.length : "") + " rag=" + (s.rag_queries || []).length + " queries/" + (s.rag_hits || []).length + " sources");
-    for (const x of violations(s, branch)) console.log("  ROJO: " + x);
+    for (const x of [...violations(s, branch), ...laneViolations(s)]) console.log("  ROJO: " + x);
   }
   process.exit(0);
 }
@@ -36,8 +36,9 @@ process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
   try {
     if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
-    const { session_id: sid = "default", transcript_path: transcript = null } = JSON.parse(raw);
+    const { session_id: sid = "default", transcript_path: transcript = null, cwd = null } = JSON.parse(raw);
     const state = load();
+    enterLane(state, sid, cwd);
     // Tamper check runs regardless of session state: shell indirection leaves
     // no edit-tool record, but it cannot survive `kj sentinel verify`, whose
     // root of trust is the INSTALLED kj package (outside this project tree) —
@@ -87,7 +88,7 @@ process.stdin.on("end", () => {
         if ((p.stdout || "").trim()) console.error(p.stdout.trim());
       }
     }
-    const v = violations(s, branchOf());
+    const v = [...violations(s, branchOf()), ...laneViolations(s)];
     if (claimsBlock) v.push(claimsBlock);
     if (!v.length) {
       s.blocks = 0;

package/src/harden/workflow-templates.js

@@ -19,7 +19,7 @@ export const PINNED_ACTIONS = {
   setupNode: "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4",
   setupPython: "actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5",
   setupGo: "actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5",
-  setupPhp: "shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2",
+  setupPhp: "shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # v2",
 };
 
 export const NO_AI_ATTRIBUTION_WORKFLOW = [

package/src/hu/board-lookup.js

@@ -0,0 +1,29 @@
+/**
+ * KJC-BUG-0454: one card of the HU Board, read where `kj hu` keeps it. `kj code --card`
+ * looked in the old kj run store, so every card `kj hu add` created was "not found".
+ * Shared board: the GitHub issue HU-<n>, as `kj hu list` reads it. Local board: the
+ * plan backlog, by id or short id.
+ */
+import { listPlans, loadPlan } from "../plan/plan-store.js";
+import { readBoardConfig } from "./board-config.js";
+import { listHus } from "./github-board.js";
+import { pinGhIdentity } from "./gh-identity.js";
+import { listWithCache } from "./team-board-cache.js";
+
+const SHARED_ID = /^HU-[1-9]\d*$/i;
+
+export async function findBoardHu(projectDir, ref, deps = {}) {
+  const board = await (deps.boardConfig ?? readBoardConfig)(projectDir);
+  if (board.backend === "github" && SHARED_ID.test(ref)) {
+    (deps.pinGhIdentity ?? pinGhIdentity)({ projectDir });
+    const { rows } = await (deps.cache?.list ?? listWithCache)({ projectDir, repo: board.repo, list: deps.listTeamHus ?? listHus });
+    const hu = rows.find((h) => h.short_id.toUpperCase() === ref.toUpperCase());
+    if (hu) return hu;
+  }
+  for (const meta of await (deps.listPlans ?? listPlans)(projectDir)) {
+    const plan = await (deps.loadPlan ?? loadPlan)(projectDir, meta.planId);
+    const hu = (plan.hus || []).find((h) => h.id === ref || h.short_id === ref);
+    if (hu) return hu;
+  }
+  throw new Error(`HU ${ref} is not on the HU Board — kj hu list shows its cards`);
+}

package/src/hu/gh-identity.js

@@ -2,6 +2,7 @@
 // accounts on one machine, another session switching the active one turned `kj hu move` into an
 // opaque GraphQL permission error, three times in a day. The clone declares its account in
 // .karajan/identity.local.yml (ADR 0005): with a declaration, the active account must be it.
+import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -42,3 +43,25 @@ export function assertGhIdentity({ projectDir, env = process.env }) {
   }
   return { declared, active };
 }
+
+/** The token gh keeps for `user`, read without switching the active account; null when it has none. */
+function ghTokenOf(user, env) {
+  const res = spawnSync("gh", ["auth", "token", "--hostname", "github.com", "--user", user], { env, encoding: "utf8" });
+  return res.status === 0 ? res.stdout.trim() || null : null;
+}
+
+/**
+ * KJC-BUG-0406: checking the active account and then calling gh was a race; another session could
+ * switch it in between. With an identity declared, GH_TOKEN is pinned to that account's token for
+ * the rest of the command, so every gh call goes out as it. A token already in the environment is
+ * the user's explicit choice and is left alone.
+ * @returns {{ declared: string | null, pinned: boolean }}
+ */
+export function pinGhIdentity({ projectDir, env = process.env, tokenOf = ghTokenOf }) {
+  const declared = readIdentity(projectDir)?.gh_user ?? null;
+  if (!declared || env.GH_TOKEN || env.GITHUB_TOKEN) return { declared, pinned: false };
+  const token = tokenOf(declared, env);
+  if (!token) throw new BoardRejectedError(`gh has no login for ${declared}, the account this clone declares: run gh auth login and retry`);
+  env.GH_TOKEN = token;
+  return { declared, pinned: true };
+}

package/src/hu/github-board.js

@@ -70,8 +70,10 @@ export async function createHu({ repo, title, acceptanceCriteria = [], tests = [
 
 /** Every HU of the repo, with its status and who holds it. */
 export async function listHus({ repo, run = runCommand }) {
-  const issues = listOf(await gh(run, ["issue", "list", "-R", repo, "--label", HU_LABEL, "--state", "all", "--limit", "1000", "--json", "number,title,state,labels,assignees"]));
-  return issues.map((i) => ({ short_id: `HU-${i.number}`, number: i.number, title: i.title, status: statusOf(i), claimed_by: i.assignees[0]?.login ?? null }));
+  const issues = listOf(await gh(run, ["issue", "list", "-R", repo, "--label", HU_LABEL, "--state", "all", "--limit", "1000", "--json", "number,title,state,labels,assignees,body"]));
+  // KJC-BUG-0443: the tracker reference kj hu add --ref wrote in the body.
+  const refOf = (body) => /^Ref: (\S.*)$/m.exec(body ?? "")?.[1].trim() ?? null;
+  return issues.map((i) => ({ short_id: `HU-${i.number}`, number: i.number, title: i.title, status: statusOf(i), claimed_by: i.assignees[0]?.login ?? null, ref: refOf(i.body) }));
 }
 
 /** The one kj:<status> of an issue; none or several is a board someone broke by hand. */

package/src/hu/lane-prune.js

@@ -5,30 +5,61 @@
  * touched, so a session may run this without risking anyone's work.
  */
 import fs from "node:fs";
+import { spawnSync } from "node:child_process";
 import path from "node:path";
+import { isLaneSetupPath, laneWork } from "./lane-setup.js";
+import { readBootstrap } from "../rag/bootstrap-index.js";
 
 const IDLE_HOURS = 24;
+// HU-3092: the lane's index and what rides along it (-wal, -shm, .bootstrap, .embed-schema) is regenerable state.
+const RAG_STATE = /^\.karajan\/rag\.db([.-]|$)/;
 const REGENERABLE = new Set(["node_modules", "dist", "build", "coverage", ".venv", "venv", "__pycache__", ".cache", "target"]);
 
+const LSOF = "/usr/sbin/lsof";
+const LSOF_TIMEOUT_MS = 10_000;
+
+/** HU-3117: `lsof -Fpn` output is `p<pid>` then `n<path>` lines; a pid with no path line is skipped. */
+export function parseLsofCwds(out) {
+  const procs = [];
+  let pid = null;
+  for (const line of out.split("\n")) {
+    if (line.startsWith("p") && /^\d+$/.test(line.slice(1))) pid = Number(line.slice(1));
+    else if (line.startsWith("n") && pid !== null) { procs.push({ pid, cwd: line.slice(1) }); pid = null; }
+  }
+  return procs;
+}
+
+/** darwin has no /proc: lsof lists this user's cwds. null when it is missing, fails or times out (never "no processes"). */
+function lsofProcesses({ run, uid }) {
+  const r = run(LSOF, ["-a", "-d", "cwd", "-u", String(uid), "-Fpn"], { encoding: "utf8", timeout: LSOF_TIMEOUT_MS });
+  if (r.error || r.status !== 0 || typeof r.stdout !== "string") return null;
+  const procs = parseLsofCwds(r.stdout);
+  return { cwds: new Set(procs.map((p) => p.cwd)), unseen: 0, procs };
+}
+
 /**
  * This user's live processes (another user's cannot write in our worktrees): the
  * cwds that can be read and how many cannot (non-dumpable ones: ssh-agent, systemd,
- * some JVMs). null when the platform has no /proc.
+ * some JVMs). null when the platform's listing is unavailable (no /proc, no lsof).
  */
-export function liveProcesses() {
+export function liveProcesses({ platform = process.platform, run = spawnSync, uid = process.getuid() } = {}) {
+  if (platform === "darwin") return lsofProcesses({ run, uid });
   let pids;
   try { pids = fs.readdirSync("/proc").filter((p) => /^\d+$/.test(p)); } catch { return null; }
   const cwds = new Set();
+  const procs = [];
   let unseen = 0;
   for (const pid of pids) {
     try {
       if (fs.statSync(`/proc/${pid}`).uid !== process.getuid()) continue;
-      cwds.add(fs.readlinkSync(`/proc/${pid}/cwd`));
+      const cwd = fs.readlinkSync(`/proc/${pid}/cwd`);
+      cwds.add(cwd);
+      procs.push({ pid: Number(pid), cwd });
     } catch (err) {
       if (err.code !== "ENOENT" && err.code !== "ESRCH") unseen += 1;
     }
   }
-  return { cwds, unseen };
+  return { cwds, unseen, procs };
 }
 
 /** Hours since anything in the lane moved: its dir, and its git index and HEAD. */
@@ -42,6 +73,32 @@ async function idleHours(git, lanePath, now) {
 
 const inside = (cwd, dir) => cwd === dir || cwd.startsWith(dir + path.sep);
 
+/** A folder git lists whole (an ignored `.karajan/`) holds only index state and setup when every file in it does. */
+function onlyRagState(lanePath, dir) {
+  try {
+    return fs.readdirSync(path.join(lanePath, dir), { recursive: true, withFileTypes: true }).filter((d) => !d.isDirectory()) // symlinks and the like are the user's, never state
+      .every((d) => { const rel = path.relative(lanePath, path.join(d.parentPath, d.name)); return RAG_STATE.test(rel) || isLaneSetupPath(rel); });
+  } catch { return false; }
+}
+const ragOnly = (lanePath, p) => RAG_STATE.test(p) || (p.endsWith("/") && onlyRagState(lanePath, p));
+
+/**
+ * The pid of the lane's background indexer: the one its marker names, while the marker notes no stop.
+ * null when KJ_RAG_DB puts the index elsewhere: the marker read is then not this lane's.
+ */
+function indexerOf(lanePath) {
+  if (process.env.KJ_RAG_DB) return null;
+  const marker = readBootstrap(lanePath);
+  return Number.isInteger(marker?.pid) && !marker.stoppedAt ? marker.pid : null;
+}
+
+/** D6: stops each removable lane's indexer; a lane whose indexer survives (marker still running) is kept, saying so. */
+export async function stopLaneIndexers(lanes, { stop, stillRunning }) {
+  for (const l of lanes.filter((x) => x.indexer && x.reasons.length === 0)) {
+    if (!(await stop(l)) && (await stillRunning(l))) l.reasons.push(`its background index (pid ${l.indexer.pid}) could not be stopped`);
+  }
+}
+
 /** @returns {Promise<{slug: string, path: string, branch: string|null, reasons: string[]}[]>} */
 export async function classifyLanes({ git, laneRoot, base, processes, now = Date.now() }) {
   const { stdout } = await git(["worktree", "list", "--porcelain"]);
@@ -55,21 +112,28 @@ export async function classifyLanes({ git, laneRoot, base, processes, now = Date
   }
   return Promise.all(lanes.map(async (lane) => {
     const reasons = [];
-    const { stdout: status } = await git(["status", "--porcelain", "--ignored=matching"], lane.path);
-    const entries = status.split("\n").filter(Boolean);
+    // KJC-TSK-1371: the identity and Sentinel files lane setup wrote are not the lane's work.
+    const { stdout: status } = await git(["status", "--porcelain", "--ignored=matching", "--untracked-files=all"], lane.path);
+    const entries = laneWork(status, lane.path).filter((e) => !ragOnly(lane.path, e.slice(3)));
     if (entries.some((e) => !e.startsWith("!! "))) reasons.push("uncommitted changes");
     // Ignored files can be valuable (.env, local artifacts); only regenerable dirs are not.
     const precious = entries.filter((e) => e.startsWith("!! ") && !REGENERABLE.has(e.slice(3).split("/")[0]));
     if (precious.length > 0) reasons.push(`ignored files that are not regenerable (${precious[0].slice(3)}${precious.length > 1 ? ", …" : ""})`);
     // The lane's HEAD, branch or detached: a detached lane's commits have no other name.
-    const { stdout: ahead } = await git(["rev-list", "--count", `${base}..HEAD`], lane.path);
-    if (Number(ahead) > 0) reasons.push(`${Number(ahead)} commit(s) not in ${base}`);
+    const ahead = await commitsNotIn({ git, base, cwd: lane.path });
+    if (ahead > 0) reasons.push(`${ahead} commit(s) not in ${base}`);
+    // The lane's own indexer alone is no reason to keep it (HU-3092); without pids (older callers) any process still is.
+    const inLane = (processes?.procs ?? []).filter((p) => inside(p.cwd, lane.path));
+    const indexer = processes?.procs ? indexerOf(lane.path) : null;
+    const busy = processes !== null && [...processes.cwds].some((cwd) => inside(cwd, lane.path));
+    const owned = busy && indexer !== null && inLane.every((p) => p.pid === indexer) ? { pid: indexer } : null;
     if (processes === null) reasons.push("cannot check for live processes on this platform");
-    else if ([...processes.cwds].some((cwd) => inside(cwd, lane.path))) reasons.push("a live process works in it");
+    else if (busy && !owned) reasons.push("a live process works in it");
+    // The owned indexer excluded, processes that cannot be inspected still protect a recently active lane.
     else if (processes.unseen > 0 && (await idleHours(git, lane.path, now)) < IDLE_HOURS) {
       reasons.push(`${processes.unseen} process(es) of yours cannot be inspected and the lane changed in the last ${IDLE_HOURS} h`);
     }
-    return { slug: path.basename(lane.path), path: lane.path, branch: lane.branch, reasons };
+    return { slug: path.basename(lane.path), path: lane.path, branch: lane.branch, reasons, indexer: owned };
   }));
 }
 
@@ -83,6 +147,12 @@ export async function resolveBase({ git, base }) {
   }
 }
 
+/** Commits of `ref` (default HEAD, run in `cwd`) that `base` lacks; 0 means merged. */
+export async function commitsNotIn({ git, base, ref = "HEAD", cwd }) {
+  const { stdout } = await git(["rev-list", "--count", `${base}..${ref}`], cwd);
+  return Number(stdout);
+}
+
 /** KJC-TSK-1037: loose kj-hu-* branches (no worktree): the empty ones, and the ones with work and how much. */
 export async function looseLaneBranches({ git, base }) {
   const { stdout: listed } = await git(["for-each-ref", "--format=%(refname:short) %(worktreepath)", "refs/heads/kj-hu-*"]);
@@ -90,9 +160,9 @@ export async function looseLaneBranches({ git, base }) {
   const empty = [];
   const withWork = [];
   for (const branch of loose) {
-    const { stdout: ahead } = await git(["rev-list", "--count", `${base}..${branch}`]);
-    if (Number(ahead) === 0) empty.push(branch);
-    else withWork.push({ branch, reason: `${Number(ahead)} commit(s) not in ${base}` });
+    const ahead = await commitsNotIn({ git, base, ref: branch });
+    if (ahead === 0) empty.push(branch);
+    else withWork.push({ branch, reason: `${ahead} commit(s) not in ${base}` });
   }
   return { empty, withWork };
 }

package/src/hu/lane-setup.js

@@ -0,0 +1,65 @@
+/**
+ * Lane setup (KJC-TSK-1371, #2852, step 6 of #2566): a lane `kj worktree start` creates is
+ * ready on creation. Two things a fresh git worktree lacks, because git does not track them:
+ * - the clone identity (.karajan/identity.local.yml), which the hooks read from the lane root
+ *   so the identity lock knows who pushes; copied from the main checkout when it has one;
+ * - the Sentinel wiring (.claude/settings.json hooks and .karajan/harness), installed in the
+ *   lane with the same installers `kj harden` uses, so the first write there is governed.
+ * A step that fails stops the start loudly, naming the step: never a half-set lane in silence.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import { installSentinelHooks } from "../harden/sentinel-hooks.js";
+import { installHarnessHooks } from "../harden/harness-hooks.js";
+
+const IDENTITY = path.join(".karajan", "identity.local.yml");
+const INSTALLERS = { sentinel: installSentinelHooks, harness: installHarnessHooks };
+
+/** What setupLane writes into a lane (and the Sentinel's runtime state): never the lane's work. */
+export const isLaneSetupPath = (p) => p === IDENTITY || p === path.join(".claude", "settings.json") || p.startsWith(path.join(".karajan", "harness") + path.sep);
+
+/** A folder git lists whole (an ignored `.claude/`) is setup only when every file in it is. */
+function onlySetup(lanePath, dir) {
+  try {
+    const files = fs.readdirSync(path.join(lanePath, dir), { recursive: true, withFileTypes: true }).filter((d) => d.isFile());
+    return files.every((d) => isLaneSetupPath(path.relative(lanePath, path.join(d.parentPath, d.name))));
+  } catch {
+    return false;
+  }
+}
+
+/** `git status --porcelain` lines that are the lane's own work, setup files left out. */
+export const laneWork = (porcelain, lanePath) => porcelain.split("\n").filter(Boolean).filter((line) => {
+  const p = line.slice(3);
+  return !(isLaneSetupPath(p) || (p.endsWith("/") && lanePath && onlySetup(lanePath, p)));
+});
+
+function step(name, fn) {
+  try {
+    return fn();
+  } catch (err) {
+    throw new Error(`lane setup failed at ${name}: ${err?.message || err}`, { cause: err });
+  }
+}
+
+/** @returns {Promise<{ identity: boolean, wired: boolean }>} */
+export async function setupLane({ mainDir, lanePath, logger = console, install = INSTALLERS }) {
+  const source = path.join(mainDir, IDENTITY);
+  const identity = step("the clone identity", () => {
+    if (!fs.existsSync(source)) return false;
+    fs.mkdirSync(path.join(lanePath, ".karajan"), { recursive: true });
+    fs.copyFileSync(source, path.join(lanePath, IDENTITY));
+    return true;
+  });
+  if (identity) logger.info?.(`  identity: ${IDENTITY} copied from the main checkout`);
+  else logger.warn?.(`! no ${IDENTITY} in the main checkout: run kj identity set in the lane before pushing`);
+
+  step("the Sentinel wiring", () => {
+    const quiet = { info: () => {}, warn: (m) => logger.warn?.(m) };
+    const results = [install.sentinel({ projectDir: lanePath, logger: quiet }), install.harness({ projectDir: lanePath, logger: quiet })];
+    if (results.some((r) => !r?.wired)) throw new Error("the hooks were not wired (unreadable .claude/settings.json?)");
+  });
+  logger.info?.("  Sentinel: hooks wired in the lane");
+  return { identity, wired: true };
+}