@catalyst-cloud/cli 0.15.1 → 0.15.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.15.3
+
+- Setup can finish once the steps needed to run work are ready. It lists optional next steps and keeps your first-ticket choice when you resume.
+- Setup shows one progress display with numbered steps and the reason a step needs attention.
+- When the Connect accounts page is available, setup uses it to finish account connections. Any usable AI account counts without a test request.
+- Setup offers API keys by default. Subscription account options appear only when your workspace enables them.
+
+## 0.15.2
+
+- `catalyst setup` is the command to set up Catalyst. It runs the same steps as `catalyst onboard`, which still works.
+- When a browser link times out, setup says so and asks whether you are ready to try again. Yes gives a new link; stopping pauses setup without moving on to steps that depend on it.
+- The GitHub link opens GitHub's install page directly. An install request already waiting on an organization owner is not requested again, and setup still shows the link to install it yourself.
+- Setup asks whether to run work on this machine only after Catalyst is installed on GitHub.
+- Sign-in says which Catalyst workspace you joined, without internal account numbers. `catalyst ready` describes each team problem in plain words, with the page to fix it and who can fix it.
+
 ## 0.15.1
 
 - Runner setup accepts verified personal team admission before a repository has been mapped to that team. Older cloud servers keep their existing admission check.

package/README.md

@@ -4,13 +4,22 @@
 
 ## Install
 
-Run the installer, then type `/catalyst-onboard` in your coding agent:
+Set up Catalyst Cloud and manage your account from the command line.
+
+Check ticket progress and see which decisions need your attention.
+
+Install: `npm install -g @catalyst-cloud/cli`
+
+[CLI documentation](https://github.com/coalesce-labs/catalyst-cloud-skills#readme)
+
+Run the installer, then run `catalyst onboard`:
 
 ```sh
 curl -fsSL https://staging.catalystcloud.dev/install.sh | sh
+catalyst onboard
 ```
 
-The installer puts the CLI and both skill packs on this machine and connects it with one browser approval. It ends by printing the next step. Then open a new session of your coding agent in any directory and type `/catalyst-onboard` (`$catalyst-onboard` in Codex). The onboarding skill reads where this machine stands and walks you through the rest one step at a time. It asks before it writes anything to your machine. Everything else on this page is the reference it follows.
+The installer puts the CLI and both skill packs on this machine and connects it with one browser approval. Run `catalyst onboard` to finish setup from the command line. You can also use the onboarding skill in your coding agent after that. Everything else on this page is the reference.
 
 This repository supplies skills for setting up and operating your Catalyst Cloud account. A coding workstation also uses [`coalesce-labs/catalyst-dev-skills`](https://github.com/coalesce-labs/catalyst-dev-skills) for research, planning, implementation, review, and shipping.
 
@@ -102,7 +111,7 @@ The command is `catalyst`. `catalyst-skills` still works as a deprecated alias,
 
 ## What this is
 
-A set of skills that let your coding agent run your own Catalyst Cloud account (https://staging.catalystcloud.dev) from your seat: what is happening, what needs you, and what to do about it. They read your account through the Catalyst Cloud SDK, write to it through the account's agent proxy, and never compose a URL or run a tool of their own; every read, write and subscription is a `catalyst` verb with `--help`. Every skill is plain Markdown under `skills/<name>/SKILL.md` in this repository, and your own login — a keyless device-code session, or a personal key — is the only credential. Your agent acts as you: the asks it raises and the comments it posts carry your name, and "what needs me" means you.
+A set of skills that let your coding agent run your own Catalyst Cloud account (https://staging.catalystcloud.dev) from your seat: what is happening, what needs you, and what to do about it. They read your account through the Catalyst Cloud SDK, write to it through the account's agent proxy, and never compose a URL or run a tool of their own; every read, write and live watch is a `catalyst` verb with `--help`. Every skill is plain Markdown under `skills/<name>/SKILL.md` in this repository, and your own login — a keyless device-code session, or a personal key — is the only credential. Your agent acts as you: the asks it raises and the comments it posts carry your name, and "what needs me" means you.
 
 ## What connecting does
 
@@ -222,7 +231,7 @@ Some of these only read, and some write: a comment, a card move, an ask, a relea
 
 ## What a key cannot see yet
 
-Your personal key reads everything the skills need — tickets, pull requests, the eligibility explainer, the dispatch queue, fleet activity, per-ticket execution history (`catalyst explain --history <ticket>`: phase attempts, remediation rounds, park state) and coding-account status (`catalyst accounts`: provider, declared and observed state, window usage, walls, quarantine — never a credential; enrolling or pausing one is `<your cloud>/settings/coding-accounts`). It also releases a parked or held ticket once its cause is fixed: `catalyst release <ticket> --because <what changed>` (the `unstick` skill runs it), recorded against your name and shown in the ticket's history. And it declares what your containers need: `catalyst environment` reads the account-wide declaration, `environment propose --file <path> --approve` proposes and approves it in one compare-and-set, and the values behind the names stay in the cloud — reading needs any active seat, proposing and approving need an admin or owner one. An admin or owner can put a repository's values in from the terminal. `catalyst secret import .env --repo owner/name` stores every name in the file and lists the declared names that still have no value. `catalyst secret set NAME --repo owner/name --command 'op read op://Vault/item/field'` runs the command on your machine and stores its output; with no `--command` it reads the value from stdin, or asks for it without echoing. No value is ever printed, and the cloud's audit records the command, not its output. That is the account's own declaration — a repository's own `.catalyst/catalyst.toml`, which `catalyst-onboard` already reports on, is a separate thing. `catalyst env inventory` lists the environment variable names a repository needs — never a value; `env check` checks the TOML syntax and environment variable table in `.catalyst/catalyst.toml` offline; `env migrate [catalyst.env.json]` prints a TOML environment table from a legacy declaration, with all names optional and values omitted. These commands need no login (the `what-this-repo-needs` skill walks through them). Two things it cannot do, and the skills say so by name rather than guess:
+Your personal key reads everything the skills need — tickets, pull requests, the eligibility explainer, the dispatch queue, fleet activity, per-ticket execution history (`catalyst explain --history <ticket>`: phase attempts, remediation rounds, park state) and coding-account status (`catalyst accounts`: provider, declared and observed state, usage limits, walls, quarantine — never a credential; enrolling or pausing one is `<your cloud>/settings/coding-accounts`). It also releases a parked or held ticket once its cause is fixed: `catalyst release <ticket> --because <what changed>` (the `unstick` skill runs it), recorded against your name and shown in the ticket's history. And it declares what your containers need: `catalyst environment` reads the account-wide declaration, `environment propose --file <path> --approve` proposes and approves it in one compare-and-set, and the values behind the names stay in the cloud — reading needs any active seat, proposing and approving need an admin or owner one. An admin or owner can put a repository's values in from the terminal. `catalyst secret import .env --repo owner/name` stores every name in the file and lists the declared names that still have no value. `catalyst secret set NAME --repo owner/name --command 'op read op://Vault/item/field'` runs the command on your machine and stores its output; with no `--command` it reads the value from stdin, or asks for it without echoing. No value is ever printed, and the cloud's audit records the command, not its output. That is the account's own declaration — a repository's own `.catalyst/catalyst.toml`, which `catalyst-onboard` already reports on, is a separate thing. `catalyst env inventory` lists the environment variable names a repository needs — never a value; `env check` checks the TOML syntax and environment variable table in `.catalyst/catalyst.toml` offline; `env migrate [catalyst.env.json]` prints a TOML environment table from a legacy declaration, with all names optional and values omitted. These commands need no login (the `what-this-repo-needs` skill walks through them). Two things it cannot do, and the skills say so by name rather than guess:
 
 - Read pull-request labels or the reviewer's reaction. The mirror does not carry them; GitHub's own page does.
 - Compute a flow number — cycle time, throughput, or how long pull requests have been open. Nothing serves those yet, so say they are not computed rather than counting something else and calling it that.

package/dist/args.js

@@ -457,7 +457,7 @@ export const FLAG_TABLES = {
     },
 };
 export const VERB_USAGE = {
-    setup: "setup --engine <file> --engine-sha256 <hex> [-- <install options>]   (run by install.sh; install.sh --help lists the options)",
+    setup: "setup [onboard options]   (sets up Catalyst step by step; same as catalyst onboard) | setup --engine <file> --engine-sha256 <hex> [-- <install options>]   (run by install.sh; install.sh --help lists the options)",
     login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
     onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--runner|--no-runner] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--json]",
     install: "install [--skills-dir <dir>] [--force]",

package/dist/capabilities.js

@@ -5,7 +5,9 @@ const agent = (method, name) => ({ method, path: `/api/v1/agent/${name}` });
  *  the person, the workspace, the project, the repository, then work. A new verb is a new row here
  *  in the same change, or `catalyst capabilities` lies to every guide that reads it. */
 export const CAPABILITIES = [
-    { verb: "setup", does: "show install.sh's plan, progress and sign-in in this terminal, and ask its questions", needs: "member", routes: [], since: "0.15.0", engineProtocol: 1 },
+    // CTC-4680: plain `catalyst setup` runs the onboard flow, so install.sh may hand off to it. install.sh
+    // reads this flag rather than `setup --help`, which already exits 0 on 0.15.x.
+    { verb: "setup", does: "set up Catalyst step by step, or show install.sh's plan, progress and sign-in in this terminal", needs: "member", routes: [], since: "0.15.0", engineProtocol: 1, bootstrapHandoff: true },
     { verb: "onboard", does: "run and resume Catalyst setup with a saved step record", needs: "member", routes: [], since: "0.14.0", bootstrapHandoff: true, headless: true },
     { verb: "status", does: "say whether this machine is connected, as whom, and to which cloud", needs: "member", routes: [], since: "0.1.0" },
     { verb: "me", does: "read the person's seat, role and Linear identity", needs: "member", routes: [], since: "0.1.0" },

package/dist/cli.js

@@ -44,12 +44,12 @@ import { cmdRepo } from "./repo.js";
 import { cmdLegacy } from "./legacy.js";
 import { cmdIdentity } from "./identity.js";
 import { cmdConnections } from "./connections.js";
-import { cmdOnboard, onboardErrorJournal, onboardRequiredStepsWaiting, } from "./onboard.js";
+import { cmdOnboard, onboardErrorJournal, } from "./onboard.js";
 import { createClackOnboardUi, shouldUseOnboardUi, } from "./onboard-ui.js";
 import { createOnboardRuntime } from "./onboard-runtime.js";
 import { argvRequestsHeadless, headlessOnboardDeps, headlessUsageRefusal, onboardHeadlessRequested, runOnboardHeadless, } from "./onboard-headless.js";
 import { savedOnboardBaseUrl } from "./onboard-next.js";
-import { onboardingReadyReport, observeCloudOnboarding, } from "./onboard-ready.js";
+import { onboardingReadyReport, onboardReadyStep, observeCloudOnboarding, } from "./onboard-ready.js";
 import { selectedOnboardTeam } from "./onboard-existing.js";
 export { CONFIG_MODE, DEFAULT_BASE_URL, FIRST_STAMPED_VERSION, LEGACY_PACKAGE_NAME, PACKAGE_NAME, PROVENANCE_MARKER, CliError, MeError, UsageError, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, fetchMe, formatMode, installedBundleVersion, installSkills, loadConfig, modernCliPath, normalizeBaseUrl, parseArgs, parseChangelogEntry, parseProvenanceVersion, readChangelog, readManifest, resolveSkillsDir, saveConfig, skillsSourceDir, updateNoticeLine, writeConfig, };
 export const CUSTOMER_SKILLS = [
@@ -69,7 +69,7 @@ const VERB_ALIASES = { join: "login" };
 const HUMAN_VERBS = new Set(["login", "install", "status", "notice"]);
 export function usageText() {
     return [
-        `${PACKAGE_NAME} — the Catalyst Cloud customer CLI: connect to your tenant, read through the SDK, write through the agent proxy`,
+        `${PACKAGE_NAME} — the Catalyst Cloud customer CLI: connect to your Catalyst workspace, read through the SDK, write through the agent proxy`,
         "",
         "Usage:",
         "  catalyst login [--base-url <url>] [--start-replica]   (keyless: logs you in as yourself)",
@@ -96,7 +96,7 @@ export function usageText() {
         "  catalyst var set <NAME> | var import <file> [--repo <owner/name>] [--names NAME[,NAME...]]   (plain environment variables)",
         "  catalyst team <list|check|map|adopt|migrate|checklist> ...",
         "  catalyst capabilities [--json]   (what this CLI can do, the role each verb needs, and whether this cloud serves it)",
-        "  catalyst project list [--json]   (all tenant projects, including those with no stage mapping)",
+        "  catalyst project list [--json]   (all workspace projects, including those with no stage mapping)",
         "  catalyst project wip-limit <get|set <n>|set default> [--team K]   (a project's new-start WIP limit; members read, owners and admins set)",
         "  catalyst repo <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]>   (a checkout's AGENTS.md block and portable agent layout; working tree only)",
         "  catalyst legacy [--remove [--data] [--yes]]   (leftovers of the old local Catalyst runtime: list them; remove them only on a yes)",
@@ -110,8 +110,8 @@ export function usageText() {
         "--key (or set CATALYST_CLOUD_TOKEN) to use a personal or account key instead. The base URL defaults",
         `to CATALYST_CLOUD_BASE_URL or ${DEFAULT_BASE_URL}.`,
         "",
-        "login discovers your tenant from GET /api/v1/me, writes ~/.config/catalyst-cloud/customer.json",
-        "(0600) holding your login session (or key) and this CLI's path, and caches the tenant contract",
+        "login finds your Catalyst workspace, writes ~/.config/catalyst-cloud/customer.json",
+        "(0600) holding your login session (or key) and this CLI's path, and caches the workspace contract",
         "beside it. A keyless session's short-lived token refreshes silently on every request. login does",
         "not install skills: your agent's own install command does that, and `install` is only here to",
         "repair a copy this package made.",
@@ -208,9 +208,15 @@ function maybePrintUpdateNotice(args, ctx) {
 }
 export async function main(argv, ctx = defaultCtx(), deps = {}) {
     // CTC-4625: setup passes the install options through to its engine untouched, so they never meet
-    // this CLI's own flag tables.
-    if (argv[0] === "setup")
-        return runSetup(argv.slice(1), ctx, deps);
+    // this CLI's own flag tables. CTC-4680: without --engine, `setup` is the name a person types for
+    // the onboard flow, so it runs exactly that.
+    if (argv[0] === "setup") {
+        const rest = argv.slice(1);
+        const own = rest.indexOf("--") === -1 ? rest : rest.slice(0, rest.indexOf("--"));
+        if (own.includes("--engine") || own.includes("--help") || own.includes("-h"))
+            return runSetup(rest, ctx, deps);
+        argv = ["onboard", ...rest];
+    }
     let args;
     try {
         args = parseArgs(argv.map((a, i) => (i === 0 && VERB_ALIASES[a] ? VERB_ALIASES[a] : a)));
@@ -231,7 +237,9 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
         onboardHeadlessRequested(args, ctx.env))
         return headlessUsageRefusal(ctx, "--help and --version print text, not the headless document; run them without --json", true, manifest.version);
     if (args.version) {
-        ctx.stdout(`${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
+        ctx.stdout(
+        // Machine-read: install.sh and catalyst-cloud's onboarding harness match this exact line.
+        `${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
         return 0;
     }
     if (args.command === null) {
@@ -298,6 +306,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                                     renderer: createSetupRenderer(process.stdout, ctx.env),
                                     disposeRenderer: true,
                                     signinTimeoutMs: deps.onboardSigninTimeoutMs,
+                                    version: manifest.version,
                                 });
                             }
                             catch (error) {
@@ -320,6 +329,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                             renderer: createSetupRenderer(output, ctx.env),
                             disposeRenderer: true,
                             signinTimeoutMs: deps.onboardSigninTimeoutMs,
+                            version: manifest.version,
                             interactive: false,
                             verbose: args.flags.verbose === true,
                         });
@@ -387,21 +397,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                                         localSync: journal?.localSync ?? args.flags["local-sync"] === true,
                                         observe: observeCloudOnboarding,
                                     });
-                                    const failed = report.checks.some((check) => check.required && check.state === "fail") && !onboardRequiredStepsWaiting(journal);
-                                    return {
-                                        state: report.state === "complete"
-                                            ? "done"
-                                            : failed
-                                                ? "failed"
-                                                : "waiting",
-                                        reason: report.state === "complete"
-                                            ? undefined
-                                            : "onboarding_checks_pending",
-                                        evidence: {
-                                            checks: report.checks.length,
-                                            passed: report.checks.filter((check) => check.state === "pass").length,
-                                        },
-                                    };
+                                    return onboardReadyStep(report, journal);
                                 },
                                 legacy: deps.legacy,
                                 openBrowser: deps.openBrowser,
@@ -687,26 +683,25 @@ async function cmdLogin(args, ctx, deps, personalOnly = false) {
     };
     checkCancelled();
     const written = writeConfig(ctx.home, config);
-    ctx.stdout(`Connected to ${me.name} (${me.slug}) — account ${me.account}`);
+    ctx.stdout(`Catalyst workspace: ${me.name} (${me.slug})`);
     if (me.user) {
-        ctx.stdout(`Connected as ${me.user.label} (${me.user.role})${me.user.linearUserId
+        ctx.stdout(`Signed in to Catalyst as ${me.user.label} (${me.user.role})${me.user.linearUserId
             ? ""
             : ' — your Linear identity is not matched yet, so "what needs me" will show everyone\'s asks until an admin matches it in Settings'}`);
     }
     else {
-        ctx.stderr(`[catalyst] this is the tenant's account key (a host credential), not your own — the skills work, but nothing your agent writes will carry your name and "what needs me" cannot mean you. Mint a personal key at Settings → API keys and log in with that.`);
+        ctx.stderr(`[catalyst] this is your Catalyst workspace's shared key (a host credential), not your own. The skills work, but nothing your agent writes will carry your name, and "what needs me" cannot mean you. Make a personal key at Settings → API keys and sign in with that.`);
     }
     ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your ${auth ? "login session" : "key"} and the CLI path)${written.mode === CONFIG_MODE
         ? ""
         : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
-    ctx.stdout(`Tenant contract range: ${manifest.tenantContractRange}`);
     try {
         const loaded = await loadContract(ctx, config, {
             refresh: true,
             signal: deps.signal,
         });
         checkCancelled();
-        ctx.stdout(`Tenant contract ${loaded.doc.contractVersion} cached at ${loaded.path}`);
+        ctx.stdout(`Saved your workspace settings (version ${loaded.doc.contractVersion}) to ${loaded.path}`);
     }
     catch (err) {
         checkCancelled();

package/dist/consent-browser.js

@@ -54,5 +54,7 @@ export const openConsentBrowser = createConsentBrowserOpener();
 /** The web page that finishes a consent step when no browser opens here. The signed link stays private. */
 export function finishOnTheWeb(baseUrl, page, action) {
     const origin = baseUrl.replace(/\/+$/, "");
-    return `No browser opened on this computer. In a browser signed in to Catalyst, open ${origin}/settings/${page} and ${action}. Setup keeps waiting here.`;
+    // CTC-4680: the GitHub install has a route that goes straight to GitHub; Integrations starts nothing.
+    const path = page === "github-install" ? "/connect/github/start" : `/settings/${page}`;
+    return `No browser opened on this computer. In a browser signed in to Catalyst, open ${origin}${path} and ${action}. Setup keeps waiting here.`;
 }

package/dist/oauth.js

@@ -156,7 +156,7 @@ export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
                         throw new Error("browser-unavailable");
                     await deps.openBrowser(auth.verification_uri_complete ?? auth.verification_uri);
                     browserOpened = true;
-                    ctx.stdout("Opened your browser to that page — approve there, or use the code above.");
+                    ctx.stdout("Opened your browser to that page. Approve there, or use the code above.");
                 }
                 catch {
                     // a browser that will not open is not a failure; the code and URL still work

package/dist/onboard-accounts.js

@@ -3,7 +3,6 @@ import { readExistingOnboardJson } from "./onboard-existing.js";
 import { pollConsent } from "./onboard-consent.js";
 import { verifyOnboardRoutes } from "./onboard-capabilities.js";
 const listPath = "/api/v1/coding-accounts";
-const validatePath = "/api/v1/coding-accounts/:slot/validate";
 const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
     ? value
     : null;
@@ -94,195 +93,92 @@ async function inventory(ctx, journal, signal) {
     }
     return { slots, identity };
 }
-/** Verify one existing Claude slot per run. A stored login, cached poll or Codex shape is not
- * fresh provider access. Enrollment and a phase's actual lease eligibility remain separate. */
+/** Why one account cannot take work, or null when it can. The Connect page's AI-account rule
+ * (the server's isUsableCodingAccount): any provider, any member's account, and a canceled
+ * subscription keeps working until its paid access ends. */
+function unusableCause(row, now) {
+    if (row.declaredState !== "active")
+        return "coding_account_inactive";
+    if (row.revokedAtMs !== null ||
+        (row.accessEndsAtMs !== null && row.accessEndsAtMs <= now))
+        return "coding_account_ended";
+    if (row.needsCredential)
+        return "coding_account_needs_login";
+    if (row.quarantined)
+        return "coding_account_quarantined";
+    if (row.walled)
+        return "coding_account_walled";
+    return null;
+}
+export function usableAiAccount(row, now) {
+    return unusableCause(row, now) === null;
+}
+/** CTC-4680: the step is done when the workspace has at least one usable AI account, from any
+ * provider. With --coding-account, that named account is the one that must be usable. */
 export function onboardAccountsAdapter(input = {}) {
-    let proof = null;
-    let attempted = false;
-    const candidate = (slots, now) => slots
+    const usable = (slots, now) => slots
         .filter((row) => (input.slot === undefined || row.accountSlot === input.slot) &&
-        row.provider === "claude" &&
-        row.declaredState === "active" &&
-        row.ownedByMe &&
-        !row.needsCredential &&
-        !row.walled &&
-        !row.quarantined &&
-        row.renewalStatus !== "canceled" &&
-        row.revokedAtMs === null &&
-        (row.accessEndsAtMs === null || row.accessEndsAtMs > now))
+        usableAiAccount(row, now))
         .sort((a, b) => a.accountSlot.localeCompare(b.accountSlot))[0];
     const check = async (ctx, journal, signal) => {
         const live = await inventory(ctx, journal, signal);
         if ("reason" in live)
             return waiting(live.reason);
-        const selected = candidate(live.slots, ctx.now().getTime());
-        if (proof &&
-            equal(live.identity, proof) &&
-            live.slots.some((row) => row.accountSlot === proof.slot &&
-                row.provider === proof.provider &&
-                row.declaredState === "active" &&
-                row.ownedByMe &&
-                !row.needsCredential &&
-                !row.walled &&
-                !row.quarantined &&
-                row.renewalStatus !== "canceled" &&
-                row.revokedAtMs === null &&
-                (row.accessEndsAtMs === null ||
-                    row.accessEndsAtMs > ctx.now().getTime())) &&
-            proof.checkedAtMs <= ctx.now().getTime() + 5000 &&
-            proof.checkedAtMs >= ctx.now().getTime() - 30000)
+        const selected = usable(live.slots, ctx.now().getTime());
+        if (selected)
             return {
                 state: "done",
                 evidence: {
-                    accountSlot: proof.slot,
-                    provider: proof.provider,
-                    checkedAt: new Date(proof.checkedAtMs).toISOString(),
+                    provider: selected.provider,
+                    checkedAt: ctx.now().toISOString(),
                 },
             };
-        proof = null;
-        if (!live.slots.length)
-            return input.waitForAccount &&
-                ["owner", "admin"].includes(live.identity.role)
-                ? { state: "pending" }
-                : waiting("account_enrollment_required");
-        if (input.slot !== undefined &&
-            !live.slots.some((row) => row.accountSlot === input.slot))
-            return waiting("coding_account_not_found");
-        if (!selected)
-            return waiting(live.slots.some((row) => row.provider === "codex")
-                ? "codex_provider_access_unverified"
-                : "account_provider_access_unverified");
-        if (attempted)
-            return waiting("account_provider_access_unverified");
-        const cfg = loadConfig(ctx.home);
-        if (!cfg?.user || !["owner", "admin"].includes(cfg.user.role))
-            return waiting("account_validation_admin_required");
-        return { state: "pending" };
+        if (input.slot !== undefined) {
+            const named = live.slots.find((row) => row.accountSlot === input.slot);
+            // A named account speaks for itself: other accounts in the workspace may be fine.
+            return waiting(named
+                ? (unusableCause(named, ctx.now().getTime()) ?? "coding_account_not_found")
+                : "coding_account_not_found");
+        }
+        if (input.waitForAccount &&
+            ["owner", "admin"].includes(live.identity.role))
+            return { state: "pending" };
+        return waiting(live.slots.length ? "ai_account_not_usable" : "account_enrollment_required");
     };
     return {
         check,
         act: async (ctx, journal, external) => {
-            if (attempted)
-                return waiting("account_provider_access_unverified");
             const initial = await inventory(ctx, journal, external);
             if ("reason" in initial)
                 return waiting(initial.reason);
-            let live = initial;
-            if (!live.slots.length &&
-                input.waitForAccount &&
-                ["owner", "admin"].includes(live.identity.role)) {
-                const result = await input.waitForAccount(() => pollConsent({
-                    timeoutMs: input.accountWaitMs,
-                    signal: external,
-                    sleep: input.sleep,
-                    readStatus: async (signal) => {
-                        const current = await inventory(ctx, journal, signal);
-                        if ("reason" in current)
-                            return { outcome: "waiting", reason: current.reason };
-                        live = current;
-                        return { outcome: current.slots.length ? "connected" : "absent" };
-                    },
-                }));
-                if (result.state !== "done")
-                    return waiting(result.reason === "consent_timeout"
-                        ? "account_enrollment_required"
-                        : (result.reason ?? "account_enrollment_required"));
-            }
-            const selected = candidate(live.slots, ctx.now().getTime());
-            if (!selected)
-                return waiting("account_provider_access_unverified");
-            const support = await verifyOnboardRoutes(ctx, journal, [{ method: "POST", path: validatePath }], external);
-            if ("reason" in support)
-                return waiting(support.reason);
-            const cfg = loadConfig(ctx.home);
-            if (!equal(binding(ctx, journal), live.identity) ||
-                !cfg?.user ||
-                !["owner", "admin"].includes(cfg.user.role))
-                return waiting("account_identity_unverified");
-            const expiry = cfg.auth
-                ? Date.parse(cfg.auth.expiresAt) - ctx.now().getTime()
-                : 0;
-            const bearer = cfg.key ||
-                (cfg.auth && Number.isFinite(expiry) && expiry > 30000
-                    ? cfg.auth.accessToken
-                    : undefined);
-            if (!bearer)
-                return waiting("account_login_refresh_required");
-            input.message?.("Checking one stored Claude account with a one-token provider request. This may use Claude quota. Codex credentials are not refreshed. Phase eligibility is checked separately.");
-            // A display callback must not be able to switch the identity used for this request.
-            if (!equal(binding(ctx, journal), live.identity))
-                return waiting("account_identity_unverified");
-            const deadline = new AbortController();
-            const signal = external
-                ? AbortSignal.any([external, deadline.signal])
-                : deadline.signal;
-            const timer = setTimeout(() => deadline.abort(), 15000);
-            let remove = () => { };
-            try {
-                return await new Promise((resolve) => {
-                    const stopped = () => resolve(waiting(external?.aborted
-                        ? "interrupted"
-                        : "account_validation_unavailable"));
-                    if (signal.aborted) {
-                        stopped();
-                        return;
-                    }
-                    signal.addEventListener("abort", stopped, { once: true });
-                    remove = () => signal.removeEventListener("abort", stopped);
-                    Promise.resolve()
-                        .then(async () => {
-                        if (signal.aborted)
-                            return waiting("interrupted");
-                        // UI callbacks can queue a config change before this deferred send executes.
-                        if (!equal(binding(ctx, journal), live.identity))
-                            return waiting("account_identity_unverified");
-                        attempted = true;
-                        const response = await ctx.fetch(`${support.origin}/api/v1/coding-accounts/${encodeURIComponent(selected.accountSlot)}/validate`, {
-                            method: "POST",
-                            redirect: "error",
-                            signal,
-                            headers: {
-                                authorization: `Bearer ${bearer}`,
-                                accept: "application/json",
-                            },
-                        });
-                        if (response.status !== 200)
-                            return waiting("account_validation_unavailable");
-                        const body = object(await response.json());
-                        if (signal.aborted ||
-                            !equal(binding(ctx, journal), live.identity))
-                            return waiting("account_identity_unverified");
-                        const now = ctx.now().getTime();
-                        if (!body ||
-                            body.provider !== selected.provider ||
-                            typeof body.checkedAtMs !== "number" ||
-                            !Number.isSafeInteger(body.checkedAtMs) ||
-                            body.checkedAtMs > now + 5000 ||
-                            body.checkedAtMs < now - 30000 ||
-                            !["working", "walled", "rejected", "inconclusive"].includes(String(body.result)))
-                            return waiting("account_validation_unverified");
-                        if (body.result !== "working")
-                            return waiting(body.result === "walled"
-                                ? "account_provider_walled"
-                                : body.result === "rejected"
-                                    ? "account_provider_rejected"
-                                    : "account_provider_access_unverified");
-                        proof = {
-                            ...live.identity,
-                            slot: selected.accountSlot,
-                            provider: selected.provider,
-                            checkedAtMs: body.checkedAtMs,
-                        };
-                        input.message?.("Claude provider access was verified. This does not reserve a runner or prove that a phase can start.");
-                        return check(ctx, journal, signal);
-                    })
-                        .then((result) => (signal.aborted ? stopped() : resolve(result)), () => stopped());
-                });
-            }
-            finally {
-                clearTimeout(timer);
-                remove();
-            }
+            if (!input.waitForAccount ||
+                !["owner", "admin"].includes(initial.identity.role))
+                return check(ctx, journal, external);
+            let enrolled = initial.slots.length > 0;
+            const result = await input.waitForAccount(() => pollConsent({
+                timeoutMs: input.accountWaitMs,
+                signal: external,
+                sleep: input.sleep,
+                readStatus: async (signal) => {
+                    const current = await inventory(ctx, journal, signal);
+                    if ("reason" in current)
+                        return { outcome: "waiting", reason: current.reason };
+                    enrolled = current.slots.length > 0;
+                    return {
+                        outcome: usable(current.slots, ctx.now().getTime())
+                            ? "connected"
+                            : "absent",
+                    };
+                },
+            }));
+            if (result.state === "done")
+                return check(ctx, journal, external);
+            // A wait that ran out holds the step and offers another try (round 5).
+            return waiting(result.reason !== "consent_timeout"
+                ? (result.reason ?? "account_enrollment_required")
+                : enrolled
+                    ? "ai_account_not_usable"
+                    : "account_enrollment_required");
         },
     };
 }