@catalyst-cloud/cli 0.14.9 → 0.15.0

package/dist/cli.js

@@ -1,22 +1,31 @@
 // cli.ts — the `catalyst` dispatcher (npm: @catalyst-cloud/cli). Verbs live in
 // their own modules; this file keeps every export the 0.1 tests and the bin import.
+import { createSetupRenderer } from "./setup-render.js";
 import { existsSync, openSync, closeSync } from "node:fs";
 import { ReadStream as TerminalInput } from "node:tty";
+import { Writable } from "node:stream";
 import { parseArgs, positionals, verbHelp } from "./args.js";
 import { CONFIG_MODE, DEFAULT_BASE_URL, LEGACY_PACKAGE_NAME, PACKAGE_NAME, cliPath, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, formatMode, installerOwnsSkills, INSTALL_COMMAND, loadConfig, modernCliPath, normalizeBaseUrl, readManifest, requireConfig, saveConfig, writeConfig, } from "./config.js";
 import { loadContract, pickPath } from "./contract.js";
 import { CliError, MeError, UsageError } from "./errors.js";
 import { fetchMe } from "./transport.js";
-import { bearerFor, deviceFlowLogin } from "./oauth.js";
+import { bearerFor, deviceFlowLogin, refreshSessionIfShort, } from "./oauth.js";
+const ONBOARD_SESSION_MIN_MS = 20 * 60_000;
+// A consent step waits up to 10 minutes, so each step starts with more than that left.
+const ONBOARD_STEP_MIN_MS = 11 * 60_000;
 import { openBrowserChecked as defaultOpenBrowser } from "./browser.js";
 import { cmdAccounts, cmdExplain, cmdHistory, cmdQueue, cmdRunning, } from "./execution.js";
 import { cmdQuery } from "./query.js";
+import { maybePrintPublishedUpdateNotice } from "./cli-update-notice.js";
 import { cmdReady } from "./ready.js";
 import { cmdReplica } from "./replica.js";
 import { cmdRuntime } from "./runtime-verb.js";
 import { cmdEvents } from "./events.js";
 import { stageOnboardLogin } from "./onboard-login-candidate.js";
 import { stdinIsTty } from "./prompt.js";
+import { cmdSetup, SETUP_USAGE } from "./setup.js";
+import { clackSetupAsk, clackSetupSpinner, openSetupTerminal, setupOnboardStreams, } from "./setup-prompts.js";
+import { keepInstalledCliPath, runSetupSignin } from "./setup-signin.js";
 import { FIRST_STAMPED_VERSION, PROVENANCE_MARKER, parseProvenanceVersion, } from "./skill-shape.js";
 import { installedBundleVersion, installSkills, parseChangelogEntry, readChangelog, resolveSkillsDir, skillsSourceDir, updateNoticeLine, } from "./skills.js";
 import { cmdWatch } from "./watch.js";
@@ -38,6 +47,7 @@ import { cmdConnections } from "./connections.js";
 import { cmdOnboard, onboardErrorJournal, onboardRequiredStepsWaiting, } 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 { selectedOnboardTeam } from "./onboard-existing.js";
@@ -66,7 +76,8 @@ export function usageText() {
         "  catalyst login --key <personal-key> [--base-url <url>]   (or CATALYST_CLOUD_TOKEN, for a key)",
         "  catalyst join ...   (deprecated alias of login; removed in the next minor version)",
         "  catalyst install [--skills-dir <dir>] [--force]   (repair path; your agent's own command installs the skills)",
-        "  catalyst onboard [--resume-from <step>] [--only <step>] [--yes] [--dry-run] [--json]",
+        "  catalyst onboard [--resume-from <step>] [--only <step>] [--runner|--no-runner] [--yes] [--dry-run] [--json]",
+        `  catalyst ${SETUP_USAGE}`,
         "  catalyst status | notice | me | ready | accounts",
         "  catalyst mcp add|list|remove (vault references only)",
         "  catalyst contract [--refresh] [--path <a.b.c>]",
@@ -196,6 +207,10 @@ function maybePrintUpdateNotice(args, ctx) {
     saveConfig(ctx.home, cfg);
 }
 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);
     let args;
     try {
         args = parseArgs(argv.map((a, i) => (i === 0 && VERB_ALIASES[a] ? VERB_ALIASES[a] : a)));
@@ -203,11 +218,18 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             args.command = VERB_ALIASES[args.command];
     }
     catch (err) {
+        if (argvRequestsHeadless(argv, ctx.env))
+            return headlessUsageRefusal(ctx, err instanceof Error ? err.message : String(err), argv.includes("--json"), readManifest().version);
         ctx.stderr(err instanceof Error ? err.message : String(err));
         ctx.stderr(usageText());
         return 1;
     }
     const manifest = readManifest();
+    if (args.json &&
+        (args.help || args.version) &&
+        args.command === "onboard" &&
+        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})`);
         return 0;
@@ -220,6 +242,12 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
         ctx.stdout(verbHelp(args.command));
         return 0;
     }
+    await maybePrintPublishedUpdateNotice(ctx, {
+        interactive: deps.isTty?.() ?? process.stdout.isTTY === true,
+        json: args.json,
+        command: args.command,
+        version: manifest.version,
+    });
     try {
         if (args.command !== "onboard") {
             migrateLegacyCliPath(ctx);
@@ -231,108 +259,178 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             case "install":
                 return cmdInstall(args, ctx);
             case "onboard": {
-                let ui;
-                let terminal;
-                let input = process.stdin;
-                const originalRaw = Boolean(input.isRaw);
-                if (shouldUseOnboardUi(args, Boolean(process.stdout.isTTY))) {
-                    if (!input.isTTY) {
-                        try {
-                            const fd = openSync("/dev/tty", "r");
+                // Setup may already own signal handlers; release them before any headless early exit.
+                if (onboardHeadlessRequested(args, ctx.env))
+                    deps.setupUi?.dispose();
+                for (const flag of ["key-file"])
+                    if (args.flags[flag] !== undefined && !onboardHeadlessRequested(args, ctx.env))
+                        throw new UsageError(`--${flag} needs --headless`);
+                if (typeof args.flags.runner === "string" && !onboardHeadlessRequested(args, ctx.env))
+                    throw new UsageError("--runner yes|no needs --headless; use --runner or --no-runner interactively");
+                // Headless runs drop the terminal UI, browser sign-in and every browser action (CTC-4633).
+                const runOnboard = async (args, ctx, headless) => {
+                    let ui = headless ? undefined : deps.setupUi;
+                    let terminal;
+                    let input = process.stdin;
+                    const originalRaw = Boolean(input.isRaw);
+                    if (!headless && !ui && shouldUseOnboardUi(args, Boolean(process.stdout.isTTY))) {
+                        if (!input.isTTY) {
+                            try {
+                                const fd = openSync("/dev/tty", "r");
+                                try {
+                                    terminal = new TerminalInput(fd);
+                                    input = terminal;
+                                }
+                                catch (error) {
+                                    closeSync(fd);
+                                    throw error;
+                                }
+                            }
+                            catch {
+                                ctx.stderr("No controlling terminal is available; using the displayed defaults.");
+                            }
+                        }
+                        if (input.isTTY) {
                             try {
-                                terminal = new TerminalInput(fd);
-                                input = terminal;
+                                ui = createClackOnboardUi(await import("@clack/prompts"), { input, output: process.stdout }, {
+                                    baseUrl: () => savedOnboardBaseUrl(ctx.home),
+                                    verbose: args.flags.verbose === true,
+                                    renderer: createSetupRenderer(process.stdout, ctx.env),
+                                    disposeRenderer: true,
+                                    signinTimeoutMs: deps.onboardSigninTimeoutMs,
+                                });
                             }
                             catch (error) {
-                                closeSync(fd);
+                                terminal?.destroy();
                                 throw error;
                             }
                         }
-                        catch {
-                            ctx.stderr("No controlling terminal is available; using the displayed defaults.");
-                        }
-                    }
-                    if (input.isTTY) {
-                        try {
-                            ui = createClackOnboardUi(await import("@clack/prompts"), { input, output: process.stdout }, { baseUrl: () => savedOnboardBaseUrl(ctx.home) });
-                        }
-                        catch (error) {
-                            terminal?.destroy();
-                            throw error;
-                        }
                     }
-                }
-                try {
-                    return await cmdOnboard(args, ctx, {
-                        ...createOnboardRuntime(args, ctx, {
-                            ui,
+                    if (!headless && !ui && !args.json && args.flags["dry-run"] !== true) {
+                        const output = process.stdout.isTTY === true
+                            ? process.stdout
+                            : new Writable({
+                                write(chunk, _encoding, callback) {
+                                    ctx.stdout(chunk.toString().replace(/\n$/, ""));
+                                    callback();
+                                },
+                            });
+                        ui = createClackOnboardUi(await import("@clack/prompts"), { input: process.stdin, output }, {
+                            baseUrl: () => savedOnboardBaseUrl(ctx.home),
+                            renderer: createSetupRenderer(output, ctx.env),
+                            disposeRenderer: true,
                             signinTimeoutMs: deps.onboardSigninTimeoutMs,
-                            stageSignin: (signal) => {
-                                if (args.key || ctx.env.CATALYST_CLOUD_TOKEN)
-                                    throw new CliError("Connect your personal key with catalyst login, then run catalyst onboard. Setup will not replace a supplied key with browser sign-in.", "onboard-person-required", 12);
-                                return stageOnboardLogin({ ...ctx, stdout: ctx.stderr }, {
-                                    baseUrl: args.baseUrl,
-                                    signal,
-                                    timeoutMs: deps.onboardSigninTimeoutMs,
-                                    device: {
-                                        isTty: deps.isTty ?? (() => Boolean(process.stdout.isTTY)),
-                                        openBrowser: deps.openBrowser ?? defaultOpenBrowser,
-                                        sleep: deps.sleep,
-                                        waitForApproval: ui
-                                            ? (run) => ui.wait("Waiting for Catalyst approval", run)
-                                            : undefined,
-                                    },
-                                });
+                            interactive: false,
+                            verbose: args.flags.verbose === true,
+                        });
+                    }
+                    // Start with a full access token: a session saved long ago would otherwise expire part way
+                    // through, or send the person back through the device sign-in. A dry run changes nothing.
+                    if (args.flags["dry-run"] !== true)
+                        await refreshSessionIfShort(ctx, ONBOARD_SESSION_MIN_MS);
+                    const jsonLines = [];
+                    const onboardCtx = args.json
+                        ? {
+                            ...ctx,
+                            stdout: (line) => {
+                                jsonLines.push(line);
                             },
-                            login: (stepCtx, signal) => cmdLogin({ ...args, command: "login", flags: {}, json: false }, stepCtx, {
-                                ...deps,
-                                signal,
-                                isTty: () => true,
-                                waitForApproval: ui
-                                    ? (run) => ui.wait("Waiting for Catalyst approval", run)
-                                    : undefined,
-                            }, true),
-                            ready: async (stepCtx, journal) => {
-                                const team = selectedOnboardTeam(journal);
-                                const report = await onboardingReadyReport(stepCtx, {
-                                    teamIds: team ? [team] : undefined,
-                                    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,
-                                    },
-                                };
+                        }
+                        : ctx;
+                    let code;
+                    try {
+                        code = await cmdOnboard(args, onboardCtx, ((value) => (headless ? headlessOnboardDeps(value, headless, args.flags.runner === true) : value))({
+                            ...(deps.setupApproved
+                                ? { reviewedSetup: true, confirm: async () => true }
+                                : {}),
+                            beforeStep: async () => {
+                                if (args.flags["dry-run"] !== true)
+                                    await refreshSessionIfShort(ctx, ONBOARD_STEP_MIN_MS);
                             },
-                            legacy: deps.legacy,
-                            openBrowser: deps.openBrowser,
-                            sleep: deps.sleep,
-                            skillNames: CUSTOMER_SKILLS,
-                        }),
-                        ...(deps.onboardBootstrap
-                            ? { bootstrap: deps.onboardBootstrap }
-                            : {}),
-                        ...(deps.isTty ? { isTty: deps.isTty } : {}),
-                        ...(deps.signal ? { signal: deps.signal } : {}),
-                    }, readManifest().version);
-                }
-                finally {
-                    ui?.dispose();
-                    if (input.isTTY && input.isRaw !== originalRaw)
-                        input.setRawMode(originalRaw);
-                    terminal?.destroy();
-                }
+                            ...createOnboardRuntime(args, ctx, {
+                                ui,
+                                signinTimeoutMs: deps.onboardSigninTimeoutMs,
+                                stageSignin: (signal) => {
+                                    if (args.key || ctx.env.CATALYST_CLOUD_TOKEN)
+                                        throw new CliError("Connect your personal key with catalyst login, then run catalyst onboard. Setup will not replace a supplied key with browser sign-in.", "onboard-person-required", 12);
+                                    return stageOnboardLogin({
+                                        ...ctx,
+                                        stdout: ui
+                                            ? (line) => ui.message(line)
+                                            : ctx.stderr,
+                                    }, {
+                                        baseUrl: args.baseUrl,
+                                        signal,
+                                        timeoutMs: deps.onboardSigninTimeoutMs,
+                                        device: {
+                                            isTty: deps.isTty ?? (() => Boolean(process.stdout.isTTY)),
+                                            openBrowser: deps.openBrowser ?? defaultOpenBrowser,
+                                            sleep: deps.sleep,
+                                            waitForApproval: ui
+                                                ? (run) => ui.wait("Waiting for Catalyst approval", run)
+                                                : undefined,
+                                        },
+                                    });
+                                },
+                                login: (stepCtx, signal) => cmdLogin({ ...args, command: "login", flags: {}, json: false }, stepCtx, {
+                                    ...deps,
+                                    signal,
+                                    isTty: () => true,
+                                    waitForApproval: ui
+                                        ? (run) => ui.wait("Waiting for Catalyst approval", run)
+                                        : undefined,
+                                }, true),
+                                ready: async (stepCtx, journal) => {
+                                    const team = selectedOnboardTeam(journal);
+                                    const report = await onboardingReadyReport(stepCtx, {
+                                        teamIds: team ? [team] : undefined,
+                                        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,
+                                        },
+                                    };
+                                },
+                                legacy: deps.legacy,
+                                openBrowser: deps.openBrowser,
+                                sleep: deps.sleep,
+                                skillNames: CUSTOMER_SKILLS,
+                            }),
+                            ...(deps.onboardBootstrap
+                                ? { bootstrap: deps.onboardBootstrap }
+                                : {}),
+                            ...(deps.isTty ? { isTty: deps.isTty } : {}),
+                            ...(deps.signal ? { signal: deps.signal } : {}),
+                        }), readManifest().version);
+                    }
+                    finally {
+                        ui?.dispose();
+                        if (input.isTTY && input.isRaw !== originalRaw)
+                            input.setRawMode(originalRaw);
+                        terminal?.destroy();
+                    }
+                    for (const line of jsonLines)
+                        ctx.stdout(line);
+                    return code;
+                };
+                if (!onboardHeadlessRequested(args, ctx.env))
+                    return await runOnboard(args, ctx, null);
+                return await runOnboardHeadless(args, ctx, {
+                    login: (key, baseUrl, loginCtx) => cmdLogin({ ...args, command: "login", key, baseUrl, flags: {}, json: false }, loginCtx, { ...deps, isTty: () => false }, true),
+                    onboard: (onboardArgs, onboardCtx, tracker) => runOnboard(onboardArgs, onboardCtx, tracker),
+                }, readManifest().version);
             }
             case "notice":
                 return 0;
@@ -424,6 +522,11 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             ctx.stderr(`catalyst: ${err.message}`);
             return 2;
         }
+        if (args.command === "onboard" && args.json) {
+            ctx.stdout(JSON.stringify(onboardErrorJournal(ctx, manifest.version, 10)));
+            ctx.stderr("catalyst: onboarding could not finish. Run catalyst onboard to try again.");
+            return 10;
+        }
         throw err;
     }
 }
@@ -461,6 +564,74 @@ const VERB_HELP_KNOWN = Object.fromEntries([
     "legacy",
     "onboard",
 ].map((v) => [v, true]));
+/** CTC-4625: `catalyst setup`, wired to this terminal, @clack/prompts and the keyless login. */
+async function runSetup(argv, ctx, deps) {
+    if (argv[0] === "--help" || argv[0] === "-h") {
+        ctx.stdout(verbHelp("setup"));
+        return 0;
+    }
+    const clack = await import("@clack/prompts");
+    const terminal = openSetupTerminal(process.stdout);
+    const spinner = clackSetupSpinner(clack, Boolean(process.stdin.isTTY));
+    try {
+        return await cmdSetup(argv, ctx, {
+            stdout: process.stdout,
+            stderr: process.stderr,
+            writeJson: (chunk) => process.stdout.write(chunk),
+            interactive: terminal !== null,
+            ...(terminal ? { ask: clackSetupAsk(clack, terminal) } : {}),
+            spinner,
+            onboard: async (renderer, flags) => {
+                // This returns through the dispatcher without launching another CLI or frame.
+                const onboardArgs = [
+                    "onboard",
+                    ...(flags.json ? ["--json"] : []),
+                    ...(flags.verbose ? ["--verbose"] : []),
+                    ...(flags.localSync ? ["--local-sync"] : []),
+                    ...(flags.yes || flags.json || !terminal ? ["--yes"] : []),
+                ];
+                let ui;
+                if (!flags.json) {
+                    ui = createClackOnboardUi(clack, setupOnboardStreams(terminal), {
+                        baseUrl: () => savedOnboardBaseUrl(ctx.home),
+                        renderer,
+                        logPath: () => flags.logPath,
+                        verbose: flags.verbose,
+                        signinTimeoutMs: deps.onboardSigninTimeoutMs,
+                        introduced: true,
+                        consentGiven: true,
+                        interactive: terminal !== null && !flags.yes,
+                    });
+                }
+                return main(onboardArgs, ctx, {
+                    ...deps,
+                    setupUi: ui,
+                    setupApproved: true,
+                });
+            },
+            signin: (seconds, r, stop, spin) => runSetupSignin(ctx, r, seconds, {
+                interrupted: stop,
+                spinner: spin,
+                login: async (loginCtx, login) => {
+                    const code = await cmdLogin(parseArgs(["login"]), loginCtx, {
+                        ...deps,
+                        isTty: deps.isTty ?? (() => terminal !== null),
+                        signal: login.signal,
+                        waitForApproval: login.waitForApproval,
+                        presentCode: login.present,
+                        presentBrowser: login.presentBrowser,
+                    });
+                    if (code === 0)
+                        keepInstalledCliPath(ctx, cliPath());
+                    return code;
+                },
+            }),
+        });
+    }
+    finally {
+        terminal?.close();
+    }
+}
 async function cmdLogin(args, ctx, deps, personalOnly = false) {
     const checkCancelled = () => {
         if (deps.signal?.aborted)
@@ -481,6 +652,8 @@ async function cmdLogin(args, ctx, deps, personalOnly = false) {
             sleep: deps.sleep,
             signal: deps.signal,
             waitForApproval: deps.waitForApproval,
+            present: deps.presentCode,
+            presentBrowser: deps.presentBrowser,
         })).accessToken;
     checkCancelled();
     const me = await fetchMe(baseUrl, bearer, ctx.fetch);

package/dist/oauth.js

@@ -126,27 +126,45 @@ export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
         cancelled();
         const auth = await deviceAuthorize(ctx, discovery);
         cancelled();
-        if (round > 1)
-            ctx.stdout(`That code expired. Here is a new one (${round} of ${MAX_DEVICE_CODES}):`);
-        ctx.stdout("");
-        ctx.stdout(`To connect this machine, visit:  ${auth.verification_uri}`);
-        ctx.stdout(`and enter the code:              ${auth.user_code}`);
-        if (auth.verification_uri_complete)
-            ctx.stdout(`Or open this link, which fills the code in: ${auth.verification_uri_complete}`);
-        if (round === 1 ? (deps.isTty ?? (() => false))() : browserOpened) {
-            try {
-                if (!deps.openBrowser)
-                    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.");
+        const opensBrowser = round === 1 ? (deps.isTty ?? (() => false))() : browserOpened;
+        if (deps.present) {
+            deps.present({
+                verificationUri: auth.verification_uri,
+                userCode: auth.user_code,
+                ...(auth.verification_uri_complete
+                    ? { completeUri: auth.verification_uri_complete }
+                    : {}),
+                round,
+                rounds: MAX_DEVICE_CODES,
+            });
+            if (opensBrowser) {
+                browserOpened = await tryOpenBrowser(deps, auth);
+                deps.presentBrowser?.(browserOpened);
             }
-            catch {
-                // a browser that will not open is not a failure; the code and URL still work
-                ctx.stdout("Open the link above in a browser.");
+        }
+        else {
+            if (round > 1)
+                ctx.stdout(`That code expired. Here is a new one (${round} of ${MAX_DEVICE_CODES}):`);
+            ctx.stdout("");
+            ctx.stdout(`To connect this machine, visit:  ${auth.verification_uri}`);
+            ctx.stdout(`and enter the code:              ${auth.user_code}`);
+            if (auth.verification_uri_complete)
+                ctx.stdout(`Or open this link, which fills the code in: ${auth.verification_uri_complete}`);
+            if (opensBrowser) {
+                try {
+                    if (!deps.openBrowser)
+                        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.");
+                }
+                catch {
+                    // a browser that will not open is not a failure; the code and URL still work
+                    ctx.stdout("Open the link above in a browser.");
+                }
             }
+            ctx.stdout("Waiting for you to approve… (Ctrl-C to cancel)");
         }
-        ctx.stdout("Waiting for you to approve… (Ctrl-C to cancel)");
         const poll = () => pollDeviceCode(ctx, discovery, auth, deps.sleep, deps.signal);
         const tokens = deps.waitForApproval
             ? await deps.waitForApproval(poll)
@@ -159,6 +177,18 @@ export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
     // unchanged from before CTC-2136; only the line is new, and its wording is Ryan's.
     throw new CliError(`The sign-in code expired ${MAX_DEVICE_CODES} times. Run the same command again when you are ready to approve.`, "login-expired");
 }
+/** Opens the browser at the code's page; false when it would not open (never a failure). */
+async function tryOpenBrowser(deps, auth) {
+    try {
+        if (!deps.openBrowser)
+            throw new Error("browser-unavailable");
+        await deps.openBrowser(auth.verification_uri_complete ?? auth.verification_uri);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Poll one device code until it yields a token pair or expires. Terminal refusals (`access_denied`,
  * a non-transient error) throw; expiry, by the server's `expired_token` or the code's own
@@ -358,6 +388,38 @@ export async function bearerFor(ctx, cfg, deps = {}) {
     const rotated = await promise;
     return rotated.accessToken;
 }
+/** A long command such as onboarding refreshes a saved OAuth session that has less than
+ * `minValidityMs` left, so it starts with a full access token instead of expiring part way.
+ * Shares bearerFor's single-flight refresh. A key config, no config or a failed refresh is left
+ * alone and returns false: the command's own sign-in check decides what happens next. */
+export async function refreshSessionIfShort(ctx, minValidityMs, deps = {}) {
+    let cfg;
+    try {
+        cfg = loadConfig(ctx.home);
+    }
+    catch {
+        return false;
+    }
+    if (!cfg?.auth || (typeof cfg.key === "string" && cfg.key !== ""))
+        return false;
+    const msToExpiry = Date.parse(cfg.auth.expiresAt) - ctx.now().getTime();
+    if (Number.isFinite(msToExpiry) && msToExpiry > minValidityMs)
+        return false;
+    try {
+        const pending = inFlight.get(ctx.home);
+        if (pending)
+            await pending;
+        else {
+            const promise = refreshAndPersist(ctx, cfg, deps).finally(() => inFlight.delete(ctx.home));
+            inFlight.set(ctx.home, promise);
+            await promise;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function refreshAndPersist(ctx, cfg, deps) {
     const sleep = deps.sleep ?? defaultSleep;
     const discovery = await fetchDiscovery(ctx, cfg.baseUrl);

package/dist/onboard-accounts.js

@@ -1,5 +1,6 @@
 import { loadConfig, normalizeBaseUrl } from "./config.js";
 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";
@@ -99,7 +100,8 @@ export function onboardAccountsAdapter(input = {}) {
     let proof = null;
     let attempted = false;
     const candidate = (slots, now) => slots
-        .filter((row) => row.provider === "claude" &&
+        .filter((row) => (input.slot === undefined || row.accountSlot === input.slot) &&
+        row.provider === "claude" &&
         row.declaredState === "active" &&
         row.ownedByMe &&
         !row.needsCredential &&
@@ -139,7 +141,13 @@ export function onboardAccountsAdapter(input = {}) {
             };
         proof = null;
         if (!live.slots.length)
-            return waiting("account_enrollment_required");
+            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"
@@ -156,9 +164,30 @@ export function onboardAccountsAdapter(input = {}) {
         act: async (ctx, journal, external) => {
             if (attempted)
                 return waiting("account_provider_access_unverified");
-            const live = await inventory(ctx, journal, external);
-            if ("reason" in live)
-                return waiting(live.reason);
+            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");