toolroll 0.9.75 → 0.9.77

package/dist/test-infra.d.ts

@@ -0,0 +1,26 @@
+/** The product's entry points: the CLI binary, the processes it starts by file name, and the browser bundles. */
+export declare const PRODUCT_ENTRIES: readonly string[];
+/** A specifier reached from the tests that names no repository file and no known package: `prefix` is the repository
+ * path it might name (a folder or file stem), or null when it might name anything. */
+export type Unresolved = {
+    from: string;
+    specifier: string | null;
+    prefix: string | null;
+};
+export type TestInfrastructure = {
+    infra: Set<string>;
+    unresolved: Unresolved[];
+    /** What the product's entry points reach (trusted product code, by Alex's decision). */
+    product: Set<string>;
+};
+/**
+ * The infrastructure among `files` (path → text: the tree's sources, and its tsconfig.json and package.json): reachable
+ * from a test root — every test file, every file under `test/`, every vitest config and its setup files — not itself a
+ * test, and not reachable from PRODUCT_ENTRIES; plus every specifier reached from a test root that couldn't be resolved.
+ */
+export declare function testInfrastructure(files: ReadonlyMap<string, string>, allPaths?: ReadonlySet<string>): TestInfrastructure;
+/**
+ * Whether a changed path is something an unresolved specifier might name. A computed one (no prefix) might name anything
+ * the other rules don't already trust: any source file that is neither a test nor product code.
+ */
+export declare function mightName(open: Unresolved, path: string, found: TestInfrastructure): boolean;

package/dist/test-infra.js

@@ -0,0 +1,321 @@
+/**
+ * Test infrastructure, found structurally (docs/plans/auto-approve-green.md): every non-test source file that the tests
+ * or the test runner's own setup import, directly or through other files, and that the product's entry points never
+ * reach. Changing one changes how tests check things — an automatic release approval leaves that to a person.
+ *
+ * Imports are read with the TypeScript compiler (typescript-parser, a runtime dependency): `preProcessFile` for static,
+ * dynamic and `require` specifiers (comments never count), and the syntax tree for dynamic imports or requires whose
+ * specifier isn't a plain string. Specifiers resolve as the build resolves them: relative paths (`./x.js` → `./x.ts`),
+ * the project's tsconfig `paths`, and package.json `imports`. Fail closed: a specifier reached from the tests that
+ * resolves to no file and to no known package is "unresolved", with what it might name, and the caller refuses when the
+ * change touches anything it might name.
+ */
+import { createRequire } from "node:module";
+import { builtinModules } from "node:module";
+let compiler;
+const typescript = () => compiler ??= createRequire(import.meta.url)("typescript-parser");
+const SOURCE = /\.(?:[cm]?[jt]sx?)$/;
+const TEST = /\.test\.[cm]?[jt]sx?$/;
+const VITEST_CONFIG = /(^|\/)vitest\.config\.[cm]?[jt]s$/;
+const EXTENSIONS = ["ts", "tsx", "mts", "cts", "js", "mjs", "cjs", "jsx"];
+/** The product's entry points: the CLI binary, the processes it starts by file name, and the browser bundles. */
+export const PRODUCT_ENTRIES = Object.freeze([
+    "src/bin.ts", "src/cli.ts", "src/controller-service.ts", "src/up-role-child.ts", "src/desktop-host.ts", "src/sandbox-launch.ts", "src/tool-launcher.ts",
+    "src/browser/app.tsx", "src/browser/terminal-app.tsx",
+]);
+const join = (dir, spec) => {
+    const parts = dir === "" ? [] : dir.split("/");
+    for (const part of spec.split("/")) {
+        if (part === "." || part === "")
+            continue;
+        if (part === "..") {
+            if (parts.length === 0)
+                return null;
+            parts.pop();
+        }
+        else
+            parts.push(part);
+    }
+    return parts.join("/");
+};
+const dirOf = (path) => path.split("/").slice(0, -1).join("/");
+/** A repository path, tried as the build tries it (with or without its extension, or as a folder's index). */
+function fileAt(target, files) {
+    const stem = target.replace(/\.(?:[cm]?js|jsx)$/, "");
+    const tries = [target, ...EXTENSIONS.map(ext => `${stem}.${ext}`), ...EXTENSIONS.map(ext => `${target}/index.${ext}`)];
+    return tries.find(one => files.has(one)) ?? null;
+}
+/** The project's resolution rules, read from its own tsconfig.json and package.json (as text in the same tree). */
+function resolverFor(files, names, allPaths, aliases) {
+    const tsc = typescript();
+    let paths = {}, baseUrl = "";
+    const config = files.get("tsconfig.json");
+    if (config !== undefined) {
+        const parsed = tsc.parseConfigFileTextToJson("tsconfig.json", config).config;
+        paths = parsed?.compilerOptions?.paths ?? {};
+        baseUrl = join("", parsed?.compilerOptions?.baseUrl ?? ".") ?? "";
+    }
+    let pkg = {};
+    try {
+        pkg = JSON.parse(files.get("package.json") ?? "{}");
+    }
+    catch {
+        pkg = {};
+    }
+    const packages = new Set([pkg.dependencies, pkg.devDependencies, pkg.peerDependencies, pkg.optionalDependencies].flatMap(one => Object.keys(one ?? {})));
+    // The package's own name resolves to itself: never "some installed package".
+    const own = typeof pkg.name === "string" ? pkg.name : null;
+    const builtins = new Set(builtinModules);
+    const pattern = (key, spec) => {
+        if (!key.includes("*"))
+            return key === spec ? "" : null;
+        const [head, tail] = key.split("*");
+        return spec.startsWith(head) && spec.endsWith(tail) && spec.length >= head.length + tail.length ? spec.slice(head.length, spec.length - tail.length) : null;
+    };
+    return (from, spec) => {
+        // vitest's own aliases come first, as vitest applies them.
+        for (const alias of aliases) {
+            if (spec !== alias.find && !spec.startsWith(`${alias.find}/`))
+                continue;
+            const target = join(alias.replacement, spec.slice(alias.find.length).replace(/^\//, ""));
+            const file = target === null ? null : fileAt(target, names);
+            return file !== null ? { file } : { unresolved: target };
+        }
+        if (spec.startsWith("./") || spec.startsWith("../")) {
+            const target = join(dirOf(from), spec);
+            const file = target === null ? null : fileAt(target, names);
+            if (file !== null)
+                return { file };
+            // A file that isn't source (a stylesheet, JSON, an asset) is a leaf: it imports nothing.
+            if (target !== null && allPaths.has(target))
+                return { external: true };
+            return { unresolved: target };
+        }
+        for (const [key, targets] of Object.entries(paths)) {
+            const star = pattern(key, spec);
+            if (star === null)
+                continue;
+            for (const one of targets) {
+                const target = join(baseUrl, one.replace("*", star));
+                const file = target === null ? null : fileAt(target, names);
+                if (file !== null)
+                    return { file };
+            }
+            return { unresolved: join(baseUrl, (targets[0] ?? "").replace("*", star)) };
+        }
+        if (spec.startsWith("#")) {
+            for (const [key, value] of Object.entries(pkg.imports ?? {})) {
+                const star = pattern(key, spec);
+                if (star === null)
+                    continue;
+                const target = typeof value === "string" ? value : typeof value?.default === "string" ? value.default : null;
+                if (target === null)
+                    return { unresolved: null };
+                const path = join("", target.replace("*", star));
+                const file = path === null ? null : fileAt(path, names) ?? fileAt(path.replace(/^dist\//, "src/"), names);
+                return file !== null ? { file } : { unresolved: path };
+            }
+            return { unresolved: null };
+        }
+        const bare = spec.startsWith("node:") ? spec.slice(5) : spec;
+        const name = bare.startsWith("@") ? bare.split("/").slice(0, 2).join("/") : bare.split("/")[0];
+        if (name === own)
+            return { unresolved: null };
+        if (spec.startsWith("node:") || builtins.has(name) || packages.has(name))
+            return { external: true };
+        // A package the manifest doesn't declare: what it names can't be known here.
+        return { unresolved: null };
+    };
+}
+/** The module-loading helpers vitest offers: each takes a specifier first. */
+const VI_LOADERS = new Set(["mock", "doMock", "unmock", "doUnmock", "importActual", "importMock"]);
+/**
+ * Every specifier a file names: string ones (preProcessFile: static, dynamic, `require`; comments don't count); every
+ * call that loads a module from its first argument — `require`, `import()`, `createRequire(…)(…)` and any name bound to
+ * `createRequire(…)`, `vi.*`/`vitest.*` mock and import helpers — whose argument isn't a plain string is computed (`null`,
+ * or the template's literal head); and `soft`: every other relative string literal, an edge when it names a repo file.
+ */
+function specifiersOf(path, text) {
+    const tsc = typescript();
+    const literal = tsc.preProcessFile(text, true, true).importedFiles.map(one => one.fileName);
+    const computed = [], soft = [];
+    const source = tsc.createSourceFile(path, text, tsc.ScriptTarget.Latest, false, /x$/.test(path) ? tsc.ScriptKind.TSX : tsc.ScriptKind.TS);
+    // Names bound to createRequire(…) anywhere in the file (a loader by another name).
+    const requires = new Set(["require"]);
+    const isCreateRequire = (node) => tsc.isCallExpression(node) && ((tsc.isIdentifier(node.expression) && node.expression.text === "createRequire")
+        || (tsc.isPropertyAccessExpression(node.expression) && node.expression.name.text === "createRequire"));
+    const bind = (node) => {
+        if (tsc.isVariableDeclaration(node) && tsc.isIdentifier(node.name) && node.initializer !== undefined && isCreateRequire(node.initializer))
+            requires.add(node.name.text);
+        if (tsc.isBinaryExpression(node) && node.operatorToken.kind === tsc.SyntaxKind.EqualsToken && tsc.isIdentifier(node.left) && isCreateRequire(node.right))
+            requires.add(node.left.text);
+        tsc.forEachChild(node, bind);
+    };
+    bind(source);
+    const loader = (callee) => callee.kind === tsc.SyntaxKind.ImportKeyword
+        || (tsc.isIdentifier(callee) && requires.has(callee.text))
+        || isCreateRequire(callee)
+        || (tsc.isPropertyAccessExpression(callee) && tsc.isIdentifier(callee.expression) && (callee.expression.text === "vi" || callee.expression.text === "vitest") && VI_LOADERS.has(callee.name.text))
+        || (tsc.isPropertyAccessExpression(callee) && callee.name.text === "require");
+    const visit = (node) => {
+        if (tsc.isCallExpression(node)) {
+            const first = node.arguments[0];
+            if (loader(node.expression) && first !== undefined) {
+                if (tsc.isStringLiteral(first) || tsc.isNoSubstitutionTemplateLiteral(first))
+                    literal.push(first.text);
+                else
+                    computed.push(tsc.isTemplateExpression(first) && (first.head.text.startsWith("./") || first.head.text.startsWith("../")) ? first.head.text : null);
+            }
+        }
+        if ((tsc.isStringLiteral(node) || tsc.isNoSubstitutionTemplateLiteral(node)) && (node.text.startsWith("./") || node.text.startsWith("../")))
+            soft.push(node.text);
+        tsc.forEachChild(node, visit);
+    };
+    visit(source);
+    return { literal, computed, soft };
+}
+/**
+ * The vitest configs' `resolve.alias` and `test.alias` (string keys to string paths, as an object or a list of
+ * `{ find, replacement }`), and whether any alias couldn't be read statically.
+ */
+function vitestAliases(files) {
+    const tsc = typescript(), aliases = [], unreadable = [];
+    for (const [path, text] of files) {
+        if (!VITEST_CONFIG.test(path))
+            continue;
+        const source = tsc.createSourceFile(path, text, tsc.ScriptTarget.Latest, false, tsc.ScriptKind.TS);
+        const text_ = (node) => node !== undefined && (tsc.isStringLiteral(node) || tsc.isNoSubstitutionTemplateLiteral(node)) ? node.text : null;
+        const visit = (node) => {
+            if (tsc.isPropertyAssignment(node) && (tsc.isIdentifier(node.name) || tsc.isStringLiteral(node.name)) && node.name.text === "alias") {
+                const value = node.initializer;
+                const add = (find, replacement) => {
+                    if (find === null || replacement === null || !(replacement.startsWith("./") || replacement.startsWith("../"))) {
+                        unreadable.push(path);
+                        return;
+                    }
+                    const target = join(dirOf(path), replacement);
+                    if (target === null)
+                        unreadable.push(path);
+                    else
+                        aliases.push({ find, replacement: target });
+                };
+                if (tsc.isObjectLiteralExpression(value)) {
+                    for (const property of value.properties) {
+                        if (!tsc.isPropertyAssignment(property)) {
+                            unreadable.push(path);
+                            continue;
+                        }
+                        add(tsc.isIdentifier(property.name) || tsc.isStringLiteral(property.name) ? property.name.text : null, text_(property.initializer));
+                    }
+                }
+                else if (tsc.isArrayLiteralExpression(value)) {
+                    for (const element of value.elements) {
+                        if (!tsc.isObjectLiteralExpression(element)) {
+                            unreadable.push(path);
+                            continue;
+                        }
+                        const field = (name) => element.properties.find((one) => tsc.isPropertyAssignment(one) && (tsc.isIdentifier(one.name) || tsc.isStringLiteral(one.name)) && one.name.text === name)?.initializer;
+                        add(text_(field("find")), text_(field("replacement")));
+                    }
+                }
+                else
+                    unreadable.push(path);
+            }
+            tsc.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    return { aliases, unreadable };
+}
+/** The vitest configs' setupFiles and globalSetup entries (string literals), as repository paths. */
+function setupRoots(files, names) {
+    const tsc = typescript(), roots = [], unresolved = [];
+    for (const [path, text] of files) {
+        if (!VITEST_CONFIG.test(path))
+            continue;
+        const source = tsc.createSourceFile(path, text, tsc.ScriptTarget.Latest, false, tsc.ScriptKind.TS);
+        const visit = (node) => {
+            if (tsc.isPropertyAssignment(node) && (tsc.isIdentifier(node.name) || tsc.isStringLiteral(node.name)) && (node.name.text === "setupFiles" || node.name.text === "globalSetup")) {
+                const values = tsc.isArrayLiteralExpression(node.initializer) ? [...node.initializer.elements] : [node.initializer];
+                for (const value of values) {
+                    if (!tsc.isStringLiteral(value)) {
+                        unresolved.push({ from: path, specifier: null, prefix: null });
+                        continue;
+                    }
+                    // vitest resolves them from its root: the config's own folder, or the repository root a config names.
+                    const found = [dirOf(path), ""].map(dir => { const target = join(dir, value.text); return target === null ? null : fileAt(target, names); }).find(one => one !== null) ?? null;
+                    if (found !== null)
+                        roots.push(found);
+                    else
+                        unresolved.push({ from: path, specifier: value.text, prefix: join("", value.text) });
+                }
+            }
+            tsc.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    return { roots, unresolved };
+}
+/**
+ * The infrastructure among `files` (path → text: the tree's sources, and its tsconfig.json and package.json): reachable
+ * from a test root — every test file, every file under `test/`, every vitest config and its setup files — not itself a
+ * test, and not reachable from PRODUCT_ENTRIES; plus every specifier reached from a test root that couldn't be resolved.
+ */
+export function testInfrastructure(files, allPaths = new Set(files.keys())) {
+    const names = new Set([...files.keys()].filter(path => SOURCE.test(path)));
+    const vitest = vitestAliases(files);
+    const resolve = resolverFor(files, names, allPaths, vitest.aliases);
+    const edges = new Map(), loose = new Map();
+    for (const path of names) {
+        const { literal, computed, soft } = specifiersOf(path, files.get(path));
+        const targets = new Set(), open = [];
+        for (const spec of literal) {
+            const found = resolve(path, spec);
+            if ("file" in found)
+                targets.add(found.file);
+            else if ("unresolved" in found)
+                open.push({ from: path, specifier: spec, prefix: found.unresolved });
+        }
+        for (const head of computed)
+            open.push({ from: path, specifier: head, prefix: head === null ? null : join(dirOf(path), head) });
+        // Any other relative string that names a repository source file is an edge (a path handed to a loader by any name).
+        for (const spec of soft) {
+            const found = resolve(path, spec);
+            if ("file" in found)
+                targets.add(found.file);
+        }
+        edges.set(path, [...targets]);
+        loose.set(path, open);
+    }
+    const setup = setupRoots(files, names);
+    const testRoots = [...[...names].filter(path => TEST.test(path) || path.startsWith("test/") || VITEST_CONFIG.test(path)), ...setup.roots];
+    const reach = (roots) => {
+        const seen = new Set(), todo = [...roots];
+        while (todo.length > 0) {
+            const at = todo.pop();
+            if (seen.has(at))
+                continue;
+            seen.add(at);
+            for (const next of edges.get(at) ?? [])
+                if (!seen.has(next))
+                    todo.push(next);
+        }
+        return seen;
+    };
+    const product = reach(PRODUCT_ENTRIES.filter(path => names.has(path)));
+    const tested = reach(testRoots);
+    const infra = new Set([...tested].filter(path => !TEST.test(path) && !product.has(path)));
+    const unresolved = [...setup.unresolved, ...vitest.unreadable.map(from => ({ from, specifier: null, prefix: null })), ...[...tested].flatMap(path => loose.get(path) ?? [])];
+    return { infra, unresolved, product };
+}
+/**
+ * Whether a changed path is something an unresolved specifier might name. A computed one (no prefix) might name anything
+ * the other rules don't already trust: any source file that is neither a test nor product code.
+ */
+export function mightName(open, path, found) {
+    if (open.prefix === null)
+        return SOURCE.test(path) && !TEST.test(path) && !found.product.has(path);
+    const prefix = open.prefix.replace(/\/$/, "");
+    const stem = path.replace(/\.[^/.]+$/, "");
+    return path === prefix || stem === prefix.replace(/\.(?:[cm]?js|jsx)$/, "") || path.startsWith(`${prefix}/`) || (open.specifier !== null && open.specifier.endsWith("/") === false && path.startsWith(prefix));
+}

package/dist/up-processes.d.ts

@@ -0,0 +1,137 @@
+export type UpRoleName = "console" | "worker";
+export type UpConsoleConfig = {
+    host: string;
+    port: number;
+    allowedHosts: string[] | null;
+    publicUrl: string | null;
+    localRunner: string;
+    poolRoot: string;
+    repos: string[];
+    projectRoots: string[];
+    registryPath: string;
+    editor: boolean;
+};
+export type UpWorkerConfig = {
+    runner: string;
+    token: string;
+    repos: string[];
+    pinnedRepos: string[];
+    projectRoots: string[];
+    registryPath: string;
+    pool: string;
+    forMs: number | null;
+    publicUrl: string | null;
+    stopGraceMs: number;
+    verbose: boolean;
+    terminal: boolean;
+    /** How long a start waits for a predecessor's watch lease to expire (a crashed worker's, after a restart). */
+    leaseWaitMs: number;
+};
+export type UpRoleStart = {
+    type: "start";
+    role: "console";
+    databaseFile: string;
+    containment: string | null;
+    build: string;
+    config: UpConsoleConfig;
+} | {
+    type: "start";
+    role: "worker";
+    databaseFile: string;
+    containment: string | null;
+    build: string;
+    config: UpWorkerConfig;
+};
+export type ParentToRole = {
+    type: "repos";
+    repos: string[];
+} | {
+    type: "stopping";
+} | {
+    type: "hard-stop";
+} | {
+    type: "sign-in-link";
+    id: number;
+    account: string;
+};
+export type RoleToParent = {
+    type: "ready";
+    role: UpRoleName;
+    build: string;
+    pid: number;
+    url: string | null;
+    port: number | null;
+} | {
+    type: "log";
+    line: string;
+} | {
+    type: "repos";
+    repos: string[];
+} | {
+    type: "failed";
+    reason: "port-busy" | "start";
+    detail: string;
+} | {
+    type: "fatal";
+    detail: string;
+} | {
+    type: "sign-in-link";
+    id: number;
+    link: string | null;
+} | {
+    type: "closed";
+    problem: string | null;
+};
+/** One role's side of the channel: the same shape over IPC (a child process) and in memory (one process). */
+export type RolePort = {
+    send: (message: RoleToParent) => void;
+    onMessage: (handler: (message: ParentToRole) => void) => void;
+    /** First call: drain. Every later call: stop now (the second signal's hard stop). */
+    onStop: (handler: (hard: boolean) => void) => void;
+};
+/** The parent's word to a role, checked before anything acts on it. */
+export declare function parentMessage(value: unknown): ParentToRole | null;
+/** A role's word to the parent, checked before the parent relays or acts on it. */
+export declare function roleMessage(value: unknown, role: UpRoleName): RoleToParent | null;
+/** The start message a role child waits for. The console's config carries no runner token; anything else refuses. */
+export declare function startMessage(value: unknown): UpRoleStart | null;
+/** Two ends of an in-memory channel: one process composing both roles (tests and the desktop host), same messages. */
+export declare function memoryChannel(role: UpRoleName): {
+    port: RolePort;
+    parent: {
+        send: (message: ParentToRole) => void;
+        onMessage: (handler: (message: RoleToParent) => void) => void;
+        stop: (hard: boolean) => void;
+    };
+};
+/** A build identity: the version and the exact code of the module that composes `up`. Both roles must report the
+ * parent's own, or the parent stops rather than run a console and a worker from different builds. */
+export declare function buildIdentity(version: string, moduleFile: string): string;
+/** How many replacements in a row may end before becoming ready, with no refusal said, before `up` stops. */
+export declare const ROLE_NOT_READY_REPLACEMENTS = 3;
+/**
+ * One supervised role's generations (Codex review round 1, finding 5): readiness is per generation, not for the role's
+ * whole life. When a generation ends, the verdict is:
+ * - `fail-start`: the role never became ready at all; the start fails as one, as before the split;
+ * - `restart`: this generation was ready and crashed afterwards (the supervisor starts it again);
+ * - `end`: a replacement refused to start (another build, another database, a start refused) — permanent, so the whole
+ *   `up` stops rather than loop — or ROLE_NOT_READY_REPLACEMENTS replacements in a row ended before readiness.
+ */
+export declare class RoleGenerations {
+    private everReady;
+    private generationReady;
+    private refusal;
+    private notReadyStreak;
+    /** A new generation was spawned: nothing about it is known yet. */
+    spawned(): void;
+    /** This generation became ready; true when it is the role's first readiness ever. */
+    ready(): boolean;
+    /** This generation refused its start for good (it said why, or its build is another). */
+    refused(detail: string): void;
+    /** What this generation said when it refused, if it did. */
+    refusedWith(): string | null;
+    /** Whether any generation ever became ready. */
+    wasReady(): boolean;
+    /** This generation ended (not stopped by `up`): what happens next. */
+    ended(): "fail-start" | "restart" | "end";
+}

package/dist/up-processes.js

@@ -0,0 +1,165 @@
+/**
+ * `toolroll up` as two processes (docs/plans/isolated-checks.md, stage 1): the console (HTTP: serving, reading and the
+ * person's ceremonies) and the worker (the watch loops: builds, checks, batch checks, follow-ups, reconcilers, the
+ * storage sweep and checkout sizing). `up` itself keeps the identities it minted (the approver's login, the runner and
+ * its token), supervises both with controller-supervisor, and relays between them. Nothing here grants authority:
+ * each role is handed only what it needs, by message, never on a command line or in the environment.
+ *
+ * What each holds:
+ *   console  the database, the console's own session and sign-in secrets, the attach (instance) secret, push keys, the
+ *            port. Never the runner token: it can't claim, lease or build.
+ *   worker   the database and the runner name and token, for the watch leases and claims. It opens no port and mints
+ *            no console session or attach secret.
+ * Both are the same user on the same database folder, so files beside the database (the saved login, tool secrets)
+ * are reachable by either: the split keeps secrets out of each other's memory and messages, not out of the folder.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+const MAX_TEXT = 16_384;
+const MAX_LIST = 4_096;
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (value, max = MAX_TEXT) => typeof value === "string" && value.length <= max;
+const nonEmpty = (value, max = MAX_TEXT) => text(value, max) && value !== "" && !value.includes("\0");
+const texts = (value) => Array.isArray(value) && value.length <= MAX_LIST && value.every(one => nonEmpty(one));
+const whole = (value, min = 0, max = 2_147_483_647) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= max;
+const orNull = (value, check) => value === null || check(value);
+/** The parent's word to a role, checked before anything acts on it. */
+export function parentMessage(value) {
+    if (!isObject(value))
+        return null;
+    switch (value["type"]) {
+        case "repos": return texts(value["repos"]) ? { type: "repos", repos: [...value["repos"]] } : null;
+        case "stopping": return { type: "stopping" };
+        case "hard-stop": return { type: "hard-stop" };
+        case "sign-in-link": return whole(value["id"]) && nonEmpty(value["account"], 256) ? { type: "sign-in-link", id: value["id"], account: value["account"] } : null;
+        default: return null;
+    }
+}
+/** A role's word to the parent, checked before the parent relays or acts on it. */
+export function roleMessage(value, role) {
+    if (!isObject(value))
+        return null;
+    switch (value["type"]) {
+        case "ready":
+            if (value["role"] !== role || !nonEmpty(value["build"], 512) || !whole(value["pid"], 1))
+                return null;
+            if (!orNull(value["url"], (one) => nonEmpty(one, 2_048)) || !orNull(value["port"], (one) => whole(one, 1, 65_535)))
+                return null;
+            // Only the console serves: a worker that names an address is not a worker.
+            if (role === "worker" && (value["url"] !== null || value["port"] !== null))
+                return null;
+            if (role === "console" && (value["url"] === null || value["port"] === null))
+                return null;
+            return { type: "ready", role, build: value["build"], pid: value["pid"], url: value["url"], port: value["port"] };
+        case "log": return text(value["line"]) ? { type: "log", line: value["line"] } : null;
+        case "repos": return role === "worker" && texts(value["repos"]) ? { type: "repos", repos: [...value["repos"]] } : null;
+        case "failed": return (value["reason"] === "port-busy" || value["reason"] === "start") && text(value["detail"]) ? { type: "failed", reason: value["reason"], detail: value["detail"] } : null;
+        case "fatal": return text(value["detail"]) ? { type: "fatal", detail: value["detail"] } : null;
+        case "sign-in-link": return role === "console" && whole(value["id"]) && orNull(value["link"], (one) => nonEmpty(one, 2_048)) ? { type: "sign-in-link", id: value["id"], link: value["link"] } : null;
+        case "closed": return orNull(value["problem"], (one) => text(one)) ? { type: "closed", problem: value["problem"] } : null;
+        default: return null;
+    }
+}
+/** The start message a role child waits for. The console's config carries no runner token; anything else refuses. */
+export function startMessage(value) {
+    if (!isObject(value) || value["type"] !== "start" || !nonEmpty(value["databaseFile"], 4_096) || !orNull(value["containment"], (one) => nonEmpty(one, 64)) || !nonEmpty(value["build"], 512))
+        return null;
+    const config = value["config"];
+    if (!isObject(config))
+        return null;
+    const base = { type: "start", databaseFile: value["databaseFile"], containment: value["containment"], build: value["build"] };
+    if (value["role"] === "console") {
+        const keys = ["host", "port", "allowedHosts", "publicUrl", "localRunner", "poolRoot", "repos", "projectRoots", "registryPath", "editor"];
+        if (Object.keys(config).some(key => !keys.includes(key)))
+            return null;
+        if (!nonEmpty(config["host"], 253) || !whole(config["port"], 0, 65_535) || !orNull(config["allowedHosts"], texts) || !orNull(config["publicUrl"], (one) => nonEmpty(one, 2_048)) ||
+            !nonEmpty(config["localRunner"], 256) || !nonEmpty(config["poolRoot"], 4_096) || !texts(config["repos"]) || !texts(config["projectRoots"]) || !nonEmpty(config["registryPath"], 4_096) || typeof config["editor"] !== "boolean")
+            return null;
+        return { ...base, role: "console", config: config };
+    }
+    if (value["role"] === "worker") {
+        const keys = ["runner", "token", "repos", "pinnedRepos", "projectRoots", "registryPath", "pool", "forMs", "publicUrl", "stopGraceMs", "verbose", "terminal", "leaseWaitMs"];
+        if (Object.keys(config).some(key => !keys.includes(key)))
+            return null;
+        if (!nonEmpty(config["runner"], 256) || !nonEmpty(config["token"], 1_024) || !texts(config["repos"]) || !texts(config["pinnedRepos"]) || !texts(config["projectRoots"]) ||
+            !nonEmpty(config["registryPath"], 4_096) || !nonEmpty(config["pool"], 4_096) || !orNull(config["forMs"], (one) => whole(one, 1)) ||
+            !orNull(config["publicUrl"], (one) => nonEmpty(one, 2_048)) || !whole(config["stopGraceMs"], 0) || typeof config["verbose"] !== "boolean" || typeof config["terminal"] !== "boolean" || !whole(config["leaseWaitMs"], 0))
+            return null;
+        return { ...base, role: "worker", config: config };
+    }
+    return null;
+}
+/** Two ends of an in-memory channel: one process composing both roles (tests and the desktop host), same messages. */
+export function memoryChannel(role) {
+    const toParent = [];
+    const toRole = [];
+    const stops = [];
+    // Delivered on a later turn, as IPC would be, and through the same checks: a role can't lean on synchronous replies.
+    const later = (fn) => { queueMicrotask(fn); };
+    return {
+        port: {
+            send: message => { const checked = roleMessage(JSON.parse(JSON.stringify(message)), role); if (checked !== null)
+                later(() => { for (const one of toParent)
+                    one(checked); }); },
+            onMessage: handler => { toRole.push(handler); },
+            onStop: handler => { stops.push(handler); },
+        },
+        parent: {
+            send: message => { const checked = parentMessage(JSON.parse(JSON.stringify(message))); if (checked !== null)
+                later(() => { for (const one of toRole)
+                    one(checked); }); },
+            onMessage: handler => { toParent.push(handler); },
+            stop: hard => { for (const one of stops)
+                one(hard); },
+        },
+    };
+}
+/** A build identity: the version and the exact code of the module that composes `up`. Both roles must report the
+ * parent's own, or the parent stops rather than run a console and a worker from different builds. */
+export function buildIdentity(version, moduleFile) {
+    let digest = `unreadable-${randomUUID()}`;
+    try {
+        digest = createHash("sha256").update(readFileSync(moduleFile)).digest("hex").slice(0, 16);
+    }
+    catch { /* unique: never equal to any other identity */ }
+    return `${version}+${digest}`;
+}
+/** How many replacements in a row may end before becoming ready, with no refusal said, before `up` stops. */
+export const ROLE_NOT_READY_REPLACEMENTS = 3;
+/**
+ * One supervised role's generations (Codex review round 1, finding 5): readiness is per generation, not for the role's
+ * whole life. When a generation ends, the verdict is:
+ * - `fail-start`: the role never became ready at all; the start fails as one, as before the split;
+ * - `restart`: this generation was ready and crashed afterwards (the supervisor starts it again);
+ * - `end`: a replacement refused to start (another build, another database, a start refused) — permanent, so the whole
+ *   `up` stops rather than loop — or ROLE_NOT_READY_REPLACEMENTS replacements in a row ended before readiness.
+ */
+export class RoleGenerations {
+    everReady = false;
+    generationReady = false;
+    refusal = null;
+    notReadyStreak = 0;
+    /** A new generation was spawned: nothing about it is known yet. */
+    spawned() { this.generationReady = false; this.refusal = null; }
+    /** This generation became ready; true when it is the role's first readiness ever. */
+    ready() { const first = !this.everReady; this.everReady = true; this.generationReady = true; return first; }
+    /** This generation refused its start for good (it said why, or its build is another). */
+    refused(detail) { this.refusal = detail; }
+    /** What this generation said when it refused, if it did. */
+    refusedWith() { return this.refusal; }
+    /** Whether any generation ever became ready. */
+    wasReady() { return this.everReady; }
+    /** This generation ended (not stopped by `up`): what happens next. */
+    ended() {
+        if (!this.everReady)
+            return "fail-start";
+        if (this.refusal !== null)
+            return "end";
+        if (this.generationReady) {
+            this.notReadyStreak = 0;
+            return "restart";
+        }
+        this.notReadyStreak += 1;
+        return this.notReadyStreak >= ROLE_NOT_READY_REPLACEMENTS ? "end" : "restart";
+    }
+}

package/dist/up-role-child.d.ts

@@ -0,0 +1 @@
+export {};