@catalyst-cloud/cli 0.14.3 → 0.14.4

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.14.4
+
+- Personal Linear and GitHub approval links stay out of logs and receipts. Setup validates the signed browser destination and its expiry before opening it.
+- Personal connection checks and browser waits stop on interruption or a deadline. Setup rechecks the current person and workspace, and keeps existing approval when its status is available.
+
 ## 0.14.3
 
 - Setup can open the workspace's Linear approval from a personal login and wait for a fresh connection check before continuing. A saved credential alone does not count as connected.

package/dist/onboard-personal.js

@@ -0,0 +1,229 @@
+import { loadConfig, normalizeBaseUrl, } from "./config.js";
+import { pollConsent } from "./onboard-consent.js";
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : null;
+const waiting = (reason) => ({
+    state: "waiting",
+    reason,
+});
+const same = (a, b) => !!b?.user &&
+    !!a.user &&
+    a.account === b.account &&
+    a.user.id === b.user.id &&
+    normalizeBaseUrl(a.baseUrl) === normalizeBaseUrl(b.baseUrl);
+/** Headers and body share an owned deadline; abandoned reads cannot rotate local credentials. */
+async function read(ctx, journal, path, timeoutMs, external) {
+    const cfg = loadConfig(ctx.home);
+    if (!cfg?.user)
+        return { reason: "personal_login_required" };
+    if (((journal.account ?? journal.tenant) &&
+        (journal.account ?? journal.tenant) !== cfg.account) ||
+        (journal.membershipId && journal.membershipId !== cfg.user.id) ||
+        (journal.baseUrl &&
+            normalizeBaseUrl(journal.baseUrl) !== normalizeBaseUrl(cfg.baseUrl)))
+        return { reason: "personal_identity_refused" };
+    const expiry = cfg.auth
+        ? Date.parse(cfg.auth.expiresAt) - ctx.now().getTime()
+        : 0;
+    const bearer = cfg.key ||
+        (cfg.auth && Number.isFinite(expiry) && expiry > 30_000
+            ? cfg.auth.accessToken
+            : undefined);
+    if (!bearer)
+        return { reason: "personal_login_refresh_required" };
+    const owned = new AbortController();
+    const timer = setTimeout(() => owned.abort(), timeoutMs);
+    const signal = external
+        ? AbortSignal.any([external, owned.signal])
+        : owned.signal;
+    let remove = () => { };
+    try {
+        return await new Promise((resolve) => {
+            const stopped = () => resolve({
+                reason: external?.aborted
+                    ? "interrupted"
+                    : "personal_status_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 { reason: "interrupted" };
+                const response = await ctx.fetch(`${normalizeBaseUrl(cfg.baseUrl)}${path}`, {
+                    method: "GET",
+                    redirect: "error",
+                    headers: {
+                        authorization: `Bearer ${bearer}`,
+                        accept: "application/json",
+                    },
+                    signal,
+                });
+                if (response.status !== 200)
+                    return { status: response.status };
+                const body = await response.json();
+                if (!same(cfg, loadConfig(ctx.home)))
+                    return { reason: "personal_identity_refused" };
+                return { status: 200, body };
+            })
+                .then((value) => (signal.aborted ? stopped() : resolve(value)), () => signal.aborted
+                ? stopped()
+                : resolve({ reason: "personal_status_unavailable" }));
+        });
+    }
+    finally {
+        clearTimeout(timer);
+        remove();
+    }
+}
+function failure(value, start = false) {
+    if ("reason" in value)
+        return ["personal_login_required", "personal_identity_refused"].includes(value.reason)
+            ? { state: "refused", reason: value.reason }
+            : waiting(value.reason);
+    if (value.status === 401 || value.status === 403)
+        return { state: "refused", reason: "personal_consent_refused" };
+    if (value.status === 503)
+        return waiting("personal_status_unavailable");
+    if (value.status === 404)
+        return waiting("cloud_capability_unavailable");
+    return value.status === 200
+        ? null
+        : {
+            state: "failed",
+            reason: start
+                ? "personal_consent_start_failed"
+                : "personal_status_failed",
+        };
+}
+function handoff(body, provider, cfg, now) {
+    const row = object(body);
+    if (!row ||
+        typeof row.authorizationUrl !== "string" ||
+        row.authorizationUrl.length > 8192 ||
+        /[\u0000-\u0020\u007f]/.test(row.authorizationUrl) ||
+        typeof row.expiresAt !== "number" ||
+        !Number.isFinite(row.expiresAt) ||
+        row.expiresAt <= now ||
+        row.expiresAt > now + 630_000)
+        return null;
+    try {
+        const url = new URL(row.authorizationUrl);
+        const keys = [...url.searchParams.keys()];
+        const token = url.searchParams.get("handoff");
+        if (url.protocol !== "https:" ||
+            url.origin !== new URL(normalizeBaseUrl(cfg.baseUrl)).origin ||
+            url.username ||
+            url.password ||
+            url.pathname !== `/connect/${provider}/personal/start` ||
+            url.hash ||
+            keys.length !== 1 ||
+            keys[0] !== "handoff" ||
+            !token ||
+            token.length > 4096 ||
+            /[\s\u0000-\u001f\u007f]/.test(token))
+            return null;
+        return url.toString();
+    }
+    catch {
+        return null;
+    }
+}
+/** The supported personal status reports server-resolved grant availability. A warm grant is
+ * not a new provider viewer probe, repository authorization, or workspace installation verdict. */
+export function personalConsentAdapter(options) {
+    const timeout = options.requestTimeoutMs ?? 30_000;
+    const consentTimeout = options.consentTimeoutMs ?? 600_000;
+    if (!["linear", "github"].includes(options.provider) ||
+        !Number.isSafeInteger(timeout) ||
+        timeout < 1 ||
+        timeout > 30_000 ||
+        !Number.isSafeInteger(consentTimeout) ||
+        consentTimeout < 1 ||
+        consentTimeout > 600_000)
+        throw new Error("personal_timeout_invalid");
+    const statusPath = `/api/v1/me/connections/${options.provider}/personal`;
+    const inspect = async (ctx, journal, signal) => {
+        const response = await read(ctx, journal, statusPath, timeout, signal);
+        const failed = failure(response);
+        if (failed)
+            return failed;
+        const body = object("body" in response ? response.body : undefined);
+        if (!body ||
+            typeof body.connected !== "boolean" ||
+            (body.reason !== undefined &&
+                (body.connected || body.reason !== "lapsed")))
+            return { state: "failed", reason: "personal_status_shape" };
+        return body.connected
+            ? {
+                state: "done",
+                evidence: {
+                    provider: options.provider,
+                    checkedAt: ctx.now().getTime(),
+                },
+            }
+            : { state: "pending" };
+    };
+    return {
+        check: inspect,
+        act: async (ctx, journal, signal) => {
+            if (signal?.aborted)
+                return waiting("interrupted");
+            const cfg = loadConfig(ctx.home);
+            if (!cfg?.user)
+                return { state: "refused", reason: "personal_login_required" };
+            const before = await inspect(ctx, journal, signal);
+            if (before.state !== "pending")
+                return before;
+            const start = await read(ctx, journal, `/connect/${options.provider}/personal/start`, timeout, signal);
+            if ("status" in start &&
+                start.status === 409 &&
+                options.provider === "linear")
+                return waiting("linear_workspace_required");
+            const failed = failure(start, true);
+            if (failed)
+                return failed;
+            const url = handoff("body" in start ? start.body : undefined, options.provider, cfg, ctx.now().getTime());
+            if (!url)
+                return { state: "refused", reason: "personal_consent_handoff" };
+            if (signal?.aborted)
+                return waiting("interrupted");
+            if (!same(cfg, loadConfig(ctx.home)))
+                return { state: "refused", reason: "personal_identity_refused" };
+            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.
+            try {
+                options.openBrowser(url);
+            }
+            catch {
+                return waiting("personal_browser_unavailable");
+            }
+            let latest = waiting("personal_status_unavailable");
+            const run = () => pollConsent({
+                timeoutMs: consentTimeout,
+                signal,
+                sleep: options.sleep,
+                readStatus: async (pollSignal) => {
+                    latest = await inspect(ctx, journal, pollSignal);
+                    if (latest.state === "done")
+                        return { outcome: "connected" };
+                    if (latest.state === "refused" || latest.state === "failed")
+                        return { outcome: latest.state, reason: latest.reason };
+                    return {
+                        outcome: latest.state === "pending" ? "absent" : "unavailable",
+                    };
+                },
+            });
+            const result = options.wait
+                ? await options.wait(`Waiting for your ${name} approval`, run)
+                : await run();
+            return result.state === "done" ? latest : result;
+        },
+    };
+}

package/dist/onboard-runtime.js

@@ -2,17 +2,20 @@ import { existsSync, realpathSync } from "node:fs";
 import { userInfo } from "node:os";
 import { join } from "node:path";
 import { openBrowser } from "./browser.js";
-import { defaultSkillsDirFor, loadConfig, normalizeBaseUrl, readManifest } from "./config.js";
+import { defaultSkillsDirFor, loadConfig, normalizeBaseUrl, readManifest, } from "./config.js";
 import { CliError } from "./errors.js";
 import { cmdLegacy, findLegacy } from "./legacy.js";
 import { bearerFor } from "./oauth.js";
-import { pollConsent } from "./onboard-consent.js";
+import { personalConsentAdapter } from "./onboard-personal.js";
 import { boundedOnboardSignin } from "./onboard-signin.js";
 import { existingLinearAdapters } from "./onboard-existing.js";
 import { linearWorkspaceAdapter } from "./onboard-workspace.js";
 import { existingRepositoryAdapter } from "./onboard-repositories.js";
 import { fetchMe } from "./transport.js";
-const waiting = (reason) => ({ state: "waiting", reason });
+const waiting = (reason) => ({
+    state: "waiting",
+    reason,
+});
 function sameHome(a, b) {
     try {
         return realpathSync(a) === realpathSync(b);
@@ -28,129 +31,152 @@ export function createOnboardRuntime(args, ctx, hooks) {
         if (!cfg)
             return null;
         const requested = args.baseUrl ?? stepCtx.env.CATALYST_CLOUD_BASE_URL;
-        if (requested && normalizeBaseUrl(requested) !== normalizeBaseUrl(cfg.baseUrl))
+        if (requested &&
+            normalizeBaseUrl(requested) !== normalizeBaseUrl(cfg.baseUrl))
             throw new CliError("the saved login uses another cloud; resume against that cloud", "onboard-base-url-mismatch", 12);
         if (!cfg.user)
             throw new CliError("sign in as yourself to set up Catalyst", "onboard-person-required", 12);
-        if (journal && (((journal.account ?? journal.tenant) && (journal.account ?? journal.tenant) !== cfg.account) ||
-            (journal.membershipId && journal.membershipId !== cfg.user.id) ||
-            (journal.baseUrl && normalizeBaseUrl(journal.baseUrl) !== normalizeBaseUrl(cfg.baseUrl))))
+        if (journal &&
+            (((journal.account ?? journal.tenant) &&
+                (journal.account ?? journal.tenant) !== cfg.account) ||
+                (journal.membershipId && journal.membershipId !== cfg.user.id) ||
+                (journal.baseUrl &&
+                    normalizeBaseUrl(journal.baseUrl) !== normalizeBaseUrl(cfg.baseUrl))))
             throw new CliError("the saved setup belongs to another workspace or member", "onboard-identity-mismatch", 12);
         const me = await fetchMe(cfg.baseUrl, await bearerFor(stepCtx, cfg), stepCtx.fetch);
         if (!me.user || me.account !== cfg.account || me.user.id !== cfg.user.id)
             throw new CliError("the saved login and live member do not match", "onboard-identity-mismatch", 12);
         // /me names a person within the account, not an independently exposed membership-row ID.
-        return { account: me.account, membershipId: me.user.id, baseUrl: normalizeBaseUrl(cfg.baseUrl), role: me.user.role };
+        return {
+            account: me.account,
+            membershipId: me.user.id,
+            baseUrl: normalizeBaseUrl(cfg.baseUrl),
+            role: me.user.role,
+        };
     };
     const legacyCheck = async (stepCtx) => {
-        const found = findLegacy(stepCtx.home, hooks.legacy?.platform ?? process.platform).filter(item => !item.data).length;
+        const found = findLegacy(stepCtx.home, hooks.legacy?.platform ?? process.platform).filter((item) => !item.data).length;
         if (!sameHome(stepCtx.home, (hooks.realHome ?? (() => userInfo().homedir))()))
-            return { state: "skipped", reason: "fake_home_report_only", evidence: { found, remaining: found } };
-        return { state: found ? "pending" : "done", evidence: { found, remaining: found } };
+            return {
+                state: "skipped",
+                reason: "fake_home_report_only",
+                evidence: { found, remaining: found },
+            };
+        return {
+            state: found ? "pending" : "done",
+            evidence: { found, remaining: found },
+        };
     };
-    const unsupported = { check: async () => waiting("cloud_capability_unavailable"), act: async () => waiting("cloud_capability_unavailable") };
-    const personalStatus = async (provider, stepCtx, signal) => {
-        const cfg = loadConfig(stepCtx.home);
-        if (!cfg || !cfg.user)
-            return { outcome: "refused", reason: "personal_login_required" };
-        const response = await stepCtx.fetch(`${normalizeBaseUrl(cfg.baseUrl)}/api/v1/me/connections/${provider}/personal`, {
-            headers: { authorization: `Bearer ${await bearerFor(stepCtx, cfg)}`, accept: "application/json" },
-            signal: signal ?? AbortSignal.timeout(30_000),
-        });
-        if (response.status === 401 || response.status === 403)
-            return { outcome: "refused", reason: "personal_consent_refused" };
-        if (response.status === 503)
-            return { outcome: "unavailable" };
-        if (!response.ok)
-            return { outcome: "failed", reason: "personal_status_failed" };
-        const body = await response.json();
-        if (!body || typeof body !== "object" || !("connected" in body))
-            return { outcome: "failed", reason: "personal_status_shape" };
-        if (body.connected === true)
-            return { outcome: "connected" };
-        if (body.connected !== false)
-            return { outcome: "failed", reason: "personal_status_shape" };
-        return { outcome: "reason" in body && body.reason === "lapsed" ? "lapsed" : "absent" };
+    const unsupported = {
+        check: async () => waiting("cloud_capability_unavailable"),
+        act: async () => waiting("cloud_capability_unavailable"),
     };
-    const personalAdapter = (provider) => ({
-        check: async (stepCtx) => {
-            const result = await personalStatus(provider, stepCtx);
-            if (result.outcome === "connected")
-                return { state: "done" };
-            if (result.outcome === "refused" || result.outcome === "failed")
-                return { state: result.outcome, reason: result.reason };
-            return result.outcome === "unavailable" ? waiting("personal_status_unavailable") : { state: "pending" };
-        }, act: async (stepCtx, _journal, signal) => {
-            const cfg = loadConfig(stepCtx.home);
-            if (!cfg || !cfg.user)
-                return { state: "refused", reason: "personal_login_required" };
-            const response = await stepCtx.fetch(`${normalizeBaseUrl(cfg.baseUrl)}/connect/${provider}/personal/start`, {
-                headers: { authorization: `Bearer ${await bearerFor(stepCtx, cfg)}`, accept: "application/json" }, signal: AbortSignal.timeout(30_000),
-            });
-            if (response.status === 409)
-                return waiting(provider === "linear" ? "linear_workspace_required" : "github_workspace_required");
-            if (response.status === 401 || response.status === 403)
-                return { state: "refused", reason: "personal_consent_refused" };
-            if (!response.ok)
-                return { state: "failed", reason: "personal_consent_start_failed" };
-            const body = await response.json();
-            if (typeof body.authorizationUrl !== "string" || typeof body.expiresAt !== "number")
-                return { state: "failed", reason: "personal_consent_shape" };
-            let url;
-            try {
-                url = new URL(body.authorizationUrl);
-            }
-            catch {
-                return { state: "failed", reason: "personal_consent_shape" };
-            }
-            if (url.protocol !== "https:" || url.origin !== new URL(cfg.baseUrl).origin || url.username || url.password)
-                return { state: "refused", reason: "personal_consent_origin" };
-            stepCtx.stderr(`Approve your personal ${provider === "linear" ? "Linear" : "GitHub"} connection in the browser.`);
-            stepCtx.stderr(url.toString());
-            (hooks.openBrowser ?? openBrowser)(url.toString());
-            const poll = () => pollConsent({ readStatus: pollSignal => personalStatus(provider, stepCtx, pollSignal), sleep: hooks.sleep, signal });
-            return hooks.ui ? hooks.ui.wait(`Waiting for your ${provider === "linear" ? "Linear" : "GitHub"} approval`, poll) : poll();
-        }
+    const personalAdapter = (provider) => personalConsentAdapter({
+        provider,
+        openBrowser: hooks.openBrowser ?? openBrowser,
+        sleep: hooks.sleep,
+        wait: hooks.ui
+            ? (message, run) => hooks.ui.wait(message, run)
+            : undefined,
     });
-    const linear = existingLinearAdapters(args, hooks.ui?.chooseTeam ? teams => hooks.ui.chooseTeam(teams.map(team => ({ ...team }))) : undefined);
+    const linear = existingLinearAdapters(args, hooks.ui?.chooseTeam
+        ? (teams) => hooks.ui.chooseTeam(teams.map((team) => ({ ...team })))
+        : undefined);
     return {
-        identity: journal => identity(ctx, journal), bindSignals: true, ui: hooks.ui,
+        identity: (journal) => identity(ctx, journal),
+        bindSignals: true,
+        ui: hooks.ui,
         adapters: {
-            machine: { check: async () => process.platform === "darwin" || process.platform === "linux"
-                    ? { state: "done", evidence: { provider: process.platform } } : waiting("machine_platform_unsupported") },
-            cli: { check: async () => ({ state: "done", evidence: { version: readManifest().version } }) },
-            skills: { check: async (stepCtx) => {
+            machine: {
+                check: async () => process.platform === "darwin" || process.platform === "linux"
+                    ? { state: "done", evidence: { provider: process.platform } }
+                    : waiting("machine_platform_unsupported"),
+            },
+            cli: {
+                check: async () => ({
+                    state: "done",
+                    evidence: { version: readManifest().version },
+                }),
+            },
+            skills: {
+                check: async (stepCtx) => {
                     const cfg = loadConfig(stepCtx.home);
-                    const dir = stepCtx.env.CATALYST_SKILLS_DIR ?? cfg?.skillsDir ?? defaultSkillsDirFor(stepCtx.home);
+                    const dir = stepCtx.env.CATALYST_SKILLS_DIR ??
+                        cfg?.skillsDir ??
+                        defaultSkillsDirFor(stepCtx.home);
                     const names = hooks.skillNames ?? [];
-                    const count = names.filter(name => existsSync(join(dir, name, "SKILL.md"))).length;
-                    return names.length > 0 && count === names.length ? { state: "done", evidence: { count, path: dir } } : waiting("skills_install_unverified");
-                } },
-            legacy: { check: legacyCheck, act: async (stepCtx) => {
+                    const count = names.filter((name) => existsSync(join(dir, name, "SKILL.md"))).length;
+                    return names.length > 0 && count === names.length
+                        ? { state: "done", evidence: { count, path: dir } }
+                        : waiting("skills_install_unverified");
+                },
+            },
+            legacy: {
+                check: legacyCheck,
+                act: async (stepCtx) => {
                     const before = await legacyCheck(stepCtx);
                     if (before.state !== "pending")
                         return before;
                     // Provider/process output is not trusted to be secret-free; keep it out of the receipt/log.
                     const quiet = { ...stepCtx, stdout: () => { }, stderr: () => { } };
-                    const code = await cmdLegacy({ ...args, command: "legacy", subcommand: null, rest: [], flags: { remove: true, yes: true }, json: false }, quiet, hooks.legacy);
-                    return code === 0 ? legacyCheck(stepCtx) : { state: "failed", reason: "legacy_cleanup_failed" };
-                } },
-            signin: { check: async (stepCtx, journal) => {
+                    const code = await cmdLegacy({
+                        ...args,
+                        command: "legacy",
+                        subcommand: null,
+                        rest: [],
+                        flags: { remove: true, yes: true },
+                        json: false,
+                    }, quiet, hooks.legacy);
+                    return code === 0
+                        ? legacyCheck(stepCtx)
+                        : { state: "failed", reason: "legacy_cleanup_failed" };
+                },
+            },
+            signin: {
+                check: async (stepCtx, journal) => {
                     const who = await identity(stepCtx, journal);
-                    return who ? { state: "done", evidence: { account: who.account, membershipId: who.membershipId, role: who.role } } : { state: "pending" };
-                }, act: async (stepCtx, _journal, signal) => {
+                    return who
+                        ? {
+                            state: "done",
+                            evidence: {
+                                account: who.account,
+                                membershipId: who.membershipId,
+                                role: who.role,
+                            },
+                        }
+                        : { state: "pending" };
+                },
+                act: async (stepCtx, _journal, signal) => {
                     return boundedOnboardSignin({ ...stepCtx, stdout: stepCtx.stderr }, hooks.login, signal, hooks.signinTimeoutMs);
-                } },
+                },
+            },
             ...linear,
-            "linear.workspace": linearWorkspaceAdapter({ fallback: linear["linear.workspace"], openBrowser: hooks.openBrowser ?? openBrowser,
-                wait: hooks.ui ? (message, work) => hooks.ui.wait(message, work) : undefined, sleep: hooks.sleep }),
+            "linear.workspace": linearWorkspaceAdapter({
+                fallback: linear["linear.workspace"],
+                openBrowser: hooks.openBrowser ?? openBrowser,
+                wait: hooks.ui
+                    ? (message, work) => hooks.ui.wait(message, work)
+                    : undefined,
+                sleep: hooks.sleep,
+            }),
             "github.install": unsupported,
-            "github.repos": existingRepositoryAdapter(args, hooks.ui?.chooseRepositories ? repositories => hooks.ui.chooseRepositories(repositories.map(row => ({ ...row }))) : undefined),
+            "github.repos": existingRepositoryAdapter(args, hooks.ui?.chooseRepositories
+                ? (repositories) => hooks.ui.chooseRepositories(repositories.map((row) => ({ ...row })))
+                : undefined),
             "linear.personal": personalAdapter("linear"),
             "github.personal": personalAdapter("github"),
-            daemon: { check: async (_stepCtx, journal) => (journal.localSync ?? args.flags["local-sync"] === true) ? waiting("local_sync_capability_unavailable")
-                    : { state: "skipped", reason: "local_sync_not_selected", evidence: { provider: "cloud" } } },
-            housekeeping: { check: async () => waiting("housekeeping_service_unverified") },
+            daemon: {
+                check: async (_stepCtx, journal) => (journal.localSync ?? args.flags["local-sync"] === true)
+                    ? waiting("local_sync_capability_unavailable")
+                    : {
+                        state: "skipped",
+                        reason: "local_sync_not_selected",
+                        evidence: { provider: "cloud" },
+                    },
+            },
+            housekeeping: {
+                check: async () => waiting("housekeeping_service_unverified"),
+            },
             ready: { check: hooks.ready },
         },
     };

package/dist/onboard-ui.js

@@ -1,13 +1,17 @@
-import { createOnboardProgress } from "./onboard-progress.js";
-import { ONBOARD_STEPS, ONBOARD_TITLES } from "./onboard.js";
+import { createOnboardProgress, } from "./onboard-progress.js";
+import { ONBOARD_STEPS, ONBOARD_TITLES, } from "./onboard.js";
 export function shouldUseOnboardUi(args, stdoutTty) {
-    return stdoutTty && !args.json && args.flags.yes !== true && args.flags["dry-run"] !== true;
+    return (stdoutTty &&
+        !args.json &&
+        args.flags.yes !== true &&
+        args.flags["dry-run"] !== true);
 }
 export function createClackOnboardUi(prompts, streams, deps = {}) {
     const abort = new AbortController();
     const options = { ...streams, signal: abort.signal };
     // Clack 1.8.1's spinner calls process.exit(0) on raw Ctrl-C, bypassing receipt/lock cleanup.
-    const spin = deps.progress ?? createOnboardProgress(streams.output, abort.signal, () => abort.abort());
+    const spin = deps.progress ??
+        createOnboardProgress(streams.output, abort.signal, () => abort.abort());
     const signals = deps.signals ?? process;
     const interrupt = () => abort.abort();
     for (const event of ["SIGINT", "SIGTERM", "SIGHUP"])
@@ -15,15 +19,23 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
     let active = false;
     let introduced = false;
     let group;
-    const stop = () => { if (active) {
-        spin.stop();
-        active = false;
-    } };
-    const message = (text) => { stop(); prompts.log.message(text, { output: streams.output }); };
-    const start = (text) => { stop(); if (!abort.signal.aborted) {
-        spin.start(text);
-        active = true;
-    } };
+    const stop = () => {
+        if (active) {
+            spin.stop();
+            active = false;
+        }
+    };
+    const message = (text) => {
+        stop();
+        prompts.log.message(text, { output: streams.output });
+    };
+    const start = (text) => {
+        stop();
+        if (!abort.signal.aborted) {
+            spin.start(text);
+            active = true;
+        }
+    };
     return {
         signal: abort.signal,
         plan(journal) {
@@ -32,52 +44,89 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
                 prompts.intro("Catalyst setup", { output: streams.output });
                 introduced = true;
             }
-            const steps = new Map(journal.steps.map(step => [step.id, step]));
-            message(ONBOARD_STEPS.map(id => `· ${ONBOARD_TITLES[id]}${steps.get(id)?.state === "done" ? " (recheck)" : ""}`).join("\n"));
+            const steps = new Map(journal.steps.map((step) => [step.id, step]));
+            message(ONBOARD_STEPS.map((id) => `· ${ONBOARD_TITLES[id]}${steps.get(id)?.state === "done" ? " (recheck)" : ""}`).join("\n"));
             message("Use cloud reads by default. Local sync is optional for SQL, offline work or sustained reads.");
         },
         async confirmPlan(localSync) {
             stop();
-            const answer = await prompts.select({ ...options, message: "Continue with this plan?", initialValue: localSync ? "local" : "cloud", options: [
-                    { value: "cloud", label: "Continue using cloud reads", hint: "default" },
+            const answer = await prompts.select({
+                ...options,
+                message: "Continue with this plan?",
+                initialValue: localSync ? "local" : "cloud",
+                options: [
+                    {
+                        value: "cloud",
+                        label: "Continue using cloud reads",
+                        hint: "default",
+                    },
                     { value: "local", label: "Continue and set up local sync" },
                     { value: "stop", label: "Stop without changes" },
-                ] });
+                ],
+            });
             if (prompts.isCancel(answer)) {
                 abort.abort();
                 return { proceed: false, localSync };
             }
-            return { proceed: answer === "cloud" || answer === "local", localSync: answer === "local" };
+            return {
+                proceed: answer === "cloud" || answer === "local",
+                localSync: answer === "local",
+            };
         },
         async chooseTeam(teams) {
             stop();
             if (!teams.length || abort.signal.aborted)
                 return null;
-            const answer = await prompts.select({ ...options, message: "Which Linear team should this project use?", initialValue: teams[0].id,
-                options: teams.map(team => ({ value: team.id, label: `${team.name || team.key || team.id}${team.key && team.name ? ` (${team.key})` : ""}` })) });
+            const answer = await prompts.select({
+                ...options,
+                message: "Which Linear team should this project use?",
+                initialValue: teams[0].id,
+                options: teams.map((team) => ({
+                    value: team.id,
+                    label: `${team.name || team.key || team.id}${team.key && team.name ? ` (${team.key})` : ""}`,
+                })),
+            });
             if (prompts.isCancel(answer)) {
                 abort.abort();
                 return null;
             }
             return typeof answer === "string" ? answer : null;
         },
-        ...(prompts.multiselect ? { async chooseRepositories(repositories) {
-                stop();
-                if (!repositories.length || abort.signal.aborted)
-                    return null;
-                const answer = await prompts.multiselect({ ...options, message: "Which repositories should use this Linear team?", required: true,
-                    options: repositories.map(row => ({ value: `${row.owner}/${row.name}`, label: `${row.owner}/${row.name}` })) });
-                if (prompts.isCancel(answer)) {
-                    abort.abort();
-                    return null;
-                }
-                return Array.isArray(answer) ? answer : null;
-            } } : {}),
+        ...(prompts.multiselect
+            ? {
+                async chooseRepositories(repositories) {
+                    stop();
+                    if (!repositories.length || abort.signal.aborted)
+                        return null;
+                    const answer = await prompts.multiselect({
+                        ...options,
+                        message: "Which repositories should use this Linear team?",
+                        required: true,
+                        options: repositories.map((row) => ({
+                            value: `${row.owner}/${row.name}`,
+                            label: `${row.owner}/${row.name}`,
+                        })),
+                    });
+                    if (prompts.isCancel(answer)) {
+                        abort.abort();
+                        return null;
+                    }
+                    return Array.isArray(answer) ? answer : null;
+                },
+            }
+            : {}),
         stepStart(id) {
-            const next = ["machine", "cli", "skills", "legacy"].includes(id) ? "This computer"
-                : id === "signin" ? "Catalyst sign-in" : id.startsWith("linear.") || id.startsWith("github.") ? "Connections"
-                    : ["projects", "accounts", "settings", "values"].includes(id) ? "Project setup"
-                        : ["capacity", "daemon", "housekeeping"].includes(id) ? "Runner and services" : "Work and readiness";
+            const next = ["machine", "cli", "skills", "legacy"].includes(id)
+                ? "This computer"
+                : id === "signin"
+                    ? "Catalyst sign-in"
+                    : id.startsWith("linear.") || id.startsWith("github.")
+                        ? "Connections"
+                        : ["projects", "accounts", "settings", "values"].includes(id)
+                            ? "Project setup"
+                            : ["capacity", "daemon", "housekeeping"].includes(id)
+                                ? "Runner and services"
+                                : "Work and readiness";
             if (next !== group) {
                 message(next);
                 group = next;
@@ -87,6 +136,11 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         stepEnd(step) {
             stop();
             const reasons = {
+                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.",
+                personal_status_unavailable: "Your personal connection could not be checked. Run catalyst onboard to try again.",
+                personal_browser_unavailable: "The browser could not open. Run catalyst onboard to try again.",
                 cloud_capability_unavailable: "Your cloud does not support this setup step yet.",
                 step_not_available_in_this_release: "This setup step is not available yet.",
                 prerequisite_not_ready: "Waiting for an earlier setup step.",
@@ -115,27 +169,39 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
                 repository_selection_unverified: "Your selected repositories could not be verified. Run catalyst onboard --repo <owner/name> to choose again.",
             };
             const text = `${ONBOARD_TITLES[step.id]}${step.reason ? `: ${reasons[step.reason] ?? step.reason.replaceAll("_", " ")}` : ""}`;
-            const kind = step.state === "done" ? "info" : step.state === "failed" ? "error" : step.state === "waiting" || step.state === "pending" ? "warn" : "message";
-            prompts.log[kind](`${step.state === "done" ? "✓ " : ""}${text}`, { output: streams.output });
+            const kind = step.state === "done"
+                ? "info"
+                : step.state === "failed"
+                    ? "error"
+                    : step.state === "waiting" || step.state === "pending"
+                        ? "warn"
+                        : "message";
+            prompts.log[kind](`${step.state === "done" ? "✓ " : ""}${text}`, {
+                output: streams.output,
+            });
         },
         message,
         finish(journal, only) {
             stop();
             let text = "Setup still needs checks. Run catalyst onboard to resume.";
             if (abort.signal.aborted)
-                text = "Setup paused. Your progress is saved.\nresume: catalyst onboard";
+                text =
+                    "Setup paused. Your progress is saved.\nresume: catalyst onboard";
             else if (journal.complete && journal.exit === 0 && !only)
                 text = "Onboarding complete.";
             else if (only && journal.exit === 0)
                 text = `${ONBOARD_TITLES[only]} finished. Onboarding still has other steps.\nresume: catalyst onboard`;
             prompts.outro(text, { output: streams.output });
         },
-        async wait(text, run) { start(text); try {
-            return await run();
-        }
-        finally {
-            stop();
-        } },
+        async wait(text, run) {
+            start(text);
+            try {
+                return await run();
+            }
+            finally {
+                stop();
+            }
+        },
         dispose() {
             try {
                 stop();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat \u2014 get set up, see what is happening, see what needs you, run a project, unstick what is stuck \u2014 plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your cloud account with one command. The skills directory is the roster; this line never counts it.",
   "license": "MIT",
   "type": "module",

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.3 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.4 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the local replica when it is fresh and the origin-fresh API otherwise, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.3 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.4 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 

package/skills/catalyst-onboard/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.3 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.4 — written in this repository for customer accounts -->
 
 # Onboard me
 

package/skills/run-this-project/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the account's event stream for the scope through the catalyst CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.3 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.4 — written in this repository for customer accounts -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.3 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.4 — written in this repository for customer accounts -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The human's decision inbox on Catalyst Cloud, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by how much open work each one holds, files an ask through the cloud's ask route with the account's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.3 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.4 — written in this repository for customer accounts -->
 
 # What needs me
 

package/skills/what-this-repo-needs/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups (build/test, deploy-only, bindings), each with where it was found, what uses it, and where a local value would come from. Never reads a value or prints one. Also checks the environment variable table in `.catalyst/catalyst.toml` offline. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing the declaration.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.3 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.4 — written in this repository for customer accounts -->
 
 # What this repository needs
 

package/skills/whats-happening/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Use for "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.3 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.4 — written in this repository for customer accounts -->
 
 # What's happening