@catalyst-cloud/cli 0.14.9 → 0.15.0

package/dist/onboard-runner.js

@@ -0,0 +1,780 @@
+import { spawn } from "node:child_process";
+import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { hostname, tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadConfig, normalizeBaseUrl, packageRoot } from "./config.js";
+import { nativeEgressReady, NATIVE_EGRESS_DIR } from "./onboard-runner-egress.js";
+import { runnerAdmission, issueRunnerOrgKey, verifyRunnerRoutes } from "./onboard-runner-cloud.js";
+import { verifyOnboardRoutes } from "./onboard-capabilities.js";
+import { liveTeamKey, onboardTeamAdmission } from "./onboard-capacity.js";
+import { readExistingOnboardJson, selectedOnboardTeam, } from "./onboard-existing.js";
+import { onboardStateRoot, } from "./onboard.js";
+// "Run Catalyst's work on this machine": the self-hosted host from catalyst-cloud's deploy/self-host
+// (a supervisor and a deadline watchdog under Compose), enrolled with the person's own owner or
+// admin login. Never the operator token. Missing host images are pulled anonymously with an empty
+// disposable Docker config. Customer delivery uses public GHCR pins, without registry credentials.
+/** The Compose project name the vendored file declares. */
+export const RUNNER_PROJECT = "catalyst-host";
+export const RUNNER_SESSION_NETWORK = "catalyst-session-v1";
+/** Public multi-architecture images: host images from main 0b5495e144 (run 36999325814),
+ * runner from main 48b5876e56 (run 37057503445). Explicit environment image values override
+ * these pins; the runner also preserves a saved image before choosing its default. */
+export const RUNNER_HOST_IMAGES = {
+    supervisor: "ghcr.io/coalesce-labs/catalyst-supervisor@sha256:fff1582e3ef763eae6728f195a8e3834383955ee03d39bcfe567f4a7361a8982",
+    watchdog: "ghcr.io/coalesce-labs/catalyst-deadline-watchdog@sha256:b64e38f9ee34240d1e3d256e954eb8de20e2d3e51ed873019d350aa60be639c1",
+    runner: "ghcr.io/coalesce-labs/catalyst-runner@sha256:50eeb256b4693fc42c81458bdfc887137a0df757260601f2a869738578d00782",
+};
+const IMAGE_REF = /^[a-z0-9][a-z0-9._:/-]{0,255}@sha256:[0-9a-f]{64}$/;
+const HOST_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/;
+const JOIN_TOKEN = /^[A-Za-z0-9._~+/=-]{16,1024}$/;
+const ENROLLMENTS = "/api/v1/hosts/enrollments";
+const JOIN_TOKENS = "/api/v1/hosts/join-tokens";
+const CAPACITY = "/api/v1/me/runner-capacity";
+const RUNNER_UID = "10001:10001";
+const DIRS = ["slots", "thoughts", "locks"];
+function isUnenrolled(value) {
+    return value !== null && "unenrolled" in value;
+}
+const spawnDocker = (args, options) => new Promise((resolve, reject) => {
+    const child = spawn("docker", args, {
+        env: options.env,
+        cwd: options.cwd,
+        signal: options.signal,
+        timeout: options.timeoutMs ?? 30_000,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "", stderr = "";
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => { if (stderr.length < 1_000_000)
+        stderr += chunk; });
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        if (stdout.length < 1_000_000)
+            stdout += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    child.stdin.end(options.input ?? "");
+});
+/** The real engine, through the docker CLI. Compose reads `.env` only: the caller's CATALYST_ and
+ * DOCKER_SOCKET_ variables are removed, because Compose prefers an exported value over the file. */
+export function dockerRunnerEngine(deps = {}) {
+    const exec = deps.exec ?? spawnDocker;
+    const env = Object.fromEntries(Object.entries(deps.env ?? process.env).filter(([key]) => !key.startsWith("CATALYST_") && !key.startsWith("DOCKER_SOCKET_")));
+    const docker = async (args, options = {}) => {
+        try {
+            return await exec(args, { env, ...options });
+        }
+        catch {
+            return { code: 1, stdout: "" };
+        }
+    };
+    const compose = (dir) => [
+        "compose",
+        "--project-name",
+        RUNNER_PROJECT,
+        "--file",
+        join(dir, "compose.yaml"),
+        "--env-file",
+        join(dir, ".env"),
+    ];
+    const supervisorShell = (dir, script) => [
+        ...compose(dir),
+        "run",
+        "--rm",
+        "-T",
+        "--no-deps",
+        "--entrypoint",
+        "sh",
+        "supervisor",
+        "-c",
+        script,
+    ];
+    let nativeLocal = false;
+    const endpoint = async (signal) => {
+        // Reject conflicting selectors rather than infer precedence across Docker/Compose versions.
+        if (env.DOCKER_CONTEXT && env.DOCKER_HOST)
+            return null;
+        if (!env.DOCKER_CONTEXT && env.DOCKER_HOST)
+            return env.DOCKER_HOST;
+        const read = await docker(["context", "inspect", ...(env.DOCKER_CONTEXT ? [env.DOCKER_CONTEXT] : []),
+            "--format", '{{(index .Endpoints "docker").Host}}'], { signal });
+        return read.code === 0 ? read.stdout.trim() || null : null;
+    };
+    return {
+        async info(signal) {
+            nativeLocal = false;
+            const read = await docker(["info", "--format", "{{json .}}"], { signal });
+            if (read.code !== 0)
+                return null;
+            let body;
+            try {
+                body = JSON.parse(read.stdout);
+            }
+            catch {
+                return null;
+            }
+            const arches = {
+                x86_64: "amd64",
+                amd64: "amd64",
+                aarch64: "arm64",
+                arm64: "arm64",
+            };
+            const arch = arches[String(body.Architecture)];
+            if (body.OSType !== "linux" || !arch)
+                return null;
+            if ((await docker(["compose", "version"], { signal })).code !== 0)
+                return null;
+            const vm = /docker desktop|orbstack/i.test(String(body.OperatingSystem));
+            const host = await endpoint(signal);
+            const platform = deps.platform ?? process.platform;
+            nativeLocal = platform === "linux" && !vm && host === "unix:///var/run/docker.sock";
+            const supportedVm = platform === "darwin" && vm && host?.startsWith("unix:///");
+            return { arch, vm, ...(!nativeLocal && !supportedVm ? { unsupported: true } : {}) };
+        },
+        async imageArch(ref, signal) {
+            const read = await docker(["image", "inspect", "--format", "{{.Architecture}}", ref], { signal });
+            return read.code === 0 ? read.stdout.trim() || null : null;
+        },
+        async pull(ref, signal) {
+            const host = await endpoint(signal);
+            if (!host?.startsWith("unix:///"))
+                return false;
+            let config;
+            try {
+                config = mkdtempSync(join(tmpdir(), "catalyst-pull-"));
+                writeFileSync(join(config, "config.json"), JSON.stringify({ auths: {} }), { mode: 0o600 });
+                const anonymousEnv = { ...env, DOCKER_CONFIG: config };
+                delete anonymousEnv.DOCKER_CONTEXT;
+                delete anonymousEnv.DOCKER_AUTH_CONFIG;
+                return (await docker(["--host", host, "--config", config, "pull", "--quiet", ref], { env: anonymousEnv, signal, timeoutMs: 900_000 })).code === 0;
+            }
+            catch {
+                return false;
+            }
+            finally {
+                if (config)
+                    rmSync(config, { recursive: true, force: true });
+            }
+        },
+        async network(name, signal) {
+            const read = await docker(["network", "inspect", name], { signal });
+            const absent = `Error response from daemon: network ${name} not found`;
+            if (read.code !== 0 && (read.stdout.trim() === "" || read.stdout.trim() === "[]") && read.stderr?.trim() === absent)
+                return "missing";
+            if (read.code !== 0 || read.stderr?.trim())
+                return "unavailable";
+            try {
+                const [net] = JSON.parse(read.stdout);
+                const options = (net?.Options ?? {});
+                const labels = (net?.Labels ?? {});
+                return net?.Driver === "bridge" &&
+                    net.Internal !== true &&
+                    net.EnableIPv6 !== true &&
+                    options["com.docker.network.bridge.enable_icc"] === "false" &&
+                    options["com.docker.network.bridge.name"] === "catalyst-sess0" &&
+                    labels["dev.catalystcloud.session-network"] === "v1"
+                    ? "ready"
+                    : "misshaped";
+            }
+            catch {
+                return "misshaped";
+            }
+        },
+        async createNetwork(name, signal) {
+            const args = [
+                "network",
+                "create",
+                "--driver=bridge",
+                "--opt",
+                "com.docker.network.bridge.enable_icc=false",
+                "--opt",
+                "com.docker.network.bridge.name=catalyst-sess0",
+                "--label",
+                "dev.catalystcloud.session-network=v1",
+                name,
+            ];
+            return (await docker(args, { signal })).code === 0;
+        },
+        async nativeEgressStatus(nowMs, signal) { return nativeLocal && await nativeEgressReady(nowMs, signal); },
+        async socketGid() {
+            if (!nativeLocal)
+                return null;
+            try {
+                return statSync(deps.socketPath ?? "/var/run/docker.sock").gid;
+            }
+            catch {
+                return null;
+            }
+        },
+        async claimDirs(dir, paths, signal) {
+            const args = [
+                ...compose(dir),
+                "run",
+                "--rm",
+                "-T",
+                "--no-deps",
+                "--user",
+                "0",
+                // The service drops every capability; root needs CHOWN back to hand over a folder.
+                "--cap-add",
+                "CHOWN",
+                "--entrypoint",
+                "chown",
+                "supervisor",
+                RUNNER_UID,
+                ...paths,
+            ];
+            return (await docker(args, { cwd: dir, signal, timeoutMs: 120_000 })).code === 0;
+        },
+        async hasVolumeFile(dir, variable, signal) {
+            return ((await docker(supervisorShell(dir, `test -s "$${variable}"`), {
+                cwd: dir,
+                signal,
+                timeoutMs: 120_000,
+            })).code === 0);
+        },
+        async enrollment(dir, signal) {
+            const script = `(() => { const {readFileSync}=require("node:fs");
+        try { const state=JSON.parse(readFileSync(process.env.CATALYST_HOST_CREDENTIAL_FILE,"utf8"));
+          if (state.version!==1 || typeof state.secret!=="string" || !/^[A-Za-z0-9_-]{32,256}$/.test(state.secret)) process.exit(1);
+          if (state.enrollment===null) {
+            if (!Array.isArray(state.spentJoinTokens) || !state.spentJoinTokens.every(v=>typeof v==="string" && /^[0-9a-f]{64}$/.test(v))) process.exit(1);
+            const token=process.env.CATALYST_HOST_JOIN_TOKEN;
+            const hash=token ? require("node:crypto").createHash("sha256").update(token).digest("hex") : null;
+            process.stdout.write(JSON.stringify({unenrolled:true,tokenSpent:!hash || state.spentJoinTokens.includes(hash)})); return;
+          }
+          const e=state.enrollment;
+          if (!e) process.exit(1);
+          process.stdout.write(JSON.stringify({hostId:e.hostId,tenant:e.tenant,team:e.team,enrollmentKind:e.enrollmentKind}));
+        } catch { process.exit(1); } })();`;
+            const read = await docker([...compose(dir), "run", "--rm", "-T", "--no-deps", "--entrypoint", "bun", "supervisor", "-e", script], { cwd: dir, signal, timeoutMs: 120_000 });
+            if (read.code !== 0)
+                return null;
+            try {
+                const parsed = JSON.parse(read.stdout);
+                const e = object(parsed);
+                if (e?.unenrolled === true && typeof e.tokenSpent === "boolean")
+                    return { unenrolled: true, tokenSpent: e.tokenSpent };
+                return e && [e.hostId, e.tenant, e.team].every((v) => typeof v === "string" && v.length > 0) &&
+                    (e.enrollmentKind === "self_hosted" || e.enrollmentKind === "dedicated")
+                    ? { hostId: e.hostId, tenant: e.tenant, team: e.team, enrollmentKind: e.enrollmentKind } : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        async orgKeyStatus(dir, account, baseUrl, candidate, signal) {
+            // Only a status leaves the container. No stored key or provider response is printed.
+            const script = `(async () => {
+        const {readFileSync,lstatSync}=require("node:fs");
+        let input=""; for await (const chunk of process.stdin) input+=chunk;
+        let stored="", storedInvalid=false;
+        try {
+          const info=lstatSync(process.env.CATALYST_ORG_KEY_FILE);
+          if (!info.isFile() || (info.mode & 0o077)!==0) storedInvalid=true;
+          else stored=readFileSync(process.env.CATALYST_ORG_KEY_FILE,"utf8").trim();
+        } catch (error) { if (error.code!=="ENOENT") storedInvalid=true; }
+        const proposed=input.trim(), key=proposed||stored;
+        const status=(s)=>process.stdout.write(s);
+        if (!proposed && storedInvalid) return status("invalid");
+        if (!key) return status("missing");
+        if (!/^[\x21-\x7e]{16,1024}$/.test(key)) return status("invalid");
+        try {
+          const response=await fetch(process.argv[1]+"/api/v1/me", {redirect:"error",signal:AbortSignal.timeout(10000),
+            headers:{authorization:"Bearer "+key,accept:"application/json"}});
+          if (response.status===429 || response.status>=500) return status("unavailable");
+          if (!response.ok) return status("invalid");
+          const body=await response.json();
+          if (body.account!==process.argv[2] || body.principal!=="service" || body.user!==undefined ||
+            !Array.isArray(body.permissions) || body.permissions.length!==3 ||
+            !["mirror:read","mirror:write","mirror:feed"].every(p=>body.permissions.includes(p)))
+            return status("invalid");
+          return status(proposed && proposed!==stored ? "different" : "valid");
+        } catch { return status("unavailable"); }
+      })().catch(()=>process.stdout.write("unavailable"));`;
+            const read = await docker([...compose(dir), "run", "--rm", "-T", "--no-deps", "--entrypoint", "bun", "supervisor", "-e", script, baseUrl, account], { cwd: dir, input: candidate ? `${candidate}\n` : undefined, signal, timeoutMs: 120_000 });
+            const status = read.stdout.trim();
+            return read.code === 0 && ["valid", "different", "missing", "invalid", "unavailable"].includes(status)
+                ? status : "unavailable";
+        },
+        async writeVolumeFile(dir, variable, value, signal) {
+            if (variable !== "CATALYST_ORG_KEY_FILE")
+                return false;
+            const script = `umask 077 && tmp=$(mktemp "$${variable}.onboard.XXXXXX") && trap 'rm -f "$tmp"' EXIT && cat > "$tmp" && test -s "$tmp" && chmod 600 "$tmp" && mv -f "$tmp" "$${variable}"`;
+            return ((await docker(supervisorShell(dir, script), {
+                cwd: dir,
+                input: `${value}\n`,
+                signal,
+                timeoutMs: 120_000,
+            })).code === 0);
+        },
+        async composeUp(dir, signal) {
+            return ((await docker([...compose(dir), "up", "--detach"], { cwd: dir, signal, timeoutMs: 600_000 }))
+                .code === 0);
+        },
+        async composeRunning(dir, signal) {
+            const read = await docker([...compose(dir), "ps", "--status", "running", "--services"], { cwd: dir, signal });
+            return read.code === 0 && read.stdout.split("\n").some((line) => line.trim() === "supervisor");
+        },
+    };
+}
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : null;
+const waiting = (reason, evidence) => ({ state: "waiting", reason, ...(evidence ? { evidence } : {}) });
+function parseHosts(body) {
+    const hosts = object(body)?.hosts;
+    if (!Array.isArray(hosts) || hosts.length > 1_000)
+        return null;
+    const parsed = [];
+    for (const value of hosts) {
+        const host = object(value);
+        const capability = host?.capability === null ? null : object(host?.capability);
+        if (!host ||
+            typeof host.hostId !== "string" ||
+            typeof host.hostName !== "string" ||
+            typeof host.team !== "string" ||
+            !(host.revokedAtMs === null || typeof host.revokedAtMs === "number") ||
+            (host.capability !== null &&
+                (!capability ||
+                    !Number.isSafeInteger(capability.placeableCapacity) ||
+                    capability.placeableCapacity < 0 ||
+                    typeof capability.runtimeLive !== "boolean" ||
+                    !Array.isArray(capability.failingRequired) ||
+                    !capability.failingRequired.every((id) => typeof id === "string"))))
+            return null;
+        parsed.push({
+            hostId: host.hostId,
+            hostName: host.hostName,
+            team: host.team,
+            revoked: host.revokedAtMs !== null,
+            capacity: capability ? (capability.runtimeLive ? capability.placeableCapacity : 0) : null,
+            failing: capability ? capability.failingRequired : [],
+        });
+    }
+    return parsed;
+}
+/** `KEY=value` lines; a single-quoted value is unquoted. Anything else is ignored. */
+function readEnvFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const values = {};
+    for (const line of text.split("\n")) {
+        const match = /^([A-Z][A-Z0-9_]*)=(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const raw = match[2];
+        values[match[1]] = /^'[^']*'$/.test(raw) ? raw.slice(1, -1) : raw;
+    }
+    return values;
+}
+function renderEnv(values) {
+    return Object.entries(values)
+        .map(([key, value]) => {
+        if (/[\n\r']/.test(value))
+            throw new Error("runner_env_value_invalid");
+        return `${key}=${/^[A-Za-z0-9._:/@+=,-]*$/.test(value) ? value : `'${value}'`}\n`;
+    })
+        .join("");
+}
+function writePrivate(path, text) {
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, text, { mode: 0o600 });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, path);
+}
+/** Enrollment uses the stored host id and exact team/name. Two machines with one hostname must not
+ * share it: a random suffix, kept in `.env` from the first write on. */
+export function runnerDefaultHostName() {
+    const suffix = randomBytes(3).toString("hex");
+    const base = `catalyst-${hostname().split(".")[0] ?? "host"}`
+        .replace(/[^A-Za-z0-9._-]/g, "-")
+        .slice(0, 55);
+    const name = `${base}-${suffix}`;
+    return HOST_NAME.test(name) ? name : `catalyst-host-${suffix}`;
+}
+export function onboardRunnerAdapter(input = {}) {
+    const engine = input.engine ?? dockerRunnerEngine();
+    const sleep = input.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const waitMs = input.waitMs ?? 120_000;
+    const pollMs = input.pollMs ?? 5_000;
+    // One question per run: the engine checks again after acting, and the receipt row is "running"
+    // in between, so the answer lives here too.
+    let decided;
+    // Only `--runner` or a yes in this run starts or repairs the runner. A yes saved by an earlier run
+    // only reports on it, so an unattended check never restarts a runner the person stopped.
+    let mayAct = false;
+    let acted = false;
+    const selected = { selected: true };
+    async function decide(journal) {
+        if (decided !== undefined)
+            return decided;
+        if (input.selected !== undefined) {
+            mayAct = input.selected;
+            return (decided = input.selected);
+        }
+        const prior = journal.steps.find((step) => step.id === "runner")?.evidence?.selected;
+        if (typeof prior === "boolean")
+            return (decided = prior);
+        if (input.choose) {
+            mayAct = (await input.choose()) === true;
+            return (decided = mayAct);
+        }
+        return (decided = null);
+    }
+    /** Everything both check and act need, verified before any local change. */
+    async function prepare(ctx, journal, signal) {
+        const choice = await decide(journal);
+        if (choice !== true)
+            return {
+                state: "skipped",
+                reason: "runner_not_selected",
+                ...(choice === false ? { evidence: { selected: false } } : {}),
+            };
+        const info = await engine.info(signal);
+        if (!info)
+            return { state: "skipped", reason: "runner_docker_missing", evidence: selected };
+        if (info.unsupported)
+            return waiting("runner_engine_unsupported", selected);
+        const cfg = loadConfig(ctx.home);
+        const account = journal.account ?? journal.tenant;
+        if (!cfg?.user ||
+            !["owner", "admin"].includes(cfg.user.role) ||
+            !account ||
+            cfg.account !== account ||
+            cfg.user.id !== journal.membershipId ||
+            !journal.baseUrl ||
+            normalizeBaseUrl(cfg.baseUrl) !== normalizeBaseUrl(journal.baseUrl))
+            return waiting("runner_identity_unverified", selected);
+        const support = await verifyOnboardRoutes(ctx, journal, [
+            { method: "GET", path: ENROLLMENTS },
+            { method: "POST", path: JOIN_TOKENS },
+            { method: "GET", path: CAPACITY },
+        ], signal);
+        if ("reason" in support)
+            return waiting(support.reason, selected);
+        const teamId = selectedOnboardTeam(journal);
+        const teamKey = teamId ? await liveTeamKey(ctx, teamId, signal ?? new AbortController().signal) : null;
+        if (!teamId || !teamKey)
+            return waiting("runner_context_unverified", selected);
+        const runnerSupport = await verifyRunnerRoutes(ctx, journal, [{ method: "GET", path: "/api/v1/agent/runner-admission" }], signal);
+        if ("reason" in runnerSupport && runnerSupport.reason !== "cloud_capability_unavailable")
+            return waiting(runnerSupport.reason, selected);
+        const cloud = !("reason" in runnerSupport);
+        let state;
+        try {
+            state = onboardStateRoot(ctx.home, ctx.env);
+        }
+        catch {
+            return waiting("runner_directory_unavailable", selected);
+        }
+        const dir = join(state, "runner");
+        const saved = readEnvFile(join(dir, ".env"));
+        const images = {
+            supervisor: ctx.env.CATALYST_SUPERVISOR_IMAGE ?? RUNNER_HOST_IMAGES.supervisor,
+            watchdog: ctx.env.CATALYST_WATCHDOG_IMAGE ?? RUNNER_HOST_IMAGES.watchdog,
+            runner: ctx.env.CATALYST_RUNNER_IMAGE ?? saved?.CATALYST_RUNNER_IMAGE ?? RUNNER_HOST_IMAGES.runner,
+        };
+        if (!Object.values(images).every((ref) => IMAGE_REF.test(ref)))
+            return waiting("runner_image_unpinned", selected);
+        if (!info.vm && !(await engine.nativeEgressStatus?.(ctx.now().getTime(), signal)))
+            return waiting("runner_native_egress_setup_required", selected);
+        return { account, baseUrl: normalizeBaseUrl(cfg.baseUrl), teamKey, teamId, cloud, dir, info, images };
+    }
+    async function desiredEnv(p, joinToken) {
+        const saved = readEnvFile(join(p.dir, ".env")) ?? {};
+        const name = saved.CATALYST_HOST_NAME || (input.hostName ?? runnerDefaultHostName)();
+        const gid = p.info.vm ? 0 : await engine.socketGid();
+        if (!HOST_NAME.test(name) || gid === null)
+            return null;
+        return {
+            DOCKER_SOCKET_PATH: "/var/run/docker.sock",
+            DOCKER_SOCKET_GID: String(gid),
+            CATALYST_WATCHDOG_IMAGE: p.images.watchdog,
+            CATALYST_SUPERVISOR_IMAGE: p.images.supervisor,
+            CATALYST_MIRROR_URL: p.baseUrl,
+            CATALYST_HOST_NAME: name,
+            CATALYST_HOST_JOIN_TOKEN: joinToken ?? saved.CATALYST_HOST_JOIN_TOKEN ?? "",
+            CATALYST_RUNNER_IMAGE: p.images.runner,
+            CATALYST_SLOTS_DIR: join(p.dir, "slots"),
+            CATALYST_THOUGHTS_DIR: join(p.dir, "thoughts"),
+            CATALYST_POOL_LOCK_DIR: join(p.dir, "locks"),
+            CATALYST_SESSION_EGRESS_DIR: p.info.vm ? join(p.dir, "session-egress") : NATIVE_EGRESS_DIR,
+        };
+    }
+    /** The step owns its own keys only; a person's tuning (CATALYST_SLOTS and the rest) is kept. */
+    const merged = (saved, want) => ({
+        ...want,
+        ...Object.fromEntries(Object.entries(saved ?? {}).filter(([key]) => !(key in want))),
+    });
+    async function listHosts(ctx, p, signal) {
+        const read = await readExistingOnboardJson(ctx, `${ENROLLMENTS}?account=${encodeURIComponent(p.account)}`, signal);
+        return "reason" in read ? null : parseHosts(read.body);
+    }
+    async function mintJoinToken(ctx, p, hostName, signal) {
+        const cfg = loadConfig(ctx.home);
+        const expiry = cfg?.auth ? Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() : 0;
+        const bearer = cfg?.key ||
+            (cfg?.auth && Number.isFinite(expiry) && expiry > 30_000 ? cfg.auth.accessToken : undefined);
+        if (!bearer)
+            return waiting("runner_login_refresh_required", selected);
+        try {
+            const response = await ctx.fetch(`${p.baseUrl}${JOIN_TOKENS}?account=${encodeURIComponent(p.account)}`, {
+                method: "POST",
+                redirect: "error",
+                signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
+                headers: {
+                    authorization: `Bearer ${bearer}`,
+                    "content-type": "application/json",
+                    accept: "application/json",
+                },
+                body: JSON.stringify({
+                    version: 1,
+                    team: p.teamKey,
+                    enrollmentKind: "self_hosted",
+                    hostName,
+                    ttlMs: 3_600_000,
+                }),
+            });
+            const body = object(await response.json().catch(() => null));
+            if (body?.refusal === "not_tenant_admin")
+                return waiting("runner_identity_unverified", selected);
+            if (response.status !== 201 || body?.ok !== true || typeof body.joinToken !== "string" || !JOIN_TOKEN.test(body.joinToken))
+                return waiting("runner_join_token_unavailable", selected);
+            return body.joinToken;
+        }
+        catch {
+            return waiting(signal?.aborted ? "interrupted" : "runner_join_token_unavailable", selected);
+        }
+    }
+    function orgKeyFromFile(ctx) {
+        const path = ctx.env.CATALYST_RUNNER_ORG_KEY_FILE;
+        if (!path)
+            return undefined;
+        try {
+            if (!lstatSync(path).isFile())
+                return null;
+            const lines = readFileSync(path, "utf8").split("\n").map((line) => line.trim()).filter(Boolean);
+            return lines.length === 1 && /^[\x21-\x7e]{16,1024}$/.test(lines[0]) ? lines[0] : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return {
+        check: async (ctx, journal, signal) => {
+            // Only the check right after this run's own act waits for the host to appear.
+            const afterAct = acted;
+            acted = false;
+            const p = await prepare(ctx, journal, signal);
+            if (!("dir" in p))
+                return p;
+            const saved = readEnvFile(join(p.dir, ".env"));
+            const want = await desiredEnv(p);
+            if (!want)
+                return waiting("runner_docker_socket_unreadable", selected);
+            const name = want.CATALYST_HOST_NAME;
+            let enrolled = null;
+            const live = (hosts) => hosts?.find((host) => host.hostId === enrolled?.hostId && host.hostName === name && host.team === p.teamKey && !host.revoked);
+            let hosts = await listHosts(ctx, p, signal);
+            if (!hosts)
+                return waiting("runner_enrollment_unavailable", selected);
+            if (hosts.some((host) => host.hostName === name && !host.revoked && host.team !== p.teamKey))
+                return waiting("runner_enrolled_for_other_team", { ...selected, hostName: name });
+            const running = await engine.composeRunning(p.dir, signal);
+            const changed = !saved || Object.entries(want).some(([key, value]) => saved[key] !== value);
+            const hostEvidence = { ...selected, hostName: name };
+            const pending = () => mayAct ? { state: "pending" } : waiting("runner_needs_runner_flag", hostEvidence);
+            if (!running || changed)
+                return afterAct ? waiting("runner_compose_not_running", hostEvidence) : pending();
+            // The supervisor enrolls on its first start and advertises shortly after.
+            for (let attempt = 1;; attempt++) {
+                const credential = await engine.enrollment(p.dir, signal);
+                enrolled = isUnenrolled(credential) ? null : credential;
+                // Enrollment can complete while the container metadata read is running. The cloud
+                // snapshot must follow that read before a missing credential ID can be called stale.
+                hosts = await listHosts(ctx, p, signal);
+                if (!hosts)
+                    return waiting("runner_enrollment_unavailable", hostEvidence);
+                if (enrolled && (enrolled.tenant !== p.account || enrolled.enrollmentKind !== "self_hosted"))
+                    return waiting("runner_identity_unverified", hostEvidence);
+                if (enrolled && enrolled.team !== p.teamKey)
+                    return waiting("runner_enrolled_for_other_team", hostEvidence);
+                if (enrolled && !hosts.some((host) => host.hostId === enrolled.hostId && host.hostName === name && !host.revoked))
+                    return waiting("runner_enrollment_stale", hostEvidence);
+                const host = live(hosts);
+                if (host && host.capacity !== null)
+                    break;
+                if (!host && !afterAct)
+                    return pending();
+                if (attempt >= Math.max(1, Math.ceil(waitMs / pollMs)) || signal?.aborted)
+                    return waiting(host ? "runner_capability_pending" : "runner_enrollment_unverified", hostEvidence);
+                await sleep(pollMs);
+            }
+            const host = live(hosts);
+            const evidence = { ...hostEvidence, hostId: host.hostId, capacity: host.capacity };
+            const orgKey = orgKeyFromFile(ctx);
+            if (orgKey === null)
+                return waiting("runner_org_key_file_invalid", evidence);
+            const keyStatus = await engine.orgKeyStatus(p.dir, p.account, p.baseUrl, orgKey, signal);
+            if (keyStatus === "different")
+                return !afterAct ? pending() : waiting("runner_org_key_write_failed", evidence);
+            if (keyStatus === "missing" && p.cloud && mayAct && !afterAct)
+                return pending();
+            if (keyStatus !== "valid")
+                return waiting(keyStatus === "missing" ? "runner_org_key_missing" : keyStatus === "invalid" ? "runner_org_key_invalid" : "runner_org_key_unavailable", evidence);
+            if (host.capacity === 0 || host.failing.length > 0)
+                return waiting("runner_host_not_ready", { ...evidence, failing: host.failing.join(",") });
+            if (p.cloud) {
+                const admission = await runnerAdmission(ctx, journal, p.teamId, false, signal);
+                if ("reason" in admission)
+                    return waiting(admission.reason, evidence);
+                if (!admission.ready)
+                    return mayAct && !afterAct ? pending() : waiting("runner_admission_disabled", evidence);
+            }
+            const admission = await onboardTeamAdmission(ctx, p.teamKey, signal);
+            if (admission !== true)
+                return waiting(admission === false ? "runner_admission_operator" : "runner_admission_unverified", evidence);
+            input.message?.(`This machine runs Catalyst's work as host ${name}, with ${host.capacity} slots free.`);
+            return { state: "done", evidence };
+        },
+        act: async (ctx, journal, signal) => {
+            const p = await prepare(ctx, journal, signal);
+            if (!("dir" in p))
+                return p;
+            if (!mayAct)
+                return waiting("runner_needs_runner_flag", selected);
+            try {
+                mkdirSync(p.dir, { recursive: true, mode: 0o700 });
+                if (lstatSync(p.dir).isSymbolicLink())
+                    throw new Error("runner_directory_unsafe");
+                chmodSync(p.dir, 0o700);
+                for (const sub of DIRS) {
+                    mkdirSync(join(p.dir, sub), { recursive: true, mode: 0o700 });
+                    // On native Linux the runner uid owns these after the first run; leave them alone.
+                    if (statSync(join(p.dir, sub)).uid === process.getuid?.())
+                        chmodSync(join(p.dir, sub), 0o700);
+                }
+                // Mounted read-only into the supervisor (uid 10001), which reads the egress attestation.
+                mkdirSync(join(p.dir, "session-egress"), { recursive: true, mode: 0o755 });
+                const compose = readFileSync(join(packageRoot(), "vendor", "self-host", "compose.yaml"));
+                let current = null;
+                try {
+                    current = readFileSync(join(p.dir, "compose.yaml"));
+                }
+                catch {
+                    /* first run */
+                }
+                if (!current?.equals(compose))
+                    writeFileSync(join(p.dir, "compose.yaml"), compose, { mode: 0o644 });
+            }
+            catch {
+                return { state: "failed", reason: "runner_directory_unavailable", evidence: selected };
+            }
+            let want = await desiredEnv(p);
+            if (!want)
+                return waiting("runner_docker_socket_unreadable", selected);
+            const writeEnv = (values) => {
+                try {
+                    const saved = readEnvFile(join(p.dir, ".env"));
+                    if (saved && Object.entries(values).every(([key, value]) => saved[key] === value))
+                        return true;
+                    writePrivate(join(p.dir, ".env"), renderEnv(merged(saved, values)));
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            };
+            if (!writeEnv(want))
+                return { state: "failed", reason: "runner_directory_unavailable", evidence: selected };
+            for (const ref of Object.values(p.images)) {
+                if (!(await engine.imageArch(ref, signal))) {
+                    await engine.pull(ref, signal);
+                }
+                const arch = await engine.imageArch(ref, signal);
+                if (!arch)
+                    return waiting("runner_images_unavailable", { ...selected, image: ref });
+                if (arch !== p.info.arch)
+                    return waiting("runner_image_emulated", { ...selected, image: ref });
+            }
+            const network = await engine.network(RUNNER_SESSION_NETWORK, signal);
+            if (network === "misshaped")
+                return waiting("runner_session_network_misshaped", selected);
+            if (network === "unavailable")
+                return waiting("runner_session_network_unavailable", selected);
+            if (network === "missing" && !(await engine.createNetwork(RUNNER_SESSION_NETWORK, signal)))
+                return { state: "failed", reason: "runner_session_network_failed", evidence: selected };
+            if (!p.info.vm && !(await engine.claimDirs(p.dir, DIRS.map((sub) => join(p.dir, sub)), signal)))
+                return { state: "failed", reason: "runner_directory_unavailable", evidence: selected };
+            const name = want.CATALYST_HOST_NAME;
+            const hasCredential = await engine.hasVolumeFile(p.dir, "CATALYST_HOST_CREDENTIAL_FILE", signal);
+            const credential = hasCredential ? await engine.enrollment(p.dir, signal) : null;
+            const enrolled = isUnenrolled(credential) ? null : credential;
+            const hosts = await listHosts(ctx, p, signal);
+            if (!hosts)
+                return waiting("runner_enrollment_unavailable", selected);
+            if (hosts.some((host) => host.hostName === name && !host.revoked && host.team !== p.teamKey))
+                return waiting("runner_enrolled_for_other_team", { ...selected, hostName: name });
+            if (enrolled && (enrolled.tenant !== p.account || enrolled.enrollmentKind !== "self_hosted"))
+                return waiting("runner_identity_unverified", { ...selected, hostName: name });
+            if (enrolled && enrolled.team !== p.teamKey)
+                return waiting("runner_enrolled_for_other_team", { ...selected, hostName: name });
+            if (hasCredential && !isUnenrolled(credential) && (!enrolled || !hosts.some((host) => host.hostId === enrolled.hostId && host.hostName === name && host.team === p.teamKey && !host.revoked)))
+                return waiting("runner_enrollment_stale", { ...selected, hostName: name });
+            // A lost volume also lost the secret that redeemed the old token. Mint a new token and match
+            // the new host id from the supervisor's credential, never an old advertisement with this name.
+            // A lost reply must retry the same token and retained secret: a new token would be
+            // refused as identity_invalid after the cloud committed that secret's enrollment.
+            // Only a token known refused/spent (or missing) can be replaced for an unenrolled file.
+            if (!hasCredential || (isUnenrolled(credential) && credential.tokenSpent)) {
+                const token = await mintJoinToken(ctx, p, name, signal);
+                if (typeof token !== "string")
+                    return token;
+                want = (await desiredEnv(p, token));
+                if (!writeEnv(want))
+                    return { state: "failed", reason: "runner_directory_unavailable", evidence: selected };
+            }
+            const orgKey = orgKeyFromFile(ctx);
+            if (orgKey === null)
+                return waiting("runner_org_key_file_invalid", selected);
+            let keyStatus = await engine.orgKeyStatus(p.dir, p.account, p.baseUrl, orgKey, signal);
+            if (keyStatus === "invalid" || keyStatus === "unavailable")
+                return waiting(keyStatus === "invalid" ? "runner_org_key_invalid" : "runner_org_key_unavailable", selected);
+            if (orgKey && keyStatus === "different")
+                if (!(await engine.writeVolumeFile(p.dir, "CATALYST_ORG_KEY_FILE", orgKey, signal)))
+                    return { state: "failed", reason: "runner_org_key_write_failed", evidence: selected };
+            if (keyStatus === "missing" && p.cloud) {
+                const issued = await issueRunnerOrgKey(ctx, journal, { dir: p.dir, teamId: p.teamId, hostName: name }, value => engine.writeVolumeFile(p.dir, "CATALYST_ORG_KEY_FILE", value, signal), signal);
+                if ("reason" in issued)
+                    return waiting(issued.reason, selected);
+                keyStatus = await engine.orgKeyStatus(p.dir, p.account, p.baseUrl, undefined, signal);
+                if (keyStatus !== "valid")
+                    return waiting(keyStatus === "invalid" ? "runner_org_key_invalid" : "runner_org_key_unavailable", selected);
+            }
+            if (p.cloud) {
+                const read = await runnerAdmission(ctx, journal, p.teamId, false, signal);
+                if ("reason" in read)
+                    return waiting(read.reason, selected);
+                if (!read.ready) {
+                    const enabled = await runnerAdmission(ctx, journal, p.teamId, true, signal);
+                    if ("reason" in enabled)
+                        return waiting(enabled.reason, selected);
+                    if (!enabled.ready)
+                        return waiting("runner_admission_unverified", selected);
+                }
+            }
+            if (!(await engine.composeUp(p.dir, signal)))
+                return { state: "failed", reason: "runner_compose_failed", evidence: selected };
+            acted = true;
+            return { state: "done" };
+        },
+    };
+}