@catalyst-cloud/cli 0.14.9 → 0.15.0

package/dist/onboard.js

@@ -6,6 +6,8 @@ import { dirname, isAbsolute, join } from "node:path";
 import { parseMachinePaths, resolveCatalystPath, } from "../vendor/paths/index.js";
 import { machinePathsFile } from "../vendor/paths/node.js";
 import { configPathFor } from "./config.js";
+import { onboardJsonView } from "./setup-onboard-copy.js";
+import { standalonePlan, standalonePlanNotes, } from "./onboard-standalone-copy.js";
 import { CliError, UsageError } from "./errors.js";
 import { onboardFileSnapshot } from "./onboard-file-snapshot.js";
 import { onboardReasonText, onboardTeamKey, savedOnboardBaseUrl, } from "./onboard-next.js";
@@ -16,6 +18,8 @@ export const ONBOARD_STEPS = [
     "skills",
     "legacy",
     "signin",
+    "daemon",
+    "housekeeping",
     "linear.workspace",
     "linear.personal",
     "linear.team",
@@ -26,11 +30,10 @@ export const ONBOARD_STEPS = [
     "github.repos",
     "projects",
     "accounts",
+    "capacity",
+    "runner",
     "settings",
     "values",
-    "capacity",
-    "daemon",
-    "housekeeping",
     "first-ticket",
     "ready",
 ];
@@ -102,6 +105,8 @@ export const ONBOARD_DEPENDENCIES = {
     settings: ["projects"],
     values: ["settings"],
     capacity: ["projects"],
+    // The join token names the selected team's pool.
+    runner: ["linear.team"],
     daemon: ["signin"],
     // What dispatch needs. Environment approval gates only implement and pr, and the first phase
     // needs no imported values, so repository settings and local sync do not hold a first ticket.
@@ -123,6 +128,7 @@ const ADMIN_STEPS = new Set([
     "settings",
     "values",
     "capacity",
+    "runner",
     "first-ticket",
 ]);
 export const ONBOARD_TITLES = {
@@ -144,6 +150,7 @@ export const ONBOARD_TITLES = {
     settings: "Review repository settings",
     values: "Import selected local values",
     capacity: "Check runner capacity",
+    runner: "Run Catalyst's work on this machine",
     daemon: "Check optional local sync",
     housekeeping: "Schedule the daily update",
     "first-ticket": "Start a first ticket",
@@ -215,6 +222,8 @@ function normalizeStep(value, fallbackAt) {
     if (!state)
         return null;
     const step = { id, state };
+    if (state === "failed" && row.refused === true)
+        step.refused = true;
     if (typeof row.at === "string")
         step.at = row.at;
     else if (typeof row.updatedAt === "string")
@@ -263,6 +272,21 @@ function normalizeStep(value, fallbackAt) {
         "passed",
         "team",
         "teamKey",
+        "selected",
+        "hostName",
+        "hostId",
+        "capacity",
+        "failing",
+        "image",
+        "automations",
+        "workspaceSlug",
+        // CTC-4629: an outdated connection's grant, scopes, action URL and who takes it.
+        "grant",
+        "granted",
+        "missing",
+        "org",
+        "url",
+        "actor",
     ]) {
         const item = evidence?.[key];
         if (item === null ||
@@ -522,13 +546,13 @@ function freshJournal(ctx, cliVersion, deps) {
 }
 /** A refusal before loading state must not reuse or copy an unreadable receipt. */
 export function onboardErrorJournal(ctx, cliVersion, exit) {
-    return {
+    return onboardJsonView({
         ...freshJournal(ctx, cliVersion, {}),
         scope: "onboarding",
         mode: "run",
         exit,
         complete: false,
-    };
+    }, savedOnboardBaseUrl(ctx.home));
 }
 function planJournal(journal) {
     return {
@@ -542,17 +566,21 @@ function planJournal(journal) {
         }),
     };
 }
-function printPlan(ctx, journal, identity) {
-    const value = planJournal(journal);
+function printPlan(ctx, journal, identity, options) {
     ctx.stdout("Catalyst setup plan");
     if (identity !== undefined)
         for (const line of onboardIdentityLines(identity))
             ctx.stdout(line);
-    for (const step of value.steps)
-        ctx.stdout(`  ${step.state === "done" ? "✓" : "·"} ${ONBOARD_TITLES[step.id]}`);
-    ctx.stdout("Use cloud reads by default. Local sync is optional for SQL or sustained local reads.");
-    ctx.stdout("Setup may check one stored Claude account using a one-token provider request. This may use Claude quota. It does not refresh Codex credentials.");
-    ctx.stdout(`Next: ${value.steps.find((step) => step.state === "pending")?.id ?? "ready"}`);
+    let group;
+    for (const row of standalonePlan(journal, options?.scope, options?.runner)) {
+        if (row.group !== group) {
+            ctx.stdout("");
+            ctx.stdout(row.group);
+            group = row.group;
+        }
+        ctx.stdout(`  ${row.number} ${row.title}  ${row.detail}`);
+    }
+    ctx.stdout(standalonePlanNotes(options?.localSync ?? journal.localSync === true));
 }
 async function confirmContinue(ctx, args, deps) {
     if (args.flags.yes === true)
@@ -591,16 +619,18 @@ function sanitizedResult(id, result, at) {
         id,
         ...result,
         state: result.state === "refused" ? "failed" : result.state,
+        ...(result.state === "refused" ? { refused: true } : {}),
     }, at);
     row.at = at;
     return row;
 }
-function stepSatisfied(step) {
+export function stepSatisfied(step) {
     return (step?.state === "done" ||
         (step?.state === "skipped" &&
             (step.id === "legacy" ||
                 step.reason === "member_scope" ||
                 (step.id === "daemon" && step.reason === "local_sync_not_selected") ||
+                (step.id === "runner" && step.reason === "runner_not_selected") ||
                 (step.id === "linear.automations" &&
                     step.reason === "automation_management_unavailable"))));
 }
@@ -609,6 +639,8 @@ function stepSatisfied(step) {
 export const ONBOARD_DEFERRED_STEPS = new Set([
     "settings",
     "values",
+    // Optional: work also runs on the workspace's other runner hosts.
+    "runner",
     "housekeeping",
     "first-ticket",
 ]);
@@ -616,7 +648,8 @@ export const ONBOARD_DEFERRED_STEPS = new Set([
  * check is that same wait, so readiness waits too instead of reporting a new failure. */
 export function onboardRequiredStepsWaiting(journal) {
     return !!journal?.steps.some((step) => step.id !== "ready" &&
-        !ONBOARD_DEFERRED_STEPS.has(step.id) &&
+        (!ONBOARD_DEFERRED_STEPS.has(step.id) ||
+            (step.id === "runner" && step.evidence?.selected === true)) &&
         step.state !== "failed" &&
         !stepSatisfied(step));
 }
@@ -664,8 +697,32 @@ function requireMatchingIdentity(journal, identity) {
 export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
     if (args.subcommand !== null || args.rest.length > 0)
         throw new UsageError("onboard takes no positional arguments");
-    if (args.json || args.flags.yes === true || args.flags["dry-run"] === true)
+    if (args.json ||
+        (args.flags.yes === true &&
+            !deps.reviewedSetup &&
+            deps.ui?.interactive !== false) ||
+        args.flags["dry-run"] === true)
         deps = { ...deps, ui: undefined };
+    const interactiveUi = Boolean(deps.ui && deps.ui.interactive !== false);
+    let activeRunSignal;
+    if (args.json) {
+        const output = ctx.stdout;
+        ctx = {
+            ...ctx,
+            stdout: (line) => {
+                const value = JSON.parse(line);
+                const paused = Boolean(activeRunSignal?.aborted ||
+                    deps.signal?.aborted ||
+                    deps.ui?.signal.aborted);
+                output(JSON.stringify(onboardJsonView(value, savedOnboardBaseUrl(ctx.home), paused, {
+                    requiredSteps: args.flags.runner === true ? ["runner"] : [],
+                    only: typeof args.flags.only === "string"
+                        ? args.flags.only
+                        : undefined,
+                })));
+            },
+        };
+    }
     const only = typeof args.flags.only === "string"
         ? args.flags.only
         : undefined;
@@ -680,6 +737,24 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
     for (const id of [only, resumeFrom])
         if (id && !ONBOARD_STEPS.includes(id))
             throw new UsageError(`unknown onboarding step: ${id}`);
+    const reviewedScope = new Set();
+    const includeReviewed = (id) => {
+        if (reviewedScope.has(id))
+            return;
+        reviewedScope.add(id);
+        for (const dependency of ONBOARD_DEPENDENCIES[id] ?? [])
+            includeReviewed(dependency);
+    };
+    if (only)
+        includeReviewed(only);
+    else
+        for (const id of ONBOARD_STEPS)
+            reviewedScope.add(id);
+    const planOptions = (journal) => ({
+        runner: args.flags.runner === true,
+        localSync: args.flags["local-sync"] === true || journal.localSync === true,
+        scope: ONBOARD_STEPS.filter((id) => reviewedScope.has(id)),
+    });
     const bootstrap = deps.bootstrap;
     const bootstrapPlan = bootstrap
         ? parseBootstrapPlan(bootstrap.plan)
@@ -744,8 +819,10 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         if (args.json)
             ctx.stdout(JSON.stringify(planJournal(journal)));
         else
-            printPlan(ctx, journal);
+            printPlan(ctx, journal, undefined, planOptions(journal));
         showBootstrap();
+        if (!args.json)
+            ctx.stdout(`Next: run catalyst onboard${only ? ` --only ${only}` : ""}`);
         return 0;
     }
     // Check tenant binding before even a local cleanup mutation. Never overwrite a mismatched receipt.
@@ -760,7 +837,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         const canRenew = error instanceof CliError &&
             error.code === "onboard-login-refresh-required" &&
             deps.stageSignin &&
-            (deps.ui || plainSigninAllowed);
+            (interactiveUi || plainSigninAllowed);
         if (!canRenew) {
             const code = error instanceof CliError ? error.exitCode : EXIT_FAILED;
             ctx.stderr(error instanceof CliError &&
@@ -772,6 +849,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
                     ...journal,
                     mode: "run",
                     exit: code,
+                    errorCode: error instanceof CliError ? error.code : undefined,
                     complete: false,
                 }));
             return code;
@@ -794,11 +872,11 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
     if (identity)
         requireBootstrapIdentity(identity);
     if (deps.ui)
-        deps.ui.plan(journal, identity);
+        deps.ui.plan(journal, identity, planOptions(journal));
     else if (!args.json)
-        printPlan(ctx, journal, identity);
+        printPlan(ctx, journal, identity, planOptions(journal));
     else
-        printPlan({ ...ctx, stdout: ctx.stderr }, journal, identity);
+        printPlan({ ...ctx, stdout: ctx.stderr }, journal, identity, planOptions(journal));
     showBootstrap();
     let localSync = args.flags["local-sync"] === true || journal.localSync === true;
     let candidate = null;
@@ -806,7 +884,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
     // person and workspace. Do not ask to approve a plan whose identity is still unknown.
     if (!identity &&
         deps.stageSignin &&
-        !deps.ui &&
+        !interactiveUi &&
         personalScope &&
         !plainSigninAllowed) {
         ctx.stderr("Sign in with catalyst login, then run catalyst onboard, or use --yes to allow browser sign-in before the displayed setup plan.");
@@ -814,9 +892,11 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
             ctx.stdout(JSON.stringify({ ...planJournal(journal), exit: EXIT_WAITING }));
         return EXIT_WAITING;
     }
-    const stageFirst = Boolean(deps.stageSignin && !identity && (deps.ui || plainSigninAllowed));
+    const stageFirst = Boolean(deps.stageSignin && !identity && (interactiveUi || plainSigninAllowed));
     if (stageFirst) {
-        const message = "Sign in in your browser first. Then review your person, workspace and setup plan. Your saved connection stays unchanged until you approve that plan.";
+        const message = deps.reviewedSetup
+            ? "Sign in in your browser to continue setup."
+            : "Sign in in your browser first. Then review your person, workspace and setup plan. Your saved connection stays unchanged until you approve that plan.";
         if (deps.ui)
             deps.ui.message(message);
         else
@@ -824,7 +904,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
     }
     let consent = stageFirst
         ? { proceed: false, localSync, signin: true }
-        : deps.ui
+        : deps.ui && interactiveUi
             ? await deps.ui.confirmPlan(localSync, deps.stageSignin
                 ? identity
                     ? "saved"
@@ -859,27 +939,32 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
             reviewedIdentity = identityTuple(identity);
             requireMatchingIdentity(journal, identity);
             requireBootstrapIdentity(identity);
+            deps.ui?.stagedSigninEnd?.("done");
             if (deps.ui)
-                deps.ui.plan(journal, identity);
+                deps.ui.plan(journal, identity, planOptions(journal));
             else if (!args.json)
-                printPlan(ctx, journal, identity);
+                printPlan(ctx, journal, identity, planOptions(journal));
             else
-                printPlan({ ...ctx, stdout: ctx.stderr }, journal, identity);
+                printPlan({ ...ctx, stdout: ctx.stderr }, journal, identity, planOptions(journal));
             showBootstrap();
-            consent = deps.ui
-                ? await deps.ui.confirmPlan(localSync, "unavailable")
-                : await confirmContinue(ctx, args, deps);
+            consent =
+                deps.ui && interactiveUi
+                    ? await deps.ui.confirmPlan(localSync, "unavailable")
+                    : await confirmContinue(ctx, args, deps);
         }
         catch (error) {
             const message = error instanceof CliError
                 ? error.message
                 : "Sign-in could not be verified. Your saved connection was not changed.";
-            if (deps.ui)
-                deps.ui.message(message);
-            else
-                ctx.stderr(message);
-            deps.ui?.dispose();
             const code = error instanceof CliError ? error.exitCode : EXIT_WAITING;
+            const rendered = deps.ui?.stagedSigninEnd?.(code === EXIT_WAITING ? "waiting" : "failed", message);
+            if (!rendered) {
+                if (deps.ui)
+                    deps.ui.message(message);
+                else
+                    ctx.stderr(message);
+            }
+            deps.ui?.dispose();
             if (args.json)
                 ctx.stdout(JSON.stringify({ ...planJournal(journal), exit: code }));
             return code;
@@ -888,7 +973,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
     if (typeof consent !== "boolean")
         localSync = consent.localSync;
     if (!(typeof consent === "boolean" ? consent : consent.proceed)) {
-        const missingConsent = !deps.ui &&
+        const missingConsent = !interactiveUi &&
             args.flags.yes !== true &&
             (args.json ||
                 !(deps.isTty ??
@@ -913,7 +998,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
             throw error;
         ctx.stderr(error.message);
         if (args.json)
-            ctx.stdout(JSON.stringify({ ...planJournal(journal), exit: error.exitCode }));
+            ctx.stdout(JSON.stringify({ ...planJournal(journal), exit: error.exitCode, errorCode: error.code }));
         return error.exitCode;
     }
     const stop = new AbortController();
@@ -922,6 +1007,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         ...(deps.signal ? [deps.signal] : []),
         ...(deps.ui ? [deps.ui.signal] : []),
     ]);
+    activeRunSignal = signal;
     const stepCtx = {
         ...ctx,
         stdout: deps.ui
@@ -937,17 +1023,33 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
     };
     let current = null;
     let mayRecordProgress = candidate === null;
+    const recordStep = (next) => {
+        const prior = journalStep(journal, next.id);
+        // Once a create was sent, generic capability, identity, scope and interruption results
+        // cannot erase the recovery key. Only a verified selection or explicit team evidence can
+        // replace it. This also retains a confirmed team's ID while adoption remains unfinished.
+        if (next.id === "linear.team" &&
+            next.state !== "done" &&
+            !next.evidence?.teamKey &&
+            (prior?.reason === "team_create_unverified" ||
+                prior?.reason === "team_created_not_adopted") &&
+            prior.evidence?.teamKey)
+            setStep(journal, { ...prior, state: "waiting", at: next.at });
+        else
+            setStep(journal, next);
+    };
+    const interruptStep = (id) => recordStep({
+        id,
+        state: "failed",
+        reason: "interrupted",
+        at: isoNow(ctx, deps),
+    });
     const interrupted = () => {
         stop.abort();
         if (!mayRecordProgress)
             return;
         if (current)
-            setStep(journal, {
-                id: current,
-                state: "failed",
-                reason: "interrupted",
-                at: isoNow(ctx, deps),
-            });
+            interruptStep(current);
         journal.exit = EXIT_WAITING;
         journal.complete = false;
         try {
@@ -958,7 +1060,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         }
     };
     const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
-    if (deps.bindSignals !== false)
+    if (deps.bindSignals !== false && deps.ui?.handlesSignals !== true)
         for (const name of signals)
             process.on(name, interrupted);
     const finish = (code) => {
@@ -975,7 +1077,8 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         else {
             if (journal.complete)
                 ctx.stdout("Onboarding complete.");
-            else if (onboardReadyForWork(journal, only)) {
+            else if (onboardReadyForWork(journal, only) &&
+                (deps.requiredSteps ?? []).every((id) => journalStep(journal, id)?.state === "done")) {
                 ctx.stdout("Ready for work.");
                 ctx.stdout("Next, when you want:");
                 for (const line of onboardNextActions(journal, savedOnboardBaseUrl(ctx.home)))
@@ -984,7 +1087,8 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
             else if (only && code === 0)
                 ctx.stdout(`${ONBOARD_TITLES[only]} finished. Onboarding still has other steps.`);
             else {
-                ctx.stdout(`Setup still needs ${journal.steps.filter((step) => !stepSatisfied(step)).length} checks.`);
+                ctx.stdout(`Setup still needs ${journal.steps.filter((step) => !stepSatisfied(step) ||
+                    (deps.requiredSteps?.includes(step.id) && step.state !== "done")).length} checks.`);
                 for (const line of onboardNextActions(journal, savedOnboardBaseUrl(ctx.home), only))
                     ctx.stdout(line);
             }
@@ -1113,7 +1217,6 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
                 identity = refreshed;
             }
         }
-        let refused = false;
         const needed = new Set();
         const include = (id) => {
             if (needed.has(id))
@@ -1128,175 +1231,224 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
             for (const id of ONBOARD_STEPS)
                 needed.add(id);
         const fromIndex = resumeFrom ? ONBOARD_STEPS.indexOf(resumeFrom) : 0;
-        for (const id of ONBOARD_STEPS.filter((id) => needed.has(id))) {
-            if (signal.aborted)
-                return finish(EXIT_WAITING);
-            current = id;
-            deps.ui?.stepStart(id);
-            // Member onboarding keeps administration outside its scope, with an explicit recorded reason.
-            if (identity?.role === "member" && memberScopeSkips(id)) {
-                setStep(journal, {
-                    id,
-                    state: "skipped",
-                    reason: "member_scope",
-                    at: isoNow(ctx, deps),
-                });
-                deps.ui?.stepEnd(journalStep(journal, id), journal);
-                continue;
-            }
-            const missing = (ONBOARD_DEPENDENCIES[id] ?? []).find((parent) => !stepSatisfied(journalStep(journal, parent)));
-            if (missing) {
-                setStep(journal, {
-                    id,
-                    state: "waiting",
-                    reason: "prerequisite_not_ready",
-                    at: isoNow(ctx, deps),
-                });
-                writeOnboardJournal(statePath, journal);
-                deps.ui?.stepEnd(journalStep(journal, id), journal);
-                continue;
-            }
-            let adapter = deps.adapters?.[id];
-            // Compatibility for the initial legacy adapter, which performs its own before/after checks.
-            if (!adapter && id === "legacy") {
-                let result = deps.runStep
-                    ? { state: "pending" }
-                    : { state: "skipped", reason: "legacy_not_selected" };
-                adapter = {
-                    check: async () => result,
-                    act: deps.runStep
-                        ? async () => (result = await deps.runStep(id, stepCtx))
-                        : undefined,
-                };
-            }
-            if (!adapter) {
-                setStep(journal, {
-                    id,
-                    state: "waiting",
-                    reason: "step_not_available_in_this_release",
-                    at: isoNow(ctx, deps),
-                });
-                writeOnboardJournal(statePath, journal);
-                deps.ui?.stepEnd(journalStep(journal, id), journal);
-                continue;
-            }
-            try {
-                let result = await adapter.check(stepCtx, journal, signal);
-                if (result.state === "pending" &&
-                    adapter.act &&
-                    (!only || id === only) &&
-                    ONBOARD_STEPS.indexOf(id) >= fromIndex) {
-                    if (deps.identity) {
-                        identity = await deps.identity(journal);
-                        requireMatchingIdentity(journal, identity);
-                        if (identity?.role === "member" && memberScopeSkips(id)) {
-                            setStep(journal, {
-                                id,
-                                state: "skipped",
-                                reason: "member_scope",
-                                at: isoNow(ctx, deps),
-                            });
-                            writeOnboardJournal(statePath, journal);
-                            deps.ui?.stepEnd(journalStep(journal, id), journal);
-                            continue;
-                        }
-                    }
-                    journal.operations[id] ??= `${journal.runId}:${id}`;
-                    setStep(journal, { id, state: "running", at: isoNow(ctx, deps) });
-                    journal.exit = null;
+        let rerun = null;
+        for (;;) {
+            let refused = false;
+            for (const id of ONBOARD_STEPS.filter((id) => needed.has(id) && (!rerun || rerun.has(id)))) {
+                if (signal.aborted)
+                    return finish(EXIT_WAITING);
+                // No step is running while the session refreshes, so an interrupt here marks none of them.
+                current = null;
+                await deps.beforeStep?.(id);
+                if (signal.aborted)
+                    return finish(EXIT_WAITING);
+                current = id;
+                deps.ui?.stepStart(id);
+                const stepSignal = deps.ui?.stepSignal
+                    ? AbortSignal.any([signal, deps.ui.stepSignal])
+                    : signal;
+                // Member onboarding keeps administration outside its scope, with an explicit recorded reason.
+                if (identity?.role === "member" && memberScopeSkips(id)) {
+                    recordStep({
+                        id,
+                        state: "skipped",
+                        reason: "member_scope",
+                        ...(id === "runner" && args.flags.runner === true
+                            ? { evidence: { selected: true } }
+                            : {}),
+                        at: isoNow(ctx, deps),
+                    });
+                    deps.ui?.stepEnd(journalStep(journal, id), journal);
+                    continue;
+                }
+                const missing = (ONBOARD_DEPENDENCIES[id] ?? []).find((parent) => !stepSatisfied(journalStep(journal, parent)));
+                if (missing) {
+                    recordStep({
+                        id,
+                        state: "waiting",
+                        reason: "prerequisite_not_ready",
+                        at: isoNow(ctx, deps),
+                    });
+                    writeOnboardJournal(statePath, journal);
+                    deps.ui?.stepEnd(journalStep(journal, id), journal);
+                    continue;
+                }
+                let adapter = deps.adapters?.[id];
+                // Compatibility for the initial legacy adapter, which performs its own before/after checks.
+                if (!adapter && id === "legacy") {
+                    let result = deps.runStep
+                        ? { state: "pending" }
+                        : { state: "skipped", reason: "legacy_not_selected" };
+                    adapter = {
+                        check: async () => result,
+                        act: deps.runStep
+                            ? async () => (result = await deps.runStep(id, stepCtx))
+                            : undefined,
+                    };
+                }
+                if (!adapter) {
+                    recordStep({
+                        id,
+                        state: "waiting",
+                        reason: "step_not_available_in_this_release",
+                        at: isoNow(ctx, deps),
+                    });
                     writeOnboardJournal(statePath, journal);
-                    const action = await adapter.act(stepCtx, journal, signal);
-                    if (action.state === "done") {
-                        result = await adapter.check(stepCtx, journal, signal);
-                        if (result.state === "pending")
-                            result = { state: "waiting", reason: "verification_pending" };
+                    deps.ui?.stepEnd(journalStep(journal, id), journal);
+                    continue;
+                }
+                try {
+                    let result = await adapter.check(stepCtx, journal, stepSignal);
+                    if (result.state === "pending" &&
+                        adapter.act &&
+                        (!only || id === only) &&
+                        ONBOARD_STEPS.indexOf(id) >= fromIndex) {
+                        if (deps.identity) {
+                            identity = await deps.identity(journal);
+                            requireMatchingIdentity(journal, identity);
+                            if (identity?.role === "member" && memberScopeSkips(id)) {
+                                recordStep({
+                                    id,
+                                    state: "skipped",
+                                    reason: "member_scope",
+                                    at: isoNow(ctx, deps),
+                                });
+                                writeOnboardJournal(statePath, journal);
+                                deps.ui?.stepEnd(journalStep(journal, id), journal);
+                                continue;
+                            }
+                        }
+                        journal.operations[id] ??= `${journal.runId}:${id}`;
+                        const prior = journalStep(journal, id);
+                        const recoveringTeam = id === "linear.team" &&
+                            (prior?.reason === "team_create_unverified" ||
+                                prior?.reason === "team_created_not_adopted");
+                        recordStep({
+                            ...(recoveringTeam ? prior : {}),
+                            id,
+                            state: "running",
+                            at: isoNow(ctx, deps),
+                        });
+                        journal.exit = null;
+                        writeOnboardJournal(statePath, journal);
+                        const action = await adapter.act(stepCtx, journal, stepSignal);
+                        if (action.state === "done") {
+                            result = await adapter.check(stepCtx, journal, stepSignal);
+                            if (result.state === "pending")
+                                result = { state: "waiting", reason: "verification_pending" };
+                        }
+                        else
+                            result = action;
+                        if (id === "signin" && result.state === "done" && deps.identity) {
+                            identity = await deps.identity(journal);
+                            requireMatchingIdentity(journal, identity);
+                            if (identity?.role === "member" && memberScopeSkips(id)) {
+                                recordStep({
+                                    id,
+                                    state: "skipped",
+                                    reason: "member_scope",
+                                    at: isoNow(ctx, deps),
+                                });
+                                writeOnboardJournal(statePath, journal);
+                                deps.ui?.stepEnd(journalStep(journal, id), journal);
+                                continue;
+                            }
+                        }
                     }
-                    else
-                        result = action;
                     if (id === "signin" && result.state === "done" && deps.identity) {
                         identity = await deps.identity(journal);
                         requireMatchingIdentity(journal, identity);
-                        if (identity?.role === "member" && memberScopeSkips(id)) {
-                            setStep(journal, {
-                                id,
-                                state: "skipped",
-                                reason: "member_scope",
-                                at: isoNow(ctx, deps),
-                            });
-                            writeOnboardJournal(statePath, journal);
-                            deps.ui?.stepEnd(journalStep(journal, id), journal);
-                            continue;
-                        }
+                        if (!identity)
+                            result = { state: "failed", reason: "membership_not_verified" };
+                        else
+                            for (const line of onboardIdentityLines(identity))
+                                stepCtx.stdout(line);
                     }
+                    if (result.state === "refused")
+                        refused = true;
+                    if (result.state === "pending")
+                        result = {
+                            ...result,
+                            state: "waiting",
+                            reason: result.reason ?? "action_required",
+                        };
+                    recordStep(sanitizedResult(id, result, isoNow(ctx, deps)));
                 }
-                if (id === "signin" && result.state === "done" && deps.identity) {
-                    identity = await deps.identity(journal);
-                    requireMatchingIdentity(journal, identity);
-                    if (!identity)
-                        result = { state: "failed", reason: "membership_not_verified" };
-                    else
-                        for (const line of onboardIdentityLines(identity))
-                            stepCtx.stdout(line);
+                catch (error) {
+                    if (error instanceof CliError && error.exitCode === EXIT_REFUSED)
+                        refused = true;
+                    const reason = stepSignal.aborted
+                        ? "interrupted"
+                        : error instanceof CliError &&
+                            /^[a-z][a-z0-9_-]{1,63}$/.test(error.code)
+                            ? error.code.replaceAll("-", "_")
+                            : "step_failed";
+                    const renewLogin = error instanceof CliError &&
+                        error.code === "onboard-login-refresh-required";
+                    recordStep({
+                        id,
+                        state: renewLogin || stepSignal.aborted ? "waiting" : "failed",
+                        ...(error instanceof CliError && error.exitCode === EXIT_REFUSED && !stepSignal.aborted ? { refused: true } : {}),
+                        reason,
+                        at: isoNow(ctx, deps),
+                    });
+                    stepCtx.stderr(renewLogin
+                        ? "Renew your login with catalyst login, then run catalyst onboard to resume."
+                        : `✗ ${ONBOARD_TITLES[id]}: ${reason}. The safe reason is saved; run the same command to resume.`);
                 }
-                if (result.state === "refused")
-                    refused = true;
-                if (result.state === "pending")
-                    result = {
-                        ...result,
-                        state: "waiting",
-                        reason: result.reason ?? "action_required",
-                    };
-                setStep(journal, sanitizedResult(id, result, isoNow(ctx, deps)));
-            }
-            catch (error) {
-                if (error instanceof CliError && error.exitCode === EXIT_REFUSED)
-                    refused = true;
-                const reason = signal.aborted
-                    ? "interrupted"
-                    : error instanceof CliError &&
-                        /^[a-z][a-z0-9_-]{1,63}$/.test(error.code)
-                        ? error.code.replaceAll("-", "_")
-                        : "step_failed";
-                const renewLogin = error instanceof CliError &&
-                    error.code === "onboard-login-refresh-required";
-                setStep(journal, {
-                    id,
-                    state: renewLogin ? "waiting" : "failed",
-                    reason,
-                    at: isoNow(ctx, deps),
-                });
-                stepCtx.stderr(renewLogin
-                    ? "Renew your login with catalyst login, then run catalyst onboard to resume."
-                    : `✗ ${ONBOARD_TITLES[id]}: ${reason}. The safe reason is saved; run the same command to resume.`);
+                if (signal.aborted) {
+                    const settled = journalStep(journal, id);
+                    if (settled?.state !== "done" && settled?.state !== "failed")
+                        recordStep({
+                            id,
+                            state: "waiting",
+                            reason: "interrupted",
+                            at: isoNow(ctx, deps),
+                        });
+                    deps.ui?.stepEnd(journalStep(journal, id), journal);
+                    return finish(EXIT_WAITING);
+                }
+                deps.ui?.stepEnd(journalStep(journal, id), journal);
+                writeOnboardJournal(statePath, journal);
+                // Later steps share the same login; preserve the actionable cause instead of cascading failures.
+                if (journalStep(journal, id)?.reason?.endsWith("_login_refresh_required"))
+                    return finish(EXIT_WAITING);
+                if (refused)
+                    break;
             }
-            if (signal.aborted) {
-                setStep(journal, {
-                    id,
-                    state: "failed",
-                    reason: "interrupted",
-                    at: isoNow(ctx, deps),
-                });
-                return finish(EXIT_WAITING);
+            current = null;
+            const scope = only ? [only] : [...ONBOARD_STEPS];
+            const requiredStepRefused = scope.some((id) => deps.requiredSteps?.includes(id) && journalStep(journal, id)?.reason === "member_scope");
+            const required = new Set(deps.requiredSteps ?? []);
+            if (args.flags.runner === true || journalStep(journal, "runner")?.evidence?.selected === true)
+                required.add("runner");
+            const code = refused || requiredStepRefused
+                ? EXIT_REFUSED
+                : [...needed].some((id) => journalStep(journal, id)?.state === "failed")
+                    ? EXIT_FAILED
+                    : scope.every((id) => (stepSatisfied(journalStep(journal, id)) &&
+                        !(required.has(id) && journalStep(journal, id)?.state !== "done")) ||
+                        (!only &&
+                            ONBOARD_DEFERRED_STEPS.has(id) &&
+                            !required.has(id)))
+                        ? 0
+                        : EXIT_WAITING;
+            journal.exit = code;
+            journal.complete =
+                !only &&
+                    code === 0 &&
+                    ONBOARD_STEPS.every((id) => stepSatisfied(journalStep(journal, id)));
+            const unfinished = journal.steps.filter((step) => !stepSatisfied(step));
+            if (!only &&
+                !refused &&
+                unfinished.length &&
+                !signal.aborted &&
+                (await deps.ui?.checkAgain?.(journal))) {
+                rerun = new Set([...unfinished.map((step) => step.id), "ready"]);
+                continue;
             }
-            deps.ui?.stepEnd(journalStep(journal, id), journal);
-            writeOnboardJournal(statePath, journal);
-            // Later steps share the same login; preserve the actionable cause instead of cascading failures.
-            if (journalStep(journal, id)?.reason?.endsWith("_login_refresh_required"))
-                return finish(EXIT_WAITING);
-            if (refused)
-                break;
+            return finish(signal.aborted ? EXIT_WAITING : code);
         }
-        current = null;
-        const scope = only ? [only] : [...ONBOARD_STEPS];
-        const code = refused
-            ? EXIT_REFUSED
-            : scope.some((id) => journalStep(journal, id)?.state === "failed")
-                ? EXIT_FAILED
-                : scope.every((id) => stepSatisfied(journalStep(journal, id)) ||
-                    (!only && ONBOARD_DEFERRED_STEPS.has(id)))
-                    ? 0
-                    : EXIT_WAITING;
-        return finish(code);
     }
     catch (error) {
         if (candidate?.accepted && !mayRecordProgress) {
@@ -1309,13 +1461,13 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         if (error instanceof CliError) {
             ctx.stderr(error.message);
             if (args.json)
-                ctx.stdout(JSON.stringify({ ...planJournal(journal), exit: error.exitCode }));
+                ctx.stdout(JSON.stringify({ ...planJournal(journal), exit: error.exitCode, errorCode: error.code }));
             return error.exitCode;
         }
         throw error;
     }
     finally {
-        if (deps.bindSignals !== false)
+        if (deps.bindSignals !== false && deps.ui?.handlesSignals !== true)
             for (const name of signals)
                 process.off(name, interrupted);
         releaseLock(lock);