@catalyst-cloud/cli 0.15.6 → 0.16.1

package/dist/onboard-runner.js

@@ -1,14 +1,13 @@
 import { spawn } from "node:child_process";
-import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { randomBytes } from "node:crypto";
+import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { hostname, tmpdir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 import { loadConfig, normalizeBaseUrl, packageRoot } from "./config.js";
 import { nativeEgressReady, NATIVE_EGRESS_DIR } from "./onboard-runner-egress.js";
 import { runnerAdmission, issueRunnerOrgKey, verifyRunnerRoutes } from "./onboard-runner-cloud.js";
 import { verifyOnboardRoutes } from "./onboard-capabilities.js";
 import { liveTeamKey, onboardTeamAdmission } from "./onboard-capacity.js";
-import { readExistingOnboardJson, selectedOnboardTeam, } from "./onboard-existing.js";
+import { readExistingOnboardJson, readOnboardTeamInventory, selectedOnboardTeam, } from "./onboard-existing.js";
 import { onboardStateRoot, } from "./onboard.js";
 // "Run Catalyst's work on this machine": the self-hosted host from catalyst-cloud's deploy/self-host
 // (a supervisor and a deadline watchdog under Compose), enrolled with the person's own owner or
@@ -133,6 +132,54 @@ export function dockerRunnerEngine(deps = {}) {
             const supportedVm = platform === "darwin" && vm && host?.startsWith("unix:///");
             return { arch, vm, ...(!nativeLocal && !supportedVm ? { unsupported: true } : {}) };
         },
+        async installation(home, supervisorImage, signal) {
+            const listed = await docker(["ps", "--all", "--filter", `label=com.docker.compose.project=${RUNNER_PROJECT}`,
+                "--filter", "label=com.docker.compose.service=supervisor", "--format", "{{.ID}}"], { signal });
+            if (listed.code !== 0)
+                return "unverified";
+            const ids = listed.stdout.trim().split(/\s+/).filter(Boolean);
+            if (ids.length === 0)
+                return "missing";
+            if (ids.length !== 1 || !/^[0-9a-f]{12,64}$/.test(ids[0]))
+                return "unverified";
+            const read = await docker(["inspect", ids[0]], { signal });
+            if (read.code !== 0)
+                return "unverified";
+            try {
+                const rows = JSON.parse(read.stdout);
+                if (!Array.isArray(rows) || rows.length !== 1)
+                    return "unverified";
+                const config = rows[0]?.Config;
+                const labels = config?.Labels;
+                const dir = labels?.["com.docker.compose.project.working_dir"];
+                if (config?.Image !== supervisorImage || labels?.["com.docker.compose.project"] !== RUNNER_PROJECT ||
+                    labels?.["com.docker.compose.service"] !== "supervisor" || typeof dir !== "string" || !isAbsolute(dir) ||
+                    labels?.["com.docker.compose.project.config_files"] !== join(dir, "compose.yaml"))
+                    return "unverified";
+                const inHome = relative(realpathSync(home), realpathSync(dir));
+                if (inHome === ".." || inHome.startsWith("../") || isAbsolute(inHome) || !lstatSync(dir).isDirectory())
+                    return "unverified";
+                for (const path of [join(dir, "compose.yaml"), join(dir, ".env")]) {
+                    const stat = lstatSync(path);
+                    if (!stat.isFile() || stat.uid !== process.getuid?.() || (stat.mode & 0o022) !== 0)
+                        return "unverified";
+                }
+                if (!Array.isArray(config.Env) || !config.Env.every((entry) => typeof entry === "string"))
+                    return "unverified";
+                const names = config.Env.filter((entry) => entry.startsWith("CATALYST_HOST_NAME="));
+                const origins = config.Env.filter((entry) => entry.startsWith("CATALYST_MIRROR_URL="));
+                if (names.length !== 1 || origins.length !== 1)
+                    return "unverified";
+                const hostName = names[0].slice("CATALYST_HOST_NAME=".length);
+                const baseUrl = origins[0].slice("CATALYST_MIRROR_URL=".length);
+                if (!HOST_NAME.test(hostName))
+                    return "unverified";
+                return { dir, hostName, baseUrl: normalizeBaseUrl(baseUrl) };
+            }
+            catch {
+                return "unverified";
+            }
+        },
         async imageArch(ref, signal) {
             const read = await docker(["image", "inspect", "--format", "{{.Architecture}}", ref], { signal });
             return read.code === 0 ? read.stdout.trim() || null : null;
@@ -148,7 +195,7 @@ export function dockerRunnerEngine(deps = {}) {
                 const anonymousEnv = { ...env, DOCKER_CONFIG: config };
                 delete anonymousEnv.DOCKER_CONTEXT;
                 delete anonymousEnv.DOCKER_AUTH_CONFIG;
-                return (await docker(["--host", host, "--config", config, "pull", "--quiet", ref], { env: anonymousEnv, signal, timeoutMs: 900_000 })).code === 0;
+                return ((await docker(["--host", host, "--config", config, "pull", "--quiet", ref], { env: anonymousEnv, signal, timeoutMs: 900_000 })).code === 0);
             }
             catch {
                 return false;
@@ -197,7 +244,9 @@ export function dockerRunnerEngine(deps = {}) {
             ];
             return (await docker(args, { signal })).code === 0;
         },
-        async nativeEgressStatus(nowMs, signal) { return nativeLocal && await nativeEgressReady(nowMs, signal); },
+        async nativeEgressStatus(nowMs, signal) {
+            return nativeLocal && (await nativeEgressReady(nowMs, signal));
+        },
         async socketGid() {
             if (!nativeLocal)
                 return null;
@@ -226,7 +275,8 @@ export function dockerRunnerEngine(deps = {}) {
                 RUNNER_UID,
                 ...paths,
             ];
-            return (await docker(args, { cwd: dir, signal, timeoutMs: 120_000 })).code === 0;
+            return ((await docker(args, { cwd: dir, signal, timeoutMs: 120_000 })).code ===
+                0);
         },
         async hasVolumeFile(dir, variable, signal) {
             return ((await docker(supervisorShell(dir, `test -s "$${variable}"`), {
@@ -316,7 +366,8 @@ export function dockerRunnerEngine(deps = {}) {
         },
         async composeRunning(dir, signal) {
             const read = await docker([...compose(dir), "ps", "--status", "running", "--services"], { cwd: dir, signal });
-            return read.code === 0 && read.stdout.split("\n").some((line) => line.trim() === "supervisor");
+            return (read.code === 0 &&
+                read.stdout.split("\n").some((line) => line.trim() === "supervisor"));
         },
     };
 }
@@ -350,7 +401,9 @@ function parseHosts(body) {
             hostName: host.hostName,
             team: host.team,
             revoked: host.revokedAtMs !== null,
-            capacity: capability ? (capability.runtimeLive ? capability.placeableCapacity : 0) : null,
+            capacity: capability ? capability.runtimeLive
+                ? capability.placeableCapacity
+                : 0 : null,
             failing: capability ? capability.failingRequired : [],
         });
     }
@@ -393,16 +446,15 @@ function writePrivate(path, text) {
 /** Enrollment uses the stored host id and exact team/name. Two machines with one hostname must not
  * share it: a random suffix, kept in `.env` from the first write on. */
 export function runnerDefaultHostName() {
-    const suffix = randomBytes(3).toString("hex");
-    const base = `catalyst-${hostname().split(".")[0] ?? "host"}`
+    const base = (hostname().split(".")[0] ?? "machine")
         .replace(/[^A-Za-z0-9._-]/g, "-")
-        .slice(0, 55);
-    const name = `${base}-${suffix}`;
-    return HOST_NAME.test(name) ? name : `catalyst-host-${suffix}`;
+        .slice(0, 63);
+    return HOST_NAME.test(base) ? base : "machine";
 }
 export function onboardRunnerAdapter(input = {}) {
     const engine = input.engine ?? dockerRunnerEngine();
-    const sleep = input.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const sleep = input.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const waitMs = input.waitMs ?? 120_000;
     const pollMs = input.pollMs ?? 5_000;
     // One question per run: the engine checks again after acting, and the receipt row is "running"
@@ -412,6 +464,7 @@ export function onboardRunnerAdapter(input = {}) {
     // only reports on it, so an unattended check never restarts a runner the person stopped.
     let mayAct = false;
     let acted = false;
+    let chosenName;
     const selected = { selected: true };
     async function decide(journal) {
         if (decided !== undefined)
@@ -460,14 +513,6 @@ export function onboardRunnerAdapter(input = {}) {
         ], signal);
         if ("reason" in support)
             return waiting(support.reason, selected);
-        const teamId = selectedOnboardTeam(journal);
-        const teamKey = teamId ? await liveTeamKey(ctx, teamId, signal ?? new AbortController().signal) : null;
-        if (!teamId || !teamKey)
-            return waiting("runner_context_unverified", selected);
-        const runnerSupport = await verifyRunnerRoutes(ctx, journal, [{ method: "GET", path: "/api/v1/agent/runner-admission" }], signal);
-        if ("reason" in runnerSupport && runnerSupport.reason !== "cloud_capability_unavailable")
-            return waiting(runnerSupport.reason, selected);
-        const cloud = !("reason" in runnerSupport);
         let state;
         try {
             state = onboardStateRoot(ctx.home, ctx.env);
@@ -475,7 +520,41 @@ export function onboardRunnerAdapter(input = {}) {
         catch {
             return waiting("runner_directory_unavailable", selected);
         }
-        const dir = join(state, "runner");
+        let dir = join(state, "runner");
+        const installation = await engine.installation?.(ctx.home, ctx.env.CATALYST_SUPERVISOR_IMAGE ?? RUNNER_HOST_IMAGES.supervisor, signal);
+        if (installation === "unverified")
+            return waiting("runner_installation_unverified", selected);
+        let credential = null;
+        if (installation && installation !== "missing") {
+            if (installation.baseUrl !== normalizeBaseUrl(cfg.baseUrl))
+                return waiting("runner_identity_unverified", selected);
+            dir = installation.dir;
+            credential = await engine.enrollment(dir, signal);
+            if (!credential)
+                return waiting("runner_credential_unverified", selected);
+            if (!isUnenrolled(credential) && (credential.tenant !== account || credential.enrollmentKind !== "self_hosted"))
+                return waiting("runner_identity_unverified", selected);
+        }
+        let teamId = selectedOnboardTeam(journal);
+        if (!teamId && credential && !isUnenrolled(credential)) {
+            // Moving on retains the verified installation's project scope. Never choose the first team.
+            const teams = await readOnboardTeamInventory(ctx, signal);
+            if (!("reason" in teams)) {
+                const installedTeam = credential.team;
+                const matching = teams.teams.filter(team => team.key === installedTeam);
+                if (matching.length === 1)
+                    teamId = matching[0].id;
+            }
+        }
+        const teamKey = teamId ? await liveTeamKey(ctx, teamId, signal ?? new AbortController().signal) : null;
+        if (!teamId || !teamKey)
+            return waiting("runner_context_unverified", selected);
+        if (credential && !isUnenrolled(credential) && credential.team !== teamKey)
+            return waiting("runner_enrolled_for_other_team", selected);
+        const runnerSupport = await verifyRunnerRoutes(ctx, journal, [{ method: "GET", path: "/api/v1/agent/runner-admission" }], signal);
+        if ("reason" in runnerSupport && runnerSupport.reason !== "cloud_capability_unavailable")
+            return waiting(runnerSupport.reason, selected);
+        const cloud = !("reason" in runnerSupport);
         const saved = readEnvFile(join(dir, ".env"));
         const images = {
             supervisor: ctx.env.CATALYST_SUPERVISOR_IMAGE ?? RUNNER_HOST_IMAGES.supervisor,
@@ -486,11 +565,12 @@ export function onboardRunnerAdapter(input = {}) {
             return waiting("runner_image_unpinned", selected);
         if (!info.vm && !(await engine.nativeEgressStatus?.(ctx.now().getTime(), signal)))
             return waiting("runner_native_egress_setup_required", selected);
-        return { account, baseUrl: normalizeBaseUrl(cfg.baseUrl), teamKey, teamId, cloud, dir, info, images };
+        return { account, baseUrl: normalizeBaseUrl(cfg.baseUrl), teamKey, teamId, cloud, dir, info, images,
+            ...(installation && installation !== "missing" ? { installedName: installation.hostName } : {}) };
     }
     async function desiredEnv(p, joinToken) {
         const saved = readEnvFile(join(p.dir, ".env")) ?? {};
-        const name = saved.CATALYST_HOST_NAME || (input.hostName ?? runnerDefaultHostName)();
+        const name = p.installedName || saved.CATALYST_HOST_NAME || chosenName || (input.hostName ?? runnerDefaultHostName)();
         const gid = p.info.vm ? 0 : await engine.socketGid();
         if (!HOST_NAME.test(name) || gid === null)
             return null;
@@ -582,11 +662,22 @@ export function onboardRunnerAdapter(input = {}) {
                 return waiting("runner_docker_socket_unreadable", selected);
             const name = want.CATALYST_HOST_NAME;
             let enrolled = null;
-            const live = (hosts) => hosts?.find((host) => host.hostId === enrolled?.hostId && host.hostName === name && host.team === p.teamKey && !host.revoked);
+            const live = (hosts) => hosts?.find((host) => host.hostId === enrolled?.hostId && host.team === p.teamKey && !host.revoked);
             let hosts = await listHosts(ctx, p, signal);
             if (!hosts)
                 return waiting("runner_enrollment_unavailable", selected);
-            if (hosts.some((host) => host.hostName === name && !host.revoked && host.team !== p.teamKey))
+            const existingCredential = await engine.enrollment(p.dir, signal);
+            if ((!existingCredential || isUnenrolled(existingCredential)) &&
+                hosts.some((host) => host.hostName === name && !host.revoked && host.team !== p.teamKey))
+                return waiting("runner_enrolled_for_other_team", {
+                    ...selected,
+                    hostName: name,
+                });
+            if (existingCredential &&
+                !isUnenrolled(existingCredential) &&
+                hosts.some((host) => host.hostId === existingCredential.hostId &&
+                    !host.revoked &&
+                    host.team !== p.teamKey))
                 return waiting("runner_enrolled_for_other_team", { ...selected, hostName: name });
             const running = await engine.composeRunning(p.dir, signal);
             const changed = !saved || Object.entries(want).some(([key, value]) => saved[key] !== value);
@@ -607,8 +698,13 @@ export function onboardRunnerAdapter(input = {}) {
                     return waiting("runner_identity_unverified", hostEvidence);
                 if (enrolled && enrolled.team !== p.teamKey)
                     return waiting("runner_enrolled_for_other_team", hostEvidence);
-                if (enrolled && !hosts.some((host) => host.hostId === enrolled.hostId && host.hostName === name && !host.revoked))
-                    return waiting("runner_enrollment_stale", hostEvidence);
+                if (enrolled) {
+                    const exact = hosts.find((host) => host.hostId === enrolled.hostId);
+                    if (exact?.revoked)
+                        return waiting("runner_enrollment_revoked", { ...hostEvidence, hostId: enrolled.hostId });
+                    if (!exact || exact.team !== p.teamKey)
+                        return waiting("runner_enrollment_unverified", hostEvidence);
+                }
                 const host = live(hosts);
                 if (host && host.capacity !== null)
                     break;
@@ -619,7 +715,7 @@ export function onboardRunnerAdapter(input = {}) {
                 await sleep(pollMs);
             }
             const host = live(hosts);
-            const evidence = { ...hostEvidence, hostId: host.hostId, capacity: host.capacity };
+            const evidence = { ...hostEvidence, hostName: host.hostName, hostId: host.hostId, capacity: host.capacity };
             const orgKey = orgKeyFromFile(ctx);
             if (orgKey === null)
                 return waiting("runner_org_key_file_invalid", evidence);
@@ -682,6 +778,17 @@ export function onboardRunnerAdapter(input = {}) {
             catch {
                 return { state: "failed", reason: "runner_directory_unavailable", evidence: selected };
             }
+            if (!p.installedName &&
+                !readEnvFile(join(p.dir, ".env"))?.CATALYST_HOST_NAME &&
+                chosenName === undefined) {
+                const suggested = (input.hostName ?? runnerDefaultHostName)();
+                const name = input.chooseName
+                    ? await input.chooseName(suggested)
+                    : suggested;
+                if (name === null || !HOST_NAME.test(name))
+                    return waiting("runner_name_required", selected);
+                chosenName = name;
+            }
             let want = await desiredEnv(p);
             if (!want)
                 return waiting("runner_docker_socket_unreadable", selected);
@@ -725,14 +832,22 @@ export function onboardRunnerAdapter(input = {}) {
             const hosts = await listHosts(ctx, p, signal);
             if (!hosts)
                 return waiting("runner_enrollment_unavailable", selected);
-            if (hosts.some((host) => host.hostName === name && !host.revoked && host.team !== p.teamKey))
+            if (!enrolled &&
+                hosts.some((host) => host.hostName === name && !host.revoked && host.team !== p.teamKey))
                 return waiting("runner_enrolled_for_other_team", { ...selected, hostName: name });
             if (enrolled && (enrolled.tenant !== p.account || enrolled.enrollmentKind !== "self_hosted"))
                 return waiting("runner_identity_unverified", { ...selected, hostName: name });
             if (enrolled && enrolled.team !== p.teamKey)
                 return waiting("runner_enrolled_for_other_team", { ...selected, hostName: name });
-            if (hasCredential && !isUnenrolled(credential) && (!enrolled || !hosts.some((host) => host.hostId === enrolled.hostId && host.hostName === name && host.team === p.teamKey && !host.revoked)))
-                return waiting("runner_enrollment_stale", { ...selected, hostName: name });
+            if (hasCredential && !isUnenrolled(credential)) {
+                if (!enrolled)
+                    return waiting("runner_credential_unverified", { ...selected, hostName: name });
+                const exact = hosts.find((host) => host.hostId === enrolled.hostId);
+                if (exact?.revoked)
+                    return waiting("runner_enrollment_revoked", { ...selected, hostName: name, hostId: enrolled.hostId });
+                if (!exact || exact.team !== p.teamKey)
+                    return waiting("runner_enrollment_unverified", { ...selected, hostName: name });
+            }
             // A lost volume also lost the secret that redeemed the old token. Mint a new token and match
             // the new host id from the supervisor's credential, never an old advertisement with this name.
             // A lost reply must retry the same token and retained secret: a new token would be

package/dist/onboard-runtime.js

@@ -8,6 +8,9 @@ import { cmdLegacy, findLegacy } from "./legacy.js";
 import { personalConsentAdapter } from "./onboard-personal.js";
 import { boundedOnboardSignin } from "./onboard-signin.js";
 import { existingLinearAdapters } from "./onboard-existing.js";
+import { returningWorkspaceAdapters } from "./onboard-returning.js";
+import { archiveReturningProject } from "./onboard-project-cleanup.js";
+import { CREATE_TEAM_CHOICE } from "./onboard-team-create.js";
 import { linearWorkspaceAdapter } from "./onboard-workspace.js";
 import { firstProjectAdapters } from "./onboard-projects.js";
 import { onboardCapacityAdapter } from "./onboard-capacity.js";
@@ -175,8 +178,15 @@ export function createOnboardRuntime(args, ctx, hooks) {
             ? (message, run) => waitFor(message, run)
             : undefined,
     });
+    let newProjectRequested = false;
     const linear = existingLinearAdapters(args, hooks.ui?.chooseTeam
-        ? (teams, create) => hooks.ui.chooseTeam(teams.map((team) => ({ ...team })), create)
+        ? async (teams, create) => {
+            if (newProjectRequested) {
+                newProjectRequested = false;
+                return CREATE_TEAM_CHOICE;
+            }
+            return hooks.ui.chooseTeam(teams.map(team => ({ ...team })), create);
+        }
         : undefined, hooks.ui?.nameNewTeam
         ? (question) => hooks.ui.nameNewTeam(question)
         : undefined, (text) => (hooks.ui ? hooks.ui.message(text) : ctx.stderr(text)));
@@ -314,6 +324,14 @@ export function createOnboardRuntime(args, ctx, hooks) {
                 ? () => hooks.ui.chooseRunner()
                 : undefined,
             engine: hooks.runnerEngine,
+            hostName: typeof args.flags["machine-name"] === "string"
+                ? () => String(args.flags["machine-name"])
+                : undefined,
+            chooseName: interactiveWait &&
+                hooks.ui?.nameMachine &&
+                args.flags["machine-name"] === undefined
+                ? (name) => hooks.ui.nameMachine(name)
+                : undefined,
             sleep: hooks.sleep,
             message: (text) => (hooks.ui ? hooks.ui.message(text) : ctx.stderr(text)),
         }),
@@ -473,7 +491,14 @@ export function createOnboardRuntime(args, ctx, hooks) {
     }
     // Public auth discovery and the existing /me sign-in bootstrap establish identity before the
     // tenant-bound step guards can run. Unsupported/local-only steps make no endpoint requests.
+    let reviewActive = false;
+    returningWorkspaceAdapters(adapters, args, hooks.ui?.reviewProjects?.bind(hooks.ui), text => hooks.ui ? hooks.ui.message(text) : ctx.stderr(text), () => { newProjectRequested = true; }, () => reviewActive, (project, stepCtx, journal, signal) => archiveReturningProject(project, stepCtx, journal, hooks.ui?.confirmProjectCleanup?.bind(hooks.ui), signal));
     return {
+        beforeStep: async (id) => {
+            await hooks.beforeStep?.(id);
+            if (id === "linear.workspace")
+                reviewActive = true;
+        },
         identity: (journal) => identity(ctx, journal),
         ...(hooks.stageSignin ? { stageSignin: hooks.stageSignin } : {}),
         bindSignals: true,

package/dist/onboard-ui.js

@@ -1,3 +1,4 @@
+import { GITHUB_CONFIRM_ACCESS } from "./onboard-github-copy.js";
 import { COMPUTER_CHECKS, standalonePlan, standalonePlanNotes, pendingContinuation, } from "./onboard-standalone-copy.js";
 import { trackedPrompt } from "./setup-prompt-frame.js";
 import { createOnboardInterrupts } from "./onboard-interrupts.js";
@@ -157,11 +158,13 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             return;
         if (renderer &&
             currentStep === "linear.adopt" &&
-            text.endsWith("already has every state and label"))
+            text.endsWith("has every required state and label"))
             return;
         if (renderer) {
             if (currentStep &&
                 setupBrowserInstruction(currentStep, deps.baseUrl?.())) {
+                if (currentStep === "github.install" && text === GITHUB_CONFIRM_ACCESS)
+                    renderer.detail(text);
                 if (/no browser opened|could not open a browser/i.test(text))
                     browserOpened = false;
                 return;
@@ -441,6 +444,49 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
                 ...(answer === "signin" ? { signin: true } : {}),
             };
         },
+        async reviewProjects(projects) {
+            stop();
+            if (abort.signal.aborted)
+                return null;
+            const answer = await select({
+                ...options,
+                message: "What should setup do with this workspace's projects?",
+                initialValue: "move-on",
+                options: [
+                    { value: "move-on", label: "Move on and finish this computer's setup", hint: "default" },
+                    ...projects.map(p => ({ value: `repair:${p.id}`, label: `Review or repair ${p.name} (${p.key})` })),
+                    ...projects.map(p => ({ value: `cleanup:${p.id}`, label: `Preview archiving ${p.name} (${p.key})` })),
+                    { value: "new", label: "Create a new Catalyst project" },
+                ],
+            });
+            if (prompts.isCancel(answer)) {
+                abort.abort();
+                return null;
+            }
+            if (answer === "move-on" || answer === "new")
+                return answer;
+            if (typeof answer === "string" && answer.startsWith("cleanup:"))
+                return { cleanup: answer.slice(8) };
+            return typeof answer === "string" && answer.startsWith("repair:") ? { repair: answer.slice(7) } : null;
+        },
+        async confirmProjectCleanup(project, lines) {
+            stop();
+            for (const line of lines)
+                message(line);
+            if (abort.signal.aborted)
+                return false;
+            const answer = await select({ ...options,
+                message: `Archive ${project.name} after reviewing these changes?`,
+                initialValue: "keep",
+                options: [{ value: "keep", label: "Keep the project and finish this computer's setup" },
+                    { value: "archive", label: "Archive this project" }],
+            });
+            if (prompts.isCancel(answer)) {
+                abort.abort();
+                return false;
+            }
+            return answer === "archive";
+        },
         async chooseTeam(teams, create) {
             stop();
             // Creating needs a name prompt; a port without one offers only the existing teams.
@@ -668,6 +714,23 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             }
             return typeof answer === "string" ? answer : null;
         },
+        async nameMachine(defaultName) {
+            if (abort.signal.aborted)
+                return null;
+            const answer = await text({
+                ...options,
+                message: "Name for this machine",
+                initialValue: defaultName,
+                validate: (value) => /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/.test(value ?? "")
+                    ? undefined
+                    : "Use 1 to 63 letters, digits, dots, underscores or hyphens, starting with a letter or digit.",
+            });
+            if (typeof answer !== "string") {
+                abort.abort();
+                return null;
+            }
+            return answer;
+        },
         async chooseRunner() {
             if (abort.signal.aborted)
                 return null;
@@ -1028,6 +1091,8 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
                     ? status()
                     : "waiting for you, up to 10 minutes");
                 renderer.action(browser.instruction);
+                if (currentStep === "github.install")
+                    renderer.detail(GITHUB_CONFIRM_ACCESS);
                 if (browser.url)
                     renderer.detail(renderer.link(browser.url));
                 renderer.detail(renderer.dim(interactive ? "Ctrl-C skips this step." : "Ctrl-C stops setup."));
@@ -1109,6 +1174,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         delete ui.chooseFirstRepository;
         delete ui.reviewSettings;
         delete ui.chooseRunner;
+        delete ui.nameMachine;
         delete ui.chooseFirstTicket;
         delete ui.retryTimedOut;
         delete ui.confirmWorkflowAdoption;

package/dist/onboard-workflow.js

@@ -145,13 +145,36 @@ export function observeOnboardWorkflow(value, team, now) {
             : {}),
     };
 }
-const label = (text) => text
+const plainText = (text) => text
     .replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g, "")
-    .trim()
-    .slice(0, 80);
+    .trim();
+const label = (text) => plainText(text).slice(0, 80);
 const listed = (names) => names.length > 10
     ? `${names.slice(0, 10).join(", ")}, and ${names.length - 10} more`
     : names.join(", ");
+function unfinishedLabelLines(plan) {
+    return [
+        ...plan.labels.filter((row) => row.outcome === "refused").map((row) => {
+            const name = plainText(row.name);
+            const reason = plainText(row.reason ?? "Linear did not supply a reason.");
+            const guidance = name === "review-followup"
+                ? "Optional for the cloud workflow; no action is needed to finish setup."
+                : [
+                    name === "catalyst-not-an-ask"
+                        ? "Required for the cloud workflow. Without this label, work held by the ask-shape check cannot be released."
+                        : "Only missing required labels block workflow readiness.",
+                    "Ask a Linear workspace administrator to resolve the reported refusal and make this label available to the team, then run catalyst onboard.",
+                ].join(" ");
+            return `Linear refused label: ${name}. ${reason} ${guidance}`;
+        }),
+        ...(plan.labelsNotCreated ?? []).map((row) => {
+            const entry = object(row);
+            const name = typeof entry?.name === "string" ? plainText(entry.name) : "";
+            const reason = typeof entry?.reason === "string" ? plainText(entry.reason) : "";
+            return `Label not added: ${name || "Unnamed label"}. ${reason || "The server did not supply a reason; run catalyst onboard again to retry."}`;
+        }),
+    ];
+}
 /** The adopt preview in plain words: stages and labels it creates or keeps. Linear's names are data. */
 export function adoptPlanLines(plan) {
     const group = (rows, outcome) => rows.filter((row) => row.outcome === outcome).map((row) => label(row.name));
@@ -161,11 +184,10 @@ export function adoptPlanLines(plan) {
         ["Linear refused stages", group(plan.stages, "refused")],
         ["Create labels", group(plan.labels, "would-create")],
         ["Labels already present", group(plan.labels, "already-present")],
-        ["Linear refused labels", group(plan.labels, "refused")],
     ]
         .filter(([, names]) => names.length > 0)
         .map(([title, names]) => `${title}: ${listed(names)}`)
-        .concat(plan.unfilledLoadBearing?.length ? [`Required work stages still missing: ${plan.unfilledLoadBearing.length}`] : [], (plan.provenanceGaps?.length ?? 0) + (plan.labelProvenanceGaps?.length ?? 0) ? ["Some existing states or labels have no recorded creator; setup keeps them"] : [], plan.labelsNotCreated?.length ? [`Labels that cannot be added: ${plan.labelsNotCreated.length}`] : []);
+        .concat(plan.unfilledLoadBearing?.length ? [`Required work stages still missing: ${plan.unfilledLoadBearing.length}`] : [], (plan.provenanceGaps?.length ?? 0) + (plan.labelProvenanceGaps?.length ?? 0) ? ["Some existing states or labels have no recorded creator; setup keeps them"] : [], unfinishedLabelLines(plan));
 }
 /** The only adopt bodies setup sends: this team, and the approved mode and hash. */
 export function adoptRequestAllowed(body, team, allow) {
@@ -391,7 +413,7 @@ export function onboardWorkflowVerificationAdapter(input = {}) {
                     : {}),
             },
         };
-    }, () => input.message?.(`${onboardTeamKey(journal) ?? "This team"} already has every state and label`));
+    }, () => input.message?.(`${onboardTeamKey(journal) ?? "This team"} has every required state and label`));
     if (!adopts)
         return { check };
     // A local non-admin never gets here; a 403 means the seat changed after login.
@@ -440,7 +462,10 @@ export function onboardWorkflowVerificationAdapter(input = {}) {
                     }
                     const created = (rows) => rows.filter((row) => row.outcome === "created").length;
                     const stages = created(reply.stages), labels = created(reply.labels);
-                    summary = `Applied the Catalyst workflow to ${key}: created ${stages} ${stages === 1 ? "stage" : "stages"} and ${labels} ${labels === 1 ? "label" : "labels"}.`;
+                    summary = [
+                        `Applied the Catalyst workflow to ${key}: created ${stages} ${stages === 1 ? "stage" : "stages"} and ${labels} ${labels === 1 ? "label" : "labels"}.`,
+                        ...unfinishedLabelLines(reply),
+                    ].join("\n");
                     return { state: "done" };
                 }, () => input.message?.(summary));
                 // Only the server's own plan-stale answer plans again; a later identity refusal does not.

package/dist/onboard.js

@@ -268,6 +268,7 @@ function normalizeStep(value, fallbackAt) {
         "membershipId",
         "checkedAt",
         "project",
+        "projectCount",
         "repository",
         "installation",
         "ticket",
@@ -673,6 +674,7 @@ export function stepSatisfied(step) {
                 // Optional: a computer without the daily update still runs work.
                 step.id === "housekeeping" ||
                 step.reason === "member_scope" ||
+                step.reason === "returning_workspace_move_on" ||
                 (step.id === "daemon" && step.reason === "local_sync_not_selected") ||
                 (step.id === "runner" && step.reason === "runner_not_selected") ||
                 (step.id === "first-ticket" && step.reason === "first_ticket_skipped") ||
@@ -711,7 +713,8 @@ export function onboardRequiredStepsWaiting(journal) {
 }
 /** A full run that exited 0 with deferred steps still open: ready for work, not complete. */
 export function onboardReadyForWork(journal, only) {
-    return !only && journal.exit === 0 && !journal.complete;
+    return !only && journal.exit === 0 && !journal.complete &&
+        !journal.steps.some(step => step.reason === "returning_workspace_move_on");
 }
 /** A recorded step's next action; a prerequisite wait names the first unfinished step it needs. */
 export function onboardStepAction(journal, step, baseUrl) {
@@ -1143,7 +1146,11 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         else if (deps.ui)
             deps.ui.finish(journal, only);
         else {
-            if (journal.complete)
+            if (journal.complete && journal.steps.some(step => step.reason === "returning_workspace_move_on")) {
+                ctx.stdout("This computer is set up. Existing projects were kept in place.");
+                ctx.stdout("Next: run catalyst ready to review their checks.");
+            }
+            else if (journal.complete)
                 ctx.stdout("Onboarding complete.");
             else if (onboardReadyForWork(journal, only) &&
                 (deps.requiredSteps ?? []).every((id) => journalStep(journal, id)?.state === "done")) {