@catalyst-cloud/cli 0.16.19 → 0.16.20

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.16.20
+
+Setup on Linux now prints every command whole, on its own line, so you can copy it from any terminal width. When this computer still needs the session egress service, setup prints one `sudo` command that checks the installer's fingerprint and installs and starts the service. Run it, then run the same setup command again. When nothing may take work for your workspace yet, setup now names the command that enrolls this computer as a self-hosted machine: `catalyst onboard --runner --team <your team>`.
+
+New: `catalyst env shell` opens your repository's declared environment on your own computer in Docker, with the declared toolchain versions on `PATH`.
+
 ## 0.16.19
 
 A self-hosted Mac whose `catalyst` command was installed with Homebrew's Node now keeps its images current and finishes setup's private thoughts storage step. Before, Docker Desktop could not read a file the check needs from the Homebrew folder, so every update and that setup step stopped. Install this version; the next 15-minute check updates the machine.

package/README.md

@@ -241,6 +241,8 @@ Your personal key reads everything the skills need — tickets, pull requests, t
 - Read pull-request labels or the reviewer's reaction. The mirror does not carry them; GitHub's own page does.
 - Compute a flow number — cycle time, throughput, or how long pull requests have been open. Nothing serves those yet, so say they are not computed rather than counting something else and calling it that.
 
+`catalyst env shell` opens this repository's environment on your computer: the image Catalyst's agents work in, the toolchain your `.catalyst/catalyst.toml` declares, and the variables it names, with values taken from your terminal or an `--env-file`. It needs Docker (Docker Desktop, OrbStack or Docker Engine) and no sign-in. The first run downloads the image, about 2.3 GB, with no credential. `catalyst env shell --check` prepares the same environment and reports each toolchain and variable without opening a shell.
+
 ## Versions and origins
 
 The package pins the contract range `1.x || 2.x`, recorded in `package.json` under `catalystCloud.tenantContractRange`, and reports it in `--version`, `status` and `login`. An account whose contract version falls outside that range is refused with one line naming both versions; update the bundle. Every skill carries a `vendored-from:` line naming this package as its origin, and that line now also carries the version it was vendored at; all of them are written in this repository for customer accounts.

package/dist/args.js

@@ -342,7 +342,7 @@ export const FLAG_TABLES = {
     env: {
         root: {
             value: true,
-            help: "draft: repository directory (default: current directory)",
+            help: "draft, shell: repository directory (default: the current repository's top level)",
         },
         write: {
             value: false,
@@ -352,6 +352,19 @@ export const FLAG_TABLES = {
             value: false,
             help: "draft: show the generated TOML as an additions-only diff",
         },
+        "env-file": {
+            value: true,
+            repeat: true,
+            help: "shell: read declared variables' values from this dotenv file (repeatable; your terminal's own values win)",
+        },
+        image: {
+            value: true,
+            help: "shell: open this digest-pinned image instead of Catalyst's (it must carry bash, and mise when toolchains are declared)",
+        },
+        check: {
+            value: false,
+            help: "shell: prepare the environment and report it, without opening a shell",
+        },
     },
     var: {
         repo: {
@@ -529,7 +542,7 @@ export const VERB_USAGE = {
     seat: "seat checkout --size big|med --harness claude,codex,opencode [--session-id ID] [--stage STAGE] [--key-env NAME]",
     mcp: "mcp <add <name> --url URL <--auth none|--bearer SECRET_NAME|--header NAME=SECRET_NAME...>|list|remove <name>> [--json]",
     team: "team <list|check <KEY>|check --all|map <KEY> [--stage role=StateName]... [--yes --plan-hash H]|adopt <KEY> [--undo] [--yes --plan-hash H]|migrate <KEY> [--choice sourceId=destinationId]... [--retire] [--yes --plan-hash H]|checklist <KEY>> [--json]",
-    env: "env <inventory [path] | check <file> | migrate [catalyst.env.json] | draft [--root DIR] [--diff] [--write]> [--json]   (THIS repository, offline — no login, no network)",
+    env: "env <inventory [path] | check <file> | migrate [catalyst.env.json] | draft [--root DIR] [--diff] [--write] | shell [--root DIR] [--env-file FILE]... [--image REF] [--check]> [--json]   (THIS repository; no login — shell needs Docker and downloads Catalyst's image once)",
     environment: "environment [read] [--json] | environment propose --file <path>|--stdin [--expect-revision N] [--approve] [--json] | environment approve [--revision N --hash H] [--json]   (your ACCOUNT's declaration; needs login)",
     secret: "secret set <NAME> --repo <owner/name> [--command '<cmd>'] [--json]   (value from --command, stdin, or a hidden prompt) | secret import <file> --repo <owner/name> [--names NAME[,NAME...]] [--rotate NAME]... [--json]",
     var: "var <set NAME|import <file>> [--repo <owner/name>] [--names NAME[,NAME...]] [--json]   (plain environment variables; set reads stdin or a hidden prompt)",

package/dist/capabilities.js

@@ -30,6 +30,7 @@ export const CAPABILITIES = [
     { verb: "project wip-limit set", does: "set a project's new-start WIP limit (0 to 9999, or back to the workspace default)", needs: "admin", routes: [agent("POST", "team-wip-limit")], since: "0.13.1" },
     { verb: "repo agents-block", does: "add or refresh the one Catalyst block in a checkout's AGENTS.md, in the working tree, for the person to commit and open as a pull request", needs: "member", routes: [], since: "0.13.1" },
     { verb: "repo agent-setup", does: "read a checkout's agent setup (AGENTS.md, CLAUDE.md, .agents and .claude skills and rules) and, on request, make it portable in the working tree", needs: "member", routes: [], since: "0.13.1" },
+    { verb: "env shell", does: "open this repository's environment on this computer: Catalyst's image, the declared toolchain and variables (needs Docker; no login for Catalyst's image)", needs: "member", routes: [], since: "0.16.20" },
     { verb: "legacy", does: "find leftovers of the old local Catalyst runtime on this machine and, on a yes, remove them through their own tools", needs: "member", routes: [], since: "0.13.1" },
     { verb: "environment read", does: "read the workspace-wide environment declaration", needs: "member", routes: [agent("GET", "account-environment")], since: "0.8.0" },
     { verb: "environment propose", does: "propose the workspace-wide environment declaration (names only)", needs: "admin", routes: [agent("POST", "account-environment/propose")], since: "0.8.0" },

package/dist/cli.js

@@ -98,7 +98,7 @@ export function usageText() {
         "  catalyst ask <raise|accept|list> ...",
         "  catalyst release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] | release --class <c> --team <K> ...",
         "  catalyst environment [read] | environment propose --file <path>|--stdin [--approve] | environment approve   (your account; needs login)",
-        "  catalyst env <inventory [path] | check <file> | migrate [catalyst.env.json] | draft [--root DIR] [--diff] [--write]> [--json]   (this repository, offline — no login, no network)",
+        "  catalyst env <inventory [path] | check <file> | migrate [catalyst.env.json] | draft [--root DIR] [--diff] [--write] | shell [--root DIR] [--env-file FILE]... [--image REF] [--check]> [--json]   (this repository; no login — shell needs Docker and downloads Catalyst's image once)",
         "  catalyst secret set <NAME> --repo <owner/name> [--command '<cmd>'] | secret import <file> --repo <owner/name> [--names NAME[,NAME...]]",
         "  catalyst var set <NAME> | var import <file> [--repo <owner/name>] [--names NAME[,NAME...]]   (plain environment variables)",
         "  catalyst team <list|check|map|adopt|migrate|checklist> ...",

package/dist/env/shell-declaration.js

@@ -0,0 +1,147 @@
+// shell-declaration.ts — what `catalyst env shell` reads from `.catalyst/catalyst.toml` (the declared
+// toolchains and variables) and how it resolves the variables' values from this terminal and any
+// `--env-file`. Pure: no Docker, no network. A value lives only in `ResolvedVariables.values`; no
+// error, list or message here ever carries one.
+import { parse } from "smol-toml";
+import { validateSettingsToml } from "./settings-toml.js";
+// Mirrors vendor/settings DECLARATION_NAME_RE / DECLARATION_VERSION_RE (index.js:607-608).
+const NAME_RE = /^[a-z][a-z0-9+._-]{0,63}$/;
+const VERSION_RE = /^[A-Za-z0-9^~*<>=][A-Za-z0-9.+_\-^~*<>=| ]{0,63}$/;
+/** What mise takes as one exact or prefix version (measured: 22 → 22.23.3, 1.3.14, 3.12, lts). */
+const PREPARABLE_RE = /^[A-Za-z0-9][A-Za-z0-9.+_-]{0,63}$/;
+const MAX_TOOLCHAINS = 32;
+/** The toolchains and variables the shell prepares. Variables are validated by `validateSettingsToml`
+ *  first, so `env check` and `env shell` refuse the same file the same way. */
+export function readShellDeclaration(text) {
+    const checked = validateSettingsToml(text);
+    if (checked.state === "invalid")
+        return { state: "invalid", errors: checked.errors };
+    if (checked.state === "no-source")
+        return { state: "valid", toolchains: [], variables: [] };
+    // validateSettingsToml parsed the same text, so this cannot throw.
+    const environment = record(record(parse(text))?.environment) ?? {};
+    const toolchains = readToolchains(environment.toolchains);
+    if (toolchains.state !== "valid")
+        return toolchains;
+    const variables = Array.isArray(environment.variables)
+        ? environment.variables.map((raw) => {
+            const entry = record(raw) ?? {};
+            return {
+                name: String(entry.name),
+                required: entry.required === true,
+                secret: entry.secret === true,
+            };
+        })
+        : [];
+    return { state: "valid", toolchains: toolchains.toolchains, variables };
+}
+function readToolchains(raw) {
+    if (raw === undefined)
+        return { state: "valid", toolchains: [] };
+    if (!Array.isArray(raw))
+        return { state: "invalid", errors: ["environment.toolchains must be an array of tables"] };
+    const errors = [];
+    if (raw.length > MAX_TOOLCHAINS)
+        errors.push(`environment.toolchains has more than ${MAX_TOOLCHAINS} entries`);
+    const toolchains = [];
+    const names = new Set();
+    for (const [index, item] of raw.entries()) {
+        const prefix = `environment.toolchains[${index}]`;
+        const entry = record(item);
+        if (!entry) {
+            errors.push(`${prefix} must be a table`);
+            continue;
+        }
+        const unknown = Object.keys(entry).filter((key) => key !== "name" && key !== "version");
+        if (unknown.length > 0)
+            errors.push(`${prefix} has an unknown key: ${unknown.sort().join(", ")}`);
+        const { name, version } = entry;
+        const nameOk = typeof name === "string" && NAME_RE.test(name);
+        const versionOk = typeof version === "string" && VERSION_RE.test(version);
+        if (!nameOk)
+            errors.push(`${prefix}.name is not a valid toolchain name`);
+        else if (names.has(name))
+            errors.push(`${prefix}.name duplicates ${name}`);
+        if (!versionOk)
+            errors.push(`${prefix}.version is not a valid toolchain version`);
+        if (nameOk)
+            names.add(name);
+        if (nameOk && versionOk)
+            toolchains.push({ name, version });
+    }
+    if (errors.length > 0)
+        return { state: "invalid", errors };
+    const range = toolchains.find((toolchain) => !PREPARABLE_RE.test(toolchain.version));
+    if (range)
+        return { state: "unsupported", toolchain: range };
+    return { state: "valid", toolchains };
+}
+/** Names the shell sets itself; a declared one is skipped with a note rather than overriding them. */
+export const RESERVED_VARIABLE_NAMES = new Set([
+    "PATH",
+    "HOME",
+    "USER",
+    "SHELL",
+    "PWD",
+    "TERM",
+    "CLAUDE_CODE_ENABLE_TELEMETRY",
+]);
+// DOCKER_: a value rides the docker client's own environment to reach the container, so a declared
+// DOCKER_HOST or DOCKER_CONTEXT from an --env-file would move `docker run` to another engine.
+const RESERVED_PREFIXES = ["MISE_", "OTEL_", "GIT_CONFIG_", "DOCKER_"];
+// On Windows, environment names are case-insensitive, so a declared docker_host reaches the docker
+// client as DOCKER_HOST; compare upper-cased there. Elsewhere user and USER are distinct (CTC-6152).
+export function isReservedVariableName(name, platform = process.platform) {
+    const key = platform === "win32" ? name.toUpperCase() : name;
+    return RESERVED_VARIABLE_NAMES.has(key) || RESERVED_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+export const TERMINAL_SOURCE = "this terminal";
+/** Resolve declared names: env files in order (later wins), then this terminal's own environment,
+ *  which wins over every file. Undeclared names are never read into `values`. */
+export function resolveShellVariables(declared, input) {
+    const values = {};
+    const set = [];
+    const missingRequired = [];
+    const unsetOptional = [];
+    const skippedReserved = [];
+    const used = new Set();
+    for (const variable of declared) {
+        if (isReservedVariableName(variable.name, input.platform)) {
+            skippedReserved.push(variable.name);
+            continue;
+        }
+        let value;
+        let source;
+        const fromTerminal = input.env[variable.name];
+        if (typeof fromTerminal === "string") {
+            value = fromTerminal;
+            source = TERMINAL_SOURCE;
+        }
+        else {
+            for (const file of input.envFiles) {
+                const fromFile = Object.hasOwn(file.values, variable.name) ? file.values[variable.name] : undefined;
+                if (typeof fromFile === "string") {
+                    value = fromFile;
+                    source = file.path;
+                }
+            }
+        }
+        if (value === undefined || source === undefined) {
+            (variable.required ? missingRequired : unsetOptional).push(variable.name);
+            continue;
+        }
+        values[variable.name] = value;
+        set.push(variable.name);
+        used.add(source);
+    }
+    const sources = [
+        ...(used.has(TERMINAL_SOURCE) ? [TERMINAL_SOURCE] : []),
+        ...input.envFiles.map((file) => file.path).filter((path, index, all) => used.has(path) && all.indexOf(path) === index),
+    ];
+    return { values, set, missingRequired: missingRequired.sort(), unsetOptional, skippedReserved, sources };
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}

package/dist/env/shell-docker.js

@@ -0,0 +1,137 @@
+// shell-docker.ts — the docker CLI as `catalyst env shell` uses it: is an engine running, where is
+// it, is the image here, one download through a throwaway config, and the container itself. Modelled
+// on onboard-runner.ts's spawnDocker, endpoint rule and anonymous pull.
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { constants, homedir, tmpdir as osTmpdir } from "node:os";
+import { join } from "node:path";
+const OUTPUT_CAP = 1_000_000;
+/** Spawn docker and wait for it. SIGINT reaches the child through the terminal's process group, so
+ *  this process only has to survive it; SIGTERM and SIGHUP are forwarded. Handlers go in `finally`. */
+function spawnWait(args, options) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn("docker", args, { env: options.env, stdio: options.stdio, timeout: options.timeoutMs });
+        }
+        catch {
+            resolve({ code: 127, stdout: "", stderr: "", missing: true });
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            if (stdout.length < OUTPUT_CAP)
+                stdout += chunk;
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            if (stderr.length < OUTPUT_CAP)
+                stderr += chunk;
+        });
+        const onInterrupt = () => { };
+        const forward = (signal) => () => {
+            child.kill(signal);
+        };
+        const onTerm = forward("SIGTERM");
+        const onHup = forward("SIGHUP");
+        process.on("SIGINT", onInterrupt);
+        process.on("SIGTERM", onTerm);
+        process.on("SIGHUP", onHup);
+        const done = (result) => {
+            process.off("SIGINT", onInterrupt);
+            process.off("SIGTERM", onTerm);
+            process.off("SIGHUP", onHup);
+            resolve(result);
+        };
+        child.on("error", (error) => done({ code: error.code === "ENOENT" ? 127 : 1, stdout, stderr, missing: error.code === "ENOENT" }));
+        child.on("close", (status, signal) => done({ code: exitCodeOf(status, signal), stdout, stderr, missing: false }));
+    });
+}
+export function exitCodeOf(status, signal) {
+    if (status !== null)
+        return status;
+    return signal ? 128 + (constants.signals[signal] ?? 0) : 1;
+}
+/** Docker's last non-empty error line, printable characters only. */
+export function lastLine(text) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => line.replace(/[^\x20-\x7e]/g, "").trim())
+        .filter((line) => line !== "");
+    return (lines.at(-1) ?? "").slice(0, 400);
+}
+export function spawnEnvShellDocker(deps) {
+    const env = deps.env;
+    const quiet = (args, timeoutMs = 30_000) => spawnWait(args, { env, stdio: ["ignore", "pipe", "pipe"], timeoutMs });
+    return {
+        async server() {
+            const read = await quiet(["version", "--format", "{{.Server.Os}}"]);
+            if (read.missing)
+                return { state: "missing" };
+            if (read.code !== 0)
+                return { state: "not_running" };
+            const os = read.stdout.trim();
+            return os === "linux" ? { state: "ok" } : { state: "not_linux", os: os.replace(/[^\x20-\x7e]/g, "").slice(0, 40) || "unknown" };
+        },
+        async endpoint() {
+            // Reject conflicting selectors rather than infer precedence across Docker versions.
+            if (env.DOCKER_CONTEXT && env.DOCKER_HOST)
+                return { ok: false, reason: "conflict" };
+            if (env.DOCKER_HOST)
+                return { ok: true, host: env.DOCKER_HOST };
+            const read = await quiet([
+                "context",
+                "inspect",
+                ...(env.DOCKER_CONTEXT ? [env.DOCKER_CONTEXT] : []),
+                "--format",
+                '{{(index .Endpoints "docker").Host}}',
+            ]);
+            const host = read.stdout.trim();
+            return read.code === 0 && host !== "" ? { ok: true, host } : { ok: false, reason: "unreadable" };
+        },
+        async imagePresent(ref) {
+            return (await quiet(["image", "inspect", "--format", "{{.Id}}", ref])).code === 0;
+        },
+        async pull(ref, host, config) {
+            let dir;
+            try {
+                // mkdtemp creates the directory 0700; the file is 0600 and holds nothing else.
+                dir = mkdtempSync(join((deps.tmpdir ?? osTmpdir)(), "catalyst-env-pull-"));
+                writeFileSync(join(dir, "config.json"), JSON.stringify(config), { mode: 0o600 });
+                const pullEnv = {
+                    ...env,
+                    DOCKER_CONFIG: dir,
+                    // A TLS endpoint keeps the developer's own certificates although the config moved.
+                    DOCKER_CERT_PATH: env.DOCKER_CERT_PATH || env.DOCKER_CONFIG || join(env.HOME || homedir(), ".docker"),
+                };
+                delete pullEnv.DOCKER_CONTEXT;
+                delete pullEnv.DOCKER_AUTH_CONFIG;
+                // Progress goes to our stderr, so `--json` stdout stays one line; the error stream is kept.
+                const result = await spawnWait(["--host", host, "--config", dir, "pull", ref], {
+                    env: pullEnv,
+                    stdio: ["ignore", 2, "pipe"],
+                    timeoutMs: 3_600_000,
+                });
+                if (result.missing)
+                    return { ok: false, detail: "docker is not installed" };
+                return { ok: result.code === 0, detail: lastLine(result.stderr) };
+            }
+            catch (error) {
+                return { ok: false, detail: error instanceof Error ? lastLine(error.message) : "the download could not start" };
+            }
+            finally {
+                if (dir)
+                    rmSync(dir, { recursive: true, force: true });
+            }
+        },
+        async run(argv, runEnv, mode) {
+            const result = await spawnWait(argv, {
+                env: runEnv,
+                stdio: mode === "interactive" ? "inherit" : ["ignore", "pipe", "inherit"],
+            });
+            return { code: result.code, stdout: result.stdout };
+        },
+    };
+}

package/dist/env/shell-plan.js

@@ -0,0 +1,120 @@
+// shell-plan.ts — the container `catalyst env shell` starts: the one `docker run` argv, the in-image
+// start script, the home volume's name and the reader for `--check`'s report. Pure: nothing here
+// spawns, reads a file or sees a variable's value. Values reach the container only as bare `-e NAME`
+// words, which Docker fills from the client process's environment.
+import { createHash } from "node:crypto";
+/** The start script's exit code when `mise install` could not prepare a declared toolchain. */
+export const START_EXIT_TOOLCHAIN = 97;
+/** The image's own user, as phases and `catalyst runner` run it. */
+export const ENV_SHELL_USER = "10001:10001";
+export const ENV_SHELL_WORKSPACE = "/workspace";
+const HOME = "/home/catalyst";
+/** Runs as `sh -c <this> catalyst-env-shell <shell|check> <name@version>...` inside the image.
+ *  Prototyped and run against mise 2026.8.14 in a Catalyst image in the plan phase (see the plan). */
+export const ENV_SHELL_START_SCRIPT = [
+    "set -u",
+    'mode="$1"; shift',
+    `if [ "$#" -gt 0 ]; then mise install "$@" >&2 || exit ${START_EXIT_TOOLCHAIN}; fi`,
+    'if [ "$mode" = check ]; then',
+    '  for spec in "$@"; do printf \'toolchain\\t%s\\t%s\\n\' "$spec" "$(basename "$(mise where "$spec")")"; done',
+    "  for name in ${CATALYST_ENV_NAMES:-}; do",
+    '    if printenv "$name" >/dev/null 2>&1; then printf \'variable\\t%s\\tset\\n\' "$name"; else printf \'variable\\t%s\\tunset\\n\' "$name"; fi',
+    "  done",
+    "  exit 0",
+    "fi",
+    // Not a login shell: that re-reads /etc/profile, which replaces the PATH mise just set, so the
+    // declared toolchain would be lost (CTC-6153). Not forced interactive either: bash decides from its
+    // stdin, so a terminal gets ~/.bashrc and piped input keeps non-interactive semantics.
+    'if [ "$#" -gt 0 ]; then exec mise exec "$@" -- bash; fi',
+    "exec bash -l",
+].join("\n");
+/** One home volume per image digest: downloaded toolchains and history persist, a new image starts fresh. */
+export function homeVolumeFor(image) {
+    const digest = /@sha256:([0-9a-f]{12})/.exec(image)?.[1];
+    return `catalyst-env-home-${digest ?? createHash("sha256").update(image).digest("hex").slice(0, 12)}`;
+}
+export function toolchainSpecs(toolchains) {
+    return toolchains.map((toolchain) => `${toolchain.name}@${toolchain.version}`);
+}
+/** THE argv builder: `--check` and the shell differ only by mode, -i/-t and CATALYST_ENV_NAMES. */
+export function shellRunArgs(input) {
+    const shell = input.mode === "shell";
+    return [
+        "run",
+        "--rm",
+        "--pull",
+        "never",
+        ...(shell ? ["-i"] : []),
+        ...(shell && input.tty ? ["-t"] : []),
+        "--user",
+        ENV_SHELL_USER,
+        "--mount",
+        `type=bind,src=${input.root},dst=${ENV_SHELL_WORKSPACE}`,
+        ...(input.gitCommonDir ? ["--mount", `type=bind,src=${input.gitCommonDir},dst=${input.gitCommonDir}`] : []),
+        "--mount",
+        `type=volume,src=${homeVolumeFor(input.image)},dst=${HOME}`,
+        "-w",
+        ENV_SHELL_WORKSPACE,
+        "-e",
+        `HOME=${HOME}`,
+        "-e",
+        "MISE_SYSTEM_DATA_DIR=/opt/catalyst/toolchain",
+        "-e",
+        "MISE_SHARED_INSTALL_DIRS=/opt/catalyst/toolchain/installs",
+        "-e",
+        "CLAUDE_CODE_ENABLE_TELEMETRY=0",
+        "-e",
+        "OTEL_METRICS_EXPORTER=none",
+        "-e",
+        "OTEL_LOGS_EXPORTER=none",
+        "-e",
+        "OTEL_TRACES_EXPORTER=none",
+        "-e",
+        "GIT_CONFIG_COUNT=1",
+        "-e",
+        "GIT_CONFIG_KEY_0=safe.directory",
+        "-e",
+        "GIT_CONFIG_VALUE_0=*",
+        ...(shell && input.tty ? ["-e", "TERM"] : []),
+        ...input.passNames.flatMap((name) => ["-e", name]),
+        ...(shell ? [] : ["-e", `CATALYST_ENV_NAMES=${input.checkNames.join(" ")}`]),
+        "--entrypoint",
+        "/bin/sh",
+        input.image,
+        "-c",
+        ENV_SHELL_START_SCRIPT,
+        "catalyst-env-shell",
+        input.mode,
+        ...toolchainSpecs(input.toolchains),
+    ];
+}
+/** Map the start script's check lines back to the declared specs and names. Null when any declared
+ *  spec or name has no line (or an empty version), so a partial report is never shown as ready. */
+export function parseCheckOutput(stdout, specs, names) {
+    const resolved = new Map();
+    const set = new Map();
+    for (const line of stdout.split(/\r?\n/)) {
+        const [kind, key, value, ...extra] = line.split("\t");
+        if (extra.length > 0 || key === undefined || value === undefined)
+            continue;
+        if (kind === "toolchain" && specs.includes(key) && value.trim() !== "")
+            resolved.set(key, value.trim());
+        if (kind === "variable" && names.includes(key) && (value === "set" || value === "unset"))
+            set.set(key, value === "set");
+    }
+    const toolchains = [];
+    for (const spec of specs) {
+        const version = resolved.get(spec);
+        if (version === undefined)
+            return null;
+        toolchains.push({ spec, resolved: version });
+    }
+    const variables = [];
+    for (const name of names) {
+        const value = set.get(name);
+        if (value === undefined)
+            return null;
+        variables.push({ name, set: value });
+    }
+    return { toolchains, variables };
+}

package/dist/env/shell-pull.js

@@ -0,0 +1,123 @@
+import { loadConfig } from "../config.js";
+import { loadContract } from "../contract.js";
+import { RUNNER_HOST_IMAGES } from "../onboard-runner.js";
+import { readLocalRepositoryName } from "../onboard-settings-context.js";
+import { apiClient } from "../transport.js";
+/** A non-empty `auths`, so the Docker CLI does not fall back to the platform's credential store. */
+export const CREDENTIAL_FREE_CONFIG = { auths: { "https://index.docker.io/v1/": {} } };
+export const PULL_USERNAME = "x-catalyst-pull";
+/** Docker's rule: the first path component is a registry when it has a "." or ":" or is "localhost". */
+export function registryOf(ref) {
+    const name = ref.split("@", 1)[0] ?? ref;
+    const slash = name.indexOf("/");
+    if (slash < 0)
+        return "docker.io";
+    const first = name.slice(0, slash);
+    return first.includes(".") || first.includes(":") || first === "localhost" ? first : "docker.io";
+}
+/** The contract's own path for the credential route: POST, ending in `/registry/pull-credential`. */
+export function pullCredentialRoute(doc) {
+    return doc.routes.find((r) => r.method === "POST" && r.path.endsWith("/registry/pull-credential"))?.path ?? null;
+}
+const REGISTRY_HOST_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+(?::[0-9]{1,5})?$/;
+const REPOSITORY_RE = /^[a-z0-9]+(?:(?:[._-]|__)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:[._-]|__)[a-z0-9]+)*)*$/;
+const PASSWORD_RE = /^[\x21-\x7e]{8,4096}$/;
+/** Strict: anything but the CTC-2565 answer shapes is `invalid`, never a partial credential. */
+export function parsePullCredential(body, nowMs) {
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return { kind: "invalid" };
+    const answer = body;
+    if (answer.issued === false)
+        return typeof answer.refusal === "string" && /^[a-z_]{1,64}$/.test(answer.refusal)
+            ? { kind: "refused", refusal: answer.refusal }
+            : { kind: "invalid" };
+    if (answer.issued !== true)
+        return { kind: "invalid" };
+    const { registry, repository, username, password, expiresAtMs } = answer;
+    if (typeof registry !== "string" ||
+        !REGISTRY_HOST_RE.test(registry) ||
+        typeof repository !== "string" ||
+        repository.length > 255 ||
+        !REPOSITORY_RE.test(repository) ||
+        username !== PULL_USERNAME ||
+        typeof password !== "string" ||
+        !PASSWORD_RE.test(password) ||
+        typeof expiresAtMs !== "number" ||
+        !Number.isFinite(expiresAtMs) ||
+        expiresAtMs <= nowMs)
+        return { kind: "invalid" };
+    return { kind: "issued", credential: { registry, repository, username, password, expiresAtMs } };
+}
+/** Covers only `<registry>/<repository>[:tag]@sha256:…`, never a sibling that shares a prefix. */
+export function credentialCovers(ref, credential) {
+    const prefix = `${credential.registry}/${credential.repository}`;
+    if (!ref.startsWith(prefix))
+        return false;
+    return /^(?::[A-Za-z0-9_][A-Za-z0-9._-]{0,127})?@sha256:[0-9a-f]{64}$/.test(ref.slice(prefix.length));
+}
+const REFUSAL_REASONS = {
+    disabled: "download credentials are not turned on for your workspace",
+    not_configured: "download credentials are not turned on for your workspace",
+};
+function withoutStop(text) {
+    return text.replace(/[.\s]+$/, "");
+}
+export async function downloadImage(input) {
+    const { ref, host, ctx, docker, notify } = input;
+    notify(ref === RUNNER_HOST_IMAGES.runner
+        ? "  Downloading it with no credential (about 2.3 GB, once per image)…"
+        : "  Downloading it with no credential…");
+    const anonymous = await docker.pull(ref, host, CREDENTIAL_FREE_CONFIG);
+    if (anonymous.ok) {
+        notify("  Downloaded.");
+        return { ok: true, credential: "none" };
+    }
+    const refused = `Could not download ${ref} with no credential: ${withoutStop(anonymous.detail) || "docker pull failed"}.`;
+    const refuse = (code, message) => ({ ok: false, refusal: { code, message } });
+    const cfg = loadConfig(ctx.home);
+    if (!cfg)
+        return refuse("image_download_refused", `${refused} If this image needs your workspace's permission, sign in with catalyst login and run this again.`);
+    const credentialRefused = (reason) => refuse("credential_refused", `Your workspace did not issue a download credential for ${ref}: ${reason}.`);
+    let route;
+    try {
+        route = pullCredentialRoute((await loadContract(ctx, cfg)).doc);
+    }
+    catch (error) {
+        return credentialRefused(withoutStop(error instanceof Error ? error.message : String(error)));
+    }
+    if (!route)
+        return refuse("image_download_refused", `${refused} Your Catalyst Cloud does not issue download credentials.`);
+    const repositoryName = await (input.readRepositoryName ?? readLocalRepositoryName)(input.root);
+    const [owner, name, ...extra] = repositoryName?.split("/") ?? [];
+    if (!owner || !name || extra.length > 0)
+        return refuse("repository_unknown", "This checkout's origin is not a GitHub repository, so your workspace cannot issue it a download credential.");
+    notify("  The download needs permission. Asking your workspace for a short-lived download credential…");
+    let body;
+    try {
+        body = (await apiClient(cfg, ctx).postJson(route, { owner, name }, { accept: [200] })).body;
+    }
+    catch {
+        return credentialRefused("the request was refused");
+    }
+    const nowMs = ctx.now().getTime();
+    const answer = parsePullCredential(body, nowMs);
+    if (answer.kind === "invalid")
+        return credentialRefused("the answer was not understood");
+    if (answer.kind === "refused")
+        return credentialRefused(answer.refusal === "unknown_repository"
+            ? `${owner}/${name} is not a repository in your workspace`
+            : (REFUSAL_REASONS[answer.refusal] ?? "the request was refused"));
+    const credential = answer.credential;
+    if (!credentialCovers(ref, credential))
+        return refuse("credential_out_of_scope", `Your workspace issued a download credential for ${credential.registry}/${credential.repository}, which does not cover ${ref}. Nothing was sent to ${registryOf(ref)}.`);
+    const minutes = Math.max(1, Math.floor((credential.expiresAtMs - nowMs) / 60_000));
+    notify(`  Downloading it with a short-lived credential your workspace issued (valid for ${minutes} minutes)…`);
+    const auth = Buffer.from(`${credential.username}:${credential.password}`).toString("base64");
+    const issued = await docker.pull(ref, host, { auths: { [credential.registry]: { auth } } });
+    if (issued.ok) {
+        notify("  Downloaded.");
+        return { ok: true, credential: "issued" };
+    }
+    const detail = withoutStop(issued.detail.split(credential.password).join("[redacted]").split(auth).join("[redacted]"));
+    return refuse("image_download_refused", `Could not download ${ref} with the credential your workspace issued: ${detail || "docker pull failed"}.`);
+}

package/dist/env/shell.js

@@ -0,0 +1,288 @@
+// shell.ts — `catalyst env shell [--check]`: open this repository's environment on this computer.
+// Every refusal a person can fix in the file or the terminal fires before Docker is touched; the
+// cloud is asked only when a credential-free download is refused (shell-pull.ts).
+import { execFile } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { basename, isAbsolute, relative, resolve } from "node:path";
+import { parseEnv, promisify } from "node:util";
+import { flagBool, flagList, flagString, positionals } from "../args.js";
+import { UsageError } from "../errors.js";
+import { IMAGE_REF, RUNNER_HOST_IMAGES } from "../onboard-runner.js";
+import { readLocalRepositoryName } from "../onboard-settings-context.js";
+import { readLocalSettings } from "./settings-authority.js";
+import { readShellDeclaration, resolveShellVariables } from "./shell-declaration.js";
+import { spawnEnvShellDocker } from "./shell-docker.js";
+import { parseCheckOutput, shellRunArgs, START_EXIT_TOOLCHAIN, toolchainSpecs } from "./shell-plan.js";
+import { downloadImage } from "./shell-pull.js";
+const DECLARATION = ".catalyst/catalyst.toml";
+const IMAGE_UID = 10001;
+const run = promisify(execFile);
+/** Git with no global or system config, no prompt, bounded: a path, or null. */
+async function gitPath(cwd, args) {
+    try {
+        const { stdout } = await run("git", args, {
+            cwd,
+            timeout: 3_000,
+            maxBuffer: 16_384,
+            env: {
+                PATH: process.env.PATH,
+                GIT_CONFIG_GLOBAL: "/dev/null",
+                GIT_CONFIG_NOSYSTEM: "1",
+                GIT_TERMINAL_PROMPT: "0",
+            },
+        });
+        const path = stdout.trim();
+        return path !== "" && isAbsolute(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+const defaultGitTopLevel = (cwd) => gitPath(cwd, ["rev-parse", "--show-toplevel"]);
+const defaultGitCommonDir = (root) => gitPath(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+/** The digest shortened for a person: `<name>@sha256:<12 hex>…`. */
+function shortImage(image) {
+    return image.replace(/@sha256:([0-9a-f]{12})[0-9a-f]{52}$/, "@sha256:$1…");
+}
+function inside(child, parent) {
+    const rel = relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function unmountable(path) {
+    if (path.includes(","))
+        return `env shell cannot mount ${path}: the path contains a comma.`;
+    if (/[\r\n]/.test(path))
+        return `env shell cannot mount ${JSON.stringify(path)}: the path contains a line break.`;
+    return null;
+}
+function toolchainLine(toolchains) {
+    return toolchains.length === 0
+        ? "  Toolchain: none declared"
+        : `  Toolchain: ${toolchains.map((t) => `${t.name} ${t.version}`).join(", ")} (the first start downloads any version the image lacks)`;
+}
+function joinSources(sources) {
+    return sources.length <= 1 ? (sources[0] ?? "") : `${sources.slice(0, -1).join(", ")} and ${sources.at(-1)}`;
+}
+export async function runEnvShell(args, ctx, deps = {}) {
+    // 1. Flags.
+    const [, ...rest] = positionals(args);
+    if (rest.length > 0)
+        throw new UsageError(`env shell takes no positional arguments (got "${rest[0]}"); use --root DIR`);
+    const check = flagBool(args, "check");
+    const json = args.json;
+    if (json && !check)
+        throw new UsageError("env shell --json needs --check: the shell itself is interactive");
+    const imageFlag = flagString(args, "image");
+    if (imageFlag !== undefined && !IMAGE_REF.test(imageFlag))
+        throw new UsageError("env shell --image needs a digest-pinned reference, such as ghcr.io/owner/image@sha256:<64 hex>");
+    const image = imageFlag ?? RUNNER_HOST_IMAGES.runner;
+    const say = (line) => {
+        if (!json)
+            ctx.stdout(line);
+    };
+    const notice = (line) => (json ? ctx.stderr(line) : ctx.stdout(line));
+    const refuse = (refusal) => {
+        if (json)
+            ctx.stdout(JSON.stringify({ ok: false, refusal }));
+        else
+            for (const line of refusal.message.split("\n"))
+                ctx.stderr(line);
+        return 1;
+    };
+    // 2. Root.
+    const rootFlag = flagString(args, "root");
+    const start = resolve(rootFlag ?? ".");
+    const requested = rootFlag !== undefined ? start : ((await (deps.gitTopLevel ?? defaultGitTopLevel)(start)) ?? start);
+    let root;
+    try {
+        root = realpathSync(requested);
+    }
+    catch {
+        return refuse({
+            code: "declaration_missing",
+            message: `No ${DECLARATION} in ${requested}. Draft one with: catalyst env draft --write`,
+        });
+    }
+    const rootProblem = unmountable(root);
+    if (rootProblem)
+        return refuse({ code: "repository_path_unsupported", message: rootProblem });
+    // 3. Declaration.
+    const text = await readLocalSettings(root);
+    if (text === null)
+        return refuse({
+            code: "declaration_missing",
+            message: `No ${DECLARATION} in ${root}. Draft one with: catalyst env draft --write`,
+        });
+    const declaration = readShellDeclaration(text);
+    if (declaration.state === "invalid")
+        return refuse({
+            code: "declaration_invalid",
+            message: [...declaration.errors.map((error) => `${DECLARATION}: ${error}`), "Fix the file, then run catalyst env check."].join("\n"),
+        });
+    if (declaration.state === "unsupported") {
+        const { name, version } = declaration.toolchain;
+        return refuse({
+            code: "toolchain_version_unsupported",
+            message: `${name} ${JSON.stringify(version)} is a version range. env shell prepares an exact or prefix version, such as 22 or 22.23.3. Change it in ${DECLARATION}.`,
+        });
+    }
+    // 4. Variables.
+    const envFiles = [];
+    for (const path of flagList(args, "env-file")) {
+        try {
+            envFiles.push({ path, values: parseEnv(readFileSync(resolve(path), "utf8")) });
+        }
+        catch {
+            return refuse({ code: "env_file_unreadable", message: `could not read --env-file ${path}` });
+        }
+    }
+    const variables = resolveShellVariables(declaration.variables, { env: ctx.env, envFiles, platform: deps.platform });
+    if (variables.missingRequired.length > 0)
+        return refuse({
+            code: "variables_missing",
+            message: `These required variables are not set in this terminal or an --env-file: ${variables.missingRequired.join(", ")}. Set them, then run catalyst env shell again.`,
+            names: variables.missingRequired,
+        });
+    // 5. Engine.
+    const docker = deps.docker ?? spawnEnvShellDocker({ env: ctx.env });
+    const server = await docker.server();
+    if (server.state === "missing")
+        return refuse({
+            code: "docker_missing",
+            message: "Docker is not installed on this computer. Install Docker Desktop, OrbStack or Docker Engine, then run catalyst env shell again.",
+        });
+    if (server.state === "not_running")
+        return refuse({
+            code: "docker_not_running",
+            message: "Docker is installed but not running. Start Docker Desktop, OrbStack or Docker Engine, then run catalyst env shell again.",
+        });
+    if (server.state === "not_linux")
+        return refuse({
+            code: "docker_not_linux",
+            message: `Docker is running ${server.os} containers. Switch it to Linux containers, then run catalyst env shell again.`,
+        });
+    // 6. Image.
+    const readRepositoryName = deps.readRepositoryName ?? readLocalRepositoryName;
+    const repository = (await readRepositoryName(root)) ?? basename(root);
+    say(`Environment for ${repository}, from ${DECLARATION}`);
+    const present = await docker.imagePresent(image);
+    say(`  Image: ${shortImage(image)} (${present ? "already on this computer" : "not on this computer yet"})`);
+    let credential = "none";
+    if (!present) {
+        const endpoint = await docker.endpoint();
+        if (!endpoint.ok)
+            return refuse(endpoint.reason === "conflict"
+                ? {
+                    code: "docker_endpoint_conflict",
+                    message: "DOCKER_HOST and DOCKER_CONTEXT are both set. Unset one, then run catalyst env shell again.",
+                }
+                : {
+                    code: "docker_endpoint_unreadable",
+                    message: "Docker's current context could not be read. Check it with docker context ls, then run catalyst env shell again.",
+                });
+        const downloaded = await downloadImage({ ref: image, host: endpoint.host, root, ctx, docker, notify: notice, readRepositoryName });
+        if (!downloaded.ok)
+            return refuse(downloaded.refusal);
+        credential = downloaded.credential;
+    }
+    // 7. Git common directory: a worktree's shared .git outside the root is mounted at its own path.
+    const commonDir = await (deps.gitCommonDir ?? defaultGitCommonDir)(root);
+    let gitCommonDir = null;
+    if (commonDir !== null) {
+        let real = commonDir;
+        try {
+            real = realpathSync(commonDir);
+        }
+        catch {
+            // Not there any more: git inside the shell reports it; nothing is mounted.
+        }
+        if (!inside(real, root)) {
+            const problem = unmountable(real);
+            if (problem)
+                return refuse({ code: "repository_path_unsupported", message: problem });
+            gitCommonDir = real;
+        }
+    }
+    // 8. Run.
+    const tty = !check && (deps.isTty?.() ?? (process.stdin.isTTY === true && process.stdout.isTTY === true));
+    const checkNames = declaration.variables.map((v) => v.name).filter((name) => !variables.skippedReserved.includes(name));
+    const argv = shellRunArgs({
+        mode: check ? "check" : "shell",
+        image,
+        root,
+        gitCommonDir,
+        toolchains: declaration.toolchains,
+        passNames: variables.set,
+        tty,
+        checkNames,
+    });
+    const runEnv = { ...ctx.env, ...variables.values };
+    if (tty)
+        runEnv.TERM = ctx.env.TERM || "xterm-256color";
+    if (variables.skippedReserved.length > 0)
+        notice(`  Note: env shell sets ${variables.skippedReserved.join(", ")} itself, so the declared value is not used.`);
+    const uid = deps.uid ?? process.getuid?.();
+    if ((deps.platform ?? process.platform) === "linux" && uid !== undefined && uid !== IMAGE_UID)
+        notice(`Note: the shell runs as uid ${IMAGE_UID}, as Catalyst's agents do. Files here belong to uid ${uid}, so on Docker Engine for Linux the shell may not be able to write them.`);
+    const toolchainNotPrepared = {
+        code: "toolchain_not_prepared",
+        message: `The shell did not start: a declared toolchain could not be prepared (mise's message above says which). Check the name and version in ${DECLARATION}, then run catalyst env shell --check.`,
+    };
+    const secret = new Set(declaration.variables.filter((v) => v.secret).map((v) => v.name));
+    if (!check) {
+        say(toolchainLine(declaration.toolchains));
+        const set = variables.set.map((name) => (secret.has(name) ? `${name} (secret)` : name));
+        const parts = [
+            ...(set.length > 0 ? [`${set.join(", ")} set from ${joinSources(variables.sources)}`] : []),
+            ...(variables.unsetOptional.length > 0 ? [`not set: ${variables.unsetOptional.map((name) => `${name} (optional)`).join(", ")}`] : []),
+        ];
+        say(`  Variables: ${parts.length > 0 ? parts.join("; ") : "none declared"}`);
+        say(`  Your repository is at /workspace. Type exit to leave.`);
+        const result = await docker.run(argv, runEnv, "interactive");
+        if (result.code === START_EXIT_TOOLCHAIN)
+            return refuse(toolchainNotPrepared);
+        return result.code;
+    }
+    const result = await docker.run(argv, runEnv, "capture");
+    if (result.code === START_EXIT_TOOLCHAIN)
+        return refuse(toolchainNotPrepared);
+    const specs = toolchainSpecs(declaration.toolchains);
+    const report = result.code === 0 ? parseCheckOutput(result.stdout, specs, checkNames) : null;
+    if (report === null)
+        return refuse({
+            code: "check_incomplete",
+            message: `The environment check did not finish (exit ${result.code}). Run catalyst env shell --check again; if it repeats, open the shell and run mise doctor.`,
+        });
+    const byName = new Map(declaration.variables.map((v) => [v.name, v]));
+    const resolvedBySpec = new Map(report.toolchains.map((t) => [t.spec, t.resolved]));
+    const resolvedOf = (t) => resolvedBySpec.get(`${t.name}@${t.version}`) ?? "";
+    if (json) {
+        ctx.stdout(JSON.stringify({
+            ok: true,
+            repository,
+            declaration: DECLARATION,
+            image: { reference: image, source: present ? "present" : "downloaded", credential },
+            toolchains: declaration.toolchains.map((t) => ({ name: t.name, version: t.version, resolved: resolvedOf(t) })),
+            variables: report.variables.map((v) => ({
+                name: v.name,
+                required: byName.get(v.name)?.required === true,
+                secret: byName.get(v.name)?.secret === true,
+                set: v.set,
+            })),
+        }));
+        return 0;
+    }
+    say(declaration.toolchains.length === 0
+        ? "  Toolchain: none declared"
+        : `  Toolchain: ${declaration.toolchains.map((t) => `${t.name} ${t.version} → ${resolvedOf(t)}`).join(", ")}`);
+    say(`  Variables: ${report.variables.length === 0
+        ? "none declared"
+        : report.variables
+            .map((v) => {
+            const notes = [...(secret.has(v.name) ? ["secret"] : []), ...(!v.set && byName.get(v.name)?.required !== true ? ["optional"] : [])];
+            return `${v.name} ${v.set ? "set" : "not set"}${notes.length > 0 ? ` (${notes.join(", ")})` : ""}`;
+        })
+            .join(", ")}`);
+    say("Ready: catalyst env shell opens this environment.");
+    return 0;
+}

package/dist/env.js

@@ -1,7 +1,9 @@
-// env.ts — `catalyst env inventory` / `env check`: a LOCAL, OFFLINE, repo-scoped reporter and
-// validator. Unlike every other verb in this file's siblings, `cmdEnv` never calls `requireConfig` or
-// `apiClient` — it needs neither a login nor a network call, which is the whole point of the feature:
-// a person reviews what a repository declares without connecting anything first.
+// env.ts — `catalyst env inventory` / `check` / `migrate` / `draft`: a LOCAL, OFFLINE, repo-scoped
+// reporter and validator. Unlike every other verb in this file's siblings, those four never call
+// `requireConfig` or `apiClient` — they need neither a login nor a network call, which is the whole
+// point of the feature: a person reviews what a repository declares without connecting anything first.
+// `env shell` (env/shell.ts) talks to Docker, and asks the cloud only when a credential-free download
+// of the image is refused; Catalyst's own image needs no login.
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { flagBool, flagString, positionals } from "./args.js";
@@ -10,11 +12,14 @@ import { convertLegacyEnvironmentJson } from "./env/legacy.js";
 import { draftEnvironment } from "./env/draft.js";
 import { inventoryRepo } from "./env/inventory.js";
 import { inventoryToJson, renderInventory } from "./env/render.js";
+import { runEnvShell } from "./env/shell.js";
 import { UsageError } from "./errors.js";
 export async function cmdEnv(args, ctx, deps = {}) {
     const [sub, ...rest] = positionals(args);
     if (sub === undefined)
-        throw new UsageError("env needs a subcommand: inventory | check | migrate | draft");
+        throw new UsageError("env needs a subcommand: inventory | check | migrate | draft | shell");
+    if (sub === "shell")
+        return await runEnvShell(args, ctx, deps.shell ?? {});
     if (sub === "draft") {
         if (rest.length > 0)
             throw new UsageError("env draft takes no positional arguments; use --root DIR");
@@ -172,5 +177,5 @@ export async function cmdEnv(args, ctx, deps = {}) {
                 ctx.stderr(`${file}: ${error}`);
         return result.state === "invalid" ? 1 : 0;
     }
-    throw new UsageError(`unknown env subcommand "${sub}": inventory | check | migrate | draft`);
+    throw new UsageError(`unknown env subcommand "${sub}": inventory | check | migrate | draft | shell`);
 }

package/dist/onboard-next.js

@@ -109,7 +109,6 @@ const REASONS = {
     workflow_unavailable: "Setup could not read the team's workflow. Run catalyst onboard again to retry.",
     capacity_context_unverified: "Setup could not confirm this project's registered repositories and its default repository for capacity. Run catalyst ready to see the project checks, then run catalyst setup again. Starting a ticket checks its own repository's admission.",
     capacity_identity_unverified: "Setup could not confirm your workspace and administrator role for the capacity check. Run catalyst login, then run catalyst setup again.",
-    capacity_admission_unverified: "No runner is allowed to take work for this workspace yet. Enroll a self-hosted runner host, or ask Catalyst to enable cloud runners for it. Then run catalyst onboard.",
     capacity_currently_full: "Every runner slot for this repository is in use. Run catalyst onboard again after current work finishes.",
     capacity_unavailable: "Setup could not read runner capacity. Run catalyst onboard again to retry.",
     runner_not_selected: "This setup does not start a runner on this machine. To start one, run catalyst onboard --runner.",
@@ -424,9 +423,16 @@ export function onboardReasonText(step, context = {}) {
             ? `This setup step is not available on this server yet. Continue in the web app at ${page}, then run catalyst onboard.`
             : "This setup step is not available on this server yet. Run catalyst onboard after the server update.";
     }
+    // CTC-6180: the command that enrolls this computer, named with its team.
+    // The command is its own line (never wrapped), and runnable as printed: with no known team key,
+    // setup asks for the team.
+    if (reason === "capacity_admission_unverified") {
+        const key = onboardTeamKey(context.journal);
+        return `No runner is allowed to take work for this workspace yet. To use Catalyst's cloud runners, ask Catalyst support to turn on cloud runners for your workspace, then run catalyst onboard. To run work on this computer instead, enroll it as a self-hosted runner${key ? "" : " (setup asks for your Linear team)"} with:\ncatalyst onboard --runner${key ? ` --team ${key}` : ""}`;
+    }
     if (reason === "runner_native_egress_setup_required") {
-        const commands = nativeEgressInstallCommands();
-        return "Native Linux needs a root-managed session egress producer before the runner can take work. Its elevated installation creates the isolated session network and private-range and host-isolation nftables rules. Review and authorize this separately; setup has not run it. It requires systemd, python3, Docker and nftables. " + (commands ? "Install the verified bundled artifacts, then run the same setup command:\n" + commands : "Setup could not verify its bundled artifacts. Reinstall the CLI before authorizing installation.");
+        const command = nativeEgressInstallCommands();
+        return "Native Linux needs a root-managed session egress service before this computer can take work. It creates the isolated session network and the nftables rules that keep sessions off private addresses and this machine. It needs systemd, python3, Docker and nftables, and setup has not run it. " + (command ? "Review it, run this one command, then run the same setup command:\n" + command : "Setup could not verify its bundled files. Reinstall the CLI, then run the same setup command.");
     }
     if (reason === "runner_images_unavailable" || reason === "runner_supervisor_image_unavailable") {
         const image = step.evidence?.image;

package/dist/onboard-runner-egress.js

@@ -51,10 +51,20 @@ export async function nativeEgressReady(now, signal, io = nodeReads) {
         return false;
     }
 }
-/** Exact bundled bytes are checked before showing the separate, elevated install commands. */
+export const EGRESS_INSTALLER = { name: 'install-session-egress.sh', digest: 'b187180a9e5965ebe5e356a5c133ff2ec715fb294197cd636f8ff1301dc49ff0' };
+const quote = (s) => "'" + s.replaceAll("'", "'\\''") + "'";
+/** CTC-6180: root copies the installer into its own temp file, checks the pinned digest there and
+ * runs only those bytes, so an edit to the user-writable CLI install cannot run as root. */
+export function egressInstallCommand(vendor, digest = EGRESS_INSTALLER.digest, sudo = 'sudo ') {
+    const script = `t=$(mktemp) && cp -- ${quote(join(vendor, EGRESS_INSTALLER.name))} "$t" && echo ${quote(digest + '  ')}"$t" | sha256sum -c --quiet - && sh "$t" ${quote(vendor)}; s=$?; rm -f "$t"; exit $s`;
+    return `${sudo}sh -c ${quote(script)}`;
+}
+/** Exact bundled bytes are checked before showing the one elevated install command (CTC-6180). */
 export function nativeEgressInstallCommands() {
-    const root = join(packageRoot(), 'vendor/self-host/linux-session-egress');
+    const vendor = join(packageRoot(), 'vendor'), root = join(vendor, 'self-host/linux-session-egress');
     try {
+        if (hash(readFileSync(join(vendor, EGRESS_INSTALLER.name))) !== EGRESS_INSTALLER.digest)
+            return null;
         for (const artifact of EGRESS_ARTIFACTS)
             if (hash(readFileSync(join(root, artifact.name))) !== artifact.digest)
                 return null;
@@ -62,6 +72,5 @@ export function nativeEgressInstallCommands() {
     catch {
         return null;
     }
-    const quote = (s) => "'" + s.replaceAll("'", "'\\''") + "'";
-    return EGRESS_ARTIFACTS.map(a => `sudo install ${a.name === 'session-egress.py' ? '-D ' : ''}-o root -g root -m ${a.mode.toString(8)} ${quote(join(root, a.name))} ${quote(a.path)}`).join('\n') + '\nsudo systemctl daemon-reload\nsudo systemctl enable --now catalyst-session-egress.service catalyst-session-egress-attest.timer\nsudo /usr/bin/python3 /usr/lib/catalyst/session-egress.py attest';
+    return egressInstallCommand(vendor);
 }

package/dist/onboard-runner.js

@@ -29,7 +29,7 @@ export const RUNNER_HOST_IMAGES = {
     watchdog: "ghcr.io/coalesce-labs/catalyst-deadline-watchdog@sha256:63a9b20c3be3dc3ea328d77aa68dece942a40be46cb3126d9a7868e082828feb",
     runner: "ghcr.io/coalesce-labs/catalyst-runner@sha256:a19f7b0859a9814740935f7aadd8fe5c5c9c5974f9a5956a057b983ada16ea01",
 };
-const IMAGE_REF = /^[a-z0-9][a-z0-9._:/-]{0,255}@sha256:[0-9a-f]{64}$/;
+export 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";

package/dist/setup-render.js

@@ -122,19 +122,21 @@ export function createSetupRenderer(stream, env, banner = {}) {
         const indent = /^ */.exec(text)?.[0].length ?? 0;
         col += indent;
         text = text.slice(indent);
-        return wrapAnsi(text, Math.max(1, width - col), {
-            hard: false,
-            wordWrap: true,
-            trim: true,
-        })
-            .split("\n")
-            .map((line) => {
-            const plain = visible(line);
-            const indent = /^https?:\/\/\S+$/.test(plain) && stringWidth(plain) > width - col
-                ? textCol
-                : col;
-            return prefix(indent) + line;
-        });
+        // CTC-6180: each line after the first is a command a person copies, so it is never wrapped.
+        const [prose = "", ...commands] = text.split("\n");
+        return [...wrapAnsi(prose, Math.max(1, width - col), {
+                hard: false,
+                wordWrap: true,
+                trim: true,
+            })
+                .split("\n")
+                .map((line) => {
+                const plain = visible(line);
+                const indent = /^https?:\/\/\S+$/.test(plain) && stringWidth(plain) > width - col
+                    ? textCol
+                    : col;
+                return prefix(indent) + line;
+            }), ...commands.map((command) => prefix(col) + command)];
     };
     const stepRows = (kind, number, title, outcome, plan = false) => {
         refresh();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.16.19",
+  "version": "0.16.20",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.19 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.20 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the cloud API by default, with local replica reads available as an explicit opt-in, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.19 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.20 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 

package/skills/catalyst-onboard/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.19 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.20 — written in this repository for customer accounts -->
 
 # Onboard me
 

package/skills/run-this-project/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the account's event stream for the scope through the catalyst CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.19 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.20 — written in this repository for customer accounts -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.19 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.20 — written in this repository for customer accounts -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The human's decision inbox on Catalyst Cloud, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by how much open work each one holds, files an ask through the cloud's ask route with the account's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.19 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.20 — written in this repository for customer accounts -->
 
 # What needs me
 

package/skills/what-this-repo-needs/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups (build/test, deploy-only, bindings), each with where it was found, what uses it, and where a local value would come from. Never reads a value or prints one. Also checks the environment variable table in `.catalyst/catalyst.toml` offline. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing the declaration.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.19 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.20 — written in this repository for customer accounts -->
 
 # What this repository needs
 

package/skills/whats-happening/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Use for "what's happening?", "what machines do we have?", "how much capacity do we have?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.19 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.20 — written in this repository for customer accounts -->
 
 # What's happening
 

package/vendor/install-session-egress.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+# Installs Catalyst's session egress service on a native Linux runner machine, from the files
+# that ship with this catalyst CLI. Setup prints the one command that runs it as root from a
+# checked root-owned copy, passing the CLI's vendor folder as $1. It copies the files into a
+# root-owned folder, checks their fingerprints there, and installs only checked bytes.
+set -eu
+if [ "$(id -u)" != 0 ]; then
+  echo "Run this with sudo: sudo sh '$0'" >&2
+  exit 1
+fi
+src="${1:-$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)}/self-host/linux-session-egress"
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+for name in session-egress.py catalyst-session-egress.service catalyst-session-egress-attest.service catalyst-session-egress-attest.timer; do
+  cp "$src/$name" "$work/$name"
+done
+(cd "$work" && sha256sum -c --quiet -) <<'SUMS'
+a20cedfa1e883127ec461e4b7f9588d379fe1633b8244ecd703c81f589d3f142  session-egress.py
+703c150ab23ec87aea47cfc394f63e061b66c4b8c1454a88a9be879c161ce2a5  catalyst-session-egress.service
+94fa75ea0616f6a1172fc20ca637a5727c36456357e4a977d5bdd65f2fad2e8d  catalyst-session-egress-attest.service
+176622c11c835601b95f36e375ba3c2e993136976c67e5d49559f13a3454fef9  catalyst-session-egress-attest.timer
+SUMS
+install -D -o root -g root -m 755 "$work/session-egress.py" /usr/lib/catalyst/session-egress.py
+for unit in catalyst-session-egress.service catalyst-session-egress-attest.service catalyst-session-egress-attest.timer; do
+  install -o root -g root -m 644 "$work/$unit" "/etc/systemd/system/$unit"
+done
+systemctl daemon-reload
+systemctl enable --now catalyst-session-egress.service catalyst-session-egress-attest.timer
+/usr/bin/python3 /usr/lib/catalyst/session-egress.py attest
+echo "Session egress is installed. Run the same catalyst setup command again."