@catalyst-cloud/cli 0.14.7 → 0.14.8

package/dist/events.js

@@ -3,8 +3,22 @@ import { normalizeBaseUrl, requireConfig } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { authStrategyFor } from "./oauth.js";
 import { eventCacheStatus } from "./event-status.js";
+import { cloudEventHead, queryCloudEvents, unreachableError, unreachableKind } from "./events-cloud.js";
+import { eventMatches, tailCloudEvents, waitForCloudEvent } from "./events-cloud-tail.js";
 const eventsModule = "@catalyst-cloud/sdk/events";
 export const loadEventsSdk = () => import(eventsModule);
+/** Consecutive failed attempts after which `wait-for` reports an outage rather than waiting on. */
+const OUTAGE_ATTEMPTS = 5;
+/** How long the cloud may be unreachable before `tail` says so on stderr. */
+const TAIL_WARN_AFTER_MS = 60_000;
+function processInterrupts(handler) {
+    process.once("SIGINT", handler);
+    process.once("SIGTERM", handler);
+    return () => {
+        process.off("SIGINT", handler);
+        process.off("SIGTERM", handler);
+    };
+}
 export async function createEventSync(ctx, deps = {}) {
     const cfg = requireConfig(ctx);
     const sdk = await (deps.loadSdk ?? loadEventsSdk)();
@@ -25,6 +39,12 @@ export async function cmdEvents(args, ctx, deps = {}) {
         throw new UsageError("events needs a subcommand: tail | wait-for | query | status");
     if (!["tail", "wait-for", "query", "status"].includes(sub))
         throw new UsageError(`unknown events subcommand: ${sub}`);
+    // CTC-4554 — the cloud is the default source; the local event file is the opt-in.
+    if (args.flags["from-cache"] !== true) {
+        if (flagString(args, "directory") !== undefined)
+            throw new UsageError("--directory names the local event cache; add --from-cache to read it");
+        return cmdCloudEvents(sub, args, ctx, deps);
+    }
     const cfg = requireConfig(ctx);
     const sdk = await (deps.loadSdk ?? loadEventsSdk)();
     const directory = flagString(args, "directory") ??
@@ -32,8 +52,8 @@ export async function cmdEvents(args, ctx, deps = {}) {
     if (sub === "status") {
         const status = await eventCacheStatus(ctx, directory, args.flags.probe === true);
         ctx.stdout(args.json
-            ? JSON.stringify(status)
-            : `events: ${status.verdict} at ${directory}${status.reasons.length ? ` (${status.reasons.join("; ")})` : ` (cursor ${status.cursor}, cloud head ${status.head})`}`);
+            ? JSON.stringify({ source: "cache", ...status })
+            : `events: local cache ${status.verdict} at ${directory}${status.reasons.length ? ` (${status.reasons.join("; ")})` : ` (cursor ${status.cursor}, cloud head ${status.head})`}`);
         return status.verdict === "current"
             ? 0
             : status.verdict === "stale"
@@ -42,8 +62,8 @@ export async function cmdEvents(args, ctx, deps = {}) {
                     ? 3
                     : 2;
     }
-    const after = startingCursor(args, sub === "query");
-    const matches = matcher(args);
+    const after = startingCursor(args);
+    const matches = eventMatches(eventFilter(args));
     if (sub === "query") {
         const events = (await sdk.readCachedEvents({ tenantId: cfg.account, directory, after }))
             .filter(matches)
@@ -80,7 +100,7 @@ export async function cmdEvents(args, ctx, deps = {}) {
         if (controller.signal.aborted)
             return sub === "wait-for" ? 1 : 0;
         if (error.code === "ENOENT")
-            throw new CliError(`event cache is absent at ${directory} — start it with: catalyst replica start --detach`, "events-absent", 3);
+            throw new CliError(`event cache is absent at ${directory}: it is written only where local sync runs. Start the local writer with: catalyst replica start --detach, or drop --from-cache to read from the cloud`, "events-absent", 3);
         throw error;
     }
     finally {
@@ -89,33 +109,159 @@ export async function cmdEvents(args, ctx, deps = {}) {
         deps.signal?.removeEventListener("abort", abort);
     }
 }
-function startingCursor(args, history) {
-    const requested = flagString(args, "after");
-    if (requested !== undefined) {
-        const parsed = Number(requested);
-        if (!Number.isSafeInteger(parsed) || parsed < 0)
-            throw new UsageError("--after must be a non-negative event sequence");
-        return parsed;
-    }
-    if (history)
+function startingCursor(args, name = "after") {
+    const requested = flagString(args, name);
+    if (requested === undefined)
         return undefined;
-    return undefined;
+    const parsed = Number(requested);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        throw new UsageError(`--${name} must be a non-negative event sequence`);
+    return parsed;
 }
-function matcher(args) {
+function eventFilter(args) {
     const type = flagString(args, "type");
     const ticket = flagString(args, "ticket")?.toUpperCase();
-    return (event) => (!type || event.type === type) &&
-        (!ticket || payloadReferences(event.payload, ticket));
+    return { ...(type ? { type } : {}), ...(ticket ? { ticket } : {}) };
+}
+/** A sink over `ctx.stdout` for contexts without a stream (tests): one call per line. */
+function lineSink(ctx) {
+    return {
+        write(chunk, callback) {
+            try {
+                ctx.stdout(chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk);
+                callback();
+            }
+            catch (error) {
+                callback(error);
+            }
+            return true;
+        },
+        on: () => undefined,
+        off: () => undefined,
+    };
 }
-function payloadReferences(value, ticket) {
-    if (typeof value === "string")
-        return value.toUpperCase() === ticket;
-    if (Array.isArray(value))
-        return value.some((item) => payloadReferences(item, ticket));
-    if (!value || typeof value !== "object")
-        return false;
-    return Object.entries(value).some(([key, item]) => ["ticket", "identifier", "workItemKey", "issueIdentifier"].includes(key) &&
-        typeof item === "string"
-        ? item.toUpperCase() === ticket
-        : payloadReferences(item, ticket));
+const QUERY_MAX_LIMIT = 200;
+const LOCAL_SYNC_HINT = "several agents on one machine are cheaper sharing one local cache: opt in to local sync (catalyst onboard --local-sync), then read it with --from-cache";
+/** CTC-4554 — `events tail | wait-for | query | status` against the cloud, with no local file. */
+async function cmdCloudEvents(sub, args, ctx, deps) {
+    requireConfig(ctx);
+    const filter = eventFilter(args);
+    if (sub === "status") {
+        let head;
+        try {
+            head = await cloudEventHead(ctx);
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            const failure = unreachableError(error);
+            if (args.json)
+                ctx.stdout(JSON.stringify({ source: "cloud", reachable: false, error: unreachableKind(error) }));
+            else
+                ctx.stderr(`catalyst: ${failure.message}`);
+            return failure.exitCode;
+        }
+        // A cloud stream has no local cursor to fall behind. Filtered reads come from the event index,
+        // which trails the head while it fills; that lag is measured, not assumed.
+        let indexedToSeq = null;
+        try {
+            indexedToSeq = (await queryCloudEvents(ctx, { limit: 1, order: "desc" })).coverage.indexedToSeq;
+        }
+        catch {
+            indexedToSeq = null;
+        }
+        const indexLag = indexedToSeq === null ? null : Math.max(0, head - indexedToSeq);
+        const status = { source: "cloud", reachable: true, head, behind: null, indexedToSeq, indexLag, note: LOCAL_SYNC_HINT };
+        ctx.stdout(args.json
+            ? JSON.stringify(status)
+            : `events: cloud stream at head ${head}; ${indexLag === null ? "the filtered index could not be read" : `filtered reads (--ticket, --type) trail it by ${indexLag}`} (every read goes to the cloud; ${LOCAL_SYNC_HINT})`);
+        return 0;
+    }
+    if (sub === "query") {
+        const limit = flagInt(args, "limit", 50);
+        if (!Number.isInteger(limit) || limit < 1 || limit > QUERY_MAX_LIMIT)
+            throw new UsageError(`--limit must be between 1 and ${QUERY_MAX_LIMIT} for a cloud query`);
+        const order = flagString(args, "order") ?? "desc";
+        if (order !== "asc" && order !== "desc")
+            throw new UsageError("--order must be asc or desc");
+        const page = await queryCloudEvents(ctx, {
+            ...filter,
+            limit,
+            order,
+            afterSeq: startingCursor(args, "after"),
+            beforeSeq: startingCursor(args, "before"),
+        });
+        for (const event of page.events)
+            ctx.stdout(JSON.stringify(event));
+        if (page.next)
+            ctx.stderr(`more: re-run with --${page.next.param === "beforeSeq" ? "before" : "after"} ${page.next.value}`);
+        if (page.events.length === 0) {
+            const { indexedFromSeq: from, indexedToSeq: to } = page.coverage;
+            ctx.stderr(from === null || to === null
+                ? "no match; the cloud index holds no events yet"
+                : `no match; the cloud index holds sequences ${from} to ${to}, so an earlier event may exist unindexed`);
+        }
+        return 0;
+    }
+    const out = deps.out ?? ctx.stdoutStream ?? lineSink(ctx);
+    const controller = new AbortController();
+    const abort = () => controller.abort(deps.signal?.reason);
+    if (deps.signal?.aborted)
+        abort();
+    else
+        deps.signal?.addEventListener("abort", abort, { once: true });
+    let interrupted = false;
+    const removeInterrupt = (deps.onInterrupt ?? processInterrupts)(() => {
+        interrupted = true;
+        controller.abort(new Error("interrupted"));
+    });
+    let outage;
+    let warned = false;
+    const seconds = (sinceMs) => Math.round((ctx.now().getTime() - sinceMs) / 1_000);
+    const cloud = {
+        ...deps.cloud,
+        onTrouble: (state) => {
+            deps.cloud?.onTrouble?.(state);
+            if (sub === "wait-for" && state.failures >= OUTAGE_ATTEMPTS && !outage) {
+                outage = state;
+                controller.abort(new Error("cloud unreachable"));
+            }
+            if (sub === "tail" && !warned && ctx.now().getTime() - state.sinceMs > TAIL_WARN_AFTER_MS) {
+                warned = true;
+                ctx.stderr(`events: the cloud has been unreachable for ${seconds(state.sinceMs)} s (${state.failures} attempts); still retrying`);
+            }
+        },
+        onHealthy: () => {
+            deps.cloud?.onHealthy?.();
+            if (warned)
+                ctx.stderr("events: the cloud is reachable again");
+            warned = false;
+        },
+    };
+    try {
+        const after = startingCursor(args);
+        if (sub === "wait-for") {
+            const timeout = flagInt(args, "timeout", 300);
+            const result = await waitForCloudEvent(ctx, { after, filter, timeoutMs: timeout * 1_000, out, signal: controller.signal }, cloud);
+            if (interrupted)
+                return 130;
+            if (outage) {
+                ctx.stderr(`events: the cloud event service was unreachable for ${outage.failures} attempts over ${seconds(outage.sinceMs)} s; this is an outage, not a timeout`);
+                return 4;
+            }
+            if (result.outcome === "matched" || result.outcome === "closed")
+                return 0;
+            if (result.outcome === "timeout")
+                ctx.stderr(`events: no matching event within ${timeout} s`);
+            return 1;
+        }
+        const result = await tailCloudEvents(ctx, { after, filter, out, signal: controller.signal }, cloud);
+        if (result.outcome !== "closed" && result.cursor !== undefined)
+            ctx.stderr(`events: stopped at sequence ${result.cursor}; resume with --after ${result.cursor}`);
+        return interrupted ? 130 : 0;
+    }
+    finally {
+        removeInterrupt();
+        deps.signal?.removeEventListener("abort", abort);
+    }
 }

package/dist/oauth.js

@@ -135,12 +135,15 @@ export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
             ctx.stdout(`Or open this link, which fills the code in: ${auth.verification_uri_complete}`);
         if (round === 1 ? (deps.isTty ?? (() => false))() : browserOpened) {
             try {
-                (deps.openBrowser ?? (() => { }))(auth.verification_uri_complete ?? auth.verification_uri);
+                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)");

package/dist/onboard-github.js

@@ -1,3 +1,4 @@
+import { finishOnTheWeb } from "./consent-browser.js";
 import { loadConfig, normalizeBaseUrl } from "./config.js";
 import { pollConsent } from "./onboard-consent.js";
 const STATUS = "/api/v1/me/connections/github/workspace";
@@ -292,11 +293,15 @@ export function githubInstallationAdapter(options) {
                 };
             ctx.stderr("Approve the GitHub App installation in your browser. Your personal GitHub connection is checked separately.");
             // The signed URL is transient credential material: only the browser receives it.
+            let browserUnavailable = false;
             try {
-                options.openBrowser(url);
+                await options.openBrowser(url, signal);
             }
             catch {
-                return waiting("github_installation_browser_unavailable");
+                if (signal?.aborted)
+                    return waiting("interrupted");
+                browserUnavailable = true;
+                ctx.stderr(finishOnTheWeb(current.baseUrl, "connections", "install the GitHub App"));
             }
             let latest = waiting("github_installation_status_unavailable");
             const run = () => pollConsent({
@@ -311,6 +316,8 @@ export function githubInstallationAdapter(options) {
                             outcome: "waiting",
                             reason: "cloud_capability_unavailable",
                         };
+                    if (latest.reason === "github_installation_login_refresh_required")
+                        return { outcome: "waiting", reason: latest.reason };
                     if (latest.state === "done")
                         return { outcome: "connected" };
                     if (latest.state === "refused" || latest.state === "failed")
@@ -323,7 +330,11 @@ export function githubInstallationAdapter(options) {
             const result = options.wait
                 ? await options.wait("Waiting for GitHub App approval", run)
                 : await run();
-            return result.state === "done" ? latest : result;
+            if (result.state === "done")
+                return latest;
+            return browserUnavailable && result.reason === "consent_timeout"
+                ? waiting("github_installation_browser_unavailable")
+                : result;
         },
     };
 }

package/dist/onboard-next.js

@@ -0,0 +1,139 @@
+import { loadConfig, normalizeBaseUrl } from "./config.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.",
+    account_validation_admin_required: "An administrator must check the workspace's coding-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.",
+    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.",
+    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.",
+    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.",
+    workspace_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
+    workspace_consent_refused: "The server did not accept this login for Linear workspace setup. Sign in again or ask your workspace administrator.",
+    github_installation_status_unavailable: "Your GitHub App installation could not be checked. Run catalyst onboard to try again.",
+    github_installation_status_shape: "The server returned a GitHub installation result that could not be verified.",
+    github_installation_consent_handoff: "The GitHub installation approval link could not be verified. Run catalyst onboard to try again.",
+    github_installation_consent_refused: "The server did not accept this login for GitHub App setup. Sign in again or ask your workspace administrator.",
+    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.",
+    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.",
+    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.",
+    linear_workspace_unverified: "Your Linear workspace connection could not be verified.",
+    team_inventory_empty: "No existing Linear teams could be verified.",
+    team_inventory_shape: "The cloud returned a team list that could not be verified.",
+    team_read_unavailable: "Your existing Linear teams could not be read. Run catalyst onboard to try again.",
+    team_read_identity_unverified: "Your login changed while setup was reading this workspace. Resume with the original workspace and person.",
+    project_identity_unverified: "Your login changed while setup was checking this project. Resume with the original workspace and person.",
+    project_options_unavailable: "Available teams and repositories could not be checked. Run catalyst onboard to try again.",
+    project_provider_inventory_unavailable: "Linear or GitHub access could not be verified. Check this workspace's connections, then resume.",
+    project_options_unverified: "The server returned a team or repository list that could not be verified.",
+    project_registration_visibility_pending: "Your project exists, but its repository binding is not visible yet. Run catalyst onboard to check again.",
+    project_binding_conflict: "This team or repository is already bound to a project. Ask your workspace administrator to check its binding, then resume.",
+    project_login_refresh_required: "Renew your login with catalyst onboard, then review the plan before creating this project.",
+    project_create_unverified: "Project creation could not be confirmed. Run catalyst onboard to check for the project before trying again.",
+    team_read_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
+    team_choice_required: "Choose an existing team with catalyst onboard --team <team ID or key>.",
+    team_selection_unverified: "Your selected Linear team could not be verified. Run catalyst onboard --team <team ID or key> to choose again.",
+    repository_choice_required: "Choose repositories with catalyst onboard --repo <owner/name>. Repeat --repo to choose more than one.",
+    repository_inventory_empty: "No accessible repositories are registered to this Linear team yet.",
+    repository_read_unavailable: "Your repository list could not be read. Run catalyst onboard to try again.",
+    repository_inventory_shape: "The cloud returned a repository list that could not be verified.",
+    repository_contract_unavailable: "Current repository IDs could not be checked. Run catalyst onboard to try again.",
+    repository_contract_unverified: "The cloud returned repository IDs that could not be verified for this workspace.",
+    repository_id_unverified: "A repository's current ID could not be verified. Keep your selection and try again.",
+    repository_binding_ambiguous: "A repository's Linear team binding is ambiguous. Your administrator needs to check it.",
+    repository_identity_unverified: "Sign in to the original workspace to choose repositories.",
+    settings_review_timeout: "The settings review timed out. Run catalyst onboard to resume.",
+    settings_checkout_unverified: "Setup could not verify the repository's local checkout or settings file. Settings are optional for a first ticket. To finish them later, run catalyst onboard from the repository's checkout.",
+    settings_draft_storage_unavailable: "A private settings draft could not be kept. Run catalyst onboard to retry.",
+    settings_draft_storage_timeout: "Keeping your settings draft took too long. Run catalyst onboard to retry.",
+    settings_approval_unverified: "Settings still need review and approval; kept drafts do not count. Settings are optional for a first ticket. To finish them later, run catalyst onboard from the repository's checkout.",
+    repository_selection_unverified: "Your selected repositories could not be verified. Run catalyst onboard --repo <owner/name> to choose again.",
+    workflow_identity_unverified: "Setup could not confirm the signed-in workspace, person or role for this team. Run catalyst onboard again as a workspace owner or administrator.",
+    workflow_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard.",
+    workflow_mapping_changed: "The team's workflow changed while setup checked it. Run catalyst onboard again.",
+    workflow_unavailable: "Setup could not read the team's workflow. Run catalyst onboard again to retry.",
+    capacity_admission_unverified: "No runner is allowed to take work for this workspace yet. Enroll a self-hosted runner host, or ask Catalyst to enable cloud runners for it. Then run catalyst onboard.",
+    capacity_currently_full: "Every runner slot for this repository is in use. Run catalyst onboard again after current work finishes.",
+    capacity_unavailable: "Setup could not read runner capacity. Run catalyst onboard again to retry.",
+    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.",
+};
+/** The saved login's web address, or nothing when the config is missing, unreadable or not http(s). */
+export function savedOnboardBaseUrl(home) {
+    try {
+        const cfg = loadConfig(home);
+        const url = cfg ? webUrl(cfg.baseUrl) : undefined;
+        return url ? normalizeBaseUrl(url) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Receipt and config text reaches the terminal only after URL parsing has escaped it.
+function webUrl(value) {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const url = new URL(value);
+        return ["https:", "http:"].includes(url.protocol) &&
+            !url.username &&
+            !url.password
+            ? url.href
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The selected team's key from the receipt, only when it is plain enough to print in a command. */
+export function onboardTeamKey(journal) {
+    const step = journal?.steps.find((row) => row.id === "linear.team");
+    const key = step?.state === "done" ? step.evidence?.teamKey : undefined;
+    return typeof key === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(key)
+        ? key
+        : 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 ?? "";
+    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 === "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.`;
+    }
+    if (reason === "cloud_capability_unavailable") {
+        // The capability guard records the web page in evidence.path only when it printed it.
+        const page = webUrl(step.evidence?.path);
+        return page
+            ? `This setup step is not available on this server yet. Continue in the web app at ${page}, then run catalyst onboard.`
+            : "This setup step is not available on this server yet. Run catalyst onboard after the server update.";
+    }
+    if (reason === "prerequisite_not_ready" && context.waitsFor)
+        return `Runs after "${context.waitsFor}".`;
+    return REASONS[reason] ?? reason.replaceAll("_", " ");
+}

package/dist/onboard-personal.js

@@ -1,3 +1,4 @@
+import { finishOnTheWeb } from "./consent-browser.js";
 import { loadConfig, normalizeBaseUrl, } from "./config.js";
 import { pollConsent } from "./onboard-consent.js";
 const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
@@ -198,11 +199,15 @@ export function personalConsentAdapter(options) {
             const name = options.provider === "linear" ? "Linear" : "GitHub";
             ctx.stderr(`Approve your personal ${name} connection in the browser.`);
             // Signed continuation credentials belong only to the browser, never transcript or journal.
+            let browserUnavailable = false;
             try {
-                options.openBrowser(url);
+                await options.openBrowser(url, signal);
             }
             catch {
-                return waiting("personal_browser_unavailable");
+                if (signal?.aborted)
+                    return waiting("interrupted");
+                browserUnavailable = true;
+                ctx.stderr(finishOnTheWeb(cfg.baseUrl, "connected-accounts", `connect your ${name} account`));
             }
             let latest = waiting("personal_status_unavailable");
             const run = () => pollConsent({
@@ -213,6 +218,8 @@ export function personalConsentAdapter(options) {
                     latest = await inspect(ctx, journal, pollSignal);
                     if (latest.reason === "cloud_capability_unavailable")
                         return { outcome: "waiting", reason: latest.reason };
+                    if (latest.reason === "personal_login_refresh_required")
+                        return { outcome: "waiting", reason: latest.reason };
                     if (latest.state === "done")
                         return { outcome: "connected" };
                     if (latest.state === "refused" || latest.state === "failed")
@@ -225,7 +232,11 @@ export function personalConsentAdapter(options) {
             const result = options.wait
                 ? await options.wait(`Waiting for your ${name} approval`, run)
                 : await run();
-            return result.state === "done" ? latest : result;
+            if (result.state === "done")
+                return latest;
+            return browserUnavailable && result.reason === "consent_timeout"
+                ? waiting("personal_browser_unavailable")
+                : result;
         },
     };
 }

package/dist/onboard-repositories.js

@@ -1,3 +1,4 @@
+import { isRepositoryId } from "./repository-id.js";
 import { loadConfig, normalizeBaseUrl, readManifest, } from "./config.js";
 import { contractVersionInRange } from "./contract.js";
 import { readExistingOnboardJson, selectedOnboardTeam, } from "./onboard-existing.js";
@@ -16,8 +17,7 @@ const valid = (value) => {
     return (!!row &&
         typeof row.teamId === "string" &&
         id.test(row.teamId) &&
-        typeof row.repoId === "string" &&
-        id.test(row.repoId) &&
+        isRepositoryId(row.repoId) &&
         typeof row.owner === "string" &&
         part.test(row.owner) &&
         typeof row.name === "string" &&
@@ -154,8 +154,7 @@ export async function readOnboardRepositoryInventory(ctx, journal, signal) {
             !part.test(row.owner) ||
             typeof row.name !== "string" ||
             !part.test(row.name) ||
-            typeof row.repoId !== "string" ||
-            !id.test(row.repoId))
+            !isRepositoryId(row.repoId))
             return { reason: "repository_contract_unverified" };
         const name = key({ owner: row.owner, name: row.name });
         if (idNames.has(row.repoId) && idNames.get(row.repoId) !== name)

package/dist/onboard-runtime.js

@@ -1,7 +1,7 @@
 import { existsSync, realpathSync } from "node:fs";
 import { userInfo } from "node:os";
 import { join } from "node:path";
-import { openBrowser } from "./browser.js";
+import { openConsentBrowser } from "./consent-browser.js";
 import { defaultSkillsDirFor, loadConfig, normalizeBaseUrl, readManifest, } from "./config.js";
 import { CliError } from "./errors.js";
 import { cmdLegacy, findLegacy } from "./legacy.js";
@@ -130,7 +130,7 @@ export function createOnboardRuntime(args, ctx, hooks) {
     };
     const personalAdapter = (provider) => personalConsentAdapter({
         provider,
-        openBrowser: hooks.openBrowser ?? openBrowser,
+        openBrowser: hooks.openBrowser ?? openConsentBrowser,
         sleep: hooks.sleep,
         wait: hooks.ui
             ? (message, run) => hooks.ui.wait(message, run)
@@ -206,14 +206,14 @@ export function createOnboardRuntime(args, ctx, hooks) {
         ...linear,
         "linear.workspace": linearWorkspaceAdapter({
             fallback: linear["linear.workspace"],
-            openBrowser: hooks.openBrowser ?? openBrowser,
+            openBrowser: hooks.openBrowser ?? openConsentBrowser,
             wait: hooks.ui
                 ? (message, work) => hooks.ui.wait(message, work)
                 : undefined,
             sleep: hooks.sleep,
         }),
         "github.install": githubInstallationAdapter({
-            openBrowser: hooks.openBrowser ?? openBrowser,
+            openBrowser: hooks.openBrowser ?? openConsentBrowser,
             wait: hooks.ui
                 ? (message, work) => hooks.ui.wait(message, work)
                 : undefined,