@north-light/cli 0.0.0 → 0.3.414

package/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 Northlight Systems. All rights reserved.
+
+This software and its associated documentation files (the "Software") are the
+proprietary and confidential property of Northlight Systems. No licence or
+right to use, copy, modify, merge, publish, distribute, sublicense, sell,
+reverse engineer, decompile or create derivative works of the Software is
+granted except under a separate written agreement with Northlight Systems.
+
+The Software is made available as compiled and minified packages through the
+npm registry solely so that it can be installed and run by those authorised by
+Northlight Systems. Installing a package from the registry does not grant any
+licence to the Software's source code.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+NORTHLIGHT SYSTEMS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,183 @@
-# @north-light/cli
+# crouter — an agent runtime: durable agents on a canvas, driven from a CLI or an SDK
 
-Placeholder that reserves the name so trusted publishing can be configured. Real releases are published by CI from Northlight-Systems/crouter.
+![crouter](assets/banner.svg)
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@north-light/cli"><img alt="npm" src="https://img.shields.io/npm/v/@north-light/cli?label=npm"></a>
+  <a href="https://nodejs.org"><img alt="node" src="https://img.shields.io/badge/node-%3E%3D22.19-339933"></a>
+  <a href="https://discord.gg/afwW4saEtr"><img alt="discord" src="https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white"></a>
+</p>
+
+crouter is an agent runtime for Node.js. Each agent is a **node**: a record with a goal, a context directory, and a detached process (its *broker*) that hosts the model session. A daemon, `crtrd`, owns every node's state and lifecycle. You drive it with the `crtr` command line, a terminal viewer, or a typed TypeScript SDK — all three are clients of the same local API. Each model session runs on [pi](https://github.com/earendil-works/pi), the open-source coding-agent harness; crouter adds the daemon, the node graph, the context system and the CLI around it.
+
+Closing a terminal does not stop an agent, and an agent that is waiting on something has no process at all. Nodes can spawn children, report to whoever subscribes to them, and share markdown documents that other agents are shown when they become relevant. crouter is not a model and does not bundle one: you sign in to a model provider during setup. It is also not a hosted service; it runs on your machine, or in a container you start.
+
+[Website](https://crouter.ai) · [Docs](https://docs.crouter.ai) · [Getting started](https://docs.crouter.ai/docs/cli/first-session) · [Concepts](https://docs.crouter.ai/docs/concepts) · [SDK](https://docs.crouter.ai/docs/sdk) · [Plugins](https://docs.crouter.ai/docs/plugin) · [Marketplace](https://github.com/crouton-labs/crouter-official-marketplace) · [Discord](https://discord.gg/afwW4saEtr)
+
+## Install
+
+```bash
+npm install -g @north-light/cli
+crtr
+```
+
+The first `crtr` on a machine opens the setup installer. It signs you in to a model provider, then offers companion packages (including the official plugin marketplace) and system dependencies such as tmux. After setup, `crtr` opens a conversation with an agent, which offers a short tour of how crouter works. `crtr sys setup` reopens the installer later.
+
+Requirements:
+
+- Node.js 22.19 or later. This is the floor set by the pi packages crouter depends on; CI and the Docker image run Node 24.
+- tmux, for the in-terminal viewer. The first-run installer offers to install it, and `crtr` started outside tmux opens a `crouter` tmux session for you and runs there.
+- macOS is what CI exercises. On Linux, the supported route is the Docker image (see [Run it in a container](#run-it-in-a-container)).
+
+## Quick start
+
+From the directory you want the agent to work in (outside tmux, `crtr` starts it for you):
+
+```bash
+crtr                                           # a conversation here
+crtr . "Inspect this repository and report the failing tests."   # with a first message
+crtr -c                                        # return to the latest conversation here
+crtr -r <node-id>                              # reopen one conversation by id (`crtr -r` alone picks)
+```
+
+Enter sends a message; Alt+Enter (Option+Enter on a Mac) or Shift+Enter starts a new line.
+
+To start an agent without taking over the terminal, from a script or another agent, create a root node:
+
+```bash
+crtr node new --root "Inspect this repository and report the failing tests."
+```
+
+`--root` creates an independent node and starts its broker. Inside tmux the command opens a viewer pane for it; outside tmux it prints the node id, and you open the viewer yourself:
+
+```bash
+crtr surface attach to <node-id>
+```
+
+The viewer is not the agent. Close it and the node keeps working; open it again later for the saved conversation. To see every node on the canvas:
+
+```bash
+crtr canvas dashboard     # the subscription tree as ASCII: status, kind, context size
+crtr canvas browse        # interactive navigator with tabs and search
+crtr canvas attention list  # nodes waiting on you
+```
+
+The [first-session guide](https://docs.crouter.ai/docs/cli/first-session) walks through this in order.
+
+## What it does
+
+Each item names the command that does it. `crtr <command> -h` prints the exact contract for any of them.
+
+**Nodes and delegation.** `crtr node new` creates a child and subscribes its parent to it; the child reports with `crtr push update` and finishes with `crtr push final`, and that report wakes the parent. `--worktree <branch>` gives a child its own git worktree on a `crtr/<node-id>` branch, `--fork-from` starts it from another node's conversation, and `--output-schema` makes its final result a JSON document validated against a schema. A node that decides its work divides into independent parts runs `crtr node promote` and becomes an orchestrator.
+
+**Waiting costs nothing.** A node with nothing to do ends its turn and becomes dormant: no broker, no model call. A child's report, a message (`crtr node message send`), a human answer, or a cron wakes it with its conversation intact. If a broker crashes, the daemon keeps the node's row, session, waits and inbox; `crtr canvas revive --all` reconnects every disconnected node after a reboot.
+
+**The canvas.** Every node, document, background job and owner is an object with a name. `crtr canvas read`, `list`, `search` and `edges` work on all of them. Reading or writing an object makes you a watcher, so later edits and reports arrive in your inbox. `crtr canvas history` searches what past runs in a directory were told and said.
+
+**Documents.** Knowledge (consulted) and preferences (followed) are markdown documents owned by a node, repo, profile, user or plugin. Delivery rules decide whether an agent is shown a document's name, its one-line "read when" preview, or its full body — at startup, when it reads a file, or before a command. `crtr doc write` and `crtr doc edit` write them; `crtr sys context` explains why one did or did not load; `crtr sys sync` imports `CLAUDE.md`, `AGENTS.md`, `.claude/rules` and skill bundles.
+
+**Human inbox.** `crtr human send` puts a typed page (a picker, a table, free text) in your inbox; your answer is delivered back to the node that asked. `crtr human review` opens a document for review with anchored comments, and `crtr human show` keeps a file live in a tmux pane.
+
+**Scheduling.** `crtr cron add` stores a bash command the daemon runs at a time or cadence (`--at`, `--every`) and can route its output to a node's inbox or to a fresh node (`--sink node:<id>` / `spawn:<kind>`). A command that exits 75 is treated as not yet eligible, and the next cadence re-checks it.
+
+**Scopes.** A node or a remote token carries an allow-list (`crtr:llm`, `crtr:act`, `crtr:schedule`, `crtr:memory:read:user`, …) that the daemon checks at the route that performs the action. `crtr sys connect --app <id> --scopes …` mints a token whose list caps everything an application can create.
+
+**Plugins and marketplaces.** A marketplace is a git repository of plugins; `crtr pkg market add <git-url>` registers one and `crtr pkg plugin install <marketplace>/<plugin>` installs from it. A plugin can add commands (local executable or HTTP), documents, agent kinds, and binaries. `crtr custom-object register` makes an outside service a watchable object on the canvas.
+
+## How it fits together
+
+```mermaid
+flowchart LR
+  CLI[crtr CLI] --> API["/v1 API"]
+  SDK[SDK application] --> API
+  Viewer[Terminal viewer] --> API
+  API --> Daemon[crtrd]
+  Daemon --> Canvas[Canvas state]
+  Daemon --> Broker[Detached broker per node]
+  Viewer -. live session .-> Broker
+```
+
+`crtrd` is the only writer of canvas state and the only launcher of brokers. The CLI, the viewer and SDK applications call its `/v1` API; none of them opens the canvas database or starts an engine of its own. On one machine they use an owner-only Unix socket. A browser or a remote process uses a TCP listener and a bearer token (`crtr sys connect`).
+
+What this costs: a daemon has to be running (the CLI and SDK start it on first use), and a network failure on a remote client fails a request loudly rather than replaying it. What it buys is one owner for state, so a node outlives the terminal, the viewer, or the application that created it. [Why a daemon](https://docs.crouter.ai/docs/concepts/why-a-daemon) covers the reasoning.
+
+## Use crouter from an application
+
+```bash
+npm install @north-light/sdk zod
+```
+
+```ts
+import Crouter from '@north-light/sdk';
+import { z } from 'zod';
+
+const client = new Crouter(); // local daemon; started on first request if it is not running
+
+const run = await client.nodes.parse({
+  prompt: 'Read package.json and return its name and version.',
+  cwd: '/absolute/path/to/project',
+  output_schema: z.object({ name: z.string(), version: z.string() }),
+});
+
+if (run.kind === 'result') console.log(run.output_parsed.name, run.output_parsed.version);
+else console.error(run.reason, run.detail);
+```
+
+`nodes.parse` returns a typed result or an explicit failure; it never hands back text you have to parse. `nodes.stream` pipes a run's text and tool calls to a UI. See the [SDK docs](https://docs.crouter.ai/docs/sdk) and the [recipes](https://docs.crouter.ai/docs/sdk/guides).
+
+## Run it in a container
+
+```bash
+docker run -e CRTRD_TOKEN=<a-secret-you-choose> -p 7777:7777 ghcr.io/northlight-systems/crtrd
+curl -H "Authorization: Bearer <a-secret-you-choose>" http://localhost:7777/healthz
+```
+
+The image runs `crtrd` headless behind TCP; every request needs the bearer token. It contains no model credential, so give the agent one before you create a run. Mount a named volume at `/home/agent/.crouter` to keep the canvas across restarts. From Node, [`@north-light/env-docker`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-env-docker) starts and stops this container for you. Details are in [`docker/README.md`](https://github.com/Northlight-Systems/crouter/blob/main/docker/README.md).
+
+## Extend crouter
+
+An application exposes typed operations as native `crtr` commands with [`@north-light/plugin`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-plugin): define a command tree once and it produces the HTTP handler and the archive that `crtr pkg plugin install --endpoint <url> --name <name>` reads. The [plugin docs](https://docs.crouter.ai/docs/plugin) cover commands, parameters, output, errors and deployment.
+
+Ready-made plugins live in the [official marketplace](https://github.com/crouton-labs/crouter-official-marketplace): `exa-search`, `capture`, `tsym`, `bird`, `github-asset`, `dev`, `vercel`, `fly`, `railway`, `cloudflare`, and others. The first-run installer offers to register it.
+
+## Packages
+
+| Package | What it is | Source |
+|---|---|---|
+| [`@north-light/cli`](https://www.npmjs.com/package/@north-light/cli) | The `crtr` CLI, the `crtrd` daemon, and the terminal viewer | [`src/`](https://github.com/Northlight-Systems/crouter/tree/main/src) |
+| [`@north-light/sdk`](https://www.npmjs.com/package/@north-light/sdk) | Typed Node and browser client: runs, streaming, results, files, bash, memory | [`packages/crouter-sdk`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-sdk) |
+| [`@north-light/plugin`](https://www.npmjs.com/package/@north-light/plugin) | Author HTTP plugins from one typed command tree | [`packages/crouter-plugin`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-plugin) |
+| [`@north-light/api`](https://www.npmjs.com/package/@north-light/api) | The `/v1` API contract: `CrtrClient`, DTOs, routes, errors | [`packages/crouter-api`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-api) |
+| [`@north-light/env-docker`](https://www.npmjs.com/package/@north-light/env-docker) | Start or attach to a `crtrd` container | [`packages/crouter-env-docker`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-env-docker) |
+| [`@north-light/identity`](https://www.npmjs.com/package/@north-light/identity) | Verify access tokens and evaluate scopes | [`packages/crouter-identity`](https://github.com/Northlight-Systems/crouter/tree/main/packages/crouter-identity) |
+
+Most applications need only `@north-light/sdk`. The other repository contents: [`docs/`](https://github.com/Northlight-Systems/crouter/tree/main/docs) is the documentation source, [`apps/docs`](https://github.com/Northlight-Systems/crouter/tree/main/apps/docs) is the TanStack Start site that publishes it at docs.crouter.ai, [`docker/`](https://github.com/Northlight-Systems/crouter/tree/main/docker) builds the `crtrd` image, and [`examples/`](https://github.com/Northlight-Systems/crouter/tree/main/examples) holds the SDK recipes and a localhost demo.
+
+## Develop
+
+The source repository is private to Northlight Systems; this section is for its developers.
+
+```bash
+git clone git@github.com:Northlight-Systems/crouter.git
+cd crouter
+npm ci
+npm run build
+```
+
+Tests come in three lanes — unit (`npm test`), integration, and seam against the compiled `dist/`. Run them with `npm run test:isolated`, which copies the checkout into a temporary `HOME` first: the suite refuses to run against your real account home, because the runtime installer and project-scope lookups could otherwise write to it. `test:isolated` uses `/usr/bin/lockf` and `/Users/Shared`, so it runs on macOS.
+
+```bash
+npm run test:isolated                    # unit lane
+npm run test:isolated -- integration seam
+npm run test:isolated -- path/to/file.test.ts
+```
+
+The docs site runs from `apps/docs` with `npm run dev`. [CONTRIBUTING.md](CONTRIBUTING.md) has the pull-request conventions for Northlight Systems developers.
+
+## Security
+
+To report a vulnerability, follow [SECURITY.md](https://github.com/Northlight-Systems/crouter/blob/main/SECURITY.md) rather than opening a public issue.
+
+## License
+
+crouter is proprietary software. Copyright (c) 2026 Northlight Systems. All rights reserved. The source repository is private; the packages are published to npm as compiled, minified builds. See [LICENSE](LICENSE).

package/bin/crouter

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runSelected } from './runtime-selector.mjs';
+
+await runSelected('crouter', 'cli');

package/bin/crtr

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runSelected } from './runtime-selector.mjs';
+
+await runSelected('crtr', 'cli');

package/bin/crtr-launcher

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runSelected } from './runtime-selector.mjs';
+
+await runSelected('crtr-launcher', 'launcher');

package/bin/crtrd

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runSelected } from './runtime-selector.mjs';
+
+await runSelected('crtrd', 'daemon');

package/bin/progress-painter.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Draws one animated progress bar line for a long install step, in its own
+// process.
+//
+// A separate process is what makes the bar move at all: the steps it covers
+// (`uv` provisioning the renderer, a marketplace git clone, `npm ci` inside
+// the runtime installer) block the parent's event loop, so a timer in the
+// parent would render nothing until the work it describes had already
+// finished. This process owns nothing but the line it draws — the parent's
+// `✓ name` / `✗ name` line remains the authoritative outcome.
+//
+// Contract:
+//   argv[2]  label drawn to the left of the bar
+//   stdin    lines holding a fraction 0..1 switch the bar to determinate and
+//            set its fill; EOF ends the bar (line erased, exit 0)
+//   stdout   the bar line — the parent maps this to whichever stream it wants
+//
+// Plain JS with no imports: `bin/runtime-selector.mjs` spawns it before any
+// runtime generation's `dist/` is loaded.
+
+const label = process.argv[2] ?? '';
+const FRAME_MS = 80;
+const MAX_TRACK = 24;
+const MIN_TRACK = 8;
+const SLIDER = 6;
+
+let fraction = null;
+let tick = 0;
+let stopped = false;
+
+/** Track width that leaves room for the label and the percent suffix in this
+ *  terminal; the label is truncated only when even MIN_TRACK will not fit. */
+function layout() {
+  // A pty with no window size set (a `script`-style capture) reports 0.
+  const columns = process.stdout.columns || 80;
+  const suffix = fraction === null ? 0 : 5;
+  const available = columns - label.length - suffix - 2;
+  if (available >= MIN_TRACK) return { text: label, track: Math.min(MAX_TRACK, available) };
+  const text = label.slice(0, Math.max(0, columns - suffix - MIN_TRACK - 3));
+  return { text: text === label ? text : `${text}…`, track: MIN_TRACK };
+}
+
+function bar(track) {
+  if (fraction !== null) {
+    const filled = Math.min(track, Math.round(fraction * track));
+    return '█'.repeat(filled) + '░'.repeat(track - filled);
+  }
+  // Indeterminate: a lit segment sliding to the end of the track and back.
+  const span = Math.max(1, track - SLIDER);
+  const at = tick % (span * 2);
+  const start = at <= span ? at : span * 2 - at;
+  const width = Math.min(SLIDER, track);
+  return '░'.repeat(start) + '█'.repeat(width) + '░'.repeat(Math.max(0, track - start - width));
+}
+
+function render() {
+  const { text, track } = layout();
+  const percent = fraction === null ? '' : ` ${String(Math.round(fraction * 100)).padStart(3)}%`;
+  process.stdout.write(`\r\x1b[2K${text} ${bar(track)}${percent}`);
+  tick += 1;
+}
+
+function stop(code) {
+  if (stopped) return;
+  stopped = true;
+  clearInterval(timer);
+  process.stdout.write('\r\x1b[2K\x1b[?25h');
+  process.exit(code);
+}
+
+process.stdout.write('\x1b[?25l');
+render();
+const timer = setInterval(render, FRAME_MS);
+
+let pending = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  pending += chunk;
+  const lines = pending.split('\n');
+  pending = lines.pop() ?? '';
+  for (const line of lines) {
+    const value = Number(line.trim());
+    if (Number.isFinite(value) && value >= 0 && value <= 1) fraction = value;
+  }
+});
+process.stdin.on('end', () => stop(0));
+process.stdin.on('error', () => stop(0));
+process.on('SIGINT', () => stop(130));
+process.on('SIGTERM', () => stop(143));

package/bin/runtime-generation-manifest.mjs

@@ -0,0 +1,286 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, readdirSync, readlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+/** Resolve the runtime home, allowing isolated test and development runtimes. */
+export function runtimeHome() {
+  return resolve(process.env.CRTR_RUNTIME_HOME || join(homedir(), '.crouter', 'runtime'));
+}
+
+export const GENERATION_ID = /^[a-f0-9]{64}$/;
+export const MANIFEST_SCHEMA = 1;
+export const PACKAGE_NAME = '@north-light/cli';
+/** The name every generation manifest records, whichever package built it. It is
+ *  frozen at the pre-rename package name on purpose: a global install of the old
+ *  `@crouter/cli` keeps its own copy of this file as its launch shim, and that
+ *  shim refuses a generation whose manifest names a package it does not know.
+ *  Recording the old name lets an install that moved to `@north-light/cli` keep
+ *  launching through the shim it already has. */
+export const GENERATION_PACKAGE_NAME = '@crouter/cli';
+/** Names earlier releases recorded in a generation manifest. A generation installed
+ *  before the rename is still valid, so the selector accepts these as well. */
+export const LEGACY_PACKAGE_NAMES = new Set(['crouter', 'crtr', '@north-light/crouter', '@crouter/cli']);
+export function isKnownPackageName(name) {
+  return name === PACKAGE_NAME || name === GENERATION_PACKAGE_NAME || LEGACY_PACKAGE_NAMES.has(name);
+}
+export const ENTRY_NAMES = ['broker', 'cli', 'daemon', 'launcher'];
+/** Entries every generation carries. Generations installed before the root
+ *  launcher existed lack `launcher`; a source-linked install moves `bin/` with
+ *  git while the installed generation stays put, so launching those older
+ *  generations must keep working for every entry they do carry. */
+const REQUIRED_ENTRY_NAMES = ['broker', 'cli', 'daemon'];
+
+function entryNamesSupported(entries) {
+  const names = Object.keys(entries);
+  return REQUIRED_ENTRY_NAMES.every((name) => names.includes(name)) && names.every((name) => ENTRY_NAMES.includes(name));
+}
+export const MANIFEST_KEYS = ['arch', 'createdAt', 'entries', 'files', 'id', 'nodeVersion', 'packageName', 'packageVersion', 'platform', 'schema'];
+
+/** Extract the Node major version number from a `process.version`-shaped
+ *  string (e.g. `v22.14.0` -> 22). Requires a complete `major.minor.patch`
+ *  version, ANCHORED at both ends: after the patch component there must be
+ *  either end-of-string or a valid semver `-`prerelease/`+`build suffix
+ *  (e.g. `v22.14.0-beta.1`), never trailing garbage. Without the end anchor
+ *  a malformed value like `v26.5.0not-a-node-version` would still match the
+ *  leading `26.5.0` and be silently accepted as major 26. Returns null when
+ *  unparsable. */
+const NODE_VERSION_PATTERN = /^v?(\d+)\.\d+\.\d+(?:[-+][0-9A-Za-z.-]*)?$/;
+export function nodeMajorVersion(version) {
+  const match = typeof version === 'string' ? NODE_VERSION_PATTERN.exec(version) : null;
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Two Node versions are ABI-compatible when they share the same major version
+ * (a correct, safe proxy for NODE_MODULE_VERSION/ABI compatibility — native
+ * addons are ABI-stable within a major, and differ across majors). Comparing
+ * the full version string is too strict: it rejects e.g. v22.22.0 against a
+ * v22.14.0-built generation even though nothing native actually changed.
+ */
+export function nodeVersionsCompatible(a, b) {
+  const majorA = nodeMajorVersion(a);
+  const majorB = nodeMajorVersion(b);
+  return majorA !== null && majorA === majorB;
+}
+
+/** Compare inventory paths with stable, locale-independent code-unit ordering. */
+export function compareFilePath(a, b) {
+  return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
+
+/** Return an inventory in the one canonical manifest order. */
+export function sortInventory(files) {
+  return [...files].sort(compareFilePath);
+}
+
+export function contained(root, candidate) {
+  const value = relative(root, candidate);
+  return value === '' || (!value.startsWith(`..${sep}`) && value !== '..' && !isAbsolute(value));
+}
+
+export function safeRelative(value) {
+  return typeof value === 'string' && value !== '' && !isAbsolute(value) && !value.split(/[\\/]/).includes('..');
+}
+
+export function parseSelectionTarget(target) {
+  const match = /^generations\/([a-f0-9]{64})$/.exec(target);
+  return match?.[1] ?? null;
+}
+
+/** Whether every directory and file under (and including) `root` is
+ *  non-writable — the sealed invariant `install-runtime.mjs` establishes via
+ *  `chmod(…, 0o555/0o444)` before switching `selected` (see `seal()` /
+ *  `validatePublished()` there). Shared, synchronous, and metadata-only so
+ *  the bootstrap fallback scan (`runtime-selector.mjs`) can apply the exact
+ *  same rule to sibling candidates without an async dependency. */
+export function isSealed(root) {
+  function unwritable(stat) {
+    return (stat.mode & 0o222) === 0;
+  }
+  function walk(dir) {
+    for (const name of readdirSync(dir)) {
+      const path = join(dir, name);
+      const stat = lstatSync(path);
+      if (stat.isDirectory()) {
+        if (!unwritable(stat) || !walk(path)) return false;
+      } else if (stat.isFile() && !unwritable(stat)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  try {
+    const rootStat = lstatSync(root);
+    return rootStat.isDirectory() && unwritable(rootStat) && walk(root);
+  } catch {
+    return false;
+  }
+}
+
+/** A metadata-only inventory (path + size, no content hash) of everything
+ *  under `root` except `generation.json` — structurally the same walk as the
+ *  installer's `inventory()`, but without reading file content. The
+ *  installer's one-time publish check can afford a full sha256 over every
+ *  byte; the bootstrap fallback scan runs on ordinary process launch and may
+ *  need to check several multi-hundred-MB sibling generations, so it uses
+ *  this cheaper size-based proxy instead. */
+export function sizeInventory(root) {
+  const files = [];
+  function walk(dir) {
+    for (const name of readdirSync(dir)) {
+      const absolute = join(dir, name);
+      const path = relative(root, absolute).split(sep).join('/');
+      if (path === 'generation.json') continue;
+      const stat = lstatSync(absolute);
+      if (stat.isDirectory()) walk(absolute);
+      else files.push({ path, size: stat.size });
+    }
+  }
+  walk(root);
+  return sortInventory(files);
+}
+
+/** Whether `root`'s on-disk inventory matches the manifest's declared
+ *  `files` list by path + size (see `sizeInventory` for why size, not
+ *  hash). Catches a generation renamed into `generations/` mid-install
+ *  before its manifest's `files` was written/finalized against reality. */
+export function inventoryMatches(root, declaredFiles) {
+  const actual = sizeInventory(root);
+  const declared = sortInventory(declaredFiles).map(({ path, size }) => ({ path, size }));
+  return actual.length === declared.length && JSON.stringify(actual) === JSON.stringify(declared);
+}
+
+/** Path of the atomic "fully published" marker for generation `id` — a
+ *  sibling of its directory under `generationsRoot`, deliberately NOT inside
+ *  the sealed generation root, so writing or removing it never requires
+ *  unsealing anything.
+ *
+ *  Ordering invariant (established by `scripts/install-runtime.mjs`): the
+ *  marker is written, atomically (temp file + rename, so the write itself
+ *  can't be observed half-done), STRICTLY AFTER `validatePublished()`'s full
+ *  content-hash check has succeeded for this exact id — i.e. after sealing
+ *  AND after every file's bytes have been re-hashed against the manifest.
+ *  Its presence is therefore proof the generation's on-disk bytes matched
+ *  the manifest at some point after sealing. That closes the corruption
+ *  window `isSealed()`/`inventoryMatches()` alone cannot: a same-size
+ *  corruption introduced between `chmod(root, 0o555)` and the installer's
+ *  full-hash check completing leaves the marker unwritten, so a candidate in
+ *  that window is simply ineligible. A same-size corruption of an
+ *  ALREADY-marked generation (disk bitrot after publication) is a distinct
+ *  scenario outside this invariant's scope — closing it would require
+ *  re-hashing every fallback candidate's full content on every process
+ *  launch, which this PR deliberately does not pay for one bootstrap scan
+ *  (see the review's accepted alternative). */
+export function publishedMarkerPath(generationsRoot, id) {
+  return join(generationsRoot, `${id}.published`);
+}
+
+/** Whether generation `id` carries the atomic published marker (see
+ *  `publishedMarkerPath`). Metadata-only and synchronous, matching
+ *  `isSealed`/`inventoryMatches`, so the bootstrap fallback scan can check it
+ *  with no async dependency. */
+export function isPublished(generationsRoot, id) {
+  try {
+    return lstatSync(publishedMarkerPath(generationsRoot, id)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** Normalize one manifest file entry to the shape `hashInventory` and a
+ *  declared `files` entry must agree on for comparison — `symlink` is
+ *  dropped when falsy so a real manifest's `undefined` and a synthetic
+ *  fixture's absent key compare equal. */
+function normalizeHashedEntry({ path, size, sha256, symlink }) {
+  return symlink ? { path, size, sha256, symlink: true } : { path, size, sha256 };
+}
+
+/** A full content-hash inventory of `root` (mirrors `install-runtime.mjs`'s
+ *  async `inventory()`, but synchronous, and used ONLY by the rare-path
+ *  legacy-fallback validation below — never on the primary launch path). */
+function hashInventory(root) {
+  const files = [];
+  function walk(dir) {
+    for (const name of readdirSync(dir)) {
+      const absolute = join(dir, name);
+      const path = relative(root, absolute).split(sep).join('/');
+      if (path === 'generation.json') continue;
+      const stat = lstatSync(absolute);
+      if (stat.isDirectory()) walk(absolute);
+      else if (stat.isFile()) files.push({ path, size: stat.size, sha256: createHash('sha256').update(readFileSync(absolute)).digest('hex') });
+      else if (stat.isSymbolicLink()) {
+        const target = readlinkSync(absolute);
+        files.push({ path, size: Buffer.byteLength(target), sha256: createHash('sha256').update(target).digest('hex'), symlink: true });
+      }
+    }
+  }
+  walk(root);
+  return sortInventory(files);
+}
+
+/** Whether `root`'s ACTUAL file content, fully re-hashed, matches every
+ *  declared `{ path, size, sha256 }` — the same full-content proof
+ *  `install-runtime.mjs`'s `validatePublished()` performs at publish time.
+ *  This is the legacy-fallback escape hatch for a markerless candidate (see
+ *  `isValidPublishedGeneration`): expensive (reads every byte), so it is
+ *  deliberately confined to the rare bootstrap-fallback-scan path and never
+ *  called for the primary `selected` load. Fails closed (returns false) on
+ *  any read error — an unreadable/ambiguous candidate is never admitted. */
+export function hashInventoryMatches(root, declaredFiles) {
+  try {
+    const actual = hashInventory(root).map(normalizeHashedEntry);
+    const declared = sortInventory(declaredFiles).map(normalizeHashedEntry);
+    return actual.length === declared.length && JSON.stringify(actual) === JSON.stringify(declared);
+  } catch {
+    return false;
+  }
+}
+
+/** The one predicate a fallback candidate must pass before it is eligible:
+ *  sealed AND inventory-consistent, AND EITHER carrying the atomic published
+ *  marker (the fast path — every generation installed by this PR's
+ *  `install-runtime.mjs`) OR passing full content-hash validation (the
+ *  legacy path — a generation installed BEFORE the marker existed, which is
+ *  markerless but still genuinely valid). The marker alone would reject
+ *  every pre-this-PR sibling and defeat Fix B's whole purpose (recovering a
+ *  machine whose `selected` generation was just built under a different
+ *  Node major) on exactly the upgrade this fix exists for, so an unmarked
+ *  candidate is never rejected outright — it just pays the full-hash cost
+ *  instead of the marker's O(1) check. Cost is confined to this rare
+ *  fallback-scan path; the primary `selected` load
+ *  (`readSelection`/`loadRuntime` in runtime-selector.mjs) does not call
+ *  this at all and stays ungated, unchanged vs main. Every error while
+ *  proving a fallback candidate is rejected locally rather than escaping the
+ *  sibling scan. The selector never writes a marker — marker writes remain
+ *  `install-runtime.mjs`'s alone. */
+export function isValidPublishedGeneration(root, declaredFiles, generationsRoot, id) {
+  try {
+    return isSealed(root) && inventoryMatches(root, declaredFiles) && (isPublished(generationsRoot, id) || hashInventoryMatches(root, declaredFiles));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate manifest metadata and the requested entry without accessing the filesystem.
+ * Full inventory verification belongs to installation and doctor, not process launch.
+ */
+export function validateManifestShape(manifest, { id, entryName }) {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest) || JSON.stringify(Object.keys(manifest).sort()) !== JSON.stringify(MANIFEST_KEYS)) {
+    return { ok: false, error: 'generation manifest has an unsupported schema or identity' };
+  }
+  if (!nodeVersionsCompatible(manifest.nodeVersion, process.version)) {
+    return {
+      ok: false,
+      code: 'node-version-mismatch',
+      error: `runtime generation was built for node ${manifest.nodeVersion}, this is ${process.version} — reinstall the runtime (\`npm run install-runtime\` / reinstall crouter)`,
+    };
+  }
+  if (manifest.schema !== MANIFEST_SCHEMA || manifest.id !== id || !GENERATION_ID.test(manifest.id) || !isKnownPackageName(manifest.packageName) || typeof manifest.packageVersion !== 'string' || manifest.packageVersion === '' || manifest.platform !== process.platform || manifest.arch !== process.arch || typeof manifest.createdAt !== 'string' || Number.isNaN(Date.parse(manifest.createdAt)) || !manifest.entries || typeof manifest.entries !== 'object' || Array.isArray(manifest.entries) || !entryNamesSupported(manifest.entries) || !Array.isArray(manifest.files)) {
+    return { ok: false, error: 'generation manifest has an unsupported schema or identity' };
+  }
+  const entry = manifest.entries[entryName];
+  if (!safeRelative(entry)) return { ok: false, error: `generation manifest has invalid ${entryName} entry` };
+  return { ok: true, entry };
+}