@rungs/cli 0.2.0 → 0.3.0

package/README.md

@@ -138,6 +138,10 @@ reported as diverged and left alone.
 | `rungs setup git [path]` | Install the merge drivers `.gitattributes` names |
 | `rungs modules` | List the set and audit the manifests |
 | `rungs backlog archive` | Move finished items to `archive/`, repointing every link that cites them |
+| `rungs session start <branch>` | Cut a branch and worktree from the last **verified** merge, not the tip |
+| `rungs preflight [path]` | Did the integration branch change files *you* changed? |
+| `rungs land <branch>` | Merge → verify the merged tree → advance with a compare-and-swap, or refuse and park it |
+| `rungs worktrees [path]` | Which worktrees are merged, prunable, or merged and still dirty |
 
 | Option | Effect |
 | --- | --- |
@@ -169,6 +173,10 @@ you when you are installing above your level.
 | **4** docs that restate each other | `doc-authority` |
 | **5** 5+ concurrent sessions | `concurrency` |
 
+The last four commands are the `concurrency` loop. They drive git, which nothing else in rungs
+does — [ADR-0009](docs/decisions/ADR-0009-rungs-drives-git.md) sets the rules they obey: verify
+before you advance, never destroy (only refuse), and never hold the integration branch.
+
 `concurrency` refuses to install without `--confirm-threshold`, because below
 five simultaneous sessions every mechanism in it costs more than it returns.
 Selling rung 5 to a rung-1 repo is the most likely way this tool does harm.
@@ -212,22 +220,27 @@ Four promises that shape everything else:
 
 ## Status
 
-**Next release: v0.2.0** — assembled from [`changelog.d/0.2.0.md`](changelog.d/0.2.0.md) and
-prepared in [`package.json`](package.json), untagged until the
-[release runbook](docs/design/release-runbook.md) is run to completion. That number is checked
-against the manifest by the `docs-version-claims` gate, so this sentence cannot drift from what
-ships.
+**Current release: v0.3.0** — that number is checked against [`package.json`](package.json) by the
+`docs-version-claims` gate, so this sentence cannot drift from what ships — and the gate fails if
+the sentence is reworded out of existence, because a claim nothing checks any more should not look
+the same as a claim that passes.
+
+It deliberately does **not** say "and it is on npm". Whether this version is tagged and published
+is a fact about the registry, not about the manifest, and it was wrong here for two days once
+already.
 
-What is **published** is deliberately not restated here. It lives on
-[the versions page](https://docs.rungscli.com/versions/), which is the one place that tracks it —
-this file and the roadmap both carried their own copy and both said `v0.1.2` for two days after
-v0.1.3 went to npm.
+Whether a release is **pending**, and what npm currently serves, live on
+[the versions page](https://docs.rungscli.com/versions/) — the one place that tracks them. This
+file and the roadmap both carried their own copy and both said `v0.1.2` for two days after v0.1.3
+went to npm. Cutting the next one follows the [release runbook](docs/design/release-runbook.md).
 
-rungs is installed in its own repo and its gates run on every change — 25 pass,
-0 fail (`rungs check`, 2026-08-17). A clean consumer has also installed the packed
-artifact and completed the doctor → init → add → check → render → upgrade/eject
-journey locally. Detection is [verified against all four source repos](docs/design/detection-verification.md).
-Not yet done: an install from the public registry and a cross-platform release matrix.
+rungs is installed in its own repo and its 29 gates run on every change — 29 pass,
+0 fail (`rungs check`, 2026-08-17). A clean consumer has installed from the **public
+registry** and run the binary, and another completed the doctor → init → add → check →
+render → upgrade/eject journey from a packed artifact. Detection is
+[verified against all four source repos](docs/design/detection-verification.md).
+Not yet done: a cross-platform release matrix — only Windows is verified — and writing
+to a repo rungs did not scaffold.
 
 Expect module *contents* to move. The command surface is settled.
 
@@ -248,7 +261,7 @@ nobody paid for does not ship.
 | [`docs/design/`](docs/design/README.md) | Product brief, module catalogue, verification |
 | [`docs/decisions/`](docs/decisions/README.md) | ADRs |
 | [`modules/`](modules/README.md) | The fifteen modules |
-| [`src/`](src/) | The CLI, ~4,700 lines (`wc -l src/*.ts`, 2026-08-17; held within 10% by `docs-version-claims`) |
+| [`src/`](src/) | The CLI, ~5,100 lines (`wc -l src/*.ts`, 2026-08-17; held within 10% by `docs-version-claims`) |
 
 ## Licence
 

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli.ts
 import { fileURLToPath as fileURLToPath3 } from "node:url";
-import { dirname as dirname8, join as join13, resolve as resolve4 } from "node:path";
+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";
@@ -880,6 +880,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 +934,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 +958,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;
@@ -1228,11 +1238,11 @@ var crossReference = (t, root, files) => {
   return { findings, examined: skills.length };
 };
 function landedWork(root, branch, base) {
-  const git = (cmd2) => execSync(`git ${cmd2}`, { cwd: root, stdio: "pipe" }).toString().trim();
+  const git2 = (cmd2) => execSync(`git ${cmd2}`, { cwd: root, stdio: "pipe" }).toString().trim();
   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;
   }
@@ -1270,8 +1280,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 +1302,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`.")
       });
     }
   }
@@ -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";
@@ -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 } 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 execFileSync("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(fileURLToPath3(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";