@rungs/cli 0.2.0 → 0.3.1

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { fileURLToPath as fileURLToPath3 } from "node:url";
-import { dirname as dirname8, join as join13, resolve as resolve4 } from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
+import { dirname as dirname9, join as join14, resolve as resolve5 } from "node:path";
 
 // src/manifest.ts
 import { readdirSync as readdirSync2, readFileSync, statSync as statSync2 } from "node:fs";
@@ -850,14 +850,15 @@ function writeReport(repoRoot, entries, harnesses, stamp) {
 
 // src/check.ts
 import { appendFileSync, existsSync as existsSync7, readFileSync as readFileSync8 } from "node:fs";
-import { execSync as execSync3 } from "node:child_process";
+import { execSync } from "node:child_process";
 import { dirname as dirname5, join as join10 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { parse as parse2 } from "smol-toml";
 
 // src/engines.ts
 import { existsSync as existsSync6, readFileSync as readFileSync7 } from "node:fs";
 import { join as join9, dirname as dirname4, resolve as resolve2 } from "node:path";
+import { fileURLToPath } from "node:url";
 import { parse as parseToml } from "smol-toml";
 
 // src/selftest.ts
@@ -880,6 +881,11 @@ function build(root, table, fx, input) {
   if (typeof input === "string") return [write(targetPath(table), `${input}
 `)];
   if (!fx || typeof fx !== "object") return null;
+  if (fx.packages && typeof fx.packages === "object") {
+    return Object.entries(fx.packages).map(
+      ([rel, version]) => write(rel, JSON.stringify({ name: rel.replace(/\W/g, "-"), version }))
+    );
+  }
   if (Array.isArray(fx.fragments) && typeof fx.version === "string") {
     const dir = fx.dir ?? "changelog.d";
     const written = fx.fragments.map((n) => write(`${dir}/${n}`, `# ${n}
@@ -929,7 +935,8 @@ var CONTEXT_FREE = /* @__PURE__ */ new Set([
   "file-budget",
   "register-schema",
   "file-population",
-  "changelog-freshness"
+  "changelog-freshness",
+  "computed-claim"
 ]);
 function deparam(spec, dir) {
   const walk3 = (v) => typeof v === "string" ? v.replace(/\{\{[^}]+\}\}/g, dir) : Array.isArray(v) ? v.map(walk3) : v && typeof v === "object" ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk3(x)])) : v;
@@ -952,6 +959,10 @@ function runSelfTests(gateId, engine, table, blocks) {
       const files = build(root, table, b.fixture, b.input);
       let spec = b.fixture?.opted_in ? Array.isArray(table) ? table.map((s) => ({ ...s, extensions_opted_in: b.fixture.opted_in })) : { ...table, extensions_opted_in: b.fixture.opted_in } : table;
       if (Array.isArray(b.fixture?.fragments)) spec = deparam(spec, b.fixture.dir ?? "changelog.d");
+      if (Array.isArray(b.fixture?.exclude)) {
+        const ex = b.fixture.exclude;
+        spec = Array.isArray(spec) ? spec.map((s) => ({ ...s, exclude: ex })) : { ...spec, exclude: ex };
+      }
       if (!files) {
         out.push({ gate: gateId, expect, outcome: "unrun", detail: `no builder for fixture ${JSON.stringify(b.fixture).slice(0, 60)}` });
         continue;
@@ -976,7 +987,7 @@ function runSelfTests(gateId, engine, table, blocks) {
 
 // src/engines2.ts
 import { readFileSync as readFileSync5 } from "node:fs";
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { join as join7 } from "node:path";
 var read = (root, rel) => {
   try {
@@ -1227,12 +1238,13 @@ var crossReference = (t, root, files) => {
   }
   return { findings, examined: skills.length };
 };
+var gitArgs = (root, args2) => execFileSync("git", args2, { cwd: root, stdio: "pipe" }).toString().trim();
 function landedWork(root, branch, base) {
-  const git = (cmd2) => execSync(`git ${cmd2}`, { cwd: root, stdio: "pipe" }).toString().trim();
+  const git2 = (...args2) => gitArgs(root, args2);
   try {
-    const tip = git(`rev-parse ${branch}`);
-    if (tip === git(`rev-parse ${base}`)) return false;
-    return git(`log ${base} --merges --format=%P`).split("\n").some((line) => line.trim().split(/\s+/).slice(1).includes(tip));
+    const tip = git2("rev-parse", branch);
+    if (tip === git2("rev-parse", base)) return false;
+    return git2("log", base, "--merges", "--format=%P").split("\n").some((line) => line.trim().split(/\s+/).slice(1).includes(tip));
   } catch {
     return true;
   }
@@ -1242,10 +1254,7 @@ var gitStatusReconcile = (t, root, files) => {
   let merged;
   try {
     merged = new Set(
-      execSync(`git branch --merged ${t.integration_branch ?? "main"} --format=%(refname:short)`, {
-        cwd: root,
-        stdio: "pipe"
-      }).toString().split("\n").map((s) => s.trim()).filter(Boolean)
+      gitArgs(root, ["branch", "--merged", t.integration_branch ?? "main", "--format=%(refname:short)"]).split("\n").map((s) => s.trim()).filter(Boolean)
     );
   } catch {
     return { findings: [{ message: "cannot read git branches; status not reconciled" }], examined: 0 };
@@ -1270,8 +1279,10 @@ var computedClaim = (t, root, files) => {
   let examined = 0;
   for (const spec of specs) {
     const values = /* @__PURE__ */ new Map();
+    const excluded = (rel) => (spec.exclude ?? []).some((p) => matchAny([rel], p).length > 0);
     for (const src of spec.sources ?? []) {
       for (const rel of matchAny(files, src.file)) {
+        if (excluded(rel)) continue;
         const text = read(root, rel);
         let v;
         if (src.path && rel.endsWith(".json")) {
@@ -1290,8 +1301,9 @@ var computedClaim = (t, root, files) => {
     }
     const distinct = new Set(values.values());
     if (spec.rule === "all-agree" && distinct.size > 1) {
+      const where = [...values.entries()].map(([rel, v]) => `${rel}=${v}`).join(", ");
       findings.push({
-        message: `${spec.id} disagrees across ${values.size} locations: ${[...distinct].join(", ")} \u2014 run \`${spec.autofix}\``
+        message: `${spec.id} disagrees across ${values.size} locations: ${where}` + (spec.autofix ? ` \u2014 run \`${spec.autofix}\`` : "") + (spec.exclude?.length ? "" : ". If one of these is versioned independently, list it in `exclude`.")
       });
     }
   }
@@ -1300,7 +1312,7 @@ var computedClaim = (t, root, files) => {
 
 // src/engines3.ts
 import { readFileSync as readFileSync6 } from "node:fs";
-import { execSync as execSync2 } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 import { join as join8 } from "node:path";
 var read2 = (root, rel) => {
   try {
@@ -1434,7 +1446,7 @@ var rulePropagation = (t, root, files) => {
 var gitState = (t, root) => {
   let out;
   try {
-    out = execSync2("git worktree list --porcelain", { cwd: root, stdio: "pipe" }).toString();
+    out = execFileSync2("git", ["worktree", "list", "--porcelain"], { cwd: root, stdio: "pipe" }).toString();
   } catch {
     return { findings: [{ message: "cannot read git worktrees; checkout state unknown" }], examined: 0 };
   }
@@ -1459,7 +1471,7 @@ var mergeDriverCheck = (t, root) => {
   for (const driver of required) {
     let configured = "";
     try {
-      configured = execSync2(`git config --get merge.${driver}.driver`, { cwd: root, stdio: "pipe" }).toString().trim();
+      configured = execFileSync2("git", ["config", "--get", `merge.${driver}.driver`], { cwd: root, stdio: "pipe" }).toString().trim();
     } catch {
     }
     if (!configured) {
@@ -1511,6 +1523,7 @@ var boardReconcile = (t, root, _files) => {
 };
 
 // src/engines.ts
+var CLI_MODULES = join9(dirname4(fileURLToPath(import.meta.url)), "..", "modules");
 var read3 = (root, rel) => {
   try {
     return readFileSync7(join9(root, rel), "utf8");
@@ -1712,7 +1725,7 @@ var gateMeta = (_t, root) => {
     const table = entry.match(/^table\s*=\s*"(.+)"/m)?.[1];
     if (!id || kind !== "declared" || !table) continue;
     examined++;
-    const tablePath = join9(dirname4(new URL(import.meta.url).pathname.slice(1)), "..", "modules", dirname4(table), "gates", table.split("/").pop());
+    const tablePath = join9(CLI_MODULES, dirname4(table), "gates", table.split("/").pop());
     const src = existsSync6(tablePath) ? readFileSync7(tablePath, "utf8") : "";
     const forGate = [...src.matchAll(/\[\[self_test\]\][\s\S]*?(?=\n\[\[|\n\[|$)/g)].map((m) => m[0]).filter((b) => b.includes(`gate   = "${id}"`) || b.includes(`gate    = "${id}"`) || b.includes(`gate = "${id}"`));
     for (const direction of ["pass", "fail"]) {
@@ -1738,7 +1751,7 @@ function optedInExtensions(rel, spec) {
   const name = rel.split("/").slice(-2)[0];
   if (!name) return /* @__PURE__ */ new Set();
   try {
-    const mods = loadAllModules(join9(dirname4(new URL(import.meta.url).pathname.slice(1)), "..", "modules"));
+    const mods = loadAllModules(CLI_MODULES);
     const owner = mods.find((m) => m.skills?.[name]?.extensions);
     return new Set(Object.keys(owner?.skills?.[name]?.extensions ?? {}));
   } catch {
@@ -1749,7 +1762,7 @@ var escapeRe3 = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 function parseTable(path, module) {
   if (!existsSync6(path)) return null;
   try {
-    const mods = loadAllModules(join9(dirname4(new URL(import.meta.url).pathname.slice(1)), "..", "modules"));
+    const mods = loadAllModules(CLI_MODULES);
     const params = resolveParams(mods, {}, ".");
     return parseToml(substitute(readFileSync7(path, "utf8"), module, params));
   } catch {
@@ -1802,7 +1815,7 @@ function isImplemented(engine) {
 }
 
 // src/check.ts
-var MODULES = join10(dirname5(fileURLToPath(import.meta.url)), "..", "modules");
+var MODULES = join10(dirname5(fileURLToPath2(import.meta.url)), "..", "modules");
 function loadRegistry(repoRoot) {
   const path = join10(repoRoot, ".ai", "gates.toml");
   if (!existsSync7(path)) return { runner: {}, gates: [] };
@@ -1825,7 +1838,7 @@ var UnknownTierError = class extends Error {
     this.declared = declared;
   }
 };
-function runGates(repoRoot, tier, now = () => Date.now()) {
+function runGates(repoRoot, tier, now = () => Date.now(), only) {
   const { runner, gates } = loadRegistry(repoRoot);
   const runnerTiers = Array.isArray(runner?.tiers) ? runner.tiers : [];
   if (tier && runnerTiers.length && !runnerTiers.includes(tier)) {
@@ -1835,6 +1848,7 @@ function runGates(repoRoot, tier, now = () => Date.now()) {
   const runs = [];
   for (const g of gates) {
     if (g.trigger) continue;
+    if (only && !only.has(g.id)) continue;
     if (tier && !tierSelects(runnerTiers, tier, g.tier)) continue;
     const started = now();
     let status = "pass";
@@ -1842,7 +1856,7 @@ function runGates(repoRoot, tier, now = () => Date.now()) {
     let examined = 0;
     if (g.kind === "command" && g.command) {
       try {
-        execSync3(g.command, { cwd: repoRoot, stdio: "pipe" });
+        execSync(g.command, { cwd: repoRoot, stdio: "pipe" });
       } catch (e) {
         status = "fail";
         findings = [{ message: String(e.stderr ?? e.stdout ?? e.message).trim().split("\n").slice(-3).join(" ") }];
@@ -1964,10 +1978,10 @@ function ledgerQuestions(repoRoot, gates) {
 // src/lifecycle.ts
 import { copyFileSync, existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "node:fs";
 import { dirname as dirname6, join as join11 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { execSync as execSync4 } from "node:child_process";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { execFileSync as execFileSync3 } from "node:child_process";
 import { parse as parse3 } from "smol-toml";
-var SRC = dirname6(fileURLToPath2(import.meta.url));
+var SRC = dirname6(fileURLToPath3(import.meta.url));
 var PROFILES = {
   minimal: ["instructions"],
   tracked: ["instructions", "gates", "backlog", "findings", "adr", "session"],
@@ -2180,8 +2194,8 @@ function setupGit(repoRoot, dryRun = false) {
 ');process.exit(1)"` : "git merge-file -L ours -L base -L theirs %A %O %B";
     if (!dryRun) {
       try {
-        execSync4(`git config merge.${d}.name "rungs ${d.replace("rungs-", "")} driver"`, { cwd: repoRoot, stdio: "pipe" });
-        execSync4(`git config merge.${d}.driver ${JSON.stringify(cmd2)}`, { cwd: repoRoot, stdio: "pipe" });
+        execFileSync3("git", ["config", `merge.${d}.name`, `rungs ${d.replace("rungs-", "")} driver`], { cwd: repoRoot, stdio: "pipe" });
+        execFileSync3("git", ["config", `merge.${d}.driver`, cmd2], { cwd: repoRoot, stdio: "pipe" });
       } catch {
         continue;
       }
@@ -2191,7 +2205,7 @@ function setupGit(repoRoot, dryRun = false) {
   let rerere = false;
   if (!dryRun) {
     try {
-      execSync4("git config rerere.enabled true", { cwd: repoRoot, stdio: "pipe" });
+      execFileSync3("git", ["config", "rerere.enabled", "true"], { cwd: repoRoot, stdio: "pipe" });
       rerere = true;
     } catch {
     }
@@ -2286,15 +2300,17 @@ function planArchive(repoRoot, backlogRoot = "docs/backlog") {
   const files = walk(repoRoot);
   const items = files.filter((f) => posix(f).startsWith(posix(relative2(repoRoot, itemsDir)) + "/") && f.endsWith(".md"));
   for (const rel of items) {
-    if (/README\.md$/i.test(rel) || /TEMPLATE\.md$/i.test(rel)) continue;
+    const base = posix(rel).split("/").pop();
+    if (/^(README|TEMPLATE)\.md$/i.test(base)) continue;
     const text = readFileSync10(join12(repoRoot, rel), "utf8");
     const status = field(text, "status");
     const id = field(text, "id");
     if (!FINISHED.has(status)) continue;
     if (field(text, "type") === "epic") {
       const children = (text.match(/^children:\s*\[(.*)\]/m)?.[1] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+      const archived = files.filter((f) => posix(f).startsWith(posix(relative2(repoRoot, archiveDir)) + "/") && f.endsWith(".md"));
       const unfinished = children.filter((c2) => {
-        const f = items.find((i) => i.includes(`${c2}-`));
+        const f = items.find((i) => i.includes(`${c2}-`)) ?? archived.find((i) => i.includes(`${c2}-`));
         return !f || !FINISHED.has(field(readFileSync10(join12(repoRoot, f), "utf8"), "status"));
       });
       if (unfinished.length) {
@@ -2362,10 +2378,268 @@ function applyArchive(repoRoot, plan) {
   }
 }
 
+// src/concurrency.ts
+import { existsSync as existsSync10, mkdtempSync as mkdtempSync2, readFileSync as readFileSync11, rmSync as rmSync2, writeFileSync as writeFileSync6, unlinkSync } from "node:fs";
+import { execFileSync as execFileSync4 } from "node:child_process";
+import { hostname } from "node:os";
+import { join as join13, resolve as resolve4, dirname as dirname8, basename as basename2 } from "node:path";
+import { tmpdir as tmpdir2 } from "node:os";
+function loopParams(root) {
+  const p = installedParams(root).concurrency ?? {};
+  const integration = String(p.integration_branch ?? "main");
+  const greenPrefix = String(p.green_prefix ?? "green/");
+  return {
+    integration,
+    // The green ref marks the last *verified* merge of the integration branch,
+    // so it is prefix + that branch — not prefix + whatever you are cutting.
+    greenRef: `${greenPrefix}${integration}`,
+    integPrefix: String(p.integ_prefix ?? "integ/")
+  };
+}
+function git(root, args2) {
+  return execFileSync4("git", args2, { cwd: root, stdio: "pipe", encoding: "utf8" }).trim();
+}
+function gitOk(root, args2) {
+  try {
+    git(root, args2);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function revParse(root, ref) {
+  try {
+    return git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  } catch {
+    return null;
+  }
+}
+function sessionStart(root, branch, at, dryRun = false) {
+  const { integration, greenRef } = loopParams(root);
+  const lines = [];
+  if (!branch) return { ok: false, lines: ["a branch name is required: `rungs session start <branch> [path]`"] };
+  if (revParse(root, `refs/heads/${branch}`)) {
+    return { ok: false, lines: [`branch '${branch}' already exists \u2014 pick another name, or check out the worktree that holds it`] };
+  }
+  const green = revParse(root, `refs/heads/${greenRef}`);
+  const base = green ? greenRef : integration;
+  const baseSha = green ?? revParse(root, integration);
+  if (!baseSha) return { ok: false, lines: [`neither '${greenRef}' nor '${integration}' resolves \u2014 is this the right repo?`] };
+  if (green) {
+    lines.push(`base ${greenRef} (${baseSha.slice(0, 8)}) \u2014 the last verified merge`);
+  } else {
+    lines.push(`no ${greenRef} ref yet \u2014 cutting from the tip of ${integration} (${baseSha.slice(0, 8)}) instead.`);
+    lines.push(`That tip has not been verified by a land. The first successful \`rungs land\` creates ${greenRef}.`);
+  }
+  const path = resolve4(at ?? join13(dirname8(root), `${basename2(root)}-${branch.replace(/[^\w.-]+/g, "-")}`));
+  if (existsSync10(path)) return { ok: false, lines: [`${path} already exists \u2014 rungs never writes over a directory it did not create`] };
+  lines.push(`worktree ${path}`);
+  lines.push(`branch   ${branch}`);
+  if (dryRun) return { ok: true, lines };
+  try {
+    git(root, ["worktree", "add", "-b", branch, path, baseSha]);
+  } catch (e) {
+    return { ok: false, lines: [...lines, `git refused: ${String(e.stderr ?? e.message).trim().split("\n").slice(-2).join(" ")}`] };
+  }
+  return { ok: true, lines };
+}
+function preflight(root) {
+  const { integration } = loopParams(root);
+  if (!revParse(root, integration)) return { ok: false, lines: [`'${integration}' does not resolve \u2014 is this the right repo?`] };
+  let base;
+  try {
+    base = git(root, ["merge-base", "HEAD", integration]);
+  } catch {
+    return { ok: false, lines: [`no merge base between HEAD and ${integration}; nothing to compare`] };
+  }
+  const names = (args2) => new Set(git(root, args2).split("\n").map((s) => s.trim()).filter(Boolean));
+  const theirs = names(["diff", "--name-only", base, integration]);
+  const mine = /* @__PURE__ */ new Set([
+    ...names(["diff", "--name-only", base, "HEAD"]),
+    ...names(["diff", "--name-only", "HEAD"]),
+    ...names(["diff", "--name-only", "--cached"])
+  ]);
+  const ahead = Number(git(root, ["rev-list", "--count", `${base}..${integration}`]));
+  const overlap = [...mine].filter((f) => theirs.has(f)).sort();
+  const lines = [
+    `${integration} is ${ahead} commit(s) ahead of your base, touching ${theirs.size} file(s).`,
+    `You have touched ${mine.size} file(s).`
+  ];
+  if (!overlap.length) {
+    lines.push("No overlap. The commit count is not the signal \u2014 these two sets not intersecting is.");
+    return { ok: true, lines };
+  }
+  lines.push(`${overlap.length} file(s) changed on both sides:`);
+  for (const f of overlap.slice(0, 20)) lines.push(`  ${f}`);
+  if (overlap.length > 20) lines.push(`  \u2026and ${overlap.length - 20} more`);
+  lines.push("Merge sooner rather than later. Shared code is a scheduling problem, not a tooling one.");
+  return { ok: true, lines };
+}
+function lockPath(root) {
+  return join13(git(root, ["rev-parse", "--git-common-dir"]).replace(/^\.git$/, join13(root, ".git")), "rungs-land.lock");
+}
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e?.code === "EPERM";
+  }
+}
+function land(root, branch, runner, dryRun = false) {
+  const { integration, greenRef, integPrefix } = loopParams(root);
+  const lines = [];
+  if (!branch) return { ok: false, lines: ["a branch name is required: `rungs land <branch>`"] };
+  const head = revParse(root, `refs/heads/${branch}`);
+  if (!head) return { ok: false, lines: [`branch '${branch}' does not exist`] };
+  const before = revParse(root, `refs/heads/${integration}`);
+  if (!before) return { ok: false, lines: [`'${integration}' does not resolve`] };
+  const lp = lockPath(root);
+  if (existsSync10(lp)) {
+    try {
+      const held = JSON.parse(readFileSync11(lp, "utf8"));
+      if (held.host === hostname() && alive(held.pid)) {
+        return {
+          ok: false,
+          lines: [
+            `another land is in progress: pid ${held.pid} on ${held.host}, landing '${held.branch}' since ${held.started}.`,
+            "Concurrent landing is refused, not silently merged."
+          ]
+        };
+      }
+      lines.push(`taking over a stale lock from pid ${held.pid} (${held.started}) \u2014 that process is gone.`);
+    } catch {
+      lines.push("an unreadable lock file was replaced.");
+    }
+  }
+  if (dryRun) {
+    lines.push(`would merge ${branch} (${head.slice(0, 8)}) onto ${integration} (${before.slice(0, 8)}) via ${integPrefix}${branch}, verify, then advance.`);
+    return { ok: true, lines };
+  }
+  const lock = { pid: process.pid, host: hostname(), started: (/* @__PURE__ */ new Date()).toISOString(), branch };
+  writeFileSync6(lp, JSON.stringify(lock));
+  const scratch = mkdtempSync2(join13(tmpdir2(), "rungs-land-"));
+  const parked = `${integPrefix}${branch}`;
+  try {
+    git(root, ["worktree", "add", "--detach", scratch, before]);
+    try {
+      git(scratch, ["-c", "user.email=rungs@localhost", "-c", "user.name=rungs", "merge", "--no-ff", "-m", `land ${branch}`, head]);
+    } catch (e) {
+      const conflicts = (() => {
+        try {
+          return git(scratch, ["diff", "--name-only", "--diff-filter=U"]).split("\n").filter(Boolean);
+        } catch {
+          return [];
+        }
+      })();
+      lines.push(`merge conflict \u2014 ${integration} is unchanged.`);
+      for (const f of conflicts.slice(0, 15)) lines.push(`  ${f}`);
+      lines.push("Reconcile generated artifacts by regenerating, never by merging text.");
+      return { ok: false, lines };
+    }
+    const merged = git(scratch, ["rev-parse", "HEAD"]);
+    const res = runner(scratch);
+    lines.push(`merged tree ${merged.slice(0, 8)} \u2014 ${res.pass} pass \xB7 ${res.failing.length} fail`);
+    if (res.failing.length) {
+      const ids = new Set(res.failing.map((f) => f.id));
+      let base = null;
+      try {
+        git(scratch, ["reset", "--hard", before]);
+        base = runner(scratch, ids);
+      } catch {
+        base = null;
+      }
+      const attributable = base !== null && base.failing.length + base.pass >= ids.size;
+      const baseFindings = new Map((base?.failing ?? []).map((f) => [f.id, new Set(f.findings)]));
+      const introduced = [];
+      const inherited = [];
+      for (const f of res.failing) {
+        const seen = attributable ? baseFindings.get(f.id) ?? /* @__PURE__ */ new Set() : null;
+        const fresh = seen ? f.findings.filter((x) => !seen.has(x)) : f.findings;
+        if (fresh.length) introduced.push({ id: f.id, findings: fresh });
+        else inherited.push(f);
+      }
+      for (const f of inherited) {
+        lines.push(`  inherited  ${f.id}${f.findings[0] ? ` \u2014 ${f.findings[0]}` : ""}`);
+      }
+      for (const f of introduced) {
+        lines.push(`  INTRODUCED ${f.id}${f.findings[0] ? ` \u2014 ${f.findings[0]}` : ""}`);
+        for (const extra of f.findings.slice(1, 4)) lines.push(`             ${extra}`);
+      }
+      if (base === null) {
+        lines.push("  The merge base could not be gated, so nothing here is attributable and all of it blocks.");
+      } else if (!attributable) {
+        lines.push("  Some gates could not be attributed against the merge base, so they block. We do not land on an unknown.");
+      }
+      if (introduced.length) {
+        git(root, ["update-ref", `refs/heads/${parked}`, merged]);
+        lines.push(
+          `${introduced.length} introduced by this branch. ${integration} is unchanged, and the merged tree is parked on '${parked}' \u2014 fix it there and land again.`
+        );
+        return { ok: false, lines };
+      }
+      lines.push(
+        `${inherited.length} failure(s), all already red on ${integration} before this branch. Landing anyway \u2014 they are not this branch's to fix, and blocking on them is how a gate gets bypassed.`
+      );
+      git(scratch, ["reset", "--hard", merged]);
+    }
+    try {
+      git(root, ["update-ref", `refs/heads/${integration}`, merged, before]);
+    } catch {
+      git(root, ["update-ref", `refs/heads/${parked}`, merged]);
+      return {
+        ok: false,
+        lines: [
+          ...lines,
+          `${integration} moved while this land was verifying, so the advance was refused rather than overwriting it.`,
+          `Your verified merge is parked on '${parked}'. Re-run \`rungs land ${branch}\` to rebuild it on the new tip.`
+        ]
+      };
+    }
+    git(root, ["update-ref", `refs/heads/${greenRef}`, merged]);
+    lines.push(`${integration} \u2192 ${merged.slice(0, 8)}, and ${greenRef} now marks it verified.`);
+    if (revParse(root, `refs/heads/${parked}`)) git(root, ["update-ref", "-d", `refs/heads/${parked}`]);
+    return { ok: true, lines };
+  } finally {
+    try {
+      git(root, ["worktree", "remove", "--force", scratch]);
+    } catch {
+      rmSync2(scratch, { recursive: true, force: true });
+      try {
+        git(root, ["worktree", "prune"]);
+      } catch {
+      }
+    }
+    try {
+      unlinkSync(lp);
+    } catch {
+    }
+  }
+}
+function worktrees(root) {
+  const { integration } = loopParams(root);
+  const out = git(root, ["worktree", "list", "--porcelain"]);
+  const rows = [];
+  for (const block of out.split("\n\n").filter((b) => b.trim())) {
+    const path = block.match(/^worktree (.+)$/m)?.[1];
+    const branch = block.match(/^branch refs\/heads\/(.+)$/m)?.[1];
+    if (!path || !branch || branch === integration) continue;
+    const merged = gitOk(root, ["merge-base", "--is-ancestor", branch, integration]);
+    let dirty = false;
+    try {
+      dirty = git(path, ["status", "--porcelain"]).length > 0;
+    } catch {
+      dirty = false;
+    }
+    rows.push({ path, branch, merged, dirty });
+  }
+  return { rows, integration };
+}
+
 // src/cli.ts
-import { existsSync as existsSync10 } from "node:fs";
-var HERE = dirname8(fileURLToPath3(import.meta.url));
-var MODULES2 = join13(HERE, "..", "modules");
+import { existsSync as existsSync11 } from "node:fs";
+var HERE = dirname9(fileURLToPath4(import.meta.url));
+var MODULES2 = join14(HERE, "..", "modules");
 var c = {
   dim: (s) => `\x1B[2m${s}\x1B[0m`,
   bold: (s) => `\x1B[1m${s}\x1B[0m`,
@@ -2423,7 +2697,7 @@ ${mods.length} modules
   return issues.length === 0 ? 0 : 1;
 }
 function cmdDoctor(target, doExplain = false) {
-  const root = resolve4(target);
+  const root = resolve5(target);
   const mods = loadAllModules(MODULES2);
   console.log(c.bold(`
 rungs doctor \u2014 ${root}
@@ -2594,6 +2868,29 @@ function cmdAdd(names, root, dryRun, harnesses, stamp) {
     }
     (overrides[modName] ??= {})[param] = rhs.join("=");
   }
+  for (const [modName, vals] of Object.entries(overrides)) {
+    const mod = mods.find((m) => m.name === modName);
+    if (!mod) {
+      console.log(
+        c.red(`
+  --set names a module that does not exist: ${modName}`) + c.dim(`
+  Known: ${mods.map((m) => m.name).join(", ")}
+`)
+      );
+      return 1;
+    }
+    for (const k of Object.keys(vals)) {
+      if (!(k in mod.params)) {
+        const known = Object.keys(mod.params);
+        console.log(
+          c.red(`
+  --set names a parameter ${modName} does not have: ${k}`) + c.dim(`
+  ${known.length ? `${modName} takes: ${known.join(", ")}` : `${modName} takes no parameters`}`) + c.dim("\n  `rungs modules --params` lists every parameter and its default.\n")
+        );
+        return 1;
+      }
+    }
+  }
   const params = resolveParams(mods, overrides, root);
   for (const [m, vals] of Object.entries(overrides)) {
     for (const [k, v] of Object.entries(vals)) console.log(c.dim(`  set ${m}.${k} = ${v}`));
@@ -2712,6 +3009,49 @@ rungs render \u2014 ${root}
   }
   return 0;
 }
+function report(r) {
+  console.log();
+  for (const l of r.lines) console.log(`  ${r.ok ? l : c.yellow(l)}`);
+  console.log();
+  return r.ok ? 0 : 1;
+}
+function landRunner(dir, only) {
+  const runs = runGates(dir, void 0, void 0, only);
+  const failing = runs.filter((r) => r.status === "fail" || r.status === "error");
+  return {
+    pass: runs.filter((r) => r.status === "pass").length,
+    // `file: message`, so the same broken link in the same file is the same
+    // finding across two runs, and a *new* one is visibly not.
+    failing: failing.map((r) => ({
+      id: r.id,
+      findings: r.findings.map((f) => `${f.file ? `${f.file}: ` : ""}${f.message}`)
+    }))
+  };
+}
+function cmdWorktrees(root) {
+  const { rows, integration } = worktrees(root);
+  console.log(c.bold(`
+rungs worktrees \u2014 merged into ${integration}?
+`));
+  if (!rows.length) {
+    console.log(c.dim("  no linked worktrees. `rungs session start <branch>` creates one.\n"));
+    return 0;
+  }
+  for (const w of rows) {
+    const state = w.merged && w.dirty ? c.red("merged \xB7 DIRTY") : w.merged ? c.green("merged \xB7 prunable") : c.dim("in flight");
+    console.log(`  ${state.padEnd(28)} ${w.branch.padEnd(30)} ${c.dim(w.path)}`);
+  }
+  const risky = rows.filter((w) => w.merged && w.dirty);
+  const prunable = rows.filter((w) => w.merged && !w.dirty);
+  console.log();
+  if (risky.length) {
+    console.log(c.red(`  ${risky.length} worktree(s) hold uncommitted work on a branch that already landed.`));
+    console.log(c.dim("  That is where work actually gets lost. Commit it somewhere or decide to drop it."));
+  }
+  if (prunable.length) console.log(c.dim(`  ${prunable.length} prunable. Removing a worktree is your call, not this command's.`));
+  console.log();
+  return 0;
+}
 function cmdCheck(root, tier, stamp) {
   let runs;
   try {
@@ -2782,7 +3122,7 @@ function cmdBacklogArchive(root, dryRun) {
   const record = readRecord(root);
   const configured = record?.modules["backlog"]?.params?.root;
   const backlogRoot = `docs/${configured ?? "backlog"}`;
-  if (!existsSync10(join13(root, ...backlogRoot.split("/"), "items"))) {
+  if (!existsSync11(join14(root, ...backlogRoot.split("/"), "items"))) {
     console.log(c.red(`
   no backlog at ${backlogRoot}/items
 `));
@@ -2907,7 +3247,11 @@ var COMMANDS = [
   ["eject [path]", "materialise the engines; stop depending on rungs"],
   ["setup git [path]", "install the merge drivers .gitattributes names"],
   ["modules", "list the module set and audit the manifests"],
-  ["backlog archive [path]", "move finished items to archive/, repointing every link"]
+  ["backlog archive [path]", "move finished items to archive/, repointing every link"],
+  ["session start <branch>", "cut a branch and worktree from the last verified merge"],
+  ["preflight [path]", "did the integration branch change files you changed?"],
+  ["land <branch>", "merge \u2192 verify the merged tree \u2192 advance, or refuse and park it"],
+  ["worktrees [path]", "which worktrees are merged, prunable, or merged and still dirty"]
 ];
 var FLAGS = [
   ["--dry-run", "report what would happen, write nothing"],
@@ -2986,22 +3330,29 @@ switch (cmd) {
   unknown: rungs backlog ${args[0] ?? ""}`) + c.dim("\n  The only subcommand is `archive`.\n"));
       process.exit(1);
     }
-    process.exit(cmdBacklogArchive(resolve4(args[1] ?? process.cwd()), flags.has("--dry-run")));
+    process.exit(cmdBacklogArchive(resolve5(args[1] ?? process.cwd()), flags.has("--dry-run")));
   }
   case "check": {
     const tier = args[1] ?? (flags.has("--full") ? "full" : flags.has("--fast") ? "fast" : void 0);
-    process.exit(cmdCheck(resolve4(args[0] ?? process.cwd()), tier, STAMP));
+    process.exit(cmdCheck(resolve5(args[0] ?? process.cwd()), tier, STAMP));
   }
   case "init": {
     const profile = args[1] ?? "tracked";
-    process.exit(cmdInit(resolve4(args[0] ?? process.cwd()), profile, flags.has("--dry-run"), HARNESSES, STAMP));
+    process.exit(cmdInit(resolve5(args[0] ?? process.cwd()), profile, flags.has("--dry-run"), HARNESSES, STAMP));
   }
   case "upgrade":
-    process.exit(cmdUpgrade(resolve4(args[0] ?? process.cwd()), flags.has("--apply")));
+    process.exit(cmdUpgrade(resolve5(args[0] ?? process.cwd()), flags.has("--apply")));
   case "eject":
-    process.exit(cmdEject(resolve4(args[0] ?? process.cwd()), flags.has("--dry-run")));
+    process.exit(cmdEject(resolve5(args[0] ?? process.cwd()), flags.has("--dry-run")));
   case "setup": {
-    const r = setupGit(resolve4(args[1] ?? process.cwd()), flags.has("--dry-run"));
+    if (args[0] !== "git") {
+      console.log(
+        c.red(`
+  unknown: rungs setup ${args[0] ?? ""}`.trimEnd()) + c.dim("\n  The only subcommand is `git`, and the path comes after it: `rungs setup git [path]`.\n")
+      );
+      process.exit(1);
+    }
+    const r = setupGit(resolve5(args[1] ?? process.cwd()), flags.has("--dry-run"));
     console.log(
       r.drivers.length ? `
   installed ${r.drivers.length} merge driver(s): ${r.drivers.join(", ")}` + (r.rerere ? c.dim(" \xB7 rerere on") : "") + c.dim("\n  Declared drivers were inert until now \u2014 a fresh clone needs this once.\n") : c.dim("\n  no rungs merge drivers declared in .gitattributes\n")
@@ -3009,11 +3360,25 @@ switch (cmd) {
     process.exit(0);
   }
   case "render":
-    process.exit(cmdRender(resolve4(args[0] ?? process.cwd()), HARNESSES, STAMP));
+    process.exit(cmdRender(resolve5(args[0] ?? process.cwd()), HARNESSES, STAMP));
+  case "session": {
+    if (args[0] !== "start") {
+      console.log(c.red(`
+  unknown: rungs session ${args[0] ?? ""}`.trimEnd()) + c.dim("\n  The only subcommand is `start`: `rungs session start <branch> [path]`.\n"));
+      process.exit(1);
+    }
+    process.exit(report(sessionStart(process.cwd(), args[1], args[2], flags.has("--dry-run"))));
+  }
+  case "preflight":
+    process.exit(report(preflight(resolve5(args[0] ?? process.cwd()))));
+  case "land":
+    process.exit(report(land(process.cwd(), args[0], landRunner, flags.has("--dry-run"))));
+  case "worktrees":
+    process.exit(cmdWorktrees(resolve5(args[0] ?? process.cwd())));
   case "add": {
     const target = flags.has("--into") ? args[args.length - 1] : process.cwd();
     const names = flags.has("--into") ? args.slice(0, -1) : args;
-    process.exit(cmdAdd(names, resolve4(target), flags.has("--dry-run"), HARNESSES, STAMP));
+    process.exit(cmdAdd(names, resolve5(target), flags.has("--dry-run"), HARNESSES, STAMP));
   }
   default: {
     const wantedHelp = cmd === void 0 || cmd === "help" || cmd === "--help" || cmd === "-h";