@catalyst-cloud/cli 0.16.0 → 0.16.2

package/dist/onboard-project-cleanup.js

@@ -0,0 +1,100 @@
+import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { readExistingOnboardJson } from "./onboard-existing.js";
+import { readReturningProjects } from "./onboard-returning.js";
+const waiting = (reason) => ({ state: "waiting", reason });
+const signature = (project) => JSON.stringify([...(project.repositories ?? [])].sort((a, b) => a.id.localeCompare(b.id)));
+/** Archiving uses the existing reversible project action. Only the explicitly reviewed scope
+ * is changed, after fresh inventory and identity checks. A failed write is never assumed absent. */
+export async function archiveReturningProject(project, ctx, journal, confirm, signal) {
+    const cfg = loadConfig(ctx.home);
+    const sameIdentity = () => {
+        const now = loadConfig(ctx.home);
+        return cfg?.user && now?.user && cfg.account === journal.account &&
+            cfg.user.id === journal.membershipId && now.account === cfg.account &&
+            now.user.id === cfg.user.id && ["owner", "admin"].includes(now.user.role) &&
+            normalizeBaseUrl(now.baseUrl) === journal.baseUrl && normalizeBaseUrl(cfg.baseUrl) === journal.baseUrl;
+    };
+    if (!sameIdentity() || !confirm)
+        return waiting("returning_project_cleanup_unverified");
+    const fresh = await readReturningProjects(ctx, journal, signal);
+    const selected = "projects" in fresh ? fresh.projects.find(p => p.id === project.id) : undefined;
+    if (!selected?.repositories?.length || selected.repositories.length > 64 || !sameIdentity())
+        return waiting("returning_project_cleanup_unverified");
+    const linked = async () => {
+        const names = new Set();
+        const boundedRead = signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
+        for (const row of selected.repositories) {
+            const read = await readExistingOnboardJson(ctx, `/api/v1/me/projects/${encodeURIComponent(row.id)}/repositories`, boundedRead);
+            if ("reason" in read || !read.body || typeof read.body !== "object")
+                return null;
+            const body = read.body;
+            if (!body.project || typeof body.project !== "object" ||
+                !("id" in body.project) || body.project.id !== row.id ||
+                !("teamId" in body.project) || body.project.teamId !== selected.id ||
+                !Array.isArray(body.repositories) || !body.repositories.length || body.repositories.length > 10_000)
+                return null;
+            const returnedNames = new Set();
+            for (const repository of body.repositories) {
+                if (!repository || typeof repository !== "object" || !("fullName" in repository) ||
+                    typeof repository.fullName !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/.test(repository.fullName))
+                    return null;
+                names.add(repository.fullName);
+                returnedNames.add(repository.fullName);
+            }
+            if (!returnedNames.has(row.name))
+                return null;
+        }
+        return [...names].sort();
+    };
+    const linkedNames = await linked();
+    if (!linkedNames || !sameIdentity())
+        return waiting("returning_project_cleanup_unverified");
+    const lines = [
+        `Archive ${selected.name} (${selected.key}) in Catalyst.`,
+        ...linkedNames.map(name => `Repository affected: ${name}.`),
+        "Archiving removes this project’s repository registrations. Mirroring may stop where no other registration keeps a repository active.",
+        "The project and its repository links are kept so it can be reactivated. Linear tickets and GitHub repositories are kept.",
+        "New work may be held when these repositories are no longer registered for this project.",
+    ];
+    if (!(await confirm(selected, lines)))
+        return { state: "done", reason: "returning_project_cleanup_declined" };
+    if (signal?.aborted || !sameIdentity())
+        return waiting("returning_project_cleanup_unverified");
+    const rechecked = await readReturningProjects(ctx, journal, signal);
+    const current = "projects" in rechecked ? rechecked.projects.find(p => p.id === selected.id) : undefined;
+    if (!current || signature(current) !== signature(selected) || !sameIdentity())
+        return waiting("returning_project_cleanup_changed");
+    const recheckedLinks = await linked();
+    if (!recheckedLinks || JSON.stringify(recheckedLinks) !== JSON.stringify(linkedNames) || !sameIdentity())
+        return waiting("returning_project_cleanup_changed");
+    const bearer = cfg?.key || (cfg?.auth && Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() > 30_000
+        ? cfg.auth.accessToken : undefined);
+    if (!bearer)
+        return waiting("returning_project_cleanup_unverified");
+    const bounded = signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
+    for (const row of selected.repositories) {
+        if (bounded.aborted || !sameIdentity())
+            return waiting("returning_project_cleanup_unverified");
+        try {
+            const response = await ctx.fetch(`${journal.baseUrl}/api/v1/me/repositories/${encodeURIComponent(row.id)}/archive`, {
+                method: "POST", redirect: "error", signal: bounded,
+                headers: { authorization: `Bearer ${bearer}`, accept: "application/json", "content-type": "application/json" },
+                body: "{}",
+            });
+            if (response.status !== 200)
+                return waiting("returning_project_cleanup_unverified");
+            const body = await response.json();
+            const returned = body && typeof body === "object" && "repository" in body ? body.repository : null;
+            if (!returned || typeof returned !== "object" || !("id" in returned) || returned.id !== row.id ||
+                !("linearTeamId" in returned) || returned.linearTeamId !== selected.id ||
+                !("status" in returned) || returned.status !== "archived")
+                return waiting("returning_project_cleanup_unverified");
+            journal.changes.push({ kind: "project-archive", label: `Archived ${selected.name}: ${row.name}`,
+                undo: "Reactivate the project from its Catalyst project page." });
+        }
+        catch {
+            return waiting("returning_project_cleanup_unverified");
+        }
+    }
+    return { state: "done" };
+}

package/dist/onboard-returning.js

@@ -0,0 +1,172 @@
+import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { readExistingOnboardJson, readOnboardTeamInventory } from "./onboard-existing.js";
+import { teamCheckCopy } from "./ready-copy.js";
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : null;
+const repository = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/;
+/** Count configured teams across their repositories, rather than every visible Linear team. */
+export async function readReturningProjects(ctx, journal, signal) {
+    const cfg = loadConfig(ctx.home);
+    if (!cfg?.user || cfg.account !== journal.account || cfg.user.id !== journal.membershipId ||
+        normalizeBaseUrl(cfg.baseUrl) !== journal.baseUrl)
+        return { reason: "returning_inventory_unverified" };
+    const contract = await readExistingOnboardJson(ctx, "/api/v1/agent/contract", signal);
+    if ("reason" in contract)
+        return { reason: "returning_inventory_unverified" };
+    const doc = object(contract.body);
+    if (object(doc?.account)?.id !== cfg.account || !Array.isArray(doc?.routes))
+        return { reason: "returning_inventory_unverified" };
+    const routes = doc.routes.map(object).filter(r => r?.method === "GET" && typeof r.path === "string" &&
+        /^\/api\/v1\/[A-Za-z0-9_/-]+\/tenant\/repositories$/.test(r.path));
+    if (routes.length !== 1)
+        return { reason: "returning_inventory_unverified" };
+    // The contract's mapped teams omit projects that have not adopted a workflow yet. Use the
+    // complete project inventory, including paused and archived rows, and group active rows by team.
+    const read = await readExistingOnboardJson(ctx, routes[0].path, signal);
+    if ("reason" in read)
+        return { reason: "returning_inventory_unverified" };
+    const list = object(read.body);
+    if (list?.canManage !== true || !Array.isArray(list.repositories) || list.repositories.length > 10_000)
+        return { reason: "returning_inventory_unverified" };
+    const inventory = await readOnboardTeamInventory(ctx, signal);
+    const configured = [];
+    const seen = new Set();
+    const clean = (text) => text.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").slice(0, 120);
+    for (const value of list.repositories) {
+        const row = object(value);
+        if (typeof row?.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/.test(row.id) || seen.has(row.id) ||
+            typeof row.linearTeamId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(row.linearTeamId) ||
+            typeof row.name !== "string" || !row.name.trim() ||
+            !(row.linearTeamKey === null || typeof row.linearTeamKey === "string") ||
+            !["active", "paused", "archived"].includes(String(row.status)) ||
+            typeof row.githubRepoOwner !== "string" || typeof row.githubRepoName !== "string" ||
+            !repository.test(`${row.githubRepoOwner}/${row.githubRepoName}`))
+            return { reason: "returning_inventory_unverified" };
+        seen.add(row.id);
+        if (row.status === "archived")
+            continue;
+        const savedProject = configured.find(p => p.id === row.linearTeamId);
+        const linked = { id: row.id, name: `${row.githubRepoOwner}/${row.githubRepoName}`, status: row.status };
+        if (savedProject) {
+            savedProject.repositories.push(linked);
+            continue;
+        }
+        const team = "reason" in inventory ? undefined : inventory.teams.find(t => t.id === row.linearTeamId);
+        configured.push({ id: row.linearTeamId, key: team?.key ?? clean(row.linearTeamKey ?? ""),
+            name: team?.name ?? clean(row.name), status: "Readiness could not be checked. Run catalyst ready to check it.", repositories: [linked] });
+    }
+    // Bound the whole readiness summary, including a workspace with many projects.
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), 30_000);
+    const bounded = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+    try {
+        for (let start = 0; start < configured.length && !bounded.aborted; start += 4) {
+            await Promise.all(configured.slice(start, start + 4).map(async (project) => {
+                const read = await readExistingOnboardJson(ctx, `/api/v1/agent/tenant/readiness?team=${encodeURIComponent(project.id)}`, bounded);
+                if ("reason" in read)
+                    return;
+                const row = object(object(read.body)?.readiness);
+                if (row?.teamId !== project.id || !["ready", "degraded", "blocked"].includes(String(row.status)) ||
+                    typeof row.checkedAt !== "number" || !Number.isFinite(row.checkedAt) || row.checkedAt < 0 || row.checkedAt > ctx.now().getTime() ||
+                    !Array.isArray(row.checks) || !row.checks.length || row.checks.length > 100)
+                    return;
+                const checks = row.checks.map(object);
+                if (!checks.every(c => c && typeof c.id === "string" && /^[a-z][a-z0-9_]{0,79}$/.test(c.id) &&
+                    ["pass", "fail", "unknown"].includes(String(c.state))) ||
+                    new Set(checks.map(c => c.id)).size !== checks.length)
+                    return;
+                const unfinished = checks.filter(c => c.state !== "pass");
+                if (row.status === "ready" && !unfinished.length)
+                    project.status = "Ready";
+                else if (unfinished.length)
+                    project.status = unfinished.map(c => teamCheckCopy(cfg.baseUrl, project.key, c.id, c.state, null).line
+                        .replace(`team ${project.key}: `, "")).join(" ");
+            }));
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    for (const project of configured) {
+        const paused = project.repositories?.filter(r => r.status === "paused") ?? [];
+        if (paused.length)
+            project.status = `Paused: ${paused.map(r => r.name).join(", ")}. ${project.status === "Ready" ? "Readiness checks pass." : project.status}`;
+    }
+    return { projects: configured };
+}
+const PROJECT_STEPS = new Set([
+    "linear.workspace", "linear.personal", "linear.team", "linear.adopt", "linear.automations",
+    "github.install", "github.personal", "github.repos", "projects", "settings", "values", "capacity", "first-ticket", "ready",
+]);
+/** Scope is enforced in the adapters and receipt, so moving on cannot perform project writes. */
+export function returningWorkspaceAdapters(adapters, args, review, message, newProject, active = () => true, cleanup) {
+    if (args.flags.team !== undefined || args.flags.only !== undefined || args.flags.headless === true)
+        return;
+    let mode = "unread";
+    let count = 0;
+    let cleanupProject;
+    const scope = async (ctx, journal, signal, act = false) => {
+        if (!active())
+            return null;
+        if (mode === "unread") {
+            if (!["owner", "admin"].includes(loadConfig(ctx.home)?.user?.role ?? "")) {
+                mode = "continue";
+                return null;
+            }
+            const inventory = await readReturningProjects(ctx, journal, signal);
+            if ("reason" in inventory)
+                mode = "unknown";
+            else {
+                count = inventory.projects.length;
+                if (!count)
+                    mode = "continue";
+                else {
+                    message(`This workspace already has ${count} Catalyst project${count === 1 ? "" : "s"}.`);
+                    for (const p of inventory.projects)
+                        message(`${p.name} (${p.key}): ${p.status}`);
+                    const choice = review ? await review(inventory.projects) : "move-on";
+                    if (!choice || signal?.aborted)
+                        return { state: "waiting", reason: "interrupted" };
+                    if (choice === "move-on")
+                        mode = "move-on";
+                    else if (choice === "new") {
+                        mode = "continue";
+                        newProject();
+                    }
+                    else if ("cleanup" in choice) {
+                        cleanupProject = inventory.projects.find(p => p.id === choice.cleanup);
+                        mode = cleanupProject ? "cleanup" : "unknown";
+                    }
+                    else if (inventory.projects.some(p => p.id === choice.repair)) {
+                        args.flags.team = choice.repair;
+                        mode = "continue";
+                    }
+                    else
+                        mode = "unknown";
+                }
+            }
+        }
+        if (mode === "cleanup") {
+            if (!act)
+                return { state: "pending", reason: "returning_project_cleanup_requested" };
+            if (!cleanup || !cleanupProject)
+                return { state: "waiting", reason: "returning_project_cleanup_unverified" };
+            const result = await cleanup(cleanupProject, ctx, journal, signal);
+            if (result.state !== "done")
+                return result;
+            mode = "move-on";
+        }
+        if (mode === "unknown")
+            return { state: "waiting", reason: "returning_inventory_unverified" };
+        return mode === "move-on" ? { state: "skipped", reason: "returning_workspace_move_on", evidence: { projectCount: count } } : null;
+    };
+    for (const id of PROJECT_STEPS) {
+        const adapter = adapters[id];
+        if (!adapter)
+            continue;
+        adapters[id] = {
+            ...adapter,
+            check: async (ctx, journal, signal) => (mode === "unread" && id !== "linear.workspace" ? null : await scope(ctx, journal, signal)) ?? adapter.check(ctx, journal, signal),
+            ...(adapter.act ? { act: async (ctx, journal, signal) => (mode === "unread" && id !== "linear.workspace" ? null : await scope(ctx, journal, signal, true)) ?? adapter.act(ctx, journal, signal) } : {}),
+        };
+    }
+}

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,