@inixiative/config 0.5.80 → 0.5.82

package/README.md

@@ -43,6 +43,7 @@ One version of `@inixiative/config` names one coherent ecosystem state:
 - `ecosystem` — the primitives lane's blessed, mutually-verified `@inixiative/*` set, plus this package
 - `agentic` — the agentic lane's blessed set
 - `consumers` — private repos that follow the blessed sets but never publish, keyed by GitHub `owner/repo`: `lanes` names the lanes each consumes, `upstream` the repo it syncs from
+- `candidates` — published lane versions newer than their blessed one, waiting for every dependent to adopt them (see `train`); absent when there are none
 
 ```jsonc
 "consumers": {
@@ -71,7 +72,7 @@ bunx @inixiative/config ports [project]
 
 `ports` prints each project's local ports from `ports.json` (also exported as `@inixiative/config/ports.json`). A project's port for a service is the service's usual default plus 100 times the project's block, so no two projects collide and none sits on a default: Archive (block 7) serves HTTP on 4700 with Postgres on 6132; Kingdom (block 2) has web 3200, API 8200, Postgres 5632, Redis 6579. Reserved ports (macOS AirPlay on 5000 and 7000) are never assigned. Give a new project the next free block, and a new kind of service its usual default; the tests fail on any collision.
 
-`check` is read-only and exits non-zero on drift — run it in CI after a frozen-lockfile install. It verifies toolchain pins — declared once, at the root, pinned exactly: a workspace member declaring one is an error, and `bun.lock` must resolve each only to its pin (no second copy) — toolchain peer ranges (they must admit the pin and no older major; `sync` writes `>=<pin major>.<pin minor>.0`), `"latest"` ranges, `packageManager`/`.bun-version`, legacy `bun.lockb`, a committed (tracked, un-ignored) `bun.lock`, required scripts (`check`/`typecheck`/`lint`/`test`), lefthook (dep + `lefthook.yml` extending the shared hooks + `prepare` script; git repos only), stub `extends`, presence of this package, and for every ecosystem dependency — in the root or any workspace member, of either lane — that the declared range admits the blessed version and the lockfile actually resolves to it (the stale-lockfile class). A range that does not admit the blessed version is rewritten to `^<blessed>`, except an exact pin, which stays exact and moves to the blessed version. An npm alias (`"@inixiative/session-archive": "npm:@inixiative/archive@^0.2.1"`) is held to its target's blessed version and rewritten as an alias; `workspace:`, `file:` and `link:` ranges are a repo linking itself and are left alone.
+`check` is read-only and exits non-zero on drift — run it in CI after a frozen-lockfile install. It verifies toolchain pins — declared once, at the root, pinned exactly: a workspace member declaring one is an error, and `bun.lock` must resolve each only to its pin (no second copy) — toolchain peer ranges (they must admit the pin and no older major; `sync` writes `>=<pin major>.<pin minor>.0`), `"latest"` ranges, `packageManager`/`.bun-version`, legacy `bun.lockb`, a committed (tracked, un-ignored) `bun.lock`, required scripts (`check`/`typecheck`/`lint`/`test`), lefthook (dep + `lefthook.yml` extending the shared hooks + `prepare` script; git repos only), stub `extends`, presence of this package, and for every ecosystem dependency — in the root or any workspace member, of either lane — that the declared range admits the blessed version and the lockfile actually resolves to it (the stale-lockfile class). A package with a candidate also accepts the candidate and anything between: a range admitting either passes, and so does a lock from the blessed version up to the candidate. A range that does not admit the blessed version is rewritten to `^<blessed>`, except an exact pin, which stays exact and moves to the blessed version. An npm alias (`"@inixiative/session-archive": "npm:@inixiative/archive@^0.2.1"`) is held to its target's blessed version and rewritten as an alias; `workspace:`, `file:` and `link:` ranges are a repo linking itself and are left alone.
 
 `sync` applies every fix (deleting member toolchain entries and their stale member links), re-locks via `bun install` (`--force` when a second toolchain copy survives), and runs `bun update` on stale ecosystem entries in the directory that declares them. It refuses to run on a dirty working tree without `--force`. The react preset is inferred from a `react` dependency; override with `--preset`. Missing scripts are filled with defaults; existing script bodies are never touched.
 
@@ -79,11 +80,23 @@ bunx @inixiative/config ports [project]
 
 `train` is the release cascade, run from a git checkout of this repo; it refuses to train from a copy that isn't one (a bunx or npm cache). One train at a time per machine: it takes one machine-wide lock, `~/.inixiative/train.lock`, shared by every clone, worktree and lane, and refuses to start while another train holds it, naming the holder and the lock path. The lock is created atomically and records the holder's pid, hostname and process start time. A lock is stale, and taken over, when its process is gone, its pid now belongs to a different process, or the file can't be parsed. A lock from another host is never judged stale; if its train is truly gone, delete the file. The lock is released on exit and on SIGINT, SIGTERM or SIGHUP. `--dry-run` takes no lock. It walks every lane in order (primitives, then agentic), or only the lane `--lane` names. Origin is the truth: it refuses to run from a config checkout behind origin, and it fast-forwards clean checkouts to origin before working (dirty or diverged repos still skip). It only ships the default branch: a checkout on a feature branch is skipped whole — never re-locked, committed to, or published from.
 
-Lanes stand alone. A lane with a package missing a checkout, or claimed by ambiguous checkouts, does not run; a lane whose check, commit or publish fails stops there and leaves its BOM entries as they were. Neither holds back the other lane. Within a lane it walks checkouts in dependency order; per checkout it: bumps ecosystem ranges to the blessed sets → re-locks → runs the repo's `check` → commits only its own changes (`package.json` files + `bun.lock`) → publishes each lane package whose local version is ahead of npm, in dependency order, and waits until the registry serves it (up to 15 minutes, since npm holds new versions for processing) → records it in its lane's section of the BOM. A root package publishes with `npm publish`; a workspace member is packed with `bun pm pack`, which rewrites `workspace:` ranges to the versions being released, and the tarball is published with `npm publish`, so OTP prompts pass through either way. A package already on npm at its local version but not yet blessed — published by hand, or by a train whose lane later failed — is blessed on the next run. Likewise, an `@inixiative/config` version committed ahead of npm (a release whose publish failed) is published by the next run, even when it blesses nothing new.
+Lanes stand alone. A lane with a package missing a checkout, or claimed by ambiguous checkouts, does not run; a lane whose own check (not one against candidates, below), commit or publish fails stops there: what it already published stays a candidate, and none of its candidates is blessed that run. Neither holds back the other lane. Within a lane it walks checkouts in dependency order; per checkout it: bumps ecosystem ranges to the blessed sets with their candidates in place → re-locks → runs the repo's `check` → commits only its own changes (`package.json` files + `bun.lock`) → publishes each lane package whose local version is ahead of npm, in dependency order, and waits until the registry serves it (up to 15 minutes, since npm holds new versions for processing) → records it as a candidate in the BOM.
 
-Consumers run once, after every selected lane, upstreams first, against the full blessed set: a consumer of both lanes ends coherent with both whichever lane ran. They get the same bump → re-lock → `check`, never a publish, and their changes go through review: the train commits them on a `train/ecosystem-sync-<date>` branch and leaves the checkout there until it is merged.
+Blessing is two-phase, so a dependent that needs work never deadlocks a release:
 
-When anything was blessed it then ships this package last, so the BOM names the new state: bumps its own patch version if npm already has the current one, blesses that version in the BOM, brings the `test/fixtures` consumers onto the blessed set, runs `check`, commits, publishes. Then every checkout the train re-locked (lane packages on their default branch, consumers on their review branch) is re-locked onto that new `@inixiative/config` and committed, so none is left pinning the previous release. It never pushes unless asked: pass `--push` to push every repo it committed to and open a PR for each consumer branch; otherwise it prints the commands. `--dry-run` walks the same plan and prints each step it would take (range rewrites, re-locks and checks, commits, review branches, publishes, BOM blessings, pushes) without running any of them; it only fetches and reads git state and `npm view`.
+1. **Candidate.** A published version is recorded under `candidates`, and the config release that ends the train carries it, so `check` in any repo's CI accepts it from then on.
+2. **Adopt.** A repo (lane checkout or consumer) whose check fails against the candidates it was moved onto doesn't stop the train. Its checkout is put back as it was, and the train opens `train/adopt-<pkg>-<version>` in a worktree (with the repo's ignored `.env*` files copied in, at any depth): the same bump and re-lock, then the repo's `train:adopt` script if its package.json declares one (Foundry's re-records cassettes with `bun run test:live`), all committed, and re-locked onto the new config release so the PR's CI judges it against the candidates. A lane checkout that adopts publishes nothing this run. A consumer that passes against candidates gets the same branch name: its default branch is still on the previous versions until the branch merges. If the adoption's commit is refused (its hooks typecheck), the branch is deleted and the summary says to adopt by hand.
+3. **Promote.** At the end of each run a candidate is blessed (moved into its lane's section) unless something holds it: its lane stopped; a repo has an adoption branch for it that is not yet on its default branch (opened this run, unmerged, or committed but never pushed); or a repo that declares it was not walked to an outcome this run — another lane's checkout, a skipped or failed one, a consumer without a checkout. A later train finds a waiting adoption branch and opens nothing new; once it merges, the repo is on the candidate and the train promotes it. A candidate every dependent already accepts is blessed in the run that published it. An adoption PR closed without merging holds its candidates until its branch is deleted.
+
+The summary lists what was blessed, every candidate with what holds it, and each pending adoption branch with its PR when `gh` can find one.
+
+A root package publishes with `npm publish`; a workspace member is packed with `bun pm pack`, which rewrites `workspace:` ranges to the versions being released, and the tarball is published with `npm publish`, so OTP prompts pass through either way. A package already on npm at its local version but neither blessed nor a candidate — published by hand, or by a train whose lane later failed — becomes a candidate on the next run. Likewise, an `@inixiative/config` version committed ahead of npm (a release whose publish failed) is published by the next run, even when it blesses nothing new.
+
+Consumers run once, after every selected lane, upstreams first, against the full blessed set: a consumer of both lanes ends coherent with both whichever lane ran. They get the same bump → re-lock → `check`, never a publish, and their changes go through review: the train commits them on a `train/ecosystem-sync-<date>` branch, in a worktree, and puts the checkout back on its default branch, clean.
+
+A train never leaves a checkout dirty or off its default branch. It only works in a checkout it found clean, so a checkout that then fails is reset to HEAD (tracked and untracked files; ignored ones such as node_modules and `.env` stay) and re-installed from its lockfile. Every branch it makes is committed in a temporary worktree, removed when the train exits.
+
+When anything was recorded or blessed it then ships this package last, so the BOM names the new state: bumps its own patch version if npm already has the current one, blesses that version in the BOM, brings the `test/fixtures` consumers onto the blessed set, runs `check`, commits, publishes. Then every checkout the train re-locked (lane packages on their default branch, consumer and adoption branches in their worktrees) is re-locked onto that new `@inixiative/config` and committed, so none is left pinning the previous release. It never pushes unless asked: pass `--push` to push every repo it committed to and open a PR for each consumer and adoption branch; otherwise it prints the commands. `--dry-run` walks the same plan and prints each step it would take (range rewrites, re-locks and checks, commits, review branches, publishes, BOM blessings, pushes) without running any of them; it only fetches and reads git state and `npm view`.
 
 Each command accepts only its own flags. An unknown or misplaced flag (`--dryrun`, `--push` on `sync`) is a usage error and exits 2 before anything runs.
 

package/dist/cli.js

@@ -2,9 +2,17 @@
 
 // src/cli.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync2, mkdtempSync, readdirSync as readdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import {
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  mkdtempSync,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync2,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync2
+} from "fs";
 import { hostname as hostname2, tmpdir } from "os";
-import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+import { basename, dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 
 // src/args.ts
 import { parseArgs } from "util";
@@ -44,6 +52,33 @@ var blessedVersions = (manifest2) => ({
   ...manifest2.ecosystem,
   ...manifest2.agentic
 });
+var laneOf = (manifest2, name) => LANES.find((lane2) => name in lanePackages(manifest2, lane2)) ?? null;
+var adoptionTarget = (manifest2) => {
+  const candidates = manifest2.candidates ?? {};
+  const overlay = (section) => Object.fromEntries(
+    Object.entries(section).map(([name, version]) => [name, candidates[name] ?? version])
+  );
+  return {
+    ...manifest2,
+    ecosystem: overlay(manifest2.ecosystem),
+    agentic: overlay(manifest2.agentic ?? {})
+  };
+};
+var promoteCandidates = (manifest2, names) => {
+  const promoted = [];
+  for (const name of names) {
+    const version = manifest2.candidates?.[name];
+    const lane2 = laneOf(manifest2, name);
+    if (!version || !lane2 || !manifest2.candidates) continue;
+    laneSection(manifest2, lane2)[name] = version;
+    delete manifest2.candidates[name];
+    promoted.push(`${name}@${version}`);
+  }
+  if (manifest2.candidates && Object.keys(manifest2.candidates).length === 0) {
+    delete manifest2.candidates;
+  }
+  return promoted;
+};
 var consumersFor = (manifest2, lanes2) => {
   const consumers = manifest2.consumers ?? {};
   const selected = Object.keys(consumers).filter((repo) => consumers[repo].lanes.some((lane2) => lanes2.includes(lane2))).sort();
@@ -296,6 +331,10 @@ var orderBy = (items, key, deps) => {
   }
   return order;
 };
+var declaredDependencies = (dir2) => {
+  const pkg = readJson(join(dir2, "package.json"));
+  return pkg ? dependencyNames(dir2, ["package.json", ...workspacePackagePaths(dir2, pkg)]) : /* @__PURE__ */ new Set();
+};
 var publishOrder = (checkout) => {
   const names = new Set(checkout.packages.map((entry) => entry.name));
   const deps = new Map(
@@ -681,6 +720,7 @@ function inspect(dir2, manifest2, presetOverride) {
     }
   }
   const blessedSet = blessedVersions(manifest2);
+  const candidateSet = manifest2.candidates ?? {};
   const staleKeys = /* @__PURE__ */ new Set();
   for (const target of rangeTargets) {
     for (const field of DEP_FIELDS) {
@@ -693,14 +733,19 @@ function inspect(dir2, manifest2, presetOverride) {
         const blessed = blessedSet[name];
         if (!blessed || name === target.pkg.name || !deps) continue;
         const rewrite = (next) => name === key ? next : `npm:${name}@${next}`;
-        const ok = admits(range, blessed);
+        const candidate = candidateSet[name];
+        const okBlessed = admits(range, blessed);
+        const okCandidate = candidate ? admits(range, candidate) : false;
+        const ok = okBlessed === true || okCandidate === true ? true : okBlessed;
+        const accepted = candidate === blessed ? `candidate ${candidate}` : `blessed ${blessed}${candidate ? ` or candidate ${candidate}` : ""}`;
         if (ok === false) {
           const next = /^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(range) ? blessed : `^${blessed}`;
           findings.push({
             level: "error",
             kind: "ecosystem-range",
             name,
-            message: `${target.label}${key} ${field} range ${spec} does not admit blessed ${blessed} \u2192 ${rewrite(next)}`,
+            target: name,
+            message: `${target.label}${key} ${field} range ${spec} does not admit ${accepted} \u2192 ${rewrite(next)}`,
             fix: () => {
               deps[key] = rewrite(next);
               target.mark();
@@ -710,28 +755,31 @@ function inspect(dir2, manifest2, presetOverride) {
         if (ok === null) {
           findings.push({
             level: "warn",
-            message: `${target.label}${key} range ${spec} not understood; verify manually against ${blessed}`
+            message: `${target.label}${key} range ${spec} not understood; verify manually against ${accepted}`
           });
         }
         if (!lockText || field === "peerDependencies" || staleKeys.has(key)) continue;
         const locked = lockedVersion(lockText, key, name);
+        const lockAccepted = locked === blessed || !!locked && locked === candidate || !!locked && !!candidate && compare(locked, blessed) >= 0 && compare(locked, candidate) <= 0;
         if (locked && admits(range, locked) === false) {
           staleKeys.add(key);
           findings.push({
             level: "error",
             kind: "stale-lock",
             name: key,
+            target: name,
             path: target.path,
             message: `${target.label}${key} locked at ${locked}, violating declared ${spec} (stale lockfile) \u2192 re-lock`
           });
-        } else if (locked && locked !== blessed) {
+        } else if (locked && !lockAccepted) {
           staleKeys.add(key);
           findings.push({
             level: "error",
             kind: "stale-lock",
             name: key,
+            target: name,
             path: target.path,
-            message: `${target.label}${key} locked at ${locked}, blessed is ${blessed} \u2192 re-lock`
+            message: `${target.label}${key} locked at ${locked}, ${accepted.replace(/^(blessed|candidate) /, "$1 is ")} \u2192 re-lock`
           });
         }
       }
@@ -1119,6 +1167,9 @@ if (command === "scan") {
   const missing = [...plan.lanes.flatMap((lane2) => lane2.missing), ...plan.missingConsumers];
   const ambiguous = [...plan.lanes.flatMap((lane2) => lane2.ambiguous), ...plan.ambiguousConsumers];
   const drifted = [];
+  for (const [name, version] of Object.entries(manifest.candidates ?? {})) {
+    console.log(`candidate: ${name}@${version} (blessed ${blessedVersions(manifest)[name]})`);
+  }
   for (const checkout of checkouts) {
     console.log(`
 ${checkout.name} \u2014 ${checkout.dir} (${laneLabel(checkout)})`);
@@ -1152,6 +1203,8 @@ scanned ${checkouts.length} repos (${lanes.join(" + ")}): ${drifted.length === 0
 }
 var Abort = class extends Error {
 };
+var CheckFailed = class extends Abort {
+};
 if (command === "train") {
   const effect = (description, planned, run) => {
     if (!dryRun) return run();
@@ -1179,9 +1232,9 @@ if (command === "train") {
       checkout: packageRoot
     });
     if (!lock.ok) {
-      const { pid, hostname: host, startedAt, lanes: held, root, checkout } = lock.heldBy;
+      const { pid, hostname: host, startedAt, lanes: held2, root, checkout } = lock.heldBy;
       console.error(
-        `\u2717 another train is running (pid ${pid} on ${host}, lanes ${held.join(" + ")}, root ${root}, from ${checkout}, since ${startedAt}) \u2014 wait for it to finish; one train at a time. If that train is truly gone, delete ${lock.path}`
+        `\u2717 another train is running (pid ${pid} on ${host}, lanes ${held2.join(" + ")}, root ${root}, from ${checkout}, since ${startedAt}) \u2014 wait for it to finish; one train at a time. If that train is truly gone, delete ${lock.path}`
       );
       process.exit(1);
     }
@@ -1212,12 +1265,21 @@ if (command === "train") {
     console.error(`\u2717 no ecosystem repos found under ${dir}`);
     process.exit(1);
   }
-  const blessed = [];
+  const recorded = [];
   const skipped = [];
   const failed = [];
+  const failedLanes = /* @__PURE__ */ new Set();
   const committed = /* @__PURE__ */ new Set();
   const reviewBranches = [];
-  let bomDirty = false;
+  const waiting = [];
+  const walked = /* @__PURE__ */ new Set();
+  const worktrees = [];
+  process.on("exit", () => {
+    for (const { repo, path } of worktrees.splice(0)) {
+      git(repo, "worktree", "remove", "--force", path);
+    }
+  });
+  const target = () => adoptionTarget(manifest);
   const ready = (checkout) => {
     const porcelain = git(checkout.dir, "status", "--porcelain");
     if (porcelain.status !== 0) {
@@ -1263,14 +1325,18 @@ if (command === "train") {
     return true;
   };
   const bumpRanges = (checkout) => {
-    const inspection = inspect(checkout.dir, manifest);
+    const inspection = inspect(checkout.dir, target());
     const bumps = inspection.findings.filter((finding) => finding.kind === "ecosystem-range");
     for (const bump of bumps) console.log(`  ${bump.message}`);
     if (bumps.length > 0) {
-      effect(`rewrite ${bumps.length} ecosystem range(s) to the blessed set`, void 0, () => {
-        for (const bump of bumps) bump.fix?.();
-        inspection.flush();
-      });
+      effect(
+        `rewrite ${bumps.length} ecosystem range(s) to the blessed set and its candidates`,
+        void 0,
+        () => {
+          for (const bump of bumps) bump.fix?.();
+          inspection.flush();
+        }
+      );
     }
     return {
       inspection,
@@ -1279,37 +1345,188 @@ if (command === "train") {
     };
   };
   const relockAndCheck = (checkout, check = true) => effect(`re-lock ${checkout.name}${check ? " and run its check" : ""}`, void 0, () => {
-    if (spawnSync2("bun", ["install"], { cwd: checkout.dir, stdio: "inherit" }).status !== 0) {
+    const install = (...flags) => spawnSync2("bun", ["install", ...flags], { cwd: checkout.dir, stdio: "inherit" }).status === 0;
+    if (!install() && !install("--no-cache")) {
       throw new Abort(`bun install failed in ${checkout.name}`);
     }
     for (const { cwd, names } of staleUpdates(
       checkout.dir,
-      inspect(checkout.dir, manifest).findings
+      inspect(checkout.dir, target()).findings
     )) {
       spawnSync2("bun", ["update", ...names], { cwd, stdio: "inherit" });
     }
     if (check && spawnSync2("bun", ["run", "check"], { cwd: checkout.dir, stdio: "inherit" }).status !== 0) {
-      throw new Abort(`check failed in ${checkout.name}`);
+      throw new CheckFailed(`check failed in ${checkout.name}`);
     }
   });
   const followers = [];
-  const commitOwned = (checkout, packagePaths, changes) => {
+  const restore = (checkout) => effect(`restore ${checkout.name} to HEAD`, void 0, () => {
+    if (git(checkout.dir, "status", "--porcelain").stdout.trim() === "") return;
+    git(checkout.dir, "reset", "--quiet", "--hard", "HEAD");
+    git(checkout.dir, "clean", "--quiet", "-fd");
+    spawnSync2("bun", ["install", "--frozen-lockfile"], { cwd: checkout.dir, stdio: "inherit" });
+  });
+  const movesOf = (checkout) => {
+    const candidates2 = manifest.candidates ?? {};
+    const names = inspect(checkout.dir, target()).findings.flatMap(
+      (finding) => (finding.kind === "ecosystem-range" || finding.kind === "stale-lock") && finding.target && finding.target in candidates2 ? [finding.target] : []
+    );
+    return [...new Set(names)].sort();
+  };
+  const adoptionBranch = (moving) => `train/adopt-${moving.map((name) => `${name.replace(/^@inixiative\//, "")}-${manifest.candidates?.[name]}`).join("-")}`;
+  const ahead = (cwd, ref) => {
+    if (git(cwd, "rev-parse", "--verify", "--quiet", ref).status !== 0) return null;
+    return Number(git(cwd, "rev-list", "--count", `HEAD..${ref}`).stdout.trim());
+  };
+  const pendingAdoption = (checkout, moving) => {
+    if (moving.length === 0) return false;
+    const branch = adoptionBranch(moving);
+    const remote = ahead(checkout.dir, `refs/remotes/origin/${branch}`);
+    const local = ahead(checkout.dir, `refs/heads/${branch}`);
+    if (!remote && !local) return false;
+    const state = remote ? "unmerged" : "unpushed";
+    console.log(
+      `\u23F3 adopting ${moving.join(", ")} on ${branch} \u2014 ${state === "unmerged" ? "waiting for it to merge" : "never pushed: push it and open its PR"}`
+    );
+    waiting.push({ name: checkout.name, dir: checkout.dir, moving, state, branch });
+    walked.add(checkout.dir);
+    return true;
+  };
+  const worktree = (checkout, branch) => {
+    const path = join2(mkdtempSync(join2(tmpdir(), "inixiative-train-")), basename(checkout.dir));
+    if (git(checkout.dir, "worktree", "add", "--quiet", "-b", branch, path, "HEAD").status !== 0) {
+      throw new Abort(`could not create ${branch} in ${checkout.name}`);
+    }
+    worktrees.push({ repo: checkout.dir, path });
+    const envFiles = git(
+      checkout.dir,
+      "ls-files",
+      "--others",
+      "--ignored",
+      "--exclude-standard",
+      "--",
+      ":(glob)**/.env*"
+    ).stdout.split("\n").filter(
+      (file) => /(^|\/)\.env[^/]*$/.test(file) && !/(^|\/)(node_modules|\.worktrees)\//.test(file)
+    );
+    for (const file of envFiles) {
+      if (existsSync2(join2(path, file))) continue;
+      mkdirSync2(dirname2(join2(path, file)), { recursive: true });
+      writeFileSync2(join2(path, file), readFileSync2(join2(checkout.dir, file)));
+    }
+    return { ...checkout, dir: path };
+  };
+  const dropBranch = (checkout, branch) => {
+    const entry = worktrees.find(
+      (tree) => tree.repo === checkout.dir && currentBranch(tree.path) === branch
+    );
+    if (entry) {
+      git(checkout.dir, "worktree", "remove", "--force", entry.path);
+      worktrees.splice(worktrees.indexOf(entry), 1);
+    }
+    git(checkout.dir, "branch", "-D", branch);
+  };
+  const defaultBranch = (cwd) => offDefaultBranch(cwd)?.main ?? currentBranch(cwd);
+  const reviewBranch = (checkout, packagePaths, moving) => {
+    const branch = moving.length > 0 ? adoptionBranch(moving) : freeBranch(checkout.dir, `train/ecosystem-sync-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`);
+    const base = defaultBranch(checkout.dir);
+    const opened = effect(
+      `create review branch ${branch} in ${checkout.name} (in a worktree; the checkout stays on ${base})`,
+      true,
+      () => {
+        const branchCheckout = worktree(checkout, branch);
+        for (const path of [...packagePaths, "bun.lock"]) {
+          if (existsSync2(join2(checkout.dir, path))) {
+            writeFileSync2(join2(branchCheckout.dir, path), readFileSync2(join2(checkout.dir, path)));
+          }
+        }
+        restore(checkout);
+        try {
+          relockAndCheck(branchCheckout, false);
+          const message = moving.length > 0 ? `chore: adopt ${moving.map((name) => `${name}@${manifest.candidates?.[name]}`).join(", ")}` : void 0;
+          if (!commitOwned(branchCheckout, packagePaths, true, message)) {
+            console.log(`\u2713 nothing to commit for ${checkout.name} after its re-lock`);
+            dropBranch(checkout, branch);
+            return false;
+          }
+        } catch (error) {
+          dropBranch(checkout, branch);
+          throw error;
+        }
+        followers.push({ checkout: branchCheckout, onBranch: true });
+        console.log(`committed on ${branch} for review; ${checkout.name} stays on ${base}`);
+        return true;
+      }
+    );
+    if (!opened) return;
+    reviewBranches.push({ dir: checkout.dir, branch, base });
+    if (moving.length > 0) {
+      waiting.push({ name: checkout.name, dir: checkout.dir, moving, state: "opened", branch });
+    }
+  };
+  const adopt = (checkout, moving) => {
+    const branch = adoptionBranch(moving);
+    const base = defaultBranch(checkout.dir);
+    const label = moving.map((name) => `${name}@${manifest.candidates?.[name]}`).join(", ");
+    const script = checkout.pkg.scripts?.["train:adopt"];
+    try {
+      effect(
+        `open ${branch} in ${checkout.name}: re-lock onto ${label}${script ? ", run train:adopt" : ""}, commit`,
+        void 0,
+        () => {
+          const branchCheckout = worktree(checkout, branch);
+          try {
+            bumpRanges(branchCheckout);
+            relockAndCheck(branchCheckout, false);
+            if (script && spawnSync2("bun", ["run", "train:adopt"], {
+              cwd: branchCheckout.dir,
+              stdio: "inherit"
+            }).status !== 0) {
+              console.log(
+                `\u26A0 train:adopt failed in ${checkout.name} \u2014 the PR needs work before it merges`
+              );
+            }
+            git(branchCheckout.dir, "add", "-A");
+            const commit = spawnSync2("git", ["commit", "-m", `chore: adopt ${label}`], {
+              cwd: branchCheckout.dir,
+              stdio: "inherit"
+            });
+            if (commit.status !== 0) {
+              throw new Abort(
+                `commit failed on ${branch} in ${checkout.name} (its hooks reject the adoption)`
+              );
+            }
+          } catch (error) {
+            dropBranch(checkout, branch);
+            throw error;
+          }
+          followers.push({ checkout: branchCheckout, onBranch: true });
+        }
+      );
+      reviewBranches.push({ dir: checkout.dir, branch, base });
+      waiting.push({ name: checkout.name, dir: checkout.dir, moving, state: "opened", branch });
+    } catch (error) {
+      if (!(error instanceof Abort)) throw error;
+      failed.push(checkout.name);
+      waiting.push({ name: checkout.name, dir: checkout.dir, moving, state: "failed" });
+      console.error(`\u2717 ${error.message} \u2014 adopt ${label} in ${checkout.name} by hand`);
+    }
+  };
+  const commitOwned = (checkout, packagePaths, changes, message = "chore: sync ecosystem deps to blessed set") => {
     if (dryRun && !changes) return false;
     return effect(`commit its package.json files + bun.lock in ${checkout.name}`, true, () => {
-      const tracked = [...packagePaths, "bun.lock"];
+      const tracked = [...packagePaths, "bun.lock"].filter(
+        (path) => existsSync2(join2(checkout.dir, path))
+      );
       const mutated = git(checkout.dir, "status", "--porcelain", "--", ...tracked);
       if (mutated.status !== 0 || mutated.stdout.trim().length === 0) return false;
       if (git(checkout.dir, "add", "--", ...tracked).status !== 0) {
         throw new Abort(`git add failed in ${checkout.name} \u2014 is bun.lock ignored?`);
       }
-      const commit = spawnSync2(
-        "git",
-        ["commit", "-m", "chore: sync ecosystem deps to blessed set"],
-        {
-          cwd: checkout.dir,
-          stdio: "inherit"
-        }
-      );
+      const commit = spawnSync2("git", ["commit", "-m", message], {
+        cwd: checkout.dir,
+        stdio: "inherit"
+      });
       if (commit.status !== 0) throw new Abort(`commit failed in ${checkout.name}`);
       return true;
     });
@@ -1350,8 +1567,7 @@ if (command === "train") {
 \u2550 ${lane2} lane: ${checkouts.map((checkout) => checkout.name).join(" \u2192 ") || "(none)"}`
     );
     const section = laneSection(manifest, lane2);
-    const before = { ...section };
-    const laneBlessed = [];
+    const laneRecorded = [];
     try {
       if (missing.length > 0) {
         throw new Abort(
@@ -1370,7 +1586,6 @@ if (command === "train") {
           skipped.push(checkout.name);
           continue;
         }
-        const { inspection, bumped, staleLock } = bumpRanges(checkout);
         const releases = checkout.packages.map((entry) => {
           const local = JSON.parse(readFileSync2(join2(checkout.dir, entry.path), "utf8")).version ?? "0.0.0";
           const remote = npmLatest(entry.name);
@@ -1386,47 +1601,50 @@ if (command === "train") {
           skipped.push(checkout.name);
           continue;
         }
+        const moving = movesOf(checkout);
+        if (pendingAdoption(checkout, moving)) continue;
+        const { inspection, bumped, staleLock } = bumpRanges(checkout);
         const relocked = bumped || staleLock || releases.some((release) => release.ahead);
-        if (relocked) relockAndCheck(checkout);
-        if (commitOwned(checkout, inspection.packagePaths, relocked)) committed.add(checkout.dir);
-        followers.push(checkout);
-        for (const { entry, local, remote, ahead } of releases) {
-          if (ahead) {
+        try {
+          if (relocked) relockAndCheck(checkout);
+          if (commitOwned(checkout, inspection.packagePaths, relocked)) committed.add(checkout.dir);
+        } catch (error) {
+          if (!(error instanceof Abort)) throw error;
+          restore(checkout);
+          if (!(error instanceof CheckFailed) || moving.length === 0) throw error;
+          console.log(`\u2717 ${error.message} against the candidates \u2014 it adopts them on a branch`);
+          walked.add(checkout.dir);
+          adopt(checkout, moving);
+          continue;
+        }
+        walked.add(checkout.dir);
+        followers.push({ checkout, onBranch: false });
+        for (const { entry, local, remote, ahead: ahead2 } of releases) {
+          if (ahead2) {
             publish(checkout, entry, local, remote);
           } else if (section[entry.name] === local) {
             console.log(`\u2713 ${entry.name}@${local} already on npm and blessed`);
             continue;
+          } else if (manifest.candidates?.[entry.name] === local) {
+            console.log(`\u2713 ${entry.name}@${local} already on npm and a candidate`);
+            continue;
           } else {
-            console.log(`\u2713 ${entry.name}@${local} already on npm \u2014 blessing it`);
+            console.log(`\u2713 ${entry.name}@${local} already on npm \u2014 recording it as a candidate`);
           }
-          section[entry.name] = local;
-          laneBlessed.push(`${entry.name}@${local}`);
+          manifest.candidates = { ...manifest.candidates, [entry.name]: local };
+          laneRecorded.push(`${entry.name}@${local}`);
         }
       }
-      if (laneBlessed.length > 0) {
-        effect(
-          `bless ${laneBlessed.join(", ")} in versions.json`,
-          void 0,
-          () => writeManifest(manifest)
-        );
-        bomDirty = true;
-        blessed.push(...laneBlessed);
-      }
       console.log(
-        `${lane2} lane blessed: ${laneBlessed.length === 0 ? "nothing new" : laneBlessed.join(", ")}`
+        `${lane2} lane candidates: ${laneRecorded.length === 0 ? "nothing new" : laneRecorded.join(", ")}`
       );
     } catch (error) {
       if (!(error instanceof Abort)) throw error;
-      for (const name of Object.keys(section)) delete section[name];
-      Object.assign(section, before);
+      failedLanes.add(lane2);
       failed.push(`${lane2} lane`);
-      console.error(`\u2717 ${error.message} \u2014 ${lane2} lane stopped; its BOM entries are unchanged`);
-      if (laneBlessed.length > 0) {
-        console.error(
-          `  published but not blessed: ${laneBlessed.join(", ")} \u2014 the next train blesses them`
-        );
-      }
+      console.error(`\u2717 ${error.message} \u2014 ${lane2} lane stopped; none of its candidates is blessed`);
     }
+    recorded.push(...laneRecorded);
   }
   if (plan.consumers.length > 0 || plan.missingConsumers.length > 0) {
     console.log(
@@ -1449,39 +1667,97 @@ if (command === "train") {
       skipped.push(checkout.name);
       continue;
     }
+    const moving = movesOf(checkout);
+    if (pendingAdoption(checkout, moving)) continue;
+    const { inspection, bumped, staleLock } = bumpRanges(checkout);
+    if (!bumped && !staleLock) {
+      walked.add(checkout.dir);
+      console.log("\u2713 already on the blessed set");
+      continue;
+    }
     try {
-      const { inspection, bumped, staleLock } = bumpRanges(checkout);
-      if (!bumped && !staleLock) {
-        console.log("\u2713 already on the blessed set");
-        continue;
-      }
       relockAndCheck(checkout);
-      const base = offDefaultBranch(checkout.dir)?.main ?? currentBranch(checkout.dir);
-      const branch = freeBranch(
-        checkout.dir,
-        `train/ecosystem-sync-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`
-      );
-      const switched = effect(
-        `create review branch ${branch} in ${checkout.name}`,
-        true,
-        () => git(checkout.dir, "switch", "-c", branch).status === 0
-      );
-      if (!switched) throw new Abort(`could not create ${branch} in ${checkout.name}`);
-      followers.push(checkout);
-      if (commitOwned(checkout, inspection.packagePaths, true)) {
-        reviewBranches.push({ dir: checkout.dir, branch, base });
-        if (!dryRun) {
-          console.log(`committed on ${branch} for review; the checkout stays on it until merged`);
-        }
-      }
+      reviewBranch(checkout, inspection.packagePaths, moving);
+      walked.add(checkout.dir);
     } catch (error) {
       if (!(error instanceof Abort)) throw error;
+      restore(checkout);
+      if (error instanceof CheckFailed && moving.length > 0) {
+        console.log(`\u2717 ${error.message} against the candidates \u2014 it adopts them on a branch`);
+        walked.add(checkout.dir);
+        adopt(checkout, moving);
+        continue;
+      }
       failed.push(checkout.name);
-      console.error(`\u2717 ${error.message} \u2014 its working tree is left as is for inspection`);
+      console.error(`\u2717 ${error.message} \u2014 its checkout is back on its default branch`);
+    }
+  }
+  const candidateNames = Object.keys(manifest.candidates ?? {});
+  if (candidateNames.length > 0) {
+    const everything = trainPlan(dir, manifest, LANES);
+    for (const checkout of [
+      ...everything.lanes.flatMap((entry) => entry.checkouts),
+      ...everything.consumers
+    ]) {
+      if (walked.has(checkout.dir)) continue;
+      const declared = declaredDependencies(checkout.dir);
+      const moving = candidateNames.filter((name) => declared.has(name));
+      if (moving.length > 0) {
+        waiting.push({ name: checkout.name, dir: checkout.dir, moving, state: "unverified" });
+      }
+    }
+    for (const repo of [
+      ...everything.missingConsumers,
+      ...everything.ambiguousConsumers.map((entry) => entry.key)
+    ]) {
+      const consumed = manifest.consumers?.[repo]?.lanes ?? [];
+      const moving = candidateNames.filter((name) => {
+        const lane2 = laneOf(manifest, name);
+        return !!lane2 && consumed.includes(lane2);
+      });
+      if (moving.length > 0) waiting.push({ name: repo, dir, moving, state: "unverified" });
     }
   }
+  const held = new Set(waiting.flatMap((entry) => entry.moving));
+  const promotable = candidateNames.filter((name) => {
+    const lane2 = laneOf(manifest, name);
+    return !!lane2 && !failedLanes.has(lane2) && !held.has(name);
+  });
+  const promoted = promoteCandidates(manifest, promotable);
+  const bomDirty = recorded.length > 0 || promoted.length > 0;
+  if (bomDirty) {
+    effect(
+      "write the candidates and blessings to versions.json",
+      void 0,
+      () => writeManifest(manifest)
+    );
+  }
+  const why = {
+    opened: "opened this run",
+    unmerged: "waiting for its PR to merge",
+    unpushed: "committed but never pushed",
+    failed: "the train could not commit it \u2014 adopt by hand",
+    unverified: "not verified this run"
+  };
   console.log(`
-blessed: ${blessed.length === 0 ? "nothing" : blessed.join(", ")}`);
+blessed: ${promoted.length === 0 ? "nothing" : promoted.join(", ")}`);
+  const candidates = Object.entries(manifest.candidates ?? {});
+  if (candidates.length > 0) {
+    console.log("candidates (check accepts them; not yet blessed):");
+    for (const [name, version] of candidates) {
+      const on = waiting.filter((entry) => entry.moving.includes(name)).map((entry) => `${entry.name} (${entry.branch ?? why[entry.state]})`);
+      console.log(`  ${name}@${version}${on.length === 0 ? "" : ` \u2014 waiting on ${on.join(", ")}`}`);
+    }
+  }
+  if (waiting.length > 0) {
+    console.log("pending (merge each adoption PR, then run the train again to bless):");
+    for (const entry of waiting) {
+      const url = entry.state === "unmerged" && !dryRun && entry.branch ? prUrl(entry.dir, entry.branch) : null;
+      console.log(
+        `  ${entry.name}: ${entry.branch ? `${entry.branch} \u2014 ` : ""}${why[entry.state]}${url ? ` ${url}` : ""}`
+      );
+    }
+  }
   if (skipped.length > 0) console.log(`skipped: ${skipped.join(", ")}`);
   if (failed.length > 0) console.log(`failed: ${failed.join(", ")}`);
   const remoteVersion = npmLatest("@inixiative/config");
@@ -1520,26 +1796,25 @@ blessed: ${blessed.length === 0 ? "nothing" : blessed.join(", ")}`);
         process.exit(1);
       }
     });
-    effect(
-      `commit "chore: bless ${blessed.join(", ")} \u2014 ${version}" in @inixiative/config`,
-      void 0,
-      () => {
-        spawnSync2("git", ["add", "--", "package.json", "versions.json", "test/fixtures"], {
-          cwd: packageRoot
-        });
-        if (spawnSync2("git", ["diff", "--cached", "--quiet"], { cwd: packageRoot }).status === 0)
-          return;
-        const commit = spawnSync2(
-          "git",
-          ["commit", "-m", `chore: bless ${blessed.join(", ")} \u2014 ${version}`],
-          { cwd: packageRoot, stdio: "inherit" }
-        );
-        if (commit.status !== 0) {
-          console.error("\u2717 commit failed in @inixiative/config \u2014 aborting before publish");
-          process.exit(1);
-        }
+    const message = `chore: ${[
+      promoted.length > 0 ? `bless ${promoted.join(", ")}` : "",
+      recorded.length > 0 ? `candidate ${recorded.join(", ")}` : ""
+    ].filter(Boolean).join("; ") || "release"} \u2014 ${version}`;
+    effect(`commit "${message}" in @inixiative/config`, void 0, () => {
+      spawnSync2("git", ["add", "--", "package.json", "versions.json", "test/fixtures"], {
+        cwd: packageRoot
+      });
+      if (spawnSync2("git", ["diff", "--cached", "--quiet"], { cwd: packageRoot }).status === 0)
+        return;
+      const commit = spawnSync2("git", ["commit", "-m", message], {
+        cwd: packageRoot,
+        stdio: "inherit"
+      });
+      if (commit.status !== 0) {
+        console.error("\u2717 commit failed in @inixiative/config \u2014 aborting before publish");
+        process.exit(1);
       }
-    );
+    });
     effect(`publish @inixiative/config@${version} to npm`, void 0, () => {
       const publish2 = spawnSync2("npm", ["publish"], { cwd: packageRoot, stdio: "inherit" });
       if (publish2.status !== 0 || !servedByRegistry("@inixiative/config", version)) {
@@ -1551,12 +1826,12 @@ blessed: ${blessed.length === 0 ? "nothing" : blessed.join(", ")}`);
     committed.add(packageRoot);
     if (followers.length > 0) console.log(`
 \u2550 re-lock onto @inixiative/config@${version}`);
-    for (const checkout of followers) {
+    for (const { checkout, onBranch } of followers) {
       try {
         const { inspection, bumped, staleLock } = bumpRanges(checkout);
         if (!bumped && !staleLock) continue;
         relockAndCheck(checkout, false);
-        if (commitOwned(checkout, inspection.packagePaths, true) && !checkout.consumer)
+        if (commitOwned(checkout, inspection.packagePaths, true) && !onBranch)
           committed.add(checkout.dir);
         if (!dryRun) console.log(`\u2713 ${checkout.name} locked to @inixiative/config@${version}`);
       } catch (error) {
@@ -1603,6 +1878,13 @@ dry run complete \u2014 a real train would commit in ${committed.size} repo(s) a
   }
   process.exit(failed.length > 0 ? 1 : 0);
 }
+function prUrl(cwd, branch) {
+  const view = spawnSync2("gh", ["pr", "view", branch, "--json", "url", "--jq", ".url"], {
+    cwd,
+    encoding: "utf8"
+  });
+  return view.status === 0 ? view.stdout.trim() || null : null;
+}
 function currentBranch(cwd) {
   return git(cwd, "rev-parse", "--abbrev-ref", "HEAD").stdout.trim();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/config",
-  "version": "0.5.80",
+  "version": "0.5.82",
   "description": "Shared toolchain for the inixiative ecosystem: tsconfig/biome/tsup presets, a version manifest (BOM), and a sync/check CLI",
   "type": "module",
   "license": "MIT",

package/versions.json

@@ -13,7 +13,7 @@
     "@types/bun"
   ],
   "ecosystem": {
-    "@inixiative/config": "0.5.80",
+    "@inixiative/config": "0.5.82",
     "@inixiative/json-rules": "3.5.4",
     "@inixiative/permissions": "0.4.0",
     "@inixiative/transitions": "0.5.0",
@@ -24,7 +24,7 @@
   },
   "agentic": {
     "@inixiative/signet": "0.4.0",
-    "@inixiative/archive": "0.18.0",
+    "@inixiative/archive": "0.19.0",
     "@inixiative/agent-session": "0.6.3",
     "@inixiative/foundry-core": "0.5.1",
     "@inixiative/foundry": "0.5.3",
@@ -48,5 +48,8 @@
         "agentic"
       ]
     }
+  },
+  "candidates": {
+    "@inixiative/agent-session": "0.6.4"
   }
 }