@catalyst-cloud/cli 0.16.19 → 0.16.21

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.16.21
+
+`catalyst accounts` now leaves out removed AI accounts: ones an admin revoked, or whose paid access ended. They take no work and take no new credential, so they no longer appear as accounts to repair. The list says how many it left out, and `catalyst accounts --all` shows them, marked "removed — kept for history". Setup now names a revoked account as ended instead of asking you to turn it on. Update the Catalyst plugin's skills along with the CLI: setup's account check uses `--all`, which older CLIs do not know.
+
+## 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

@@ -331,7 +331,9 @@ export const FLAG_TABLES = {
             help: "skip the published-release check (no network)",
         },
     },
-    accounts: {},
+    accounts: {
+        all: { value: false, help: "also list removed accounts, which are kept for history and take no work" },
+    },
     seat: {
         size: { value: true, help: "model size: big or med" },
         stage: { value: true, help: "sized relay stage; defaults from size" },
@@ -342,7 +344,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 +354,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: {
@@ -525,11 +540,11 @@ export const VERB_USAGE = {
     write: "write <comment <ticket> --body|--stdin [--parent] [--bookkeeping] [--as-user] | state <ticket> --slot|--state-id|--state-type | label <ticket> --add... --remove... | create --team --title [--description|--stdin] [--label] [--priority] | reaction <ticket>|--comment <id> --emoji <e> | attachment <ticket> --title --url | session <ticket> [--title] [--plan-file] [--activity]>",
     ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] [--gates-pr <n>... --released-by <letter>... [--gates-label hold|hold:preview]... [--gates-repo <owner/name>]] | accept <askTicket> --answer <commentId> --role <role> | list [--anyone] [--json]>",
     ready: "ready [--onboarding] [--local-sync] [--json] [--offline]",
-    accounts: "accounts [--json]",
+    accounts: "accounts [--all] [--json]",
     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"}.`);
+}