@catalyst-cloud/cli 0.15.1 → 0.15.3

package/dist/onboard-housekeeping.js

@@ -0,0 +1,93 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+/** The names install.sh schedules the daily update under (catalyst-cloud's install-script.ts). */
+export const HOUSEKEEPING_LABEL = "dev.catalystcloud.housekeeping";
+export const HOUSEKEEPING_TIMER = "catalyst-housekeeping.timer";
+const defaultRun = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 5_000 });
+    return {
+        status: r.status ?? 1,
+        stdout: r.stdout ?? "",
+        stderr: r.error ? r.error.message : (r.stderr ?? ""),
+    };
+};
+function onPath(name, env) {
+    return (env.PATH ?? process.env.PATH ?? "")
+        .split(delimiter)
+        .filter(Boolean)
+        .some((dir) => {
+        try {
+            accessSync(join(dir, name), constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** The installer's own test for "systemctl is here but nothing manages user services". */
+const NO_USER_MANAGER = /failed to connect to bus: (no medium found|no such file or directory)|system has not been booted with systemd/i;
+/** Every answer but "scheduled" is a skip: the daily update is optional, so it never holds setup
+ * or becomes its next action. The reason keeps which case it is. */
+const skipped = (reason, path) => ({
+    state: "skipped",
+    reason,
+    ...(path ? { evidence: { path } } : {}),
+});
+/** CTC-4680: the daily update step reports what this computer actually has. It only observes:
+ * scheduling stays the installer's job. */
+export function onboardHousekeepingAdapter(options = {}) {
+    const run = options.run ?? defaultRun;
+    return {
+        check: async (ctx, journal) => {
+            const platform = options.platform ?? process.platform;
+            const choice = journal.dailyUpdate;
+            const notChosen = () => choice?.state === "off"
+                ? skipped("housekeeping_off_chosen")
+                : choice?.state === "skipped"
+                    ? skipped("housekeeping_no_scheduler")
+                    : undefined;
+            if (platform === "darwin") {
+                if (!onPath("launchctl", ctx.env))
+                    return notChosen() ?? skipped("housekeeping_no_scheduler");
+                const plist = join(ctx.home, "Library", "LaunchAgents", `${HOUSEKEEPING_LABEL}.plist`);
+                if (!existsSync(plist))
+                    return notChosen() ?? skipped("housekeeping_not_scheduled");
+                const uid = options.uid ?? process.getuid?.() ?? 0;
+                // `print` answers for a loaded job only; the plist alone schedules nothing.
+                if (run("launchctl", ["print", `gui/${uid}/${HOUSEKEEPING_LABEL}`]).status === 0)
+                    return {
+                        state: "done",
+                        evidence: { scheduled: true, provider: "launchd", path: plist },
+                    };
+                return notChosen() ?? skipped("housekeeping_not_loaded", plist);
+            }
+            if (platform === "linux") {
+                if (!onPath("systemctl", ctx.env))
+                    return notChosen() ?? skipped("housekeeping_no_scheduler");
+                const timer = join(ctx.env.XDG_CONFIG_HOME ?? join(ctx.home, ".config"), "systemd", "user", HOUSEKEEPING_TIMER);
+                if (existsSync(timer)) {
+                    const enabled = run("systemctl", ["--user", "is-enabled", HOUSEKEEPING_TIMER]);
+                    if (enabled.status === 0 && enabled.stdout.trim() === "enabled")
+                        return {
+                            state: "done",
+                            evidence: { scheduled: true, provider: "systemd", path: timer },
+                        };
+                    if (NO_USER_MANAGER.test(enabled.stderr))
+                        return notChosen() ?? skipped("housekeeping_no_scheduler");
+                    return notChosen() ?? skipped("housekeeping_not_enabled", timer);
+                }
+                const chosen = notChosen();
+                if (chosen)
+                    return chosen;
+                // A systemctl binary is not a scheduler: a container or WSL has it with no user manager.
+                const manager = run("systemctl", ["--user", "show-environment"]);
+                return manager.status !== 0 && NO_USER_MANAGER.test(manager.stderr)
+                    ? skipped("housekeeping_no_scheduler")
+                    : skipped("housekeeping_not_scheduled");
+            }
+            return notChosen() ?? skipped("housekeeping_no_scheduler");
+        },
+    };
+}

package/dist/onboard-next.js

@@ -1,27 +1,35 @@
 import { nativeEgressInstallCommands } from "./onboard-runner-egress.js";
-import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { INSTALL_COMMAND, loadConfig, normalizeBaseUrl } from "./config.js";
 import { githubInstallationPage } from "./onboard-permissions.js";
+import { valuesFacts, valuesFix } from "./ready-copy.js";
 /** What a person reads for a step that is not done. Each line ends in an action they can take. */
 const REASONS = {
-    account_identity_unverified: "Your login changed while coding accounts were checked. Run catalyst onboard again to verify your person and workspace.",
-    account_inventory_unavailable: "Coding accounts could not be read. Run catalyst onboard again to retry.",
-    account_inventory_unverified: "The server did not return a fresh supported coding-account list. Run catalyst onboard after the server update.",
-    coding_account_not_found: "The coding account named by --coding-account is not enrolled in this workspace. Run catalyst accounts to list the slots, then run catalyst onboard with one of them.",
-    account_validation_admin_required: "An administrator must check the workspace's coding-account access.",
+    account_identity_unverified: "Your login changed while AI accounts were checked. Run catalyst onboard again to verify your person and workspace.",
+    account_inventory_unavailable: "AI accounts could not be read. Run catalyst onboard again to retry.",
+    account_inventory_unverified: "The server did not return a fresh supported AI account list. Run catalyst onboard after the server update.",
+    connect_checklist_refused: "Catalyst refused to show this login the Connect accounts page's status. Sign in again with catalyst login, then run catalyst onboard.",
+    connect_checklist_identity_unverified: "Your login changed while setup was checking the Connect accounts page. Run catalyst onboard again to verify your person and workspace.",
+    coding_account_inactive: "The AI account named by --coding-account is turned off. Turn it on in the workspace's AI account settings, then run catalyst onboard.",
+    coding_account_ended: "The AI account named by --coding-account was removed or its access has ended. Name another one with --coding-account, or add one in the workspace's AI account settings.",
+    coding_account_needs_login: "The AI account named by --coding-account needs its key added again. Replace it in the workspace's AI account settings, then run catalyst onboard.",
+    coding_account_quarantined: "The AI account named by --coding-account is held after repeated failures. Check it in the workspace's AI account settings, then run catalyst onboard.",
+    coding_account_walled: "The AI account named by --coding-account has used its usage limit for now. Check when it resets, then run catalyst onboard again.",
+    coding_account_not_found: "The AI account named by --coding-account is not in this workspace. Run catalyst accounts to list the slots, then run catalyst onboard with one of them.",
+    account_validation_admin_required: "An administrator must check the workspace's AI account access.",
     account_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard.",
     account_validation_unavailable: "The provider check could not finish. Run catalyst onboard again to retry.",
     account_validation_unverified: "The server did not return a fresh provider check. Run catalyst onboard after the server update.",
-    account_provider_access_unverified: "Coding-account provider access is not freshly verified. Check the account in the workspace's coding-account settings, then resume setup.",
+    account_provider_access_unverified: "AI account access is not freshly verified. Check the account in the workspace's AI account settings, then resume setup.",
     codex_provider_access_unverified: "Codex credentials are stored, but provider access is not freshly verified. Setup did not refresh or rotate the Codex login.",
     account_provider_walled: "Claude's usage limit is spent for now. Check the account's reset time, then run catalyst onboard again.",
-    account_provider_rejected: "Claude refused the stored login. Replace it in the workspace's coding-account settings, then resume setup.",
+    account_provider_rejected: "Claude refused the stored login. Replace it in the workspace's AI account settings, then resume setup.",
     personal_consent_handoff: "The browser approval link could not be verified. Run catalyst onboard to try again.",
     personal_identity_refused: "Your current login no longer matches this setup. Resume with the original workspace and person.",
     personal_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
     onboard_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
     personal_status_unavailable: "Your personal connection could not be checked. Run catalyst onboard to try again.",
-    workspace_browser_unavailable: "This computer could not open a browser. Connect Linear from this workspace’s Integrations page in your browser, then run catalyst onboard to resume.",
-    personal_browser_unavailable: "This computer could not open a browser. Finish this login’s connection from Connected accounts in your browser, then run catalyst onboard to resume.",
+    workspace_browser_unavailable: "The link to connect Linear timed out. Run catalyst setup for a new one.",
+    personal_browser_unavailable: "The link to connect your own account timed out. Run catalyst setup for a new one.",
     onboarding_capability_unavailable: "The server's setup capabilities could not be checked. Run catalyst onboard to try again.",
     onboarding_capability_identity_unverified: "The server's setup capabilities belong to another login or workspace. Sign in to the original workspace to resume.",
     onboarding_capability_login_refresh_required: "Your login needs a refresh before setup capabilities can be checked. Run catalyst login, then catalyst onboard.",
@@ -34,13 +42,17 @@ const REASONS = {
     github_installation_identity_refused: "GitHub setup belongs to another login or workspace. Sign in to the original workspace to resume.",
     github_installation_admin_required: "A workspace owner or administrator approves the GitHub App installation.",
     github_installation_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
-    github_installation_browser_unavailable: "This computer could not open a browser. Install the GitHub App from this workspace’s Integrations page in your browser, then run catalyst onboard to resume.",
+    github_installation_browser_unavailable: "The link to install Catalyst on GitHub timed out. Run catalyst setup for a new one.",
+    github_installation_approval_pending: "An install request is waiting on GitHub. An owner of your GitHub organization approves it there, then run catalyst setup.",
+    github_install_pending: "Runs after Catalyst is installed on GitHub.",
+    consent_timeout: "The link timed out. Run catalyst setup for a new one.",
     skills_install_unverified: "The Catalyst skills are not in this user's skills folder. Run catalyst install, then run catalyst onboard.",
     step_not_available_in_this_release: "This setup step is not available yet.",
     prerequisite_not_ready: "Waiting for an earlier setup step.",
     local_sync_not_selected: "Using cloud reads. Local sync was not selected.",
     local_sync_capability_unavailable: "Local sync was selected but could not be verified.",
     member_scope: "Your workspace administrator handles this step.",
+    member_team_required: "Setup needs your Linear team to check what Catalyst can work on. Run catalyst setup again with --team <KEY>, using your team's key from Linear.",
     onboarding_checks_pending: "Some required checks are still unverified.",
     interrupted: "Setup paused. Run the same command to resume.",
     signin_timeout: "Sign-in timed out. Run catalyst onboard to try again.",
@@ -135,7 +147,15 @@ const REASONS = {
     linear_workspace_permissions_unverified: "The workspace's Linear connection works, but its granted scopes could not be checked. Run catalyst onboard to try again.",
     linear_personal_scope_outdated: "Your personal Linear connection is missing scopes this version needs. Re-authorize it from Connected accounts, then run catalyst onboard.",
     personal_permissions_unverified: "Your personal connection's granted scopes could not be checked. Run catalyst onboard to try again.",
+    required_values_unverified: "Catalyst has not read the repository's settings yet. Run catalyst setup again in a few minutes.",
+    first_ticket_team_unverified: "Setup could not confirm the selected Linear team. Run catalyst setup again.",
+    first_ticket_dispatch_unmapped: "Catalyst does not know which of the team's stages starts its work yet. Set up the team's Catalyst workflow, then run catalyst setup again.",
     housekeeping_service_unverified: "The daily update needs a user service manager, launchd on macOS or systemd --user on Linux. Setup cannot schedule it on this computer. It is optional, and work does not depend on it.",
+    housekeeping_off_chosen: "The daily update is off, as you chose when you installed. It is optional. catalyst says when an update is out.",
+    housekeeping_no_scheduler: "The daily update can't run on this computer: it needs launchd on macOS or systemd --user on Linux. It is optional. catalyst says when an update is out.",
+    housekeeping_not_loaded: "The daily update is installed but not turned on. Run launchctl load ~/Library/LaunchAgents/dev.catalystcloud.housekeeping.plist to turn it on.",
+    housekeeping_not_enabled: "The daily update is installed but not turned on. Run systemctl --user enable --now catalyst-housekeeping.timer to turn it on.",
+    housekeeping_not_scheduled: `The daily update is not scheduled on this computer. Run the installer again to schedule it: ${INSTALL_COMMAND} -s -- --housekeeping yes`,
 };
 /** The saved login's web address, or nothing when the config is missing, unreadable or not http(s). */
 export function savedOnboardBaseUrl(home) {
@@ -258,6 +278,26 @@ export function onboardStepDetail(step) {
         : undefined;
     return granted ? `granted ${granted}` : undefined;
 }
+/** The dispatch stage's name as the contract gave it, or what it does when unknown. */
+export function dispatchStageName(value) {
+    return typeof value === "string" && /^[\p{L}\p{N}][\p{L}\p{N} ._&'()-]{0,59}$/u.test(value)
+        ? value
+        : "the stage that starts Catalyst's work";
+}
+function firstTicketText(reason, key, stage) {
+    const move = `move one of ${key ? `${key}'s` : "your team's"} tickets to ${dispatchStageName(stage)} in Linear`;
+    switch (reason) {
+        case "first_ticket_choice_required":
+            return `${move.charAt(0).toUpperCase()}${move.slice(1)}. Catalyst picks it up next.`;
+        case "first_ticket_move_refused":
+            return `Catalyst could not move the ticket for you. Ask a Catalyst owner or admin to check its Linear connection, or ${move} yourself.`;
+        case "first_ticket_unavailable":
+            return `Setup could not read or move the team's tickets. Run catalyst setup to try again, or ${move} yourself.`;
+        case "first_ticket_unverified":
+            return `Setup could not confirm which ticket moved. Check ${dispatchStageName(stage)} in Linear before choosing again.`;
+    }
+    return undefined;
+}
 /** One step's next action. `waitsFor` names the unfinished step a prerequisite wait is blocked on. */
 export function onboardReasonText(step, context = {}) {
     const reason = step.reason ?? "";
@@ -269,13 +309,52 @@ export function onboardReasonText(step, context = {}) {
         const path = reason === "workspace_approval_required"
             ? "/settings/connections?connect=linear"
             : reason === "github_installation_approval_required"
-                ? "/settings/connections?install=github"
+                ? "/connect/github/start"
                 : `/settings/connected-accounts?connect=${step.id === "github.personal" ? "github" : "linear"}`;
         const where = context.baseUrl
             ? `${normalizeBaseUrl(context.baseUrl)}${path}`
             : "Catalyst settings";
         return `Open ${where} and approve this connection, then run catalyst onboard.`;
     }
+    // CTC-4680: only a Catalyst owner or admin can start the GitHub install (the start route refuses
+    // anyone else), so a member is told who to ask and where, on every channel.
+    if (step.id === "github.install" &&
+        (reason === "github_installation_admin_required" || reason === "member_scope"))
+        return `Only an owner or admin of your Catalyst workspace can install Catalyst on GitHub. Ask one to open ${context.baseUrl ? `${normalizeBaseUrl(context.baseUrl)}/settings/connections` : "Catalyst settings, Integrations,"} and install it there.`;
+    if (reason === "admin_setup_pending") {
+        const words = {
+            "linear.workspace": "connect Linear",
+            "github.install": "install Catalyst on GitHub",
+            "linear.adopt": "set up the team's Catalyst workflow",
+        };
+        const left = String(step.evidence?.admin ?? "")
+            .split(",")
+            .flatMap((id) => (words[id] ? [words[id]] : []));
+        const list = left.length > 1 ? `${left.slice(0, -1).join(", ")} and ${left.at(-1)}` : (left[0] ?? "finish setup");
+        return `A Catalyst owner or admin still has to ${list}. Ask one to open ${context.baseUrl ? `${normalizeBaseUrl(context.baseUrl)}/settings/connections` : "Catalyst settings"}, then run catalyst setup.`;
+    }
+    // A member is told which admin action is left and where an admin takes it.
+    if (reason === "member_scope") {
+        const key = onboardTeamKey(context.journal);
+        const adminOnly = {
+            "linear.workspace": ["connect Linear", "/settings/connections", " and connect it there"],
+            "linear.adopt": [
+                "set up the team's Catalyst workflow",
+                key ? `/settings/linear-teams/${encodeURIComponent(key)}/adopt` : "/settings/linear-teams",
+                "",
+            ],
+        };
+        const admin = adminOnly[step.id];
+        if (admin) {
+            const [what, path, rest] = admin;
+            const url = context.baseUrl ? `${normalizeBaseUrl(context.baseUrl)}${path}` : "Catalyst settings";
+            return `Only a Catalyst owner or admin can ${what}. Ask one to open ${url}${rest}.`;
+        }
+    }
+    // An install request can sit on GitHub for good (a wrong organization, or an owner who said no),
+    // so the step always keeps a way to install it directly.
+    if (reason === "github_installation_approval_pending" && context.baseUrl)
+        return `${REASONS[reason] ?? ""} If you own the organization, or want a different one, install it at ${normalizeBaseUrl(context.baseUrl)}/connect/github/start.`;
     if (reason === "workflow_mapping_unverified")
         return `This team's workflow mapping is not verified yet. Run catalyst team adopt ${onboardTeamKey(context.journal) ?? "<TEAM KEY>"} to preview the adoption plan. Run it again with the --yes --plan-hash value it prints. Then run catalyst onboard.`;
     if (reason === "team_created_not_adopted" ||
@@ -290,11 +369,22 @@ export function onboardReasonText(step, context = {}) {
         if (team)
             return `Setup could not confirm whether Linear created the team ${team}. Check Linear for it. If it is there: ${adopt(team)} If it is not, run catalyst onboard to create it again.`;
     }
+    if (reason === "ai_account_not_usable") {
+        const where = context.baseUrl
+            ? `at ${normalizeBaseUrl(context.baseUrl)}/settings/coding-accounts`
+            : "in the web app on the Settings → AI accounts page";
+        return `No AI account in this workspace can take work yet. A workspace owner or administrator checks them ${where}: one may need its key replaced, or may have reached its usage limit. Then run catalyst onboard.`;
+    }
     if (reason === "account_enrollment_required") {
         const where = context.baseUrl
             ? `at ${normalizeBaseUrl(context.baseUrl)}/settings/coding-accounts, the Settings → AI accounts page`
             : "in the web app on the Settings → AI accounts page";
-        return `No coding account is enrolled. A workspace owner or administrator adds one ${where}. A Claude account needs its email and the token printed by \`claude setup-token\`. Then run catalyst onboard.`;
+        // CTC-4716: subscriptions are offered only to a workspace the cloud enables for them.
+        const kinds = step.evidence?.aiAccountKinds;
+        const what = typeof kinds === "string" && kinds.split(",").includes("subscription")
+            ? "an API key, billed per token, or a subscription, a fixed monthly plan"
+            : "an API key, billed per token";
+        return `No AI account is added yet. A workspace owner or administrator adds one ${where}: ${what}. Then run catalyst onboard.`;
     }
     if (reason === "automation_management_unavailable") {
         const conflicts = typeof step.evidence?.automations === "string" &&
@@ -345,6 +435,27 @@ export function onboardReasonText(step, context = {}) {
     }
     if (reason === "runner_admission_operator")
         return `The admission policy for team ${onboardTeamKey(context.journal) ?? "<TEAM KEY>"} needs a Catalyst operator to check it. Setup changes only restricted admission and preserves existing policy fields. Ask Catalyst support to confirm a compatible policy, then run the same setup command.`;
+    if (reason === "required_values_missing") {
+        let facts;
+        try {
+            facts = JSON.parse(String(step.evidence?.requiredValues ?? "null"));
+        }
+        catch {
+            facts = null;
+        }
+        const fix = valuesFix(context.baseUrl, valuesFacts(facts)) ??
+            valuesFix(context.baseUrl, { names: ["the missing values"] });
+        // A member cannot set a value; the line says who does, and still never prints one.
+        const member = context.journal?.steps.find((row) => row.id === "signin")?.evidence?.role === "member";
+        if (member)
+            return fix.startsWith("set ")
+                ? `Ask a Catalyst owner or admin to ${fix}. Then run catalyst setup.`
+                : `${fix.charAt(0).toUpperCase()}${fix.slice(1)}. Ask a Catalyst owner or admin to fix it, then run catalyst setup.`;
+        return `${fix.charAt(0).toUpperCase()}${fix.slice(1)}. Then run catalyst setup.`;
+    }
+    const firstTicket = firstTicketText(reason, onboardTeamKey(context.journal), step.evidence?.stage);
+    if (step.id === "first-ticket" && firstTicket)
+        return firstTicket;
     if (reason === "prerequisite_not_ready" && context.waitsFor)
         return `Runs after "${context.waitsFor}".`;
     const permission = permissionText(step, context.baseUrl);

package/dist/onboard-ready.js

@@ -1,5 +1,6 @@
 import { loadConfig } from "./config.js";
 import { loadContract } from "./contract.js";
+import { ONBOARD_DEFERRED_STEPS, onboardRequiredStepsWaiting, } from "./onboard.js";
 const evidenceNames = new Set(["account", "membershipId", "project", "team", "repository", "count", "checkedAt", "expiresAt", "revision", "lag", "cursor", "heartbeatAgeMs", "supervised", "available", "validated", "phaseStarted", "linearComment", "fleetActivity"]);
 const slug = (value) => value && /^[a-z][a-z0-9_]{1,63}$/.test(value) ? value : undefined;
 function cleanCheck(check) {
@@ -32,6 +33,66 @@ export async function onboardingReadyReport(ctx, deps) {
         : required.length === 0 || required.some(check => check.state === "unknown") || work.state === "unknown" ? "unknown" : "complete";
     return { schema: 1, readMode: deps.localSync ? "local" : "cloud", state, checks, work };
 }
+/** Team check outcomes that do not hold setup's readiness, as `check:reason`: the cloud's four
+ * WAITING_PAIRS (nothing has happened yet before a first ticket: a webhook delivery, a write, a host
+ * attaching, a reviewer's first answer), plus two of setup's own. A missing value is the values
+ * step's action; a reference with no value is not here, because the checkout refuses it before any
+ * work starts. A team with no reviewer still runs. */
+const READY_EXEMPT = new Set([
+    "webhook_covers_team:delivery_window_empty",
+    "writes_land:no_write_observed",
+    "hosts_current:no_host_connected",
+    "reviewer_answering:reviewer_not_yet_answered",
+    "required_values:required_value_missing",
+    "reviewer_configured:no_reviewer_configured",
+]);
+/** Admin-owned steps a member's run skips, and the team checks that show an admin finished them. A
+ * member's skip is not a finished setup: readiness holds until these checks pass. */
+const ADMIN_OWNED = [
+    ["linear.workspace", ["oauth_scope", "token_live"]],
+    ["github.install", ["github_app_installed"]],
+    ["linear.adopt", ["mapping_total", "mapped_states_exist"]],
+];
+/** The setup step's verdict. Every required step must be satisfied, and every required check must
+ * pass or be one of the exempt outcomes above. A failing check fails; anything else unread (a stale
+ * or unverified team, a check the cloud could not read, the cloud itself) waits. Work nobody can
+ * observe yet does not hold it. */
+export function onboardReadyStep(report, journal) {
+    const evidence = {
+        checks: report.checks.length,
+        passed: report.checks.filter((check) => check.state === "pass").length,
+    };
+    const failedStep = (journal?.steps ?? []).some((step) => step.id !== "ready" &&
+        !ONBOARD_DEFERRED_STEPS.has(step.id) &&
+        step.state === "failed");
+    if (onboardRequiredStepsWaiting(journal) || failedStep)
+        return { state: "waiting", reason: "onboarding_checks_pending", evidence };
+    const skipped = (id) => journal?.steps.some((step) => step.id === id && step.state === "skipped" && step.reason === "member_scope");
+    // A member's plain run has no team, so nothing can show what an admin finished.
+    if (skipped("linear.team"))
+        return { state: "waiting", reason: "member_team_required", evidence };
+    // Only a check read from a fresh team (`team.<id>.<check>`) that fails counts. An absent, stale or
+    // unknown one (an outage, a workflow just adopted) says nothing about the admin step, so it falls
+    // through to the waits below.
+    const read = new Map(report.checks
+        .filter((check) => /^team\.[^.]+\.[a-z0-9_]+$/.test(check.id))
+        .map((check) => [check.id.split(".")[2], check.state]));
+    const adminLeft = ADMIN_OWNED.filter(([id, checks]) => skipped(id) && checks.some((check) => read.get(check) === "fail")).map(([id]) => id);
+    if (adminLeft.length)
+        return { state: "waiting", reason: "admin_setup_pending", evidence: { ...evidence, admin: adminLeft.join(",") } };
+    const open = report.checks.filter((check) => {
+        if (!check.required || check.state === "pass")
+            return false;
+        // `team.<id>.<check>` is one team check; `team.<id>` alone is the team's whole check list.
+        const parts = check.id.split(".");
+        return !(parts[0] === "team" && parts.length === 3 && READY_EXEMPT.has(`${parts[2]}:${check.reason}`));
+    });
+    if (open.some((check) => check.state === "fail"))
+        return { state: "failed", reason: "onboarding_checks_pending", evidence };
+    if (open.length)
+        return { state: "waiting", reason: "onboarding_checks_pending", evidence };
+    return { state: "done", evidence };
+}
 /** The current contract exposes checked project setup, but not fresh starter-ticket proof. */
 export async function observeCloudOnboarding(ctx, scope = {}) {
     const cfg = loadConfig(ctx.home);

package/dist/onboard-runtime.js

@@ -15,10 +15,22 @@ import { onboardRunnerAdapter } from "./onboard-runner.js";
 import { onboardAutomationManagementAdapter } from "./onboard-automation-management.js";
 import { onboardWorkflowVerificationAdapter } from "./onboard-workflow.js";
 import { onboardAccountsAdapter } from "./onboard-accounts.js";
+import { onboardFirstTicketAdapter } from "./onboard-first-ticket.js";
+import { onboardValuesAdapter } from "./onboard-values.js";
 import { githubInstallationAdapter } from "./onboard-github.js";
+import { connectChecklistAdapter, } from "./onboard-checklist.js";
+import { onboardHousekeepingAdapter, } from "./onboard-housekeeping.js";
 import { guardOnboardCapabilities, } from "./onboard-capabilities.js";
 import { onboardSettingsAdapter, } from "./onboard-settings.js";
+import { TIMED_OUT_REASONS } from "./setup-onboard-copy.js";
 import { fetchMe } from "./transport.js";
+const HOLD_ON_TIMEOUT = [
+    "linear.workspace",
+    "linear.personal",
+    "github.install",
+    "github.personal",
+    "accounts",
+];
 const waiting = (reason) => ({
     state: "waiting",
     reason,
@@ -136,12 +148,31 @@ export function createOnboardRuntime(args, ctx, hooks) {
         !args.json &&
         args.flags.yes !== true &&
         args.flags.headless !== true;
+    // CTC-4680 round 5: whether the step now acting ran a browser wait, so a timed-out wait can be
+    // re-offered with a fresh link instead of moving on to steps that need it.
+    let waited = false;
+    const waitFor = (message, run, page) => {
+        waited = true;
+        return hooks.ui.wait(message, run, page);
+    };
+    // CTC-4680: the Connect accounts page opens once per run, whichever step needs it first.
+    const connectPage = { openedBy: null };
+    const checklistOptions = {
+        openBrowser: hooks.openBrowser ?? openConsentBrowser,
+        wait: interactiveWait
+            ? (message, work, page) => waitFor(message, work, page)
+            : undefined,
+        note: (text) => hooks.ui?.note ? hooks.ui.note(text) : hooks.ui ? hooks.ui.message(text) : ctx.stderr(text),
+        sleep: hooks.sleep,
+        page: connectPage,
+        cache: { last: null },
+    };
     const personalAdapter = (provider) => personalConsentAdapter({
         provider,
         openBrowser: hooks.openBrowser ?? openConsentBrowser,
         sleep: hooks.sleep,
         wait: interactiveWait
-            ? (message, run) => hooks.ui.wait(message, run)
+            ? (message, run) => waitFor(message, run)
             : undefined,
     });
     const linear = existingLinearAdapters(args, hooks.ui?.chooseTeam
@@ -218,16 +249,21 @@ export function createOnboardRuntime(args, ctx, hooks) {
             fallback: linear["linear.workspace"],
             openBrowser: hooks.openBrowser ?? openConsentBrowser,
             wait: interactiveWait
-                ? (message, work) => hooks.ui.wait(message, work)
+                ? (message, work) => waitFor(message, work)
                 : undefined,
             sleep: hooks.sleep,
         }),
-        "github.install": githubInstallationAdapter({
-            openBrowser: hooks.openBrowser ?? openConsentBrowser,
-            wait: interactiveWait
-                ? (message, work) => hooks.ui.wait(message, work)
-                : undefined,
-            sleep: hooks.sleep,
+        "github.install": connectChecklistAdapter({
+            ...checklistOptions,
+            step: "github.install",
+            item: "github-app",
+            fallback: githubInstallationAdapter({
+                openBrowser: hooks.openBrowser ?? openConsentBrowser,
+                wait: interactiveWait
+                    ? (message, work) => waitFor(message, work)
+                    : undefined,
+                sleep: hooks.sleep,
+            }),
         }),
         settings: onboardSettingsAdapter({
             ...hooks.settings,
@@ -247,21 +283,23 @@ export function createOnboardRuntime(args, ctx, hooks) {
                 : undefined,
             message: (text) => (hooks.ui ? hooks.ui.message(text) : ctx.stderr(text)),
         }),
-        accounts: onboardAccountsAdapter({
-            ...(hooks.ui &&
-                hooks.ui.interactive !== false &&
-                !args.json &&
-                args.flags.yes !== true &&
-                args.flags.headless !== true
-                ? {
-                    waitForAccount: (work) => hooks.ui.wait("Waiting for a coding account", work),
-                    sleep: hooks.sleep,
-                }
-                : {}),
-            message: (text) => (hooks.ui ? hooks.ui.message(text) : ctx.stderr(text)),
-            ...(typeof args.flags["coding-account"] === "string"
-                ? { slot: args.flags["coding-account"] }
-                : {}),
+        accounts: connectChecklistAdapter({
+            ...checklistOptions,
+            step: "accounts",
+            item: "ai-account",
+            // A named account is checked on its own: the checklist answers for the whole workspace.
+            enabled: typeof args.flags["coding-account"] !== "string",
+            fallback: onboardAccountsAdapter({
+                ...(interactiveWait
+                    ? {
+                        waitForAccount: (work) => waitFor("Waiting for an AI account", work),
+                        sleep: hooks.sleep,
+                    }
+                    : {}),
+                ...(typeof args.flags["coding-account"] === "string"
+                    ? { slot: args.flags["coding-account"] }
+                    : {}),
+            }),
         }),
         capacity: onboardCapacityAdapter({
             message: (text) => (hooks.ui ? hooks.ui.message(text) : ctx.stderr(text)),
@@ -300,9 +338,14 @@ export function createOnboardRuntime(args, ctx, hooks) {
                     evidence: { provider: "cloud" },
                 },
         },
-        housekeeping: {
-            check: async () => waiting("housekeeping_service_unverified"),
-        },
+        housekeeping: onboardHousekeepingAdapter(hooks.scheduler),
+        values: onboardValuesAdapter(),
+        // Only a person at a terminal picks a ticket; --yes, JSON and headless runs leave it waiting.
+        "first-ticket": onboardFirstTicketAdapter(interactiveWait && hooks.ui?.chooseFirstTicket
+            ? {
+                choose: (tickets, where) => hooks.ui.chooseFirstTicket(tickets.map((ticket) => ({ ...ticket })), { ...where }),
+            }
+            : {}),
         ready: { check: hooks.ready },
     };
     const get = (path) => ({ method: "GET", path });
@@ -362,6 +405,10 @@ export function createOnboardRuntime(args, ctx, hooks) {
             check: [get("/api/v1/repos"), get("/api/v1/agent/contract")],
             fallback: "connections",
         },
+        values: {
+            check: [get("/api/v1/agent/contract")],
+            fallback: "connections",
+        },
         ready: {
             check: [get("/api/v1/agent/contract")],
             fallback: "connections",
@@ -376,6 +423,50 @@ export function createOnboardRuntime(args, ctx, hooks) {
                 message: (text) => hooks.ui ? hooks.ui.message(text) : ctx.stderr(text),
             });
     }
+    // CTC-4680 round 5: a browser link that ran out of time holds the step. The person gets a fresh
+    // link on yes; on stop the UI pauses setup, so nothing that depends on the step runs.
+    const retry = interactiveWait ? hooks.ui?.retryTimedOut?.bind(hooks.ui) : undefined;
+    if (retry)
+        for (const step of HOLD_ON_TIMEOUT) {
+            const adapter = adapters[step];
+            if (!adapter?.act)
+                continue;
+            const act = adapter.act;
+            adapters[step] = {
+                ...adapter,
+                act: async (stepCtx, journal, signal) => {
+                    for (;;) {
+                        waited = false;
+                        const result = await act(stepCtx, journal, signal);
+                        const timedOut = result.state === "waiting" &&
+                            (TIMED_OUT_REASONS.has(result.reason ?? "") ||
+                                (step === "accounts" &&
+                                    (result.reason === "account_enrollment_required" ||
+                                        result.reason === "ai_account_not_usable")));
+                        if (!timedOut || !waited || signal?.aborted || hooks.ui?.signal.aborted)
+                            return result;
+                        if (!(await retry(step)))
+                            return result;
+                    }
+                },
+            };
+        }
+    // Round 5: the runner question waits until Catalyst is on GitHub; asking it earlier left people
+    // answering later steps while nothing could work.
+    const runner = adapters.runner;
+    if (runner?.act && hooks.ui?.chooseRunner && args.flags.runner !== true && args.flags["no-runner"] !== true) {
+        const { check, act } = runner;
+        const githubPending = (journal) => {
+            const github = journal.steps.find((step) => step.id === "github.install");
+            return Boolean(github && github.state !== "done" && github.state !== "skipped");
+        };
+        // Both: the engine runs check before act, and the runner's check is where the question is asked.
+        adapters.runner = {
+            ...runner,
+            check: async (stepCtx, journal, signal) => githubPending(journal) ? waiting("github_install_pending") : check(stepCtx, journal, signal),
+            act: async (stepCtx, journal, signal) => githubPending(journal) ? waiting("github_install_pending") : act(stepCtx, journal, signal),
+        };
+    }
     // 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.
     return {