@omnitron-dev/omnitron 0.2.0 → 0.3.1

package/dist/services/bundle-builder.js

@@ -0,0 +1,1159 @@
+/**
+ * Building the bundle the planner describes.
+ *
+ * `local-bundle.ts` decides what travels; this puts it on disk. Kept apart
+ * because the decision is where the mistakes live and the decision is pure —
+ * this half runs `pnpm pack` and writes files, and can only be checked by
+ * doing it.
+ *
+ * The layout:
+ *
+ *     <out>/package.json        root manifest: file: deps + overrides
+ *     <out>/dist/               the built daemon
+ *     <out>/webapp/dist/        the console
+ *     <out>/vendor/*.tgz        every workspace package, packed
+ *     <out>/BUNDLE.json         what this is, and what it was built from
+ *
+ * `node_modules` is deliberately absent. It is the one thing that must NOT
+ * travel: a tree installed here carries `@esbuild/darwin-arm64` and no
+ * `linux-x64`, and the target is the only machine that knows what it is.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolvePnpm } from '../shared/pnpm.js';
+import { readBuildStamp } from '../shared/build-stamp.js';
+import { planBundle, bundleRootManifest, isLinkRange, localVersion, VENDOR_DIR, } from './local-bundle.js';
+const exec = promisify(execFile);
+/**
+ * Find the repository root from a directory inside it.
+ *
+ * `process.cwd()` is where the operator was standing, and for a command run
+ * from `apps/omnitron` that is two levels below the packages it needs to
+ * bundle. Measured: `fleet upgrade` from the package directory reported
+ * "@omnitron-dev/omnitron is not a package in this workspace" — true of the
+ * directory it was given, and useless about the mistake.
+ *
+ * `pnpm-workspace.yaml` is the marker, because it is what defines the
+ * workspace this file reads. Null rather than a guess when there is none.
+ */
+export function findWorkspaceRoot(from) {
+    let dir = path.resolve(from);
+    for (;;) {
+        if (fs.existsSync(path.join(dir, 'pnpm-workspace.yaml')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Why `fleet upgrade` must not build from here — or null.
+ *
+ * Three refusals, each naming the place rather than a package. No workspace
+ * above the directory. A workspace, but somebody else's: run from
+ * `~/projects/examples/sample`, the command found sample's root and failed inside the
+ * bundler with «@omnitron-dev/omnitron is not a package in this workspace»,
+ * which reads as a broken omnitron checkout (`planBundle` keeps that refusal
+ * for callers that arrive some other way). And a tree with uncommitted
+ * changes: the version a node reports names the commit, so a bundle built
+ * from a dirty tree is a node reporting a commit that is not what it runs —
+ * the record that outlives everyone who knew. That one is lifted only by
+ * `--allow-dirty`, as for `stack start`.
+ */
+export function upgradeWorkspaceRefusal(input) {
+    if (!input.root) {
+        return `This command builds omnitron from source, and there is no workspace above ${input.cwd}. Run it from inside the omnitron repository.`;
+    }
+    if (!input.hasOmnitron) {
+        return (`This command builds omnitron from source, and ${input.root} is a workspace — but not omnitron's: ` +
+            `it holds no ${OMNITRON_PACKAGE}. Run it from inside the omnitron repository.`);
+    }
+    if (input.dirty && !input.allowDirty) {
+        return (`The omnitron working tree at ${input.root} has uncommitted changes, and a node would report a version ` +
+            `naming a commit that is not what it runs. Commit or stash them, or pass --allow-dirty to ship this disk deliberately.`);
+    }
+    return null;
+}
+/**
+ * Read every workspace package's manifest.
+ *
+ * The root is resolved to an absolute path first, and every directory
+ * recorded below is absolute too. `pnpm --dir` resolves a relative path
+ * against ITS OWN working directory, not against the caller's — so a
+ * `workspaceRoot` of `../..` produced `/Users/taaliman/projects/luxquant/
+ * packages`, two levels above where it meant, and the error named a
+ * directory nobody had written down. Paths that cross a process boundary are
+ * absolute.
+ */
+/**
+ * Read several workspace roots into one map.
+ *
+ * An app can depend on packages of another checkout — sample declares every
+ * omni package as `link:/Users/…/omni/packages/<name>` — and a planner given
+ * only the app's own workspace refuses those as missing, which is true of
+ * that workspace and useless about the artifact.
+ *
+ * Earlier roots win a name collision: the first root is the one whose package
+ * is being built, and a package it defines is the one it meant.
+ */
+export function readWorkspaces(roots) {
+    const merged = new Map();
+    for (const root of roots) {
+        for (const [name, manifest] of readWorkspace(root)) {
+            if (!merged.has(name))
+                merged.set(name, manifest);
+        }
+    }
+    return merged;
+}
+/**
+ * Every workspace root a manifest's `link:` dependencies are INSTALLED from.
+ *
+ * Asked of the installed tree first — `<packageDir>/node_modules/<name>` is
+ * the link pnpm made, and it is what the package's code actually loads — and
+ * of the declared range only when nothing is installed. The two differ where
+ * it matters: sample declares every omni package as an ABSOLUTE
+ * `link:/Users/…/omni/…`, while its lockfile records them relative, and a
+ * release is built in a layout where the relative links land on a clean
+ * clone of omni (`release/layout.ts`). Reading the declaration, the release
+ * builder's packer found the DEVELOPER'S omni instead: on 2026-09-22 both
+ * releases of the day vendored `@omnitron-dev/omnitron` from the working tree
+ * — «rebuilding @omnitron-dev/omnitron — src/services/node-upgrade.service.ts
+ * is newer than anything in dist», a file edited after the clone was made —
+ * and rebuilt the running daemon's own `dist` in passing, uncommitted edits
+ * of other sessions included. The install had been checked to resolve inside
+ * the clone (98 of 98 links); the packer never asked it.
+ *
+ * A relative range is resolved against the package's directory, as pnpm
+ * resolves it — not against whatever directory this process runs in.
+ */
+export function linkedWorkspaceRoots(manifest, packageDir) {
+    const roots = [];
+    for (const group of [manifest.dependencies, manifest.optionalDependencies]) {
+        for (const [name, range] of Object.entries(group ?? {})) {
+            if (!isLinkRange(range))
+                continue;
+            let target = null;
+            if (packageDir) {
+                try {
+                    target = fs.realpathSync(path.join(packageDir, 'node_modules', name));
+                }
+                catch {
+                    // Not installed: the declaration is all there is.
+                }
+            }
+            target ??= path.resolve(packageDir ?? process.cwd(), range.slice('link:'.length));
+            const root = findWorkspaceRoot(target);
+            if (root && !roots.includes(root))
+                roots.push(root);
+        }
+    }
+    return roots;
+}
+export function readWorkspace(workspaceRootInput) {
+    const workspaceRoot = path.resolve(workspaceRootInput);
+    const found = new Map();
+    for (const group of ['packages', 'apps']) {
+        const dir = path.join(workspaceRoot, group);
+        if (!fs.existsSync(dir))
+            continue;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const manifestPath = path.join(dir, entry.name, 'package.json');
+            if (!fs.existsSync(manifestPath))
+                continue;
+            try {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+                if (!manifest.name)
+                    continue;
+                manifest.__dir = path.join(dir, entry.name);
+                found.set(manifest.name, manifest);
+            }
+            catch {
+                // A manifest that does not parse is not a workspace package. The
+                // planner refuses later if something needed it.
+            }
+        }
+    }
+    return found;
+}
+/**
+ * Where packed tarballs are kept for the rest of a run.
+ *
+ * One directory per process, under the system temp dir. It is not cleaned up
+ * here: the cache is handed in by the caller and lives exactly as long as the
+ * caller keeps the map, and a directory of tarballs in `TMPDIR` is what the
+ * operating system already knows how to reclaim.
+ */
+function cacheDir() {
+    const dir = path.join(os.tmpdir(), 'omnitron-pack-cache');
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/**
+ * Where a packed workspace package is kept, named by what is in it.
+ *
+ * The version is in the name because two versions of one package are two
+ * packages; the content hash is in it because during development a version
+ * stands still for weeks while the code under it moves, and a cache keyed on
+ * the version alone would hand a deployment last week's package under this
+ * week's number. Nothing has to be invalidated: a package that changed has a
+ * different name here and is packed.
+ */
+export function packedCachePath(cacheRoot, name, version, contentHash) {
+    const flat = name.replace(/^@/, '').replace(/\//g, '-');
+    return path.join(cacheRoot, `${flat}-${version}-${contentHash.slice(0, 16)}.tgz`);
+}
+/**
+ * Remove every incremental-build record a package keeps.
+ *
+ * `tsc` trusts `tsBuildInfoFile`: if the inputs have not changed since that
+ * record was written, it emits nothing and exits zero. The record is written
+ * by whatever machine last built, and a `build` script of `rm -rf dist && tsc`
+ * removes the OUTPUT while leaving the record saying the output is current —
+ * so the build succeeds and `dist` stays exactly as stale as it was.
+ *
+ * Measured on `@sample/bitcoin-rpc`: `src/errors.ts` dated 2026-09-16,
+ * `dist/errors.js` dated 2026-09-10, and `pnpm build` leaving it at
+ * 2026-09-10. Six days of source changes that the build refused to emit,
+ * silently, with a zero exit code — which is why the staleness guard above
+ * has to re-check AFTER building rather than trusting the build.
+ *
+ * Every spelling, because the path is a per-package choice: the root, `dist`,
+ * and `node_modules/.tmp`, which is where a `tsconfig.build.json` in this
+ * workspace tends to put it.
+ */
+export function clearBuildInfo(packageDir) {
+    const candidates = [
+        'tsconfig.tsbuildinfo',
+        '.tsbuildinfo',
+        'tsconfig.build.tsbuildinfo',
+        'dist/tsconfig.tsbuildinfo',
+        'dist/.tsbuildinfo',
+        'dist/tsconfig.build.tsbuildinfo',
+    ];
+    for (const rel of candidates) {
+        try {
+            fs.rmSync(path.join(packageDir, rel), { force: true });
+        }
+        catch {
+            // Not there, or not ours to remove: the build is what reports.
+        }
+    }
+    // `node_modules/.tmp` is a directory of them, one per tsconfig.
+    const tmp = path.join(packageDir, 'node_modules', '.tmp');
+    try {
+        for (const name of fs.readdirSync(tmp)) {
+            if (name.endsWith('.tsbuildinfo'))
+                fs.rmSync(path.join(tmp, name), { force: true });
+        }
+    }
+    catch {
+        // No such directory is the common case.
+    }
+}
+/**
+ * The most recently modified file under a directory, by a filter.
+ *
+ * `node_modules` and `.git` are skipped: neither says anything about whether
+ * this project's own output is current, and walking them turns a handful of
+ * `stat` calls into tens of thousands.
+ */
+function newestFile(dir, filter) {
+    let best = null;
+    const walk = (d) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(d, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name === '.git')
+                    continue;
+                walk(full);
+                continue;
+            }
+            if (!filter(entry.name))
+                continue;
+            const mtime = fs.statSync(full).mtimeMs;
+            if (!best || mtime > best.mtime)
+                best = { file: full, mtime };
+        }
+    };
+    walk(dir);
+    return best;
+}
+/**
+ * Whether a built frontend is older than the sources it was built from.
+ *
+ * The gateway serves `apps/portal/dist` and the deployment ships it exactly
+ * as it finds it. Measured on the test stack: the `index.html` on the node
+ * was built on 2026-09-10 and **879 source files were newer than it** — so
+ * the "test portal", the thing the whole deployment exists to put in front of
+ * someone, was ten days behind the tree it was supposedly testing. Nothing
+ * said so, because nothing looked.
+ *
+ * Same reasoning as `staleDist` and a different shape: a frontend has no
+ * manifest pointing at its output, so the caller names both directories.
+ *
+ * **A frontend's sources are not all under its own `src`.** The portal
+ * resolves several workspace packages from source through Vite aliases, two
+ * of them in a DIFFERENT repository (`@omnitron-dev/prism`,
+ * `@omnitron-dev/netron-browser`), so a change confined to the design system
+ * left `apps/portal/src` untouched, this check said «current», and the
+ * deployment shipped yesterday's bundle. Measured 2026-09-21: all ten «behind
+ * its sources» entries in the daemon log name files under `apps/portal/src`,
+ * not one came from prism, while prism changed on several of those days.
+ *
+ * So the sources are the frontend's own `src` PLUS the `src` of every
+ * dependency that resolves outside `node_modules` — which is what a workspace
+ * link is. Under pnpm every dependency is a symlink (57 of 57 for the
+ * portal), so the symlink itself says nothing; the real path does, and seven
+ * of the portal's dependencies live outside `node_modules`.
+ *
+ * The answer names the directories it watched, because the caller logs it:
+ * a reader must be able to tell «no linked sources» from «never looked».
+ *
+ * **Every linked package counts, even one the frontend imports only for its
+ * types.** Measured on the portal: of its seven, `@sample/geo` is type-only (3
+ * imports, all `import type`) and contributes nothing to the bundle, so
+ * watching it can cost a rebuild nobody needed. Telling types from values
+ * statically is an import-parsing heuristic, and the same counting done twice
+ * here gave 47 value-imports and then 8 — the difference being multi-line
+ * `import type {` blocks whose closing line looks like a value import. The
+ * asymmetry decides it: a false rebuild costs a couple of minutes of CPU, a
+ * missed one puts yesterday's portal in front of a person.
+ */
+export function staleBuild(srcDir, buildDir) {
+    if (!fs.existsSync(buildDir))
+        return 'there is no build at all';
+    if (!fs.existsSync(srcDir))
+        return null;
+    const isSource = (n) => /\.(ts|tsx|js|jsx|css|scss|html|json|svg|png|jpg|webp)$/.test(n) && !/\.(spec|test)\.[jt]sx?$/.test(n);
+    const watched = [srcDir, ...linkedSourceDirs(path.dirname(srcDir))];
+    const names = watched.map((d) => path.basename(path.dirname(d)) + '/' + path.basename(d)).join(', ');
+    const newestBuilt = newestFile(buildDir, () => true);
+    if (!newestBuilt)
+        return 'the build directory is empty';
+    let newestSource = null;
+    for (const dir of watched) {
+        const found = newestFile(dir, isSource);
+        if (found && (!newestSource || found.mtime > newestSource.mtime)) {
+            newestSource = { ...found, root: dir };
+        }
+    }
+    if (!newestSource)
+        return null;
+    if (newestSource.mtime <= newestBuilt.mtime)
+        return null;
+    const count = watched.reduce((n, dir) => n + countNewerThan(dir, isSource, newestBuilt.mtime), 0);
+    const where = path.relative(newestSource.root, newestSource.file);
+    return `${count} source file${count === 1 ? '' : 's'} newer than the build, the most recent being ${where} (watched: ${names})`;
+}
+/**
+ * The `src` of every dependency that lives outside `node_modules`.
+ *
+ * That is what a workspace link is, and it is the only reliable tell: pnpm
+ * makes EVERY dependency a symlink into its store, so `isSymbolicLink()`
+ * matches all of them. What separates a package being developed here from one
+ * that was installed is where the link lands.
+ *
+ * A package without a `src/` contributes nothing to look at and is skipped,
+ * which also drops anything vendored as built output.
+ */
+/**
+ * The `src` of every dependency that resolves to a working package rather
+ * than an installed copy — what this bundle is actually built FROM.
+ *
+ * Exported because two questions need the same answer and neither may
+ * re-derive it: whether the build is stale, and whether the trees it reads
+ * are the commits they claim.
+ */
+export function linkedSourceDirs(pkgDir) {
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    const names = Object.keys({ ...manifest.dependencies, ...manifest.devDependencies });
+    const dirs = [];
+    for (const name of names) {
+        const linked = path.join(pkgDir, 'node_modules', ...name.split('/'));
+        let real;
+        try {
+            real = fs.realpathSync(linked);
+        }
+        catch {
+            continue;
+        }
+        if (real.includes(`${path.sep}node_modules${path.sep}`))
+            continue;
+        const src = path.join(real, 'src');
+        if (fs.existsSync(src))
+            dirs.push(src);
+    }
+    return dirs;
+}
+/** How many files under `dir` are newer than `mtime` — for a message worth reading. */
+function countNewerThan(dir, filter, mtime) {
+    let n = 0;
+    const walk = (d) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(d, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name === '.git')
+                    continue;
+                walk(full);
+                continue;
+            }
+            if (filter(entry.name) && fs.statSync(full).mtimeMs > mtime)
+                n += 1;
+        }
+    };
+    walk(dir);
+    return n;
+}
+/**
+ * Whether a package's shipped `dist` is older than its sources.
+ *
+ * Only asked of packages that actually ship one — a package whose manifest
+ * points at `src` is consumed as TypeScript by whatever transpiles it, and
+ * has no `dist` to be stale. `publishConfig` is consulted because that is
+ * what `pnpm pack` applies, so the question is about the file the TARBALL
+ * will name, not the one this working tree uses.
+ *
+ * Returns a sentence naming the newest source file, or null when there is
+ * nothing to say — the message is the useful part, since "rebuild it" is
+ * only actionable once you know which package and why.
+ */
+export function staleDist(packageDir) {
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const effective = JSON.stringify({
+        main: manifest.publishConfig?.main ?? manifest.main,
+        exports: manifest.publishConfig?.exports ?? manifest.exports,
+    });
+    if (!effective.includes('dist/'))
+        return null;
+    const dist = path.join(packageDir, 'dist');
+    if (!fs.existsSync(dist))
+        return 'there is no dist at all';
+    const src = path.join(packageDir, 'src');
+    if (!fs.existsSync(src))
+        return null;
+    // Tests are not shipped and their timestamps are not evidence about `dist`.
+    const newestSource = newestFile(src, (n) => n.endsWith('.ts') && !/\.(spec|test)\.ts$/.test(n));
+    const newestBuilt = newestFile(dist, (n) => n.endsWith('.js'));
+    if (!newestSource)
+        return null;
+    if (!newestBuilt)
+        return 'dist holds no compiled JavaScript';
+    if (newestSource.mtime <= newestBuilt.mtime)
+        return null;
+    return `${path.relative(packageDir, newestSource.file)} is newer than anything in dist`;
+}
+/** Where a workspace package lives, as recorded by `readWorkspace`. */
+function directoryOf(manifest) {
+    const dir = manifest.__dir;
+    if (!dir)
+        throw new Error(`No directory recorded for ${manifest.name}`);
+    return dir;
+}
+/** `git rev-parse HEAD` and whether the tree is clean. */
+export async function describeTree(cwd) {
+    let commit = '';
+    let dirty = false;
+    try {
+        const { stdout } = await exec('git', ['rev-parse', 'HEAD'], { cwd });
+        commit = stdout.trim();
+    }
+    catch {
+        // Not a repository, or no commits. `localVersion` says `nocommit`.
+    }
+    try {
+        const { stdout } = await exec('git', ['status', '--porcelain'], { cwd });
+        dirty = stdout.trim().length > 0;
+    }
+    catch {
+        // Same.
+    }
+    return { commit, dirty };
+}
+/**
+ * Build the bundle.
+ *
+ * Packs into a temporary sibling and renames at the end, so `<out>` either
+ * does not exist or holds a complete bundle. A half-built one is worse than
+ * none: the transfer step has no way to tell it from a finished one, and the
+ * failure lands on the node.
+ */
+export async function buildBundle(options) {
+    const workspaceRoot = path.resolve(options.workspaceRoot);
+    const workspace = readWorkspaces([workspaceRoot, ...(options.additionalWorkspaceRoots ?? [])]);
+    const plan = planBundle(options.rootPackage, workspace);
+    if (plan.refusal)
+        throw new Error(plan.refusal);
+    const tree = await describeTree(workspaceRoot);
+    const version = localVersion(plan.root.version, tree.commit, new Date());
+    const outDir = path.resolve(options.outDir);
+    const staging = `${outDir}.building`;
+    fs.rmSync(staging, { recursive: true, force: true });
+    fs.mkdirSync(path.join(staging, VENDOR_DIR), { recursive: true });
+    try {
+        const rootDir = directoryOf(workspace.get(options.rootPackage));
+        // The package's own built output. Copied rather than packed: `npm pack`
+        // of the root would produce a tarball we would immediately unpack, and
+        // the bundle's root IS the install directory.
+        for (const rel of options.include ?? ['dist', 'webapp/dist', 'data', 'README.md']) {
+            const from = path.join(rootDir, rel);
+            if (!fs.existsSync(from))
+                continue;
+            const to = path.join(staging, rel);
+            fs.mkdirSync(path.dirname(to), { recursive: true });
+            fs.cpSync(from, to, { recursive: true });
+        }
+        // A package that ships `dist` must have a `dist` that is not older than
+        // its sources.
+        //
+        // `pnpm pack` packs what is on disk. Six sample packages declare
+        // `publishConfig.main = dist/…` — because a tarball cannot ship
+        // TypeScript and expect `node` to read it — and NOTHING in the workspace
+        // imported that `dist`, so it had been drifting since whenever it was
+        // last built by hand. Measured the first time one shipped:
+        //
+        //     The requested module '@sample/titan-kit' does not provide an export
+        //     named 'DEFAULT_PAGE_SIZE'
+        //
+        // — a constant that had been in `src` for months and in `dist` never.
+        // Worse than a missing package, because it looks like an API mistake in
+        // the code that imports it.
+        //
+        // Built rather than refused: the deployment already builds the app it is
+        // deploying, and a dependency of that app is the same question. A build
+        // that fails still stops the artifact.
+        for (const vendored of plan.vendored) {
+            const dir = directoryOf(workspace.get(vendored.name));
+            const stale = staleDist(dir);
+            if (!stale)
+                continue;
+            options.logger?.info(`rebuilding ${vendored.name} — ${stale}`);
+            // Without this the build exits zero and changes nothing: see
+            // `clearBuildInfo`. It is what made this guard's own rebuild useless
+            // on the first package that needed it.
+            clearBuildInfo(dir);
+            try {
+                await exec(resolvePnpm(), ['--dir', dir, 'run', 'build'], {
+                    cwd: workspaceRoot,
+                    maxBuffer: 16 * 1024 * 1024,
+                });
+            }
+            catch (err) {
+                throw new Error(`${vendored.name} ships 'dist' and its 'dist' is out of date (${stale}), and rebuilding it failed: ` +
+                    `${err.message.slice(0, 300)}`, { cause: err });
+            }
+            // What this package hashed to a moment ago is no longer what it is:
+            // the build decision and the packing step both read that number.
+            options.packCache?.delete(dir);
+            const still = staleDist(dir);
+            if (still) {
+                throw new Error(`${vendored.name} ships 'dist' and its 'dist' is still out of date after a build (${still}). ` +
+                    `Packing it would put months-old compiled code on a node under a current version number.`);
+            }
+        }
+        // Every workspace package, packed where npm can install it from.
+        for (const vendored of plan.vendored) {
+            const produced = path.join(staging, VENDOR_DIR, vendored.tarball);
+            const dir = directoryOf(workspace.get(vendored.name));
+            // What is in the package decides whether it is packed again — never
+            // when it was last packed. `pnpm pack` resolves `workspace:*` to the
+            // concrete version and rebuilds that object in the order it resolved
+            // them, so packing one unchanged package twice produced two tarballs
+            // differing in the ORDER of `peerDependencies` and nothing else. Every
+            // bundle was therefore a new bundle, and a deployment that skips what
+            // the node already has could never skip anything.
+            let contentHash = options.packCache?.get(dir);
+            if (!contentHash) {
+                contentHash = await bundleChecksum(dir, { skip: withoutNodeModules });
+                options.packCache?.set(dir, contentHash);
+            }
+            const kept = packedCachePath(cacheDir(), vendored.name, vendored.version, contentHash);
+            if (fs.existsSync(kept)) {
+                fs.copyFileSync(kept, produced);
+                continue;
+            }
+            options.logger?.info(`packing ${vendored.name}@${vendored.version}`);
+            // `resolvePnpm()`, not `'pnpm'`: launchd's PATH does not include the
+            // directory pnpm installs itself into, so a bare name is an ENOENT for
+            // every build the daemon runs and for none that a developer runs by
+            // hand. See `shared/pnpm.ts`.
+            await exec(resolvePnpm(), ['--dir', dir, 'pack', '--pack-destination', path.join(staging, VENDOR_DIR)], {
+                cwd: workspaceRoot,
+                maxBuffer: 16 * 1024 * 1024,
+            });
+            if (!fs.existsSync(produced)) {
+                // `pnpm pack` names the file from the manifest, and the planner named
+                // it the same way — a mismatch here means one of them changed, and
+                // the override would point at a file that is not there.
+                throw new Error(`Packing ${vendored.name} produced no ${vendored.tarball}. ` +
+                    `The bundle's overrides would point at a file that does not exist.`);
+            }
+            // Kept where the next bundle can copy it from — this build's, and any
+            // later one that finds the package in the same state. The staging
+            // directory this file is in is removed at the end, so the cache holds a
+            // copy of its own rather than a path that is about to stop existing.
+            // Written aside and renamed, because another build may be reading this
+            // name while this one writes it and half a tarball is not a tarball.
+            const staged = `${kept}.${process.pid}.part`;
+            fs.copyFileSync(produced, staged);
+            fs.renameSync(staged, kept);
+        }
+        fs.writeFileSync(path.join(staging, 'package.json'), JSON.stringify(bundleRootManifest(plan, version), null, 2) + '\n');
+        const metadata = {
+            version,
+            commit: tree.commit,
+            dirty: tree.dirty,
+            builtAt: new Date().toISOString(),
+            vendored: plan.vendored.map((v) => `${v.name}@${v.version}`),
+        };
+        fs.writeFileSync(path.join(staging, BUNDLE_METADATA_FILE), JSON.stringify(metadata, null, 2) + '\n');
+        fs.rmSync(outDir, { recursive: true, force: true });
+        fs.renameSync(staging, outDir);
+        return { outDir, metadata, plan };
+    }
+    catch (err) {
+        fs.rmSync(staging, { recursive: true, force: true });
+        throw err;
+    }
+}
+/**
+ * Tar a built bundle for transfer.
+ *
+ * `-C <dir> .` so the archive holds the bundle's contents at its root rather
+ * than a directory named after wherever it was built. The unpack step extracts
+ * into a version directory it chose; an archive carrying its own top-level
+ * name would put everything one level deeper, and every path after that —
+ * `dist/cli/omnitron.js`, the symlinks, the install — would be wrong by one
+ * segment.
+ */
+/** The file a bundle carries about its own making. */
+export const BUNDLE_METADATA_FILE = 'BUNDLE.json';
+/**
+ * The record of the packing, which is not part of what was packed.
+ *
+ * It carries `builtAt` and a version stamped from the clock, so a bundle
+ * that includes it in its identity is a different bundle every time it is
+ * built. What it says about the commit and the vendored packages is a
+ * statement about the build, and the files those produced are hashed on
+ * their own account.
+ */
+export const isBuildRecord = (relativePath) => relativePath === BUNDLE_METADATA_FILE;
+/**
+ * The name a build gave itself, which is not part of what it built.
+ *
+ * `localVersion` stamps the minute of the build into the bundle's root
+ * manifest — `0.2.0+local.<sha>.202609201755` — so that a node can say which
+ * of two builds of one commit it is running. It is also the one thing in a
+ * bundle that cannot be the same twice, and comparing bundles with it in
+ * hand says "different" about two builds of an untouched tree. Everything
+ * else in that manifest decides what gets installed and is compared.
+ *
+ * Only the bundle's own manifest: a `package.json` below it belongs to a
+ * package that travels, and its version is that package's.
+ */
+export const withoutBuildVersion = {
+    appliesTo: (relativePath) => relativePath === 'package.json',
+    to: (bytes) => {
+        let manifest;
+        try {
+            manifest = JSON.parse(bytes.toString('utf8'));
+        }
+        catch {
+            // Not a manifest this understands. Hashed as the bytes it is, which is
+            // the conservative answer: a bundle nobody can read is not a bundle
+            // anybody should call unchanged.
+            return bytes;
+        }
+        delete manifest['version'];
+        return Buffer.from(JSON.stringify(manifest));
+    },
+};
+/**
+ * Build output, which is what a compiler produces and never what it reads.
+ *
+ * Matched on the whole last segment, so `dist-tools/` and
+ * `node_modules_shim.ts` are sources like any other.
+ */
+const BUILD_OUTPUT = new Set(['node_modules', 'dist', 'coverage', '.turbo', '.omnitron-build', '.git', '.cache']);
+export const withoutBuildOutput = (relativePath) => BUILD_OUTPUT.has(relativePath.slice(relativePath.lastIndexOf('/') + 1));
+/**
+ * Installed dependencies, which are not sources and are not packed.
+ *
+ * Matched on the whole last segment: `node_modules_shim.ts` is a source file.
+ */
+export const withoutNodeModules = (relativePath) => relativePath === 'node_modules' || relativePath.endsWith('/node_modules');
+/**
+ * What a bundle IS, independent of when it was packed.
+ *
+ * The archive cannot answer this. `tar -czf` writes the compression time
+ * into the gzip header and every file's own mtime into its entry, and a
+ * bundle is assembled into a fresh staging tree on each build, so two packs
+ * of byte-identical sources are two different files. A deployment that asks
+ * "does the node already have this?" by comparing archive hashes is asking
+ * what time it is.
+ *
+ * So the identity is read from the tree that will travel: every path under
+ * it, sorted, each with the bytes at that path, whether it may be executed,
+ * and — for a symlink — where it points, which is read rather than followed.
+ * Nothing here is a property of this machine or this minute.
+ *
+ * Framed with NULs and lengths so that no rearrangement of names and bodies
+ * can produce the same stream as a different tree.
+ */
+export async function bundleChecksum(bundleDir, options) {
+    const { createHash } = await import('node:crypto');
+    const root = path.resolve(bundleDir);
+    const paths = [];
+    const walk = (dir) => {
+        // Deliberately unguarded: a directory this cannot read is a bundle this
+        // cannot identify, and a hash over the part that happened to be readable
+        // would be a confident answer to a question nobody asked.
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            const rel = path.relative(root, full).split(path.sep).join('/');
+            if (options?.skip?.(rel))
+                continue;
+            paths.push(rel);
+            // `isDirectory()` is lstat's answer, so a symlink to a directory is a
+            // link here and is never descended into.
+            if (entry.isDirectory())
+                walk(full);
+        }
+    };
+    walk(root);
+    paths.sort();
+    const hash = createHash('sha256');
+    for (const rel of paths) {
+        const full = path.join(root, rel);
+        const stat = fs.lstatSync(full);
+        if (stat.isSymbolicLink()) {
+            const target = fs.readlinkSync(full);
+            hash.update(`L\0${rel}\0${target.length}\0${target}\0`);
+            continue;
+        }
+        if (stat.isDirectory()) {
+            hash.update(`D\0${rel}\0`);
+            continue;
+        }
+        const mode = stat.mode & 0o111 ? 'x' : '-';
+        if (options?.rewrite?.appliesTo(rel)) {
+            // Framed by the length of what is hashed, not of what is on disk: the
+            // original size would put back the difference the rewrite took out.
+            const bytes = options.rewrite.to(fs.readFileSync(full));
+            hash.update(`F\0${rel}\0${mode}\0${bytes.length}\0`);
+            hash.update(bytes);
+            continue;
+        }
+        hash.update(`F\0${rel}\0${mode}\0${stat.size}\0`);
+        await new Promise((resolve, reject) => {
+            const stream = fs.createReadStream(full);
+            stream.on('data', (chunk) => hash.update(chunk));
+            stream.on('end', () => resolve());
+            stream.on('error', reject);
+        });
+    }
+    return hash.digest('hex');
+}
+export async function archiveBundle(bundleDir, archivePath) {
+    const resolved = path.resolve(archivePath);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    await exec('tar', ['-czf', resolved, '-C', path.resolve(bundleDir), '.'], {
+        maxBuffer: 16 * 1024 * 1024,
+        // `COPYFILE_DISABLE=1`, because macOS `tar` writes an AppleDouble
+        // sidecar — `._index.html`, `._dist`, 163 bytes each — for every file
+        // carrying an extended attribute. Measured on the test node: they are in
+        // every artifact and in the gateway's web root, where `/._index.html` is
+        // a 163-byte binary the server will happily hand to anyone who asks.
+        // They are this machine's metadata about its own filesystem and they
+        // mean nothing on the far side.
+        env: { ...process.env, COPYFILE_DISABLE: '1' },
+    });
+    return resolved;
+}
+/** The package omnitron itself is — what a node's own upgrade is built from. */
+export const OMNITRON_PACKAGE = '@omnitron-dev/omnitron';
+/**
+ * Where one build of omnitron's own bundle is staged.
+ *
+ * Under the temporary directory and named by the caller's label, so that the
+ * console upgrading one node and a `fleet upgrade` running in a terminal
+ * never stage into each other's directory.
+ */
+export function ownBundleStaging(label) {
+    return path.join(os.tmpdir(), `omnitron-bundle-${label}`);
+}
+/**
+ * Why omnitron's own build may not travel under the tree's commit — or null.
+ *
+ * The bundle copies `dist` and `webapp/dist` as they are on disk and names
+ * itself after the working tree's HEAD, and nothing compared the two.
+ * Measured 2026-09-23: a node installed as `0.2.0+local.f1715106…` received a
+ * console build older than f1715106, whose only change was that console. A
+ * `dist` compiled before the last commit ships the code before it under the
+ * commit's name, and the node's version is the record everyone reads
+ * afterwards. Each build now carries its own stamp (`BUILD.json`, written by
+ * `scripts/stamp-build.mjs`), and it must name the commit the tree is on,
+ * from a clean tree.
+ */
+export function ownBuildRefusal(input) {
+    const short = (sha) => sha.slice(0, 8);
+    for (const rel of ['dist', 'webapp/dist']) {
+        const dir = path.join(input.packageDir, rel);
+        const name = `${path.basename(input.packageDir)}/${rel}`;
+        if (!fs.existsSync(dir)) {
+            if (rel === 'dist')
+                return `${name} does not exist: there is no build to ship. Build omnitron first.`;
+            continue;
+        }
+        const stamp = readBuildStamp(dir);
+        if (!stamp) {
+            return (`${name} carries no build stamp, so nothing says which commit it was compiled from. ` +
+                `Rebuild it (\`pnpm --filter ${rel === 'dist' ? OMNITRON_PACKAGE : '@omnitron/console'} build\`), which stamps it.`);
+        }
+        if (stamp.dirty) {
+            return (`${name} was compiled from a tree with uncommitted changes (${stamp.builtAt}): what it holds is no commit ` +
+                `at all. Rebuild it from a clean tree.`);
+        }
+        if (stamp.commit !== input.tree.commit) {
+            return (`${name} was compiled from ${short(stamp.commit)} (${stamp.builtAt}) and the tree is at ` +
+                `${short(input.tree.commit)}: a node would run ${short(stamp.commit)} under ${short(input.tree.commit)}'s ` +
+                `name. Rebuild it.`);
+        }
+    }
+    return null;
+}
+/**
+ * Build omnitron from a working tree, for installing on a node.
+ *
+ * Two callers do this — `omnitron fleet upgrade` from a terminal, and the
+ * daemon when the console asks — and each used to write it out: the package
+ * name, the staging path, the `buildBundle`/`archiveBundle` pair. The copies
+ * had already drifted, in the way copies do: the daemon removed its staging
+ * tree in a `finally`, and the CLI left several hundred megabytes in the
+ * temporary directory on every run, including every `--dry-run` that shipped
+ * nothing at all.
+ *
+ * Packing is separate from building because a dry run wants the version and
+ * not the tarball.
+ */
+export async function buildOwnBundle(options) {
+    const own = readWorkspaces([path.resolve(options.workspaceRoot)]).get(OMNITRON_PACKAGE);
+    if (own) {
+        const refusal = ownBuildRefusal({
+            packageDir: directoryOf(own),
+            tree: await describeTree(path.resolve(options.workspaceRoot)),
+        });
+        if (refusal)
+            throw new Error(refusal);
+    }
+    const staging = ownBundleStaging(options.label);
+    const archivePath = `${staging}.tar.gz`;
+    const built = await buildBundle({
+        workspaceRoot: options.workspaceRoot,
+        rootPackage: OMNITRON_PACKAGE,
+        outDir: staging,
+        ...(options.logger ? { logger: options.logger } : {}),
+    });
+    let packed = null;
+    return {
+        version: built.metadata.version,
+        dirty: built.metadata.dirty,
+        pack: () => (packed ??= archiveBundle(built.outDir, archivePath)),
+        cleanup: async () => {
+            // The staging tree is hundreds of megabytes; leaving it behind fills
+            // the temporary directory one upgrade at a time.
+            await fs.promises.rm(staging, { recursive: true, force: true }).catch(() => undefined);
+            await fs.promises.rm(archivePath, { force: true }).catch(() => undefined);
+        },
+    };
+}
+/**
+ * Everything that decides what an application's compiler emits.
+ *
+ * The application's own sources, and every workspace package that travels
+ * with it — the same closure the bundle vendors, because a package whose
+ * code moved changes both what the app compiles against and what ships
+ * beside it. A dependency is read whole, sources and `dist` together: which
+ * of the two moved is not the question, only whether anything did.
+ *
+ * `null` for every answer that cannot be had — no workspace above the app, a
+ * manifest that will not parse, a plan that refuses. The caller compiles.
+ *
+ * `memo` is shared with the packing step, which asks the same question of
+ * the same directories; `buildBundle` drops an entry for any package it
+ * rebuilds, so nothing here outlives the state it measured.
+ */
+export async function buildInputsChecksum(appDir, options) {
+    const workspaceRoot = findWorkspaceRoot(appDir);
+    if (!workspaceRoot)
+        return null;
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(path.join(appDir, 'package.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!manifest.name)
+        return null;
+    const workspace = readWorkspaces([workspaceRoot, ...(options?.additionalWorkspaceRoots ?? [])]);
+    const plan = planBundle(manifest.name, workspace);
+    if (plan.refusal)
+        return null;
+    const memo = options?.memo;
+    const readOnce = async (key, dir, skip) => {
+        const seen = memo?.get(key);
+        if (seen)
+            return seen;
+        const hash = await bundleChecksum(dir, { skip });
+        memo?.set(key, hash);
+        return hash;
+    };
+    const parts = [`app ${manifest.name} ${await readOnce(sourcesKey(appDir), appDir, withoutBuildOutput)}`];
+    for (const vendored of plan.vendored) {
+        const entry = workspace.get(vendored.name);
+        if (!entry)
+            return null;
+        const dir = directoryOf(entry);
+        parts.push(`dep ${vendored.name}@${vendored.version} ${await readOnce(dir, dir, withoutNodeModules)}`);
+    }
+    parts.sort();
+    const { createHash } = await import('node:crypto');
+    return createHash('sha256').update(parts.join('\n')).digest('hex');
+}
+/** The memo key for an app's own sources, which are read without its output. */
+const sourcesKey = (appDir) => `sources:${path.resolve(appDir)}`;
+export function versionDir(layout) {
+    if (!/^\d+\.\d+\.\d+(?:-[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*)?(?:\+[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*)?$/.test(layout.version))
+        throw new Error('Bundle version must be one complete semantic-version path segment');
+    if (!path.posix.isAbsolute(layout.prefix) || layout.prefix === '/' || path.posix.normalize(layout.prefix) !== layout.prefix || /[\\\r\n\0]/.test(layout.prefix))
+        throw new Error('Bundle prefix must be a canonical absolute directory');
+    return `${layout.prefix}/versions/${layout.version}`;
+}
+/** Shell-quote for the remote's POSIX shell. */
+function q(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Unpack and install a transferred bundle archive, without disturbing the
+ * version that is running.
+ *
+ * `archivePath` is where the caller put the tarball on the target.
+ */
+const installPrefixSource = String.raw `
+function directory(p) {
+  let parent=p;
+  while (!fs.existsSync(parent)) {
+    try { fs.lstatSync(parent); throw Error('Dangling installation path: '+parent); }
+    catch(e) { if(e.code!=='ENOENT') throw e; }
+    const next=path.dirname(parent); if(next===parent) throw Error('Missing installation root'); parent=next;
+  }
+  if(fs.realpathSync(parent)!==parent || !fs.statSync(parent).isDirectory()) throw Error('Noncanonical installation parent: '+parent);
+  fs.mkdirSync(p,{recursive:true});
+  if(fs.realpathSync(p)!==p || !fs.lstatSync(p).isDirectory()) throw Error('Noncanonical installation directory: '+p);
+}
+for(const p of [prefix,prefix+'/versions',prefix+'/releases']) directory(p);
+`;
+/** Check physical ownership before even uploading into the prefix. */
+export function installPreflightCommand(layout) {
+    versionDir(layout);
+    const code = `const fs=require('node:fs'),path=require('node:path'),prefix=${JSON.stringify(layout.prefix)};${installPrefixSource}`;
+    return `node -e ${q(code)}`;
+}
+/**
+ * A completed version is never unpacked or installed again. Each attempt gets
+ * a fresh sibling and publishes it only after npm and the actual CLI pass.
+ * The receipt hashes the complete installed tree, so reuse verifies both the
+ * archive identity and physical dependencies, including modes and symlinks.
+ * Failed siblings remain available for diagnosis; they are never reused.
+ */
+export function installSteps(layout, archivePath, expectedArchiveSha256) {
+    versionDir(layout);
+    if (expectedArchiveSha256 !== undefined && !/^[a-f0-9]{64}$/.test(expectedArchiveSha256))
+        throw new Error('Bundle archive identity must be a SHA256');
+    const code = String.raw `
+const fs=require('node:fs'),path=require('node:path'),crypto=require('node:crypto'),cp=require('node:child_process');
+const [prefix,version,archive,expected]=process.argv.slice(1),dir=prefix+'/versions/'+version;
+${installPrefixSource}
+const sha=b=>crypto.createHash('sha256').update(b).digest('hex');
+const archiveHash=sha(fs.readFileSync(archive));
+if(expected && archiveHash!==expected) throw Error('Bundle archive SHA256 mismatch');
+const record='.omnitron-install.json';
+function present(p){try{fs.lstatSync(p);return true}catch(e){if(e.code==='ENOENT')return false;throw e}}
+function snapshot(root) {
+  const entries={};
+  function visit(relative) {
+    for(const name of fs.readdirSync(path.join(root,relative)).sort()) {
+      const rel=relative?relative+'/'+name:name;
+      if(rel===record)continue;
+      const p=path.join(root,rel),st=fs.lstatSync(p);
+      if(st.isSymbolicLink()) {
+        const link=fs.readlinkSync(p),resolved=path.resolve(path.dirname(p),link);
+        if(path.isAbsolute(link))throw Error('Installed symlink must remain relative after promotion: '+rel);
+        if(!resolved.startsWith(root+'/'))throw Error('Installed symlink escapes bundle: '+rel);
+        entries[rel]={kind:'link',link};
+      } else if(st.isDirectory()){entries[rel]={kind:'directory',mode:st.mode&0o777};visit(rel)}
+      else if(st.isFile())entries[rel]={kind:'file',mode:st.mode&0o777,sha256:sha(fs.readFileSync(p))};
+      else throw Error('Unsupported installed entry: '+rel);
+    }
+  }
+  visit('');return entries;
+}
+function identity(root){
+  const pkg=JSON.parse(fs.readFileSync(root+'/package.json','utf8'));
+  const bundle=JSON.parse(fs.readFileSync(root+'/BUNDLE.json','utf8'));
+  if(pkg.version!==version || bundle.version!==version)throw Error('Bundle metadata version mismatch');
+}
+function check(root){
+  identity(root);
+  const out=cp.execFileSync(root+'/dist/cli/omnitron.js',['--version'],{encoding:'utf8',timeout:120000,stdio:['ignore','pipe','pipe']});
+  if(out.trim().split('\n').pop().trim()!==version)throw Error('Installed CLI version mismatch');
+}
+function reuse(){
+  if(fs.realpathSync(dir)!==dir || !fs.lstatSync(dir).isDirectory())throw Error('Existing bundle path is not an immutable directory');
+  const r=JSON.parse(fs.readFileSync(dir+'/'+record,'utf8'));
+  if(r.schema!==1 || r.version!==version || r.archiveSha256!==archiveHash)throw Error('Existing bundle identity conflicts with archive');
+  if(JSON.stringify(r.entries)!==JSON.stringify(snapshot(dir)))throw Error('Existing bundle content differs from install receipt');
+  check(dir);console.log(version);
+}
+if(present(dir)){reuse();process.exit(0)}
+// Refuse unsafe archive paths and links before tar can write anything. Bundle
+// archives created by packBundle contain regular files/directories only.
+const names=cp.execFileSync('tar',['-tzf',archive],{encoding:'utf8',maxBuffer:32*1024*1024}).trim().split('\n');
+for(const name of names){
+  if(!name || name.startsWith('/') || name.split('/').includes('..') || name.includes('\r'))throw Error('Unsafe bundle archive path');
+}
+const listing=cp.execFileSync('tar',['-tvzf',archive],{encoding:'utf8',maxBuffer:32*1024*1024}).trim().split('\n');
+if(listing.some(line=>!['-','d'].includes(line[0])))throw Error('Bundle archive must contain regular files and directories only');
+const stage=prefix+'/versions/.install-'+version+'-'+crypto.randomUUID();fs.mkdirSync(stage,{mode:0o700});
+cp.execFileSync('tar',['-xzf',archive,'-C',stage],{timeout:300000,stdio:'inherit'});
+identity(stage);
+if(present(stage+'/'+record))throw Error('Archive may not supply an installation receipt');
+fs.chmodSync(stage+'/dist/cli/omnitron.js',0o755);
+cp.execFileSync('npm',['install','--omit=dev','--no-audit','--no-fund'],{cwd:stage,timeout:900000,stdio:'inherit'});
+check(stage);
+const entries=snapshot(stage);
+fs.writeFileSync(stage+'/'+record,JSON.stringify({schema:1,version,archiveSha256:archiveHash,entries})+'\n',{flag:'wx',mode:0o600});
+function syncTree(p){
+  const st=fs.lstatSync(p);if(st.isSymbolicLink())return;
+  if(st.isDirectory())for(const name of fs.readdirSync(p))syncTree(path.join(p,name));
+  const fd=fs.openSync(p,'r');try{fs.fsyncSync(fd)}finally{fs.closeSync(fd)}
+}
+syncTree(stage);
+if(present(dir))throw Error('Bundle appeared while the sibling was installing; refusing replacement');
+fs.renameSync(stage,dir);
+const fd=fs.openSync(prefix+'/versions','r');try{fs.fsyncSync(fd)}finally{fs.closeSync(fd)}
+console.log(version);
+`;
+    return [{
+            what: 'install dependencies in an immutable sibling and check that it runs',
+            command: `node -e ${q(code)} ${q(layout.prefix)} ${q(layout.version)} ${q(archivePath)} ${q(expectedArchiveSha256 ?? '')}`,
+            timeoutMs: 1_500_000,
+        }];
+}
+/**
+ * Make an installed version the live one.
+ *
+ * Separate from `installSteps` because this is the only step that changes
+ * what runs, and a caller that stopped before it has changed nothing.
+ */
+export function activateSteps(layout, pathDir = '/usr/local/bin') {
+    const dir = versionDir(layout);
+    const cli = `${layout.prefix}/current/dist/cli/omnitron.js`;
+    return [
+        {
+            what: `point current at ${layout.version}`,
+            // `-n` so a `current` that is already a symlink to a directory is
+            // replaced rather than followed — without it the second upgrade
+            // creates `current/<version>` inside the first one.
+            command: `mkdir -p ${q(`${layout.prefix}/bin`)} && ` +
+                `ln -sfn ${q(dir)} ${q(`${layout.prefix}/current`)} && ` +
+                `ln -sfn ${q(cli)} ${q(`${layout.prefix}/bin/omnitron`)}`,
+            timeoutMs: 60_000,
+        },
+        {
+            // The step this design was missing, and the node said so.
+            //
+            // `<prefix>/bin` is not on anyone's PATH. So after `current` moved, a
+            // bare `omnitron` still resolved to whatever was there before — on the
+            // test host, the registry copy in the runtime's own bin. The activation
+            // then restarted THAT, and the failure it reported was the old version's
+            // missing dependency, under a message saying the new version had not
+            // come up. Everything was true and nothing pointed at the cause.
+            //
+            // Guarded like every other link this code makes: only over nothing, or
+            // over a symlink, which is what an earlier install of ours leaves. A
+            // real binary somebody else put there is kept, and `<prefix>/bin` still
+            // has the CLI.
+            what: `make omnitron on PATH resolve to ${layout.version}`,
+            command: `if [ ! -e ${q(`${pathDir}/omnitron`)} ] || [ -L ${q(`${pathDir}/omnitron`)} ]; then ` +
+                `ln -sfn ${q(cli)} ${q(`${pathDir}/omnitron`)}; fi`,
+            timeoutMs: 60_000,
+        },
+    ];
+}
+/**
+ * Keep the last `keep` versions and remove the rest.
+ *
+ * «Last» by the build stamp that ends every local version —
+ * `0.2.0+local.<sha>.<stamp>` — not by the name. The name was the sort key,
+ * on the stated ground that it «is chronological»; it is not, because the
+ * sha comes first. On sample/test (2026-09-25) three upgrades in one morning
+ * left the node with the running version and three from 22–23 September,
+ * and deleted 311bddb1 and de454a80 — the two a rollback would have wanted.
+ * A version without a numeric stamp counts as the oldest.
+ *
+ * `current` is never removed whatever its age: a retention that reasons
+ * about age must not be the thing that deletes what is running. Portable
+ * `awk` rather than GNU `head -n -N`, so the court can run the command
+ * itself on the machine that builds.
+ */
+export function pruneSteps(layout, keep, protectedRoots = []) {
+    const versions = `${layout.prefix}/versions`;
+    return [
+        {
+            what: `keep the ${keep} most recent versions`,
+            command: `cd ${q(versions)} 2>/dev/null || exit 0; ` +
+                `CURRENT=$(readlink ${q(`${layout.prefix}/current`)} 2>/dev/null); ` +
+                `ls -1 | awk -F. '{ s = $NF; if (s !~ /^[0-9]+$/) s = 0; print s "\\t" $0 }' | sort -n -k1,1 | cut -f2- | ` +
+                `awk -v keep=${keep} '{ a[NR] = $0 } END { for (i = 1; i <= NR - keep; i++) print a[i] }' | while read -r v; do ` +
+                `[ "${versions}/$v" = "$CURRENT" ] && continue; ` +
+                protectedRoots.map(root => `[ "${versions}/$v" = ${q(root)} ] && continue; `).join('') +
+                `rm -rf -- "$v"; done; true`,
+            timeoutMs: 120_000,
+        },
+    ];
+}
+//# sourceMappingURL=bundle-builder.js.map