@catalyst-cloud/cli 0.14.1 → 0.14.3

package/dist/onboard-runtime.js

@@ -0,0 +1,157 @@
+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 { CliError } from "./errors.js";
+import { cmdLegacy, findLegacy } from "./legacy.js";
+import { bearerFor } from "./oauth.js";
+import { pollConsent } from "./onboard-consent.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 });
+function sameHome(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+/** Only existing bearer routes are registered here. Missing server capabilities stay unfinished. */
+export function createOnboardRuntime(args, ctx, hooks) {
+    const identity = async (stepCtx = ctx, journal) => {
+        const cfg = loadConfig(stepCtx.home);
+        if (!cfg)
+            return null;
+        const requested = args.baseUrl ?? stepCtx.env.CATALYST_CLOUD_BASE_URL;
+        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))))
+            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 };
+    };
+    const legacyCheck = async (stepCtx) => {
+        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 } };
+    };
+    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 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 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,
+        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) => {
+                    const cfg = loadConfig(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 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 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 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 }),
+            "github.install": unsupported,
+            "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") },
+            ready: { check: hooks.ready },
+        },
+    };
+}

package/dist/onboard-signin.js

@@ -0,0 +1,43 @@
+import { CliError, UsageError } from "./errors.js";
+const TIMED_OUT = Symbol("signin_timeout");
+const cancelled = () => new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11);
+/** One onboarding budget includes every device-code round and final member verification. */
+export async function boundedOnboardSignin(ctx, login, external, timeoutMs = 600_000) {
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 600_000)
+        throw new UsageError("onboarding sign-in timeout must be 1 to 600000 milliseconds");
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    const signal = external ? AbortSignal.any([external, deadline.signal]) : deadline.signal;
+    let removeAbort = () => { };
+    try {
+        const exit = await new Promise((resolve, reject) => {
+            const stopped = () => external?.aborted ? reject(cancelled()) : resolve(TIMED_OUT);
+            if (signal.aborted) {
+                stopped();
+                return;
+            }
+            signal.addEventListener("abort", stopped, { once: true });
+            removeAbort = () => signal.removeEventListener("abort", stopped);
+            const stepCtx = { ...ctx, fetch: (async (input, init) => {
+                    if (signal.aborted)
+                        throw cancelled();
+                    const response = await ctx.fetch(input, { ...init, signal: init?.signal ? AbortSignal.any([signal, init.signal]) : signal });
+                    if (signal.aborted)
+                        throw cancelled();
+                    return response;
+                }) };
+            // Attach both handlers even when a custom callback ignores abort and settles after the budget.
+            Promise.resolve().then(() => {
+                if (signal.aborted)
+                    throw cancelled();
+                return login(stepCtx, signal);
+            }).then(code => signal.aborted ? stopped() : resolve(code), error => signal.aborted ? stopped() : reject(error));
+        });
+        return exit === TIMED_OUT ? { state: "waiting", reason: "signin_timeout" }
+            : exit === 0 ? { state: "done" } : { state: "failed", reason: "signin_failed" };
+    }
+    finally {
+        clearTimeout(timer);
+        removeAbort();
+    }
+}

package/dist/onboard-ui.js

@@ -0,0 +1,155 @@
+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;
+}
+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 signals = deps.signals ?? process;
+    const interrupt = () => abort.abort();
+    for (const event of ["SIGINT", "SIGTERM", "SIGHUP"])
+        signals.on(event, interrupt);
+    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;
+    } };
+    return {
+        signal: abort.signal,
+        plan(journal) {
+            stop();
+            if (!introduced) {
+                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"));
+            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" },
+                    { 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" };
+        },
+        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})` : ""}` })) });
+            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;
+            } } : {}),
+        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";
+            if (next !== group) {
+                message(next);
+                group = next;
+            }
+            start(ONBOARD_TITLES[id]);
+        },
+        stepEnd(step) {
+            stop();
+            const reasons = {
+                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.",
+                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_login_refresh_required: "Your login needs a refresh. 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.",
+                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 });
+        },
+        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";
+            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();
+        } },
+        dispose() {
+            try {
+                stop();
+            }
+            finally {
+                abort.abort();
+                try {
+                    spin.dispose();
+                }
+                finally {
+                    for (const event of ["SIGINT", "SIGTERM", "SIGHUP"])
+                        signals.off(event, interrupt);
+                }
+            }
+        },
+    };
+}

package/dist/onboard-workspace.js

@@ -0,0 +1,185 @@
+import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { pollConsent } from "./onboard-consent.js";
+const STATUS = "/api/v1/me/connections/linear/workspace";
+const HANDOFF = "/connect/linear/workspace/handoff";
+const idPattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const states = new Set(["connected", "missing-scope", "expired-or-revoked", "unreachable", "not-connected"]);
+const warmth = new Set(["warm", "absent", "expired", "renewal-due", "no-expiry", "unavailable"]);
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : null;
+const waiting = (reason) => ({ state: "waiting", reason });
+const nullableText = (v) => v === null || typeof v === "string";
+const nullableTime = (v) => v === null || typeof v === "number" && Number.isFinite(v) && v >= 0;
+/** A bounded read never rotates credentials or writes a token after the receipt lock is released. */
+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: "workspace_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: "workspace_login_refresh_required" };
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    const signal = external ? AbortSignal.any([external, deadline.signal]) : deadline.signal;
+    let remove = () => { };
+    try {
+        return await new Promise(resolve => {
+            const stopped = () => resolve({ reason: external?.aborted ? "interrupted" : "workspace_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,
+                });
+                // Refusal bodies and provider diagnostics are never parsed, returned or printed.
+                if (response.status !== 200)
+                    return { status: response.status };
+                return { status: 200, body: await response.json() };
+            }).then(value => signal.aborted ? stopped() : resolve(value), () => signal.aborted ? stopped() : resolve({ reason: "workspace_status_unavailable" }));
+        });
+    }
+    finally {
+        clearTimeout(timer);
+        remove();
+    }
+}
+function readFailure(value) {
+    if ("reason" in value)
+        return value.reason === "workspace_identity_refused" || value.reason === "personal_login_required"
+            ? { state: "refused", reason: value.reason } : waiting(value.reason);
+    if (value.status === 401 || value.status === 403)
+        return { state: "refused", reason: "workspace_consent_refused" };
+    return value.status === 200 ? null : waiting("workspace_status_unavailable");
+}
+/** Live liveness plus stored grant scopes is a connection verdict, not live workspace identity. */
+function observation(body, now) {
+    const row = object(body);
+    const workspace = object(row?.workspace);
+    const credential = object(row?.credential);
+    const verification = object(row?.verification);
+    if (!row || typeof row.connected !== "boolean" || !workspace || typeof workspace.bound !== "boolean" ||
+        !nullableText(workspace.workspaceId) || !nullableText(workspace.workspaceSlug) || !nullableText(workspace.workspaceName) ||
+        !credential || ![true, false, null].includes(credential.stored) ||
+        !nullableTime(credential.updatedAt) || !nullableTime(credential.expiresAt) || (typeof credential.warmth !== "string" || !warmth.has(credential.warmth)) || !verification)
+        return waiting("workspace_status_shape");
+    if (verification.source === "none" && verification.state === "not-run" && verification.checkedAt === null && row.connected === false)
+        return waiting("workspace_status_unavailable");
+    if (verification.source !== "live-probe" || (typeof verification.state !== "string" || !states.has(verification.state)) ||
+        typeof verification.checkedAt !== "number" || !Number.isFinite(verification.checkedAt) ||
+        verification.checkedAt < now - 120_000 || verification.checkedAt > now + 30_000 ||
+        row.connected !== (verification.state === "connected"))
+        return waiting("workspace_status_shape");
+    if (verification.state === "unreachable")
+        return waiting("workspace_status_unavailable");
+    if (!row.connected)
+        return { state: "pending" };
+    // A working credential alone cannot prove this account has a bound Linear workspace.
+    if (!workspace.bound || typeof workspace.workspaceId !== "string" || !idPattern.test(workspace.workspaceId))
+        return waiting("linear_workspace_unverified");
+    return { state: "done", evidence: { provider: "linear", workspace: workspace.workspaceId, checkedAt: verification.checkedAt } };
+}
+function safeHandoff(body, ctx) {
+    const row = object(body);
+    const cfg = loadConfig(ctx.home);
+    if (!cfg || !row || typeof row.authorizationUrl !== "string" || row.authorizationUrl.length > 8192 || /[\u0000-\u0020\u007f]/.test(row.authorizationUrl) ||
+        typeof row.expiresAt !== "number" || !Number.isFinite(row.expiresAt))
+        return null;
+    const remaining = row.expiresAt - ctx.now().getTime();
+    // Thirty seconds accommodates clock skew; an expired link is never launched.
+    if (remaining <= 0 || remaining > 630_000)
+        return null;
+    try {
+        const url = new URL(row.authorizationUrl);
+        const keys = [...url.searchParams.keys()];
+        const handoff = url.searchParams.get("handoff");
+        if (url.protocol !== "https:" || url.origin !== new URL(normalizeBaseUrl(cfg.baseUrl)).origin || url.username || url.password ||
+            url.pathname !== HANDOFF || url.hash || keys.length !== 1 || keys[0] !== "handoff" ||
+            !handoff || handoff.length > 4096 || /[\s\u0000-\u001f\u007f]/.test(handoff))
+            return null;
+        return url.toString();
+    }
+    catch {
+        return null;
+    }
+}
+/** Uses the new personal bearer twins; old clouds retain their supported read-only readiness path. */
+export function linearWorkspaceAdapter(options) {
+    const timeoutMs = options.requestTimeoutMs ?? 30_000;
+    const consentTimeoutMs = options.consentTimeoutMs ?? 600_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000 ||
+        !Number.isSafeInteger(consentTimeoutMs) || consentTimeoutMs < 1 || consentTimeoutMs > 600_000)
+        throw new Error("workspace_timeout_invalid");
+    const inspect = async (ctx, journal, signal) => {
+        const result = await read(ctx, journal, STATUS, timeoutMs, signal);
+        if ("status" in result && result.status === 404)
+            return { result: await options.fallback.check(ctx, journal, signal), unsupported: true };
+        const failure = readFailure(result);
+        return { result: failure ?? observation("body" in result ? result.body : undefined, ctx.now().getTime()) };
+    };
+    return {
+        check: async (ctx, journal, signal) => (await inspect(ctx, journal, signal)).result,
+        act: async (ctx, journal, signal) => {
+            const cfg = loadConfig(ctx.home);
+            if (!cfg?.user || !["owner", "admin"].includes(cfg.user.role))
+                return { state: "refused", reason: "workspace_admin_required" };
+            if (signal?.aborted)
+                return waiting("interrupted");
+            const before = await inspect(ctx, journal, signal);
+            if (before.result.state !== "pending")
+                return before.result;
+            if (before.unsupported)
+                return waiting("cloud_capability_unavailable");
+            const start = await read(ctx, journal, `${STATUS}/start`, timeoutMs, signal);
+            if ("status" in start && start.status === 404)
+                return waiting("cloud_capability_unavailable");
+            const failure = readFailure(start);
+            if (failure)
+                return failure;
+            const url = safeHandoff("body" in start ? start.body : undefined, ctx);
+            if (!url)
+                return { state: "refused", reason: "workspace_consent_handoff" };
+            if (signal?.aborted)
+                return waiting("interrupted");
+            const current = loadConfig(ctx.home);
+            if (!current?.user || current.account !== cfg.account || current.user.id !== cfg.user.id ||
+                normalizeBaseUrl(current.baseUrl) !== normalizeBaseUrl(cfg.baseUrl))
+                return { state: "refused", reason: "workspace_identity_refused" };
+            if (!["owner", "admin"].includes(current.user.role))
+                return { state: "refused", reason: "workspace_admin_required" };
+            ctx.stderr("Approve the organization's Linear connection in your browser. Your personal approval follows.");
+            // The signed URL is transient credential material: only the browser receives it.
+            try {
+                options.openBrowser(url);
+            }
+            catch {
+                return waiting("workspace_browser_unavailable");
+            }
+            let latest = waiting("workspace_status_unavailable");
+            const run = () => pollConsent({ timeoutMs: consentTimeoutMs, signal, sleep: options.sleep,
+                readStatus: async (pollSignal) => {
+                    const value = await inspect(ctx, journal, pollSignal);
+                    latest = value.result;
+                    if (value.unsupported)
+                        return { outcome: "failed", reason: "cloud_capability_unavailable" };
+                    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 workspace approval", run) : await run();
+            return result.state === "done" ? latest : result;
+        },
+    };
+}