karajan-code 4.70.4 → 5.0.1

package/src/commands/skills.js

@@ -13,6 +13,7 @@
 import { listCached, clearCache, getCacheRoot, DEFAULT_TTL_MS } from "../skills/skills-cache.js";
 import { refreshIfStale, listAvailableSlugs, getCatalogRoot, loadSkillBySlug } from "../skills/addyosmani-catalog.js";
 import { ATRIL_COMMANDS, runAtril } from "../skills/atril-cli.js";
+import { skillsSearch } from "../skills/skills-search.js";
 
 function humanAge(cachedAt) {
   const ms = Date.now() - Date.parse(cachedAt);
@@ -22,7 +23,9 @@ function humanAge(cachedAt) {
   return `${days.toFixed(1)}d ago`;
 }
 
-export async function skillsCommand({ action = "list", args = [], deps = { atril: runAtril } } = {}) {
+export async function skillsCommand({ action = "list", args = [], deps = { atril: runAtril, skillsSearch } } = {}) {
+  // HU-2782: search is kj's own, so the query can be translated into English first.
+  if (action === "search") return deps.skillsSearch({ args });
   // KJC-TSK-1193: atril's own commands go to atril, on the .karajan store.
   if (ATRIL_COMMANDS.includes(action)) return deps.atril({ action, args });
   switch (action) {

package/src/commands/start.js

@@ -2,7 +2,7 @@
 // Wires the read-only sweep (0568) → deterministic assessment (0569) → haiku
 // decider (0569), reports the recommended next step, and — interactively only —
 // confirms and dispatches the chosen intent to its saved command
-// (harden/rag/run/plan). --json / --yes / no-TTY stay read-only: emit the
+// (harden/rag). --json / --yes / no-TTY stay read-only: emit the
 // assessment + intent and apply nothing. Collaborators are injected for testing.
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -17,16 +17,15 @@ const NEXT_STEP = {
   ASSESS_ONLY: "Everything looks healthy — nothing to do.",
   RECOMMEND_HARDEN: "Suggested: `kj harden --interactive`",
   RECOMMEND_INDEX: "Suggested: `kj rag index`",
-  START_TASK: 'Suggested: `kj run "<task>"`',
-  PROPOSE_PLAN: 'Suggested: `kj plan "<goal>"`',
+  // KJC-TSK-1322: kj run and kj plan generate are retired in 5.0; your agent does the work.
+  START_TASK: 'Suggested: ask your agent for it, and put it on the board first with `kj hu add "<task>"`',
+  PROPOSE_PLAN: 'Suggested: have your agent plan it with `kj brief planner`, then `kj hu add` each piece',
 };
 
 // Each writing intent maps to the saved command + args `kj start` dispatches.
 const DISPATCH = {
   RECOMMEND_HARDEN: () => ["harden", "--interactive"],
   RECOMMEND_INDEX: () => ["rag", "index"],
-  START_TASK: (task) => ["run", task],
-  PROPOSE_PLAN: (task) => ["plan", task],
 };
 
 const ASK_FALLBACK = "What would you like to do with this project?";

package/src/commands/steward.js

@@ -19,6 +19,7 @@ import { loadPreviousAudit } from "../audit/basal-cost.js";
 import { collectOsvFindings } from "../audit/osv-findings.js";
 import { recordGateDecision } from "../policy/decisions.js";
 import { syncProposedWork } from "../steward/proposed-work.js";
+import { sweepPhantoms } from "../steward/phantom-sweep.js";
 
 const stewardDir = (projectDir) => path.join(projectDir, ".karajan", "steward");
 
@@ -30,39 +31,63 @@ const ghRuns = (projectDir, baseBranch) => () => {
 
 const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } };
 
+const MARK = { [VERDICTS.OK]: "✓", [VERDICTS.BROKEN]: "✗", [VERDICTS.UNKNOWN]: "?", [VERDICTS.NOT_OBSERVABLE]: "∅" };
+
+/**
+ * STW-E (KJC-TSK-0793): --if-stale <days> — resuming work with a fresh
+ * report does not re-sweep; the report in the repo stays the ONE source.
+ * @returns {object|null} the fresh previous report, or null when a sweep is due
+ */
+function freshReport(projectDir, flags, probes) {
+  if (flags.ifStale === undefined) return null;
+  const prev = readJson(path.join(stewardDir(projectDir), "report.json"));
+  const ageMs = prev?.sweptAt ? (probes.nowMs ?? Date.now()) - Date.parse(prev.sweptAt) : Infinity;
+  return ageMs < Number(flags.ifStale) * 86_400_000 ? prev : null;
+}
+
+/**
+ * Live osv probe (best-effort): unavailable is null → the invariant answers
+ * unknown with its remedy, never a clean bill.
+ */
+async function liveVulns({ projectDir, logger, probes }) {
+  if (probes.vulns != null) return probes.vulns;
+  try {
+    const osv = await (probes.osvFn ?? collectOsvFindings)(projectDir, logger);
+    if (osv?.available) return (osv.vulnerabilities || []).map((v) => ({ id: v.id, severity: v.severity, publishedAt: v.publishedAt ?? null }));
+  } catch { /* stays null — unknown */ }
+  return null;
+}
+
+/** The dead code the last audit counted: knip's exports + files, or the older deadExports list. */
+async function deadCodeNow(projectDir) {
+  const snapshot = await loadPreviousAudit(projectDir).catch(() => null);
+  if (typeof snapshot?.knipDeadExports?.exports === "number") {
+    return { deadExports: snapshot.knipDeadExports.exports + (snapshot.knipDeadExports.files || 0) };
+  }
+  return Array.isArray(snapshot?.deadExports) ? { deadExports: snapshot.deadExports.length } : null;
+}
+
+/** The phantom detectors over the project's test↔source pairs; a failure is said, never clean. */
+function phantomSweep(projectDir, probes) {
+  if (probes.phantoms) return probes.phantoms;
+  try { return sweepPhantoms({ projectDir }); } catch (err) { return { reason: `the phantom sweep failed (${err.message})` }; }
+}
+
 export async function stewardSweepCommand({ flags = {}, config = {}, logger = console, probes = {} } = {}) {
   const projectDir = config.projectDir || process.cwd();
   const baseBranch = config.base_branch || "main";
-  // STW-E (KJC-TSK-0793): --if-stale <days> — resuming work with a fresh
-  // report does not re-sweep; the report in the repo stays the ONE source.
-  if (flags.ifStale !== undefined) {
-    const prev = readJson(path.join(stewardDir(projectDir), "report.json"));
-    const ageMs = prev?.sweptAt ? (probes.nowMs ?? Date.now()) - Date.parse(prev.sweptAt) : Infinity;
-    if (ageMs < Number(flags.ifStale) * 86_400_000) {
-      logger.info?.(`steward: report is fresh (swept ${prev.sweptAt}) — not re-sweeping`);
-      return 0;
-    }
+  const fresh = freshReport(projectDir, flags, probes);
+  if (fresh) {
+    logger.info?.(`steward: report is fresh (swept ${fresh.sweptAt}) — not re-sweeping`);
+    return 0;
   }
   const freshness = resolveFreshness(config);
   const nowMs = probes.nowMs ?? Date.now();
   const runsFn = probes.runsFn ?? ghRuns(projectDir, baseBranch);
-
-  // Live osv probe (best-effort): unavailable is null → the invariant answers
-  // unknown with its remedy, never a clean bill.
-  let vulns = probes.vulns ?? null;
-  if (vulns === null) {
-    try {
-      const osv = await (probes.osvFn ?? collectOsvFindings)(projectDir, logger);
-      if (osv?.available) vulns = (osv.vulnerabilities || []).map((v) => ({ id: v.id, severity: v.severity, publishedAt: v.publishedAt ?? null }));
-    } catch { /* stays null — unknown */ }
-  }
-
+  const vulns = await liveVulns({ projectDir, logger, probes });
   // Dead-code baseline: the PREVIOUS report in the repo — shared memory.
   const prevReport = readJson(path.join(stewardDir(projectDir), "report.json"));
-  const snapshot = await loadPreviousAudit(projectDir).catch(() => null);
-  const deadNow = typeof snapshot?.knipDeadExports?.exports === "number"
-    ? { deadExports: snapshot.knipDeadExports.exports + (snapshot.knipDeadExports.files || 0) }
-    : Array.isArray(snapshot?.deadExports) ? { deadExports: snapshot.deadExports.length } : null;
+  const deadNow = await deadCodeNow(projectDir);
 
   const invariants = [
     { id: "main-ci", renew: "push to the base branch (or fix the red run)", evaluate: () => evaluateMainCi({ projectDir, baseBranch, freshness: freshness.values, runsFn, nowMs }) },
@@ -70,7 +95,7 @@ export async function stewardSweepCommand({ flags = {}, config = {}, logger = co
     { id: "vulnerable-deps", renew: "kj audit (osv-scanner)", evaluate: () => evaluateVulnAging({ vulns, freshness: freshness.values, nowMs }) },
     { id: "dead-code-trend", renew: "kj audit (knip inventory)", evaluate: () => evaluateDeadCodeTrend({ current: deadNow, previous: prevReport?.deadCodeBaseline ?? null }) },
     { id: "coverage-config", renew: "configure a coverage threshold", evaluate: () => evaluateCoverageConfig({ projectDir }) },
-    { id: "phantom-coverage", renew: "KJC-TSK-0800 ships the detectors", evaluate: () => evaluatePhantomCoverage() },
+    { id: "phantom-coverage", renew: "kj steward sweep (runs the phantom detectors)", evaluate: () => evaluatePhantomCoverage(phantomSweep(projectDir, probes)) },
   ];
   const results = runInvariants(invariants, {}).map((r, i) => ({ ...r, renew: invariants[i].renew }));
   const broken = results.filter((r) => r.verdict === VERDICTS.BROKEN);
@@ -82,57 +107,81 @@ export async function stewardSweepCommand({ flags = {}, config = {}, logger = co
     invariants: results,
     deadCodeBaseline: deadNow ? { ...deadNow, timestamp: new Date(nowMs).toISOString() } : (prevReport?.deadCodeBaseline ?? null),
   };
-  const mark = { [VERDICTS.OK]: "✓", [VERDICTS.BROKEN]: "✗", [VERDICTS.UNKNOWN]: "?", [VERDICTS.NOT_OBSERVABLE]: "∅" };
+  writeReport(projectDir, report, freshness);
+  sealSweep({ projectDir, results, broken, logger });
+  await cardBrokenInvariants({ projectDir, config, results, sweptAt: report.sweptAt, logger });
+  warnIfReportIgnored(projectDir, logger);
+  printSweep({ flags, report, results, broken, logger });
+  process.exitCode = broken.length ? 1 : 0;
+  return broken.length ? 1 : 0;
+}
+
+function writeReport(projectDir, report, freshness) {
+  const freshnessValues = Object.entries(freshness.values).map(([k, v]) => `${k}=${v}`).join(", ");
   const md = [
     "# Steward report",
     "", `Last swept: ${report.sweptAt}`, "",
-    `Freshness: ${freshness.declared ? "declared by the project" : "calibrated defaults (the project declared none)"} — ${Object.entries(freshness.values).map(([k, v]) => `${k}=${v}`).join(", ")}`, "",
-    ...results.map((r) => [
-      `## ${mark[r.verdict] || "?"} ${r.id} — ${r.verdict}`,
+    `Freshness: ${freshness.declared ? "declared by the project" : "calibrated defaults (the project declared none)"} — ${freshnessValues}`, "",
+    ...report.invariants.flatMap((r) => [
+      `## ${MARK[r.verdict] || "?"} ${r.id} — ${r.verdict}`,
       `- evidence: ${r.evidence || "(none)"}`,
       ...(r.remedy ? [`- remedy: ${r.remedy}`] : []),
       `- renews with: ${r.renew}`, "",
-    ]).flat(),
+    ]),
   ].join("\n");
-
   fs.mkdirSync(stewardDir(projectDir), { recursive: true });
   fs.writeFileSync(path.join(stewardDir(projectDir), "report.md"), md);
   fs.writeFileSync(path.join(stewardDir(projectDir), "report.json"), `${JSON.stringify(report, null, 2)}\n`);
+}
 
-  // Every sweep is SEALED in the decision chain — the same criterion policy
-  // decisions already meet: recorded and verifiable, not just notified.
+/**
+ * Every sweep is SEALED in the decision chain — the same criterion policy
+ * decisions already meet: recorded and verifiable, not just notified.
+ */
+function sealSweep({ projectDir, results, broken, logger }) {
   try {
     const counts = {};
     for (const r of results) counts[r.verdict] = (counts[r.verdict] || 0) + 1;
     recordGateDecision(projectDir, { kind: "steward-sweep", verdicts: { ok: counts[VERDICTS.OK] || 0, broken: broken.length, unknown: counts[VERDICTS.UNKNOWN] || 0, "not-observable": counts[VERDICTS.NOT_OBSERVABLE] || 0 }, broken_ids: broken.map((b) => b.id) });
   } catch (err) { logger.warn?.(`⚠ steward: the sweep could not be sealed in the decision chain (${err.message})`); }
+}
 
-  // STW-D (KJC-TSK-0792): every break is PROPOSED work on the board the brain
-  // already consumes. AFTER the report and the seal: a board failure never
-  // costs either, and it is said loudly — never swallowed.
+/**
+ * STW-D (KJC-TSK-0792): every break is PROPOSED work on the board the brain
+ * already consumes. AFTER the report and the seal: a board failure never
+ * costs either, and it is said loudly — never swallowed.
+ */
+async function cardBrokenInvariants({ projectDir, config, results, sweptAt, logger }) {
   try {
-    const sync = await syncProposedWork({ projectDir, config, results, sweptAt: report.sweptAt });
-    if (!sync.synced) logger.warn?.(`⚠ steward: broken invariants not carded — ${sync.reason}`);
-    else if (sync.created || sync.updated || sync.resolved) {
-      logger.info?.(`steward board: ${sync.created} card(s) proposed, ${sync.updated} updated, ${sync.resolved} resolved`);
-      if (sync.replicateIn) logger.info?.(`→ replicate them in ${sync.replicateIn} through your agent's board tools (kj hu list shows them)`);
+    const sync = await syncProposedWork({ projectDir, config, results, sweptAt });
+    if (!sync.synced) {
+      logger.warn?.(`⚠ steward: broken invariants not carded — ${sync.reason}`);
+      return;
     }
+    if (!(sync.created || sync.updated || sync.resolved)) return;
+    logger.info?.(`steward board: ${sync.created} card(s) proposed, ${sync.updated} updated, ${sync.resolved} resolved`);
+    if (sync.replicateIn) logger.info?.(`→ replicate them in ${sync.replicateIn} through your agent's board tools (kj hu list shows them)`);
   } catch (err) { logger.warn?.(`⚠ steward: carding the broken invariants failed (${err.message}) — the report and the seal stand`); }
+}
 
-  // A report nobody can see is not shared state — say it, do not fix their tree.
+/** A report nobody can see is not shared state — say it, do not fix their tree. */
+function warnIfReportIgnored(projectDir, logger) {
   try {
     execFileSync("git", ["check-ignore", "-q", path.join(".karajan", "steward", "report.md")], { cwd: projectDir });
     logger.warn?.("⚠ steward: the report path is gitignored — untrack .karajan/steward from .gitignore so the state is shared");
   } catch { /* not ignored — good */ }
+}
 
+function printSweep({ flags, report, results, broken, logger }) {
   if (flags.json) {
     process.stdout.write(`${JSON.stringify(report)}\n`);
-  } else {
-    for (const r of results) logger.info?.(`${mark[r.verdict]} ${r.id}: ${r.verdict}${r.verdict === VERDICTS.OK ? "" : ` — ${r.remedy || r.evidence}`}`);
-    logger.info?.(broken.length ? `steward: ${broken.length} invariant(s) BROKEN — the report names them (.karajan/steward/report.md)` : "steward: nothing broken — the full state is in .karajan/steward/report.md");
+    return;
   }
-  process.exitCode = broken.length ? 1 : 0;
-  return broken.length ? 1 : 0;
+  for (const r of results) {
+    const why = r.verdict === VERDICTS.OK ? "" : ` — ${r.remedy || r.evidence}`;
+    logger.info?.(`${MARK[r.verdict]} ${r.id}: ${r.verdict}${why}`);
+  }
+  logger.info?.(broken.length ? `steward: ${broken.length} invariant(s) BROKEN — the report names them (.karajan/steward/report.md)` : "steward: nothing broken — the full state is in .karajan/steward/report.md");
 }
 
 /**

package/src/commands/tournament.js

@@ -20,47 +20,53 @@ function tournamentDirFor(config, rawId) {
   return path.join(config?.projectDir || process.cwd(), ".kj", "tournaments", id);
 }
 
+// TOR-C: `--judge <id>` ranks the finalists.
+async function judgeAction({ config, logger, flags, judgeTournamentFn }) {
+  const judgement = await judgeTournamentFn({ tournamentDir: tournamentDirFor(config, flags.judge), config, logger });
+  if (flags.json) logger?.info?.(JSON.stringify(judgement));
+  else logger?.info?.(`  siguiente: kj tournament --crown ${flags.judge}${judgement.escalated ? " (ganador vía solomon)" : ""}`);
+  return judgement;
+}
+
+// TOR-C: `--crown <id>` commits the winner through the real gate in its lane.
+async function crownAction({ config, logger, flags, crownWinnerFn }) {
+  const crown = await crownWinnerFn({
+    tournamentDir: tournamentDirFor(config, flags.crown), config, logger, cardRef: flags.card || null,
+  });
+  if (flags.json) logger?.info?.(JSON.stringify(crown));
+  return crown;
+}
+
+function scoreboardRow(r) {
+  if (!r.finalist) return `  ${r.coder.padEnd(10)} eliminado (${r.eliminated_by})`;
+  const mut = typeof r.mutation?.score === "number" ? `${r.mutation.score}%` : "n/a";
+  return `  ${r.coder.padEnd(10)} FINALISTA  loc:${String(r.loc.net).padStart(5)}  tests:${r.loc.testsTouched}  mutation:${mut}`;
+}
+
+// TOR-B: `--score <id>` scores an EXISTING tournament from its artifacts.
+async function scoreAction({ config, logger, flags, scoreTournamentFn }) {
+  const board = await scoreTournamentFn({ tournamentDir: tournamentDirFor(config, flags.score) });
+  if (flags.json) logger?.info?.(JSON.stringify(board));
+  else printScoreboard(board, logger);
+  return board;
+}
+
+function printScoreboard(board, logger) {
+  logger?.info?.(`scoreboard ${board.id} — regla: ${board.rule}`);
+  for (const r of board.rows) logger?.info?.(scoreboardRow(r));
+  logger?.info?.(`  ranking: ${board.ranking.join(" > ") || "(sin finalistas)"}`);
+}
+
+// The first of --judge, --crown, --score that is set wins, in that order.
+const ID_ACTIONS = [["judge", judgeAction], ["crown", crownAction], ["score", scoreAction]];
+
 export async function tournamentCommand({
   task, config, logger = console, flags = {},
   runTournamentFn = runTournament, scoreTournamentFn = scoreTournament,
   judgeTournamentFn = judgeTournament, crownWinnerFn = crownWinner,
 }) {
-  // TOR-C: `--judge <id>` ranks the finalists; `--crown <id>` commits the
-  // winner through the real gate in its lane.
-  if (flags.judge) {
-    const judgement = await judgeTournamentFn({ tournamentDir: tournamentDirFor(config, flags.judge), config, logger });
-    if (flags.json) logger?.info?.(JSON.stringify(judgement));
-    else logger?.info?.(`  siguiente: kj tournament --crown ${flags.judge}${judgement.escalated ? " (ganador vía solomon)" : ""}`);
-    return judgement;
-  }
-  if (flags.crown) {
-    const crown = await crownWinnerFn({
-      tournamentDir: tournamentDirFor(config, flags.crown), config, logger, cardRef: flags.card || null,
-    });
-    if (flags.json) logger?.info?.(JSON.stringify(crown));
-    return crown;
-  }
-
-  // TOR-B: `--score <id>` scores an EXISTING tournament from its artifacts.
-  if (flags.score) {
-    const tournamentDir = tournamentDirFor(config, flags.score);
-    const board = await scoreTournamentFn({ tournamentDir });
-    if (flags.json) {
-      logger?.info?.(JSON.stringify(board));
-      return board;
-    }
-    logger?.info?.(`scoreboard ${board.id} — regla: ${board.rule}`);
-    for (const r of board.rows) {
-      if (!r.finalist) {
-        logger?.info?.(`  ${r.coder.padEnd(10)} eliminado (${r.eliminated_by})`);
-        continue;
-      }
-      const mut = typeof r.mutation?.score === "number" ? `${r.mutation.score}%` : "n/a";
-      logger?.info?.(`  ${r.coder.padEnd(10)} FINALISTA  loc:${String(r.loc.net).padStart(5)}  tests:${r.loc.testsTouched}  mutation:${mut}`);
-    }
-    logger?.info?.(`  ranking: ${board.ranking.join(" > ") || "(sin finalistas)"}`);
-    return board;
-  }
+  const idAction = ID_ACTIONS.find(([flag]) => flags[flag]);
+  if (idAction) return idAction[1]({ config, logger, flags, scoreTournamentFn, judgeTournamentFn, crownWinnerFn });
 
   if (!task || !String(task).trim()) {
     throw new Error("tournament: falta la tarea — kj tournament \"<tarea>\" --coders claude,codex");
@@ -74,12 +80,15 @@ export async function tournamentCommand({
   }
 
   const res = await runTournamentFn({ task, coders, config, logger });
+  printRunSummary(res, logger);
+  return res;
+}
 
+function printRunSummary(res, logger) {
   const completed = res.lanes.filter((l) => l.status === "completed");
   const green = completed.filter((l) => l.suite?.ok);
   logger?.info?.("");
   logger?.info?.(`torneo ${res.id}: ${completed.length}/${res.lanes.length} carriles completados, ${green.length} con suite verde`);
   logger?.info?.(`  evidencia: ${res.dir}`);
   logger?.info?.("  siguiente: el scoreboard determinista (TOR-B) puntuará los carriles; de momento compara los diff.patch a mano.");
-  return res;
 }

package/src/commands/worktree.js

@@ -3,7 +3,8 @@
  * host agent. Field case: the playbook said "one worktree per task" and an
  * agent NARRATED the isolation while editing the project root. Ordering a
  * command beats ordering a practice: start = worktree + feat/ branch +
- * dependency bootstrap + the exact cd printed; done = remove after merge.
+ * dependency bootstrap + the exact cd printed; done = remove after merge
+ * and delete the branch once it is merged into origin/<base>.
  * Same lane dir (.kj/worktrees) and bootstrap the headless pipeline uses.
  */
 import fs from "node:fs";
@@ -11,8 +12,37 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { bootstrapWorktree } from "../hu/worktree-bootstrap.js";
-import { classifyLanes, liveProcesses, looseLaneBranches, resolveBase } from "../hu/lane-prune.js";
+import { laneWork, setupLane } from "../hu/lane-setup.js";
+import { classifyLanes, commitsNotIn, liveProcesses, looseLaneBranches, resolveBase, stopLaneIndexers } from "../hu/lane-prune.js";
+import { stopBootstrap } from "../rag/bootstrap-index.js";
 import { recordGateDecision } from "../policy/decisions.js";
+import { mainCheckout } from "../utils/main-checkout.js";
+import { cardsOfLane, parseLanes, prsByBranch } from "../hu/lanes.js";
+import { listPlans, loadPlan } from "../plan/plan-store.js";
+
+// The pid itself, not the marker's expiry: an indexer past MAX_RUN_MS still runs. EPERM is a process too.
+const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (err) { return err.code === "EPERM"; } };
+
+const REF_SEPARATOR =" · "; // external_ref joins a tracker card and an issue (src/commands/hu.js)
+
+// KJC-TSK-1316: ONE gh call for every lane, open and merged PRs alike.
+const listPrs = async (cwd) => JSON.parse((await execFileAsync("gh", ["pr", "list", "--state", "all", "--limit", "200", "--json", "number,url,state,headRefName"], { cwd })).stdout);
+
+/** Each branch's PR; when gh fails the lanes go without PRs, and kj says so. */
+async function lanePrs(list, cwd) {
+  try {
+    return prsByBranch(await list(cwd));
+  } catch (err) {
+    console.warn(`! kj worktree list: cannot read the PRs (${String(err.stderr || err.message).trim().split("\n")[0]}); lanes listed without them`);
+    return new Map();
+  }
+}
+
+/** Every HU of the project's plans with its references, as `{id, refs}`. */
+async function planCards(projectDir) {
+  const plans = await Promise.all((await listPlans(projectDir)).map((m) => loadPlan(projectDir, m.planId)));
+  return plans.flatMap((p) => (p?.hus ?? []).map((h) => ({ id: h.id, refs: String(h.external_ref ?? "").split(REF_SEPARATOR).filter(Boolean) })));
+}
 
 const execFileAsync = promisify(execFile);
 const WORKTREE_DIR = ".kj/worktrees"; // shared with the headless lanes
@@ -22,7 +52,10 @@ const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 export async function worktreeCommand({ config = null, action, args = [], flags = {}, deps = {} }) {
   const projectDir = config?.projectDir || process.cwd();
   const git = (gitArgs, cwd = projectDir) => execFileAsync("git", gitArgs, { cwd });
-  const lanePath = (slug) => path.join(projectDir, WORKTREE_DIR, slug);
+  // #2566: lanes hang from the main checkout, never from the lane the command runs in.
+  const lanesDir = path.join(mainCheckout(projectDir), WORKTREE_DIR);
+  const lanePath = (slug) => path.join(lanesDir, slug);
+  const baseName = config?.base_branch || "main";
 
   if (action === "start") {
     const slug = String(args[0] || "").trim();
@@ -34,28 +67,48 @@ export async function worktreeCommand({ config = null, action, args = [], flags
       throw new Error(`lane "${slug}" already exists — cd ${wtPath}, or finish it with: kj worktree done ${slug}`);
     }
     const branch = `feat/${slug}`;
+    // HU-2761: a lane is cut from origin/<base>, never from the HEAD the command runs in (#2566).
+    const from = await resolveBase({ git, base: baseName });
+    try { await git(["rev-parse", "--verify", "--quiet", `${from}^{commit}`]); } catch {
+      throw new Error(`base "${baseName}" not found — set base_branch in kj config`);
+    }
+    if (from === baseName) {
+      console.warn(`! no origin/${baseName} ref — lane starts from local ${baseName}, which may lag (git fetch origin ${baseName} to refresh)`);
+    }
+    const leftover = await git(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]).then(() => true, () => false);
+    if (leftover) {
+      throw new Error(`branch ${branch} already exists (kept by an unmerged done?) — delete it with git branch -D ${branch} or pick another slug`);
+    }
     // KJC-TSK-1093: --no-track, so no upstream lands in .git/config (read-only in the host sandbox).
-    await git(["worktree", "add", "--no-track", "-b", branch, wtPath]);
+    await git(["worktree", "add", "--no-track", "-b", branch, wtPath, from]);
     const boot = await bootstrapWorktree({ worktreePath: wtPath, setupCommand: config?.session?.worktree_setup || null });
-    console.log(`✓ lane ready: ${branch}`);
+    // KJC-TSK-1371 (#2852): identity and Sentinel in the lane; a failure names the step and the way out.
+    const retire = `kj worktree done ${slug} --force`;
+    const setup = await (deps.setupLane ?? setupLane)({ mainDir: mainCheckout(projectDir), lanePath: wtPath }).catch((err) => {
+      throw new Error(`${err.message} — the lane is half set; retire it with: ${retire}`, { cause: err });
+    });
+    const { stdout: touched } = await git(["status", "--porcelain", "--untracked-files=no"], wtPath);
+    if (touched.trim()) throw new Error(`lane setup changed tracked files (${touched.trim().split("\n").join(", ")}) — retire it with: ${retire}`);
+    console.log(`✓ lane ready: ${branch} (from ${from})`);
     console.log(`  cd ${wtPath}`);
     console.log("  The gates travel with the repo — kj review --staged works there. When merged: kj worktree done " + slug);
-    return { path: wtPath, branch, bootstrap: boot };
+    return { path: wtPath, branch, from, bootstrap: boot, setup };
   }
 
   if (action === "list") {
-    const laneRoot = path.join(projectDir, WORKTREE_DIR) + path.sep;
     const { stdout } = await git(["worktree", "list", "--porcelain"]);
-    const rows = [];
-    let current = null;
-    for (const line of stdout.split("\n")) {
-      if (line.startsWith("worktree ")) current = { path: line.slice(9).trim() };
-      else if (line.startsWith("branch ") && current) {
-        current.branch = line.slice(7).trim().replace("refs/heads/", "");
-        if (current.path.startsWith(laneRoot)) {
-          rows.push({ slug: path.basename(current.path), branch: current.branch, path: current.path });
-        }
-      }
+    const rows = parseLanes(stdout, { root: lanesDir });
+    if (flags.json) {
+      // KJC-TSK-1313: what the HU Board paints on each card.
+      const base = await resolveBase({ git, base: baseName });
+      const cards = await planCards(projectDir);
+      const prs = flags.prs ? await lanePrs(deps.listPrs ?? listPrs, projectDir) : null;
+      const out = await Promise.all(rows.map(async (r) => ({
+        ...r, ahead: await commitsNotIn({ git, base, ref: r.branch }).catch(() => null), cards: cardsOfLane(r, cards),
+        ...(prs && { pr: prs.get(r.branch) ?? null }),
+      })));
+      console.log(JSON.stringify(out));
+      return out;
     }
     if (rows.length === 0) console.log("no lanes — create one with: kj worktree start <slug>");
     for (const r of rows) console.log(`${r.slug.padEnd(24)} ${r.branch.padEnd(30)} ${r.path}`);
@@ -66,19 +119,46 @@ export async function worktreeCommand({ config = null, action, args = [], flags
     const slug = String(args[0] || "").trim();
     const wtPath = lanePath(slug);
     if (!fs.existsSync(wtPath)) throw new Error(`lane "${slug}" not found — see kj worktree list`);
-    const { stdout: dirty } = await git(["status", "--porcelain"], wtPath);
-    if (dirty.trim() && !flags.force) {
+    // KJC-TSK-1371: the identity and Sentinel files lane setup wrote are not the lane's work.
+    const { stdout: status } = await git(["status", "--porcelain", "--untracked-files=all"], wtPath);
+    const dirty = laneWork(status, wtPath).join("\n");
+    if (dirty && !flags.force) {
       throw new Error(`lane "${slug}" has uncommitted changes — commit them (through the gate) or discard with --force`);
     }
-    await git(["worktree", "remove", ...(flags.force ? ["--force"] : []), wtPath]);
-    console.log(`✓ lane "${slug}" removed — its branch survives; delete it after merge if you want`);
-    return { removed: true, slug };
+    // HU-3114: the lane's background indexer must not outlive it (any age); a failure never blocks the removal.
+    const stopIndexer = deps.stopBootstrap ?? stopBootstrap;
+    const indexerStopped = await stopIndexer(wtPath, { force: true }).catch((err) => {
+      console.warn(`warning: could not stop the background indexer of "${slug}": ${err.message}`);
+      return null;
+    });
+    // The lane's real branch (headless kj-hu-* lanes share the folder); detached HEAD → null.
+    // symbolic-ref -q exits 1 on a detached HEAD; any other failure is a real error.
+    const branch = await git(["symbolic-ref", "--short", "-q", "HEAD"], wtPath).then((r) => r.stdout.trim() || null, (err) => {
+      if (err.code === 1) return null;
+      throw err;
+    });
+    const base = await resolveBase({ git, base: baseName });
+    // A missing base must not block removing a clean lane: the branch is kept, with its remedy.
+    const ahead = branch ? await commitsNotIn({ git, base, ref: branch }).catch(() => null) : 0;
+    // Only setup files left (checked above): git still calls them untracked, so the remove is forced.
+    await git(["worktree", "remove", ...(flags.force || status.trim() ? ["--force"] : []), wtPath]);
+    // -D after our own check: -d measures against HEAD/upstream, not origin/<base>. Never the base itself.
+    const branchDeleted = Boolean(branch) && branch !== baseName && (ahead === 0 || Boolean(flags.force));
+    if (branchDeleted) await git(["branch", "-D", branch]);
+    const note = !branch ? "detached HEAD, no branch"
+      : branchDeleted ? (ahead === 0 ? `branch ${branch} deleted (merged into ${base})` : `branch ${branch} deleted with --force (${ahead ?? "unknown"} commit(s) not in ${base} were discarded)`)
+        : ahead === null ? `branch ${branch} kept: base "${base}" not found, cannot tell if it is merged (git branch -D ${branch} to delete it)`
+          : `branch ${branch} kept: ${ahead} commit(s) not in ${base} (squash-merged or not fetched? git fetch, then git branch -D ${branch})`;
+    console.log(`✓ lane "${slug}" removed; ${note}`);
+    return { removed: true, slug, branch, branchDeleted, merged: branch ? ahead === 0 : null, indexerStopped };
   }
 
   if (action === "prune") {
     const { processes = liveProcesses() } = deps;
-    const base = await resolveBase({ git, base: config?.base_branch || "main" });
-    const lanes = await classifyLanes({ git, laneRoot: path.join(projectDir, WORKTREE_DIR), base, processes, now: deps.now });
+    const base = await resolveBase({ git, base: baseName });
+    const lanes = await classifyLanes({ git, laneRoot: lanesDir, base, processes, now: deps.now });
+    // HU-3092: a removable lane's own background indexer is stopped first (never in a dry run); one that survives keeps the lane.
+    if (!flags.dryRun) await stopLaneIndexers(lanes, { stop: deps.stopIndexer ?? ((l) => stopBootstrap(l.path, { force: true })), stillRunning: deps.indexerRunning ?? ((l) => pidAlive(l.indexer.pid)) });
     const abandoned = lanes.filter((l) => l.reasons.length === 0);
     const kept = lanes.filter((l) => l.reasons.length > 0);
     for (const l of kept) console.log(`kept    ${l.slug.padEnd(24)} ${l.reasons.join("; ")}`);
@@ -87,7 +167,7 @@ export async function worktreeCommand({ config = null, action, args = [], flags
     const { empty: branches, withWork } = await looseLaneBranches({ git, base });
     for (const b of withWork) console.log(`kept    branch ${b.branch.padEnd(17)} ${b.reason}`);
     if (flags.dryRun) {
-      for (const l of abandoned) console.log(`would retire ${l.slug} (${l.branch ?? "detached"})`);
+      for (const l of abandoned) console.log(`would retire ${l.slug} (${l.branch ?? "detached"})${l.indexer ? ` (stopping its background index, pid ${l.indexer.pid})` : ""}`);
       for (const b of branches) console.log(`would delete branch ${b}`);
       return { wouldRemove: abandoned, kept, wouldRemoveBranches: branches, branchesKept: withWork };
     }
@@ -96,7 +176,8 @@ export async function worktreeCommand({ config = null, action, args = [], flags
       console.log(`✓ deleted branch ${b}`);
     }
     for (const l of abandoned) {
-      await git(["worktree", "remove", l.path]);
+      // Judged abandoned above: what is left are setup or regenerable files, which git would refuse.
+      await git(["worktree", "remove", "--force", l.path]);
       if (l.branch) await git(["branch", "-D", l.branch]);
       console.log(`✓ retired ${l.slug} (${l.branch ?? "detached"})`);
     }

package/src/config/defaults.js

@@ -28,6 +28,7 @@ const DEFAULTS = {
     discover: { provider: null, model: null },
     architect: { provider: null, model: null },
     hu_reviewer: { provider: null, model: null },
+    translator: { provider: null, model: null },
     start: { provider: null, model: "haiku" }
   },
   pipeline: {