/** * `kj worktree start|list|done` (KJC-TSK-0679) — isolated lanes for the * 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 * and delete the branch once it is merged into origin/. * Same lane dir (.kj/worktrees) and bootstrap the headless pipeline uses. */ import fs from "node:fs"; import path from "node:path"; import { execFile } from "node:child_process"; import { promisify } from "node:util"; import { LANE_BASE_FILE, baseBranchFrom } from "../config/base-branch.js"; import { bootstrapWorktree } from "../hu/worktree-bootstrap.js"; import { laneWork, setupLane } from "../hu/lane-setup.js"; import { classifyLanes, commitsNotIn, liveProcesses, looseLaneBranches, mergedBranches, resolveBase, stopLaneIndexers } from "../hu/lane-prune.js"; import { archiveKjState } from "../hu/lane-kj-state.js"; import { pruneLaneRecord } from "../harden/sentinel-lane-state.js"; import { clearLaneNote, noteLine, writeLaneNote } from "../hu/lane-note.js"; import { stopBootstrap } from "../rag/bootstrap-index.js"; import { catchUpLine } from "../rag/lane-catchup.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 MERGED_BATCH = 200; // KJC-TSK-1480: branches per git branch -D, well under any argv limit export 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 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 }); // #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 = baseBranchFrom({ config, projectDir }); if (action === "start") { const slug = String(args[0] || "").trim(); if (!SLUG_RE.test(slug)) { throw new Error("invalid slug — use letters, digits, dots, dashes (no slashes): kj worktree start "); } const wtPath = lanePath(slug); if (fs.existsSync(wtPath)) { throw new Error(`lane "${slug}" already exists — cd ${wtPath}, or finish it with: kj worktree done ${slug}`); } const branch = `feat/${slug}`; // HU-4424: --base names the branch this lane is cut from and keeps as its base. const base = flags.base ? String(flags.base).trim() : baseName; // HU-2761: a lane is cut from origin/, never from the HEAD the command runs in (#2566). const from = await resolveBase({ git, base }); try { await git(["rev-parse", "--verify", "--quiet", `${from}^{commit}`]); } catch { throw new Error(flags.base ? `base "${base}" not found: no origin/${base} nor local ${base} (git fetch origin ${base}, or check the name)` : `base "${base}" not found — set base_branch in kj config`); } if (from === base) { console.warn(`! no origin/${base} ref — lane starts from local ${base}, which may lag (git fetch origin ${base} 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, from]); if (flags.base) { // HU-4424: in the lane's own git dir: per lane, never tracked, no write to .git/config. const { stdout: laneGitDir } = await git(["rev-parse", "--path-format=absolute", "--git-dir"], wtPath); fs.writeFileSync(path.join(laneGitDir.trim(), LANE_BASE_FILE), `${base}\n`); } clearLaneNote(mainCheckout(projectDir), slug); // KJC-TSK-1541: never the note of an older lane of that slug const boot = await bootstrapWorktree({ worktreePath: wtPath, setupCommand: config?.session?.worktree_setup || null }); // 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}`); const { seed } = boot; console.log(await catchUpLine({ laneDir: wtPath, seed, git, start: deps.startDeltaIndex })); 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, from, bootstrap: boot, setup }; } // KJC-TSK-1541 (issue 3853): what a lane waits for, as kj stage shows it. if (action === "note") { const out = writeLaneNote({ mainDir: mainCheckout(projectDir), slug: String(args[0] ?? "").trim(), text: args.slice(1).join(" ") }); console.log(noteLine(out)); return out; } if (action === "list") { const { stdout } = await git(["worktree", "list", "--porcelain"]); 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 "); for (const r of rows) console.log(`${r.slug.padEnd(24)} ${r.branch.padEnd(30)} ${r.path}`); return rows; } if (action === "done") { 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`); // 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`); } // 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; archiveKjState(wtPath, path.join(mainCheckout(projectDir), ".karajan", "retired-lanes", slug)); // KJC-TSK-1477 const laneTops = [...new Set([wtPath, fs.realpathSync(wtPath)])]; // HU-4003: before the lane is gone // 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]); clearLaneNote(mainCheckout(projectDir), slug); pruneLaneRecord(mainCheckout(projectDir), laneTops); // HU-4003: a removed lane holds nothing pending // -D after our own check: -d measures against HEAD/upstream, not origin/. 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: 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("; ")}`); if (lanes.length === 0) console.log("no kj lanes"); // KJC-TSK-1037: loose kj-hu-* branches of old runs, measured against the same base. const { empty: branches, withWork } = await looseLaneBranches({ git, base }); for (const b of withWork) console.log(`kept branch ${b.branch.padEnd(17)} ${b.reason}`); // KJC-TSK-1480: any other local branch already whole in the base, out of every worktree. const merged = (await mergedBranches({ git, base, baseName })).filter((b) => !branches.includes(b)); if (flags.dryRun) { 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}`); if (merged.length > 0) console.log(`would delete ${merged.length} local branch(es) already in ${base}`); return { wouldRemove: abandoned, kept, wouldRemoveBranches: branches, branchesKept: withWork, wouldRemoveMerged: merged }; } for (const b of branches) { await git(["branch", "-D", b]); console.log(`✓ deleted branch ${b}`); } for (let i = 0; i < merged.length; i += MERGED_BATCH) await git(["branch", "-D", ...merged.slice(i, i + MERGED_BATCH)]); if (merged.length > 0) console.log(`✓ deleted ${merged.length} local branch(es) already in ${base}`); for (const l of abandoned) { // KJC-TSK-1477: the governance record outlives the lane, archived in the main checkout. archiveKjState(l.path, path.join(mainCheckout(projectDir), ".karajan", "retired-lanes", l.slug)); // Judged abandoned above: what is left are setup, kj state or regenerable files, which git would refuse. await git(["worktree", "remove", "--force", l.path]); clearLaneNote(mainCheckout(projectDir), l.slug); if (l.branch) await git(["branch", "-D", l.branch]); console.log(`✓ retired ${l.slug} (${l.branch ?? "detached"})`); } if (abandoned.length > 0 || branches.length > 0 || merged.length > 0) { recordGateDecision(projectDir, { decision: "allow", chokepoint: "tool", kind: "worktree-prune", lanes: abandoned.map((l) => l.slug), branches: [...branches, ...merged] }); } return { removed: abandoned, kept, branchesRemoved: branches, branchesKept: withWork, mergedBranchesRemoved: merged }; } throw new Error(`unknown action "${action}" — use: start | list | done | prune`); }