@catalyst-cloud/cli 0.16.13 → 0.16.15

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.16.15
+
+Command-line workflows can report stage progress with `catalyst stage start`, `renew`, `done`, and `fail`, and choose an eligible AI account and model for a local session with `catalyst seat checkout`. Retries reuse the same stage attempt. `catalyst write create --label` and `write label --add`/`--remove` now accept a label by name, and a refused write exits non-zero with a JSON error on stdout under `--json`.
+
+## 0.16.14
+
+Setup uses the updated macOS folder checks and verifies the required release image before starting work. Re-run setup to update this computer.
+
 ## 0.16.13
 
 Setup on macOS now verifies private file access when Docker changes a folder’s displayed owner in either direction. Signed access verification remains required. Re-run setup to update this computer.

package/dist/args.js

@@ -327,6 +327,13 @@ export const FLAG_TABLES = {
         },
     },
     accounts: {},
+    seat: {
+        size: { value: true, help: "model size: big or med" },
+        stage: { value: true, help: "sized relay stage; defaults from size" },
+        harness: { value: true, help: "comma-separated runnable harnesses" },
+        "session-id": { value: true, help: "stable id for this local session; generated when omitted" },
+        "key-env": { value: true, help: "read the bearer from this environment variable, never argv" },
+    },
     env: {
         root: {
             value: true,
@@ -483,6 +490,12 @@ export const FLAG_TABLES = {
             help: "with --class: at most this many tickets (the cloud caps it at 25)",
         },
     },
+    stage: {
+        artifact: { value: true, help: "done/fail: path to the phase artifact" },
+        evidence: { value: true, help: "done: JSON file with phase-specific receipt evidence" },
+        summary: { value: true, help: "done/fail: concise outcome summary" },
+        assertion: { value: true, help: "renew: work completed since the previous renewal" },
+    },
 };
 export const VERB_USAGE = {
     hosts: "hosts [list] | hosts remove <name-or-id> [--yes] | hosts rename <name-or-id> <new-name> [--json]",
@@ -507,6 +520,7 @@ export const VERB_USAGE = {
     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]",
+    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)",
@@ -520,6 +534,7 @@ export const VERB_USAGE = {
     legacy: "legacy [--remove [--data] [--yes]] [--json]",
     connections: "connections personal <linear|github> <start|status> [--wait <seconds>] [--json]",
     release: "release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] [--json] | release --class <failure-class> --team <K> --because <what changed> [--retry-unchanged] [--dry-run] [--limit N] [--json]",
+    stage: "stage start|renew|done|fail <ticket> <phase> [--artifact <path>] [--evidence <json>] [--summary <text>] [--assertion <work done>]",
 };
 export function parseArgs(argv) {
     const out = {

package/dist/cli.js

@@ -1,4 +1,5 @@
 import { cmdHosts } from "./hosts.js";
+import { cmdSeat } from "./seat.js";
 // cli.ts — the `catalyst` dispatcher (npm: @catalyst-cloud/cli). Verbs live in
 // their own modules; this file keeps every export the 0.1 tests and the bin import.
 import { createSetupRenderer, setupBanner, } from "./setup-render.js";
@@ -34,6 +35,7 @@ import { cmdWrite } from "./write.js";
 import { cmdAsk } from "./ask.js";
 import { cmdMcp } from "./mcp.js";
 import { cmdRelease } from "./release.js";
+import { cmdStage } from "./stage.js";
 import { cmdEnvironment } from "./environment.js";
 import { cmdEnv } from "./env.js";
 import { cmdSecret } from "./secret.js";
@@ -80,6 +82,7 @@ export function usageText() {
         "  catalyst onboard [--resume-from <step>] [--only <step>] [--runner|--no-runner] [--yes] [--dry-run] [--json]",
         `  catalyst ${SETUP_USAGE}`,
         "  catalyst status | notice | me | ready | accounts",
+        "  catalyst seat checkout --size big|med --harness claude,codex,opencode [--session-id ID] [--stage STAGE]",
         "  catalyst hosts [list] | hosts remove <name-or-id> [--yes] | hosts rename <name-or-id> <new-name>",
         "  catalyst mcp add|list|remove (vault references only)",
         "  catalyst contract [--refresh] [--path <a.b.c>]",
@@ -99,6 +102,7 @@ export function usageText() {
         "  catalyst team <list|check|map|adopt|migrate|checklist> ...",
         "  catalyst capabilities [--json]   (what this CLI can do, the role each verb needs, and whether this cloud serves it)",
         "  catalyst project list [--json]   (all workspace projects, including those with no stage mapping)",
+        "  catalyst stage <start|renew|done|fail> <ticket> <phase>   (a cloud-claimed local phase)",
         "  catalyst project wip-limit <get|set <n>|set default> [--team K]   (a project's new-start WIP limit; members read, owners and admins set)",
         "  catalyst repo <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]>   (a checkout's AGENTS.md block and portable agent layout; working tree only)",
         "  catalyst legacy [--remove [--data] [--yes]]   (leftovers of the old local Catalyst runtime: list them; remove them only on a yes)",
@@ -491,8 +495,12 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdMcp(args, ctx);
             case "accounts":
                 return await cmdAccounts(args, ctx);
+            case "seat":
+                return await cmdSeat(args, ctx);
             case "release":
                 return await cmdRelease(args, ctx);
+            case "stage":
+                return await cmdStage(args, ctx);
             case "environment":
                 return await cmdEnvironment(args, ctx, deps.environment ?? {});
             case "env":

package/dist/onboard-next.js

@@ -150,7 +150,8 @@ const REASONS = {
     runner_org_key_invalid: "The runner account key is invalid, belongs to another workspace, or lacks mirror read, write and feed permissions. Supply a scoped key for this workspace with CATALYST_RUNNER_ORG_KEY_FILE, then run catalyst onboard --runner.",
     runner_org_key_unavailable: "The runner account key could not be checked with Catalyst. Run catalyst onboard --runner to retry.",
     runner_org_key_write_failed: "Setup could not place the organization key on the runner. Check that Docker is running, then run catalyst onboard again.",
-    runner_compose_failed: "Docker Compose could not start the runner. Run docker compose -p catalyst-host logs to see why, then run catalyst onboard again.",
+    runner_compose_failed: "Docker Compose could not start the runner project catalyst-host. Run docker compose -p catalyst-host logs to see why, then run catalyst onboard --runner again.",
+    runner_compose_paused: "The existing catalyst-host Compose project's containers are paused. Run docker compose -p catalyst-host unpause to resume them, then run catalyst onboard --runner again. Setup removed nothing.",
     runner_compose_not_running: "The runner's supervisor is not running. Run docker compose -p catalyst-host logs supervisor to see why, then run catalyst onboard again.",
     runner_enrollment_unverified: "The runner started but has not enrolled yet. Run docker compose -p catalyst-host logs supervisor to see why, or run catalyst onboard again in a minute.",
     runner_needs_runner_flag: "This machine was set up to run Catalyst's work, but its runner is not running or not enrolled. To bring it up, run catalyst onboard --runner.",
@@ -427,13 +428,15 @@ export function onboardReasonText(step, context = {}) {
         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.");
     }
-    if (reason === "runner_images_unavailable") {
+    if (reason === "runner_images_unavailable" || reason === "runner_supervisor_image_unavailable") {
         const image = step.evidence?.image;
         const named = typeof image === "string" &&
             /^[a-z0-9][a-z0-9._:/-]{0,255}@sha256:[0-9a-f]{64}$/.test(image)
             ? ` ${image}`
             : "";
-        return `This machine does not have the Catalyst image${named}, and its pull did not complete. Check network access and run the same setup command to retry the anonymous pull.`;
+        return reason === "runner_supervisor_image_unavailable"
+            ? `Setup could not verify or download the supervisor image required by this CLI release${named}. It has not started new work. Check network access and run the same setup command again.`
+            : `This machine does not have the Catalyst image${named}, and its pull did not complete. Check network access and run the same setup command to retry the anonymous pull.`;
     }
     if (reason === "runner_org_key_missing") {
         const where = context.baseUrl
@@ -448,6 +451,25 @@ export function onboardReasonText(step, context = {}) {
             : "";
         return `The runner is enrolled but its readiness checks fail${checks}. Run docker compose -p catalyst-host logs supervisor for the remedy, then run catalyst onboard again.`;
     }
+    // CTC-5721: a Compose failure, or a paused older project, carries the evidence the adapter recorded.
+    if (reason === "runner_compose_paused") {
+        const services = typeof step.evidence?.services === "string" &&
+            /^[a-z0-9][a-z0-9_-]{0,63}(,[a-z0-9][a-z0-9_-]{0,63})*$/.test(step.evidence.services)
+            ? ` (${step.evidence.services.split(",").join(", ")})`
+            : "";
+        return `Setup found the existing catalyst-host Compose project's containers${services} paused and could not resume them. Run docker compose -p catalyst-host unpause to resume them, then run catalyst onboard --runner again. Setup removed nothing.`;
+    }
+    if (reason === "runner_compose_failed") {
+        const project = typeof step.evidence?.project === "string" &&
+            /^[a-z0-9][a-z0-9-]{0,63}$/.test(step.evidence.project)
+            ? step.evidence.project
+            : "catalyst-host";
+        const error = typeof step.evidence?.composeError === "string" &&
+            /^[\x20-\x7e]{1,500}$/.test(step.evidence.composeError)
+            ? step.evidence.composeError.replace(/\.+$/, "")
+            : undefined;
+        return `Docker Compose could not start the runner project ${project}${error ? `: ${error}` : ""}. Run docker compose -p ${project} logs to see why, then run catalyst onboard --runner again.`;
+    }
     if (reason === "runner_admission_operator")
         return `The admission policy for team ${onboardTeamKey(context.journal) ?? "<TEAM KEY>"} needs a Catalyst operator to check it. Setup changes only restricted admission and preserves existing policy fields. Ask Catalyst support to confirm a compatible policy, then run the same setup command.`;
     // CTC-4744: the cloud has not read the settings yet. Setup already waited a minute; this is

package/dist/onboard-runner-custody.js

@@ -144,6 +144,39 @@ class Custody {
         }
         this.hold(value, false);
     }
+    /** Atomically re-records an already-held private file. The replacement is created inside the
+     * held directory and renamed over the target, then re-held, so every custody invariant
+     * (single-owner 0600, nlink 1, no symlinks) is re-verified on the new bytes. */
+    replace(value, bytes) {
+        const held = this.hold(value, false);
+        this.recheck();
+        const temporary = value + "." + randomBytes(16).toString("hex") + ".tmp";
+        let renamed = false;
+        try {
+            const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT |
+                fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+            try {
+                fs.writeFileSync(fd, bytes);
+                fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            fs.renameSync(temporary, value);
+            renamed = true;
+        }
+        finally {
+            if (!renamed)
+                try {
+                    fs.unlinkSync(temporary);
+                }
+                catch { /* The original error propagates. */ }
+        }
+        fs.closeSync(held.fd);
+        this.held.delete(value);
+        this.hold(value, false);
+        this.recheck();
+    }
     recheck() {
         for (const [value, held] of this.held) {
             const current = this.ports.stat(value, fs.fstatSync(held.fd, { bigint: true }));
@@ -244,7 +277,7 @@ function factory(ports) {
             const nodeHash = executable(executables.nodeExecutable, principal, roots);
             const dockerHash = executable(executables.dockerExecutable, principal, roots);
             let authority;
-            let producerSupervisorImage = input.supervisorImage;
+            let enrolledSupervisorImage;
             if (existing) {
                 custody.walk(state, false, 0o700, true);
                 const runtime = record(parse(custody.read(join(state, "runtime.json"), 4096)), ["version", "nodeExecutable", "nodeExecutableSha256"]);
@@ -274,20 +307,19 @@ function factory(ports) {
                 }
                 if (key.asymmetricKeyType !== "ed25519" || createPublicKey(key).export({ type: "spki", format: "der" }).toString("base64") !== authority.publicKey)
                     fail("private_key_authority_mismatch");
-                // The enrolled producer attests its helper image. A runtime update does not re-enroll it.
-                producerSupervisorImage = row.supervisorImage;
+                // The recorded helper image only authenticates the existing state. When it is not the
+                // current pin, the producer is re-attested on the current pin below, before the proof.
+                enrolledSupervisorImage = row.supervisorImage;
             }
             custody.recheck();
             alive();
             const engine = await ports.engineIdentity({ ...executables, principal,
-                supervisorImage: input.supervisorImage, producerSupervisorImage,
+                supervisorImage: input.supervisorImage,
                 runnerImage: input.runnerImage, deadlineMs: input.deadlineMs, signal });
             alive();
             if (!/^unix:\/\/\/[^,\0]+$/.test(engine.endpoint) || normalize(engine.endpoint.slice(7)) !== engine.endpoint.slice(7) ||
                 !engine.cachedSupervisor || !engine.cachedRunner || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/.test(engine.daemonId))
                 fail("engine_endpoint_or_cache_invalid");
-            if (engine.cachedProducerSupervisor !== true)
-                fail("producer_helper_cache_unavailable");
             if (engine.runnerCustodyVersion !== "v1")
                 fail("runner_custody_label_unqualified");
             if (authority && (authority.endpoint !== engine.endpoint || authority.daemonId !== engine.daemonId))
@@ -311,6 +343,15 @@ function factory(ports) {
                     dockerExecutable: executables.dockerExecutable, dockerExecutableSha256: dockerHash,
                 })));
             }
+            else if (enrolledSupervisorImage !== input.supervisorImage) {
+                // Re-attest the enrolled producer on the current pinned helper, exactly as first
+                // enrollment records it before proving it: same authority, key and executable pins,
+                // same repository, cache-only, and the signed bootstrap below runs on the new pin.
+                custody.replace(configPath, Buffer.from(canonicalDarwinThoughtsJson({
+                    version: 1, authority, privateKeyFile, supervisorImage: input.supervisorImage,
+                    dockerExecutable: executables.dockerExecutable, dockerExecutableSha256: dockerHash,
+                })));
+            }
             const artifacts = ports.artifacts();
             for (const [name, bytes] of [["producer.mjs", artifacts.producer], ["watchdog.mjs", artifacts.watchdog],
                 ["watchdog-deadline.mjs", artifacts.deadline]]) {
@@ -344,7 +385,7 @@ function factory(ports) {
             await ports.service({ ...executables, uid: principal.uid, serviceLabel: LABEL, plistPath, deadlineMs: input.deadlineMs, signal });
             alive();
             const receipt = await ports.receiveBootstrap({ ...executables, authority, configPath,
-                supervisorImage: producerSupervisorImage, deadlineMs: input.deadlineMs, signal });
+                supervisorImage: input.supervisorImage, deadlineMs: input.deadlineMs, signal });
             alive();
             if (ports.now() >= input.deadlineMs)
                 fail("startup_proof_expired");
@@ -470,9 +511,6 @@ async function actualEngine(input) {
     const run = (args) => command(input.dockerExecutable, ["--config", config, "--host", selected, ...args], input.deadlineMs, 16384, input.signal);
     const daemon = await run(["info", "--format", "{{.ID}}"]);
     const supervisor = await run(["image", "inspect", "--format", "{{.Id}}", input.supervisorImage]);
-    const producerSupervisorImage = input.producerSupervisorImage ?? input.supervisorImage;
-    const producerSupervisor = producerSupervisorImage === input.supervisorImage ? supervisor :
-        await run(["image", "inspect", "--format", "{{.Id}}", producerSupervisorImage]);
     const runner = await run(["image", "inspect", "--format", "{{json .}}", input.runnerImage]);
     if (daemon.code !== 0)
         fail("engine_identity_unavailable");
@@ -506,7 +544,6 @@ async function actualEngine(input) {
     }
     return { endpoint: selected, daemonId: daemon.stdout,
         cachedSupervisor: supervisor.code === 0 && /^sha256:[a-f0-9]{64}$/.test(supervisor.stdout),
-        cachedProducerSupervisor: producerSupervisor.code === 0 && /^sha256:[a-f0-9]{64}$/.test(producerSupervisor.stdout),
         cachedRunner: runnerId !== undefined,
         ...(runnerCustodyVersion === undefined ? {} : { runnerCustodyVersion }) };
 }

package/dist/onboard-runner.js

@@ -20,13 +20,13 @@ import { onboardStateRoot, } from "./onboard.js";
 /** The Compose project name the vendored file declares. */
 export const RUNNER_PROJECT = "catalyst-host";
 export const RUNNER_SESSION_NETWORK = "catalyst-session-v1";
-/** Qualified public images from main 72e4e20f86: host run 38073557244 and
- * runner run 38073557245; the unchanged watchdog retains its earlier reviewed pin.
+/** Supervisor from ee729b12 (Host images 38138827750); runner from
+ * 91a82214 (Runner image 38133282600). The watchdog retains its reviewed pin.
  * Explicit environment values override these pins; a saved runner image is preserved. */
 export const RUNNER_HOST_IMAGES = {
-    supervisor: "ghcr.io/coalesce-labs/catalyst-supervisor@sha256:5aa2e7ab67d85c837a81e272ee089c8438ae1ba5b886b05354515be4058d15f6",
+    supervisor: "ghcr.io/coalesce-labs/catalyst-supervisor@sha256:3331ebc4204ae3975a4efb2c870c941f9c0f5ab435735e91dc9977941c91e9a8",
     watchdog: "ghcr.io/coalesce-labs/catalyst-deadline-watchdog@sha256:a5999dbf229ac432b83c2ed3fe43fa251366baceb73af2f57590890a6a758f0d",
-    runner: "ghcr.io/coalesce-labs/catalyst-runner@sha256:dc83c11d357f1f5fa1ec55c669d02e9ff6f5ec9633a9bdc6fc15fbe7497f9655",
+    runner: "ghcr.io/coalesce-labs/catalyst-runner@sha256:9db2bf2c5580e2a1459fd076fa32c9af34456cc639ec3ab92b57b6ad98da67fb",
 };
 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}$/;
@@ -91,6 +91,18 @@ const spawnDocker = (args, options) => new Promise((resolve, reject) => {
     child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
     child.stdin.end(options.input ?? "");
 });
+/** Compose's own error lines, reduced to short printable text a person can act on. */
+function composeErrorText(raw) {
+    if (!raw)
+        return undefined;
+    const lines = raw
+        .split(/\r?\n/)
+        .map((line) => line.replace(/[^\x20-\x7e]/g, "").trim())
+        .filter((line) => line !== "" && !line.startsWith("time="));
+    const errors = lines.filter((line) => /error|failed|cannot|conflict|paused|in use|refused|denied|invalid/i.test(line));
+    const text = (errors.length > 0 ? errors : lines).slice(0, 3).join(" | ").slice(0, 480);
+    return text !== "" ? text : undefined;
+}
 /** The real engine, through the docker CLI. Compose reads `.env` only: the caller's CATALYST_ and
  * DOCKER_SOCKET_ variables are removed, because Compose prefers an exported value over the file. */
 export function dockerRunnerEngine(deps = {}) {
@@ -267,15 +279,53 @@ export function dockerRunnerEngine(deps = {}) {
                             return "unverified";
                     }
                 }
-                return { dir, hostName, baseUrl: normalizeBaseUrl(baseUrl) };
+                return { dir, hostName, baseUrl: normalizeBaseUrl(baseUrl), supervisorImage: config.Image };
             }
             catch {
                 return "unverified";
             }
         },
+        async projectContainers(signal) {
+            const read = await docker(["ps", "--all",
+                "--filter", `label=com.docker.compose.project=${RUNNER_PROJECT}`,
+                "--format", '{{.Label "com.docker.compose.service"}}\t{{.State}}'], { signal });
+            if (read.code !== 0)
+                return null;
+            const rows = [];
+            for (const line of read.stdout.split("\n")) {
+                const [service, state] = line.trim().split("\t");
+                if (service && state &&
+                    /^[a-z][a-z0-9_-]{0,63}$/.test(service) && /^[a-z]+$/.test(state))
+                    rows.push({ service, state });
+            }
+            return rows;
+        },
+        async composeUnpause(dir, signal) {
+            const files = compose(dir);
+            if (!files)
+                return false;
+            return (await docker([...files, "unpause"], { cwd: dir, signal, timeoutMs: 120_000 })).code === 0;
+        },
         async imageArch(ref, signal) {
-            const read = await docker(["image", "inspect", "--format", "{{.Architecture}}", ref], { signal });
-            return read.code === 0 ? read.stdout.trim() || null : null;
+            if (!IMAGE_REF.test(ref))
+                return null;
+            const read = await docker(["image", "inspect", ref], { signal });
+            if (read.code !== 0)
+                return null;
+            try {
+                const rows = JSON.parse(read.stdout);
+                if (!Array.isArray(rows) || rows.length !== 1)
+                    return null;
+                const row = object(rows[0]);
+                if (typeof row?.Id !== "string" || !/^sha256:[0-9a-f]{64}$/.test(row.Id) ||
+                    row.Os !== "linux" || typeof row.Architecture !== "string" || !row.Architecture ||
+                    !Array.isArray(row.RepoDigests) || !row.RepoDigests.includes(ref))
+                    return null;
+                return row.Architecture;
+            }
+            catch {
+                return null;
+            }
         },
         async pull(ref, signal) {
             const host = await endpoint(signal);
@@ -478,9 +528,11 @@ export function dockerRunnerEngine(deps = {}) {
         async composeUp(dir, signal) {
             const files = compose(dir);
             if (!files)
-                return false;
-            return ((await docker([...files, "up", "--detach"], { cwd: dir, signal, timeoutMs: 600_000 }))
-                .code === 0);
+                return { ok: false };
+            const read = await docker([...files, "up", "--detach"], { cwd: dir, signal, timeoutMs: 600_000 });
+            return read.code === 0
+                ? { ok: true }
+                : { ok: false, error: composeErrorText(read.stderr || read.stdout) };
         },
         async composeRunning(dir, signal) {
             const files = compose(dir);
@@ -711,7 +763,8 @@ export function onboardRunnerAdapter(input = {}) {
         if (!info.vm && !(await engine.nativeEgressStatus?.(ctx.now().getTime(), signal)))
             return waiting("runner_native_egress_setup_required", selected);
         return { account, baseUrl: normalizeBaseUrl(cfg.baseUrl), teamKey, teamId, cloud, dir, info, images,
-            ...(installation && installation !== "missing" ? { installedName: installation.hostName } : {}) };
+            ...(installation && installation !== "missing" ? { installedName: installation.hostName,
+                installedSupervisorImage: installation.supervisorImage } : {}) };
     }
     async function desiredEnv(p, ctx, joinToken) {
         const saved = readEnvFile(join(p.dir, ".env")) ?? {};
@@ -852,8 +905,9 @@ export function onboardRunnerAdapter(input = {}) {
             catch {
                 /* A missing or unreadable compose needs an explicitly authorized repair. */
             }
-            const changed = !saved || !composeMatches || Object.entries(want).some(([key, value]) => saved[key] !== value);
-            const hostEvidence = { ...selected, hostName: name };
+            const changed = !saved || !composeMatches || Object.entries(want).some(([key, value]) => saved[key] !== value) ||
+                (p.installedSupervisorImage !== undefined && p.installedSupervisorImage !== p.images.supervisor);
+            const hostEvidence = { ...selected, hostName: name, supervisorImage: p.images.supervisor };
             const pending = () => mayAct ? { state: "pending" } : waiting("runner_needs_runner_flag", hostEvidence);
             if (!running || changed)
                 return afterAct ? waiting("runner_compose_not_running", hostEvidence) : pending();
@@ -923,6 +977,7 @@ export function onboardRunnerAdapter(input = {}) {
                 return p;
             if (!mayAct)
                 return waiting("runner_needs_runner_flag", selected);
+            let replacingContainers = false;
             try {
                 mkdirSync(p.dir, { recursive: true, mode: 0o700 });
                 if (lstatSync(p.dir).isSymbolicLink())
@@ -949,8 +1004,10 @@ export function onboardRunnerAdapter(input = {}) {
                 catch {
                     /* first run */
                 }
-                if (!current?.equals(compose))
+                if (!current?.equals(compose)) {
+                    replacingContainers = current !== null;
                     writeFileSync(join(p.dir, "compose.yaml"), compose, { mode: 0o644 });
+                }
             }
             catch {
                 return { state: "failed", reason: "runner_directory_unavailable", evidence: selected };
@@ -983,7 +1040,9 @@ export function onboardRunnerAdapter(input = {}) {
             };
             const imagesRefused = await prepareRunnerImages(engine, Object.values(p.images), p.info.arch, signal);
             if (imagesRefused)
-                return waiting(imagesRefused.reason, { ...selected, ...(imagesRefused.image ? { image: imagesRefused.image } : {}) });
+                return waiting(imagesRefused.reason === "runner_images_unavailable" && imagesRefused.image === p.images.supervisor
+                    ? "runner_supervisor_image_unavailable" : imagesRefused.reason, { ...selected, supervisorImage: p.images.supervisor,
+                    ...(imagesRefused.image ? { image: imagesRefused.image } : {}) });
             if (p.info.vm) {
                 const capability = await engine.vmCapabilities(p.dir, p.images.supervisor, p.baseUrl, signal);
                 if (capability !== "ready")
@@ -1093,8 +1152,29 @@ export function onboardRunnerAdapter(input = {}) {
                         return waiting("runner_admission_unverified", selected);
                 }
             }
-            if (!(await engine.composeUp(p.dir, signal)))
-                return { state: "failed", reason: "runner_compose_failed", evidence: selected };
+            // CTC-5721: an older catalyst-host project must never meet Compose as a surprise exit.
+            // Its paused containers cannot be started by Compose: adopt them, or name the exact command.
+            const containers = (await engine.projectContainers?.(signal)) ?? null;
+            const paused = containers?.filter((row) => row.state === "paused") ?? [];
+            const pausedNames = [...new Set(paused.map((row) => row.service))];
+            if (paused.length > 0) {
+                const resumed = (await engine.composeUnpause?.(p.dir, signal)) === true;
+                if (!resumed)
+                    return waiting("runner_compose_paused", { ...selected, hostName: name,
+                        project: RUNNER_PROJECT, services: pausedNames.join(",") });
+                input.message?.(`Resumed the paused containers (${pausedNames.join(", ")}) of the existing ${RUNNER_PROJECT} project; setup adopts it.`);
+            }
+            else if (containers && containers.length > 0 && replacingContainers) {
+                input.message?.(`Replacing the existing ${RUNNER_PROJECT} project's containers (${[...new Set(containers.map((row) => row.service))].join(", ")}) with this release's Compose definitions.`);
+            }
+            else if (containers && containers.some((row) => row.state !== "running")) {
+                const stopped = [...new Set(containers.filter((row) => row.state !== "running").map((row) => row.service))];
+                input.message?.(`Starting the existing ${RUNNER_PROJECT} project's stopped containers (${stopped.join(", ")}); setup adopts it.`);
+            }
+            const up = await engine.composeUp(p.dir, signal);
+            if (!up.ok)
+                return { state: "failed", reason: "runner_compose_failed", evidence: { ...selected,
+                        project: RUNNER_PROJECT, ...(up.error ? { composeError: up.error } : {}) } };
             acted = true;
             return { state: "done" };
         },

package/dist/onboard.js

@@ -300,6 +300,7 @@ function normalizeStep(value, fallbackAt) {
         "teamKey",
         "selected",
         "hostName",
+        "supervisorImage",
         "hostId",
         "capacity",
         "failing",

package/dist/seat.js

@@ -0,0 +1,45 @@
+import { randomUUID } from "node:crypto";
+import { flagString, positionals } from "./args.js";
+import { DEFAULT_BASE_URL, requireConfig } from "./config.js";
+import { UsageError } from "./errors.js";
+import { ApiClient, apiClient } from "./transport.js";
+const HARNESSES = new Set(["claude", "codex", "opencode"]);
+/** The full response goes to stdout for a launcher to capture in an owner-only file. */
+export async function cmdSeat(args, ctx) {
+    const [action, ...extra] = positionals(args);
+    if (action !== "checkout" || extra.length > 0)
+        throw new UsageError("seat checkout --size big|med --harness claude,codex,opencode [--session-id ID] [--stage STAGE]");
+    const size = flagString(args, "size");
+    const stage = flagString(args, "stage");
+    if (size !== undefined && size !== "big" && size !== "med")
+        throw new UsageError("--size must be big or med");
+    if (size === undefined && stage === undefined)
+        throw new UsageError("--size or --stage is required");
+    const harnesses = flagString(args, "harness")?.split(",");
+    if (!harnesses || harnesses.length === 0 || harnesses.some((h) => !HARNESSES.has(h)))
+        throw new UsageError("--harness must list claude, codex or opencode, separated by commas");
+    const sessionId = flagString(args, "session-id") ?? randomUUID();
+    if (!/^[A-Za-z0-9._-]{1,128}$/.test(sessionId))
+        throw new UsageError("--session-id must be one token of at most 128 letters, digits, dots, underscores or hyphens");
+    const keyEnv = flagString(args, "key-env");
+    if (keyEnv !== undefined && !/^[A-Z][A-Z0-9_]*$/.test(keyEnv))
+        throw new UsageError("--key-env must name an uppercase environment variable");
+    const key = keyEnv === undefined ? undefined : ctx.env[keyEnv];
+    if (keyEnv !== undefined && !key)
+        throw new UsageError(`--key-env ${keyEnv} is empty`);
+    const api = key === undefined
+        ? apiClient(requireConfig(ctx), ctx)
+        : new ApiClient(ctx.env.CATALYST_CLOUD_BASE_URL ?? DEFAULT_BASE_URL, async () => key, ctx.fetch);
+    const response = await api.postJson("/api/v1/agent/credential-checkout", {
+        sessionId,
+        ...(size === undefined ? {} : { size }),
+        ...(stage === undefined ? {} : { stage }),
+        harnesses,
+    }, { accept: [409] });
+    if (response.status !== 200 || response.body.outcome !== "issued") {
+        ctx.stderr(`seat checkout refused: ${response.body.reason ?? "unexpected response"}`);
+        return 2;
+    }
+    ctx.stdout(JSON.stringify({ ...response.body, sessionId }));
+    return 0;
+}